======================================================================= Latest version is "x509-6.1.1" and location is: "http://roumenpetrov.info/openssh/x509-6.1.1/README.x509v3" Please check main page too: "http://roumenpetrov.info/openssh/index.html" Readme file for this version follow after separator: ======================================================================= Roumen Petrov Sofia, Bulgaria Fri Jan 30 2003 How to use X.509 certificates with OpenSSH? Identity or hostkey file for protocol version 2 can contain private key plus x509 certificate in PEM format. Note that protocol version 2 keys are in PEM format. To use X.509 certificate as identity or hostkey user should convert certificate in PEM format and append to file. After this with "ssh-keygen -y ..." user must update "pub" file. File (identity or hostkey) with X.509 certificate (RSA key): -----BEGIN RSA PRIVATE KEY----- ..... -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- ..... -----END CERTIFICATE----- Note that to use X.509 certificates in OpenSSH files must contain private key followed by certificate. 1.) server configuration: 1.1.) .../sshd_config 1.1.1.) "X509 store". "X509 store" is used to verify client keys. AllowedCertPurpose sslclient The intended use off the X509 client certificate. CACertificateFile /etc/ssh/ca/ca-bundle.crt This file contain multiple certificates of certificate signers in PEM format concatenated together. You can get a copy from openssl, apache, KDE, mutt, etc. packages. Original file might is exported from Netscape certificate database and one download URL is: http://www.modssl.org/contrib/ca-bundle.crt.tar.gz CACertificatePath /etc/ssh/ca/crt "Hash dir" with certificates of certificate signers. Each certificate should be stored in separate file with name [HASH].[NUMBER], where [HASH] is certificate hash value and [NUMBER] is an integer starting from zero. Hash is result from command like this: $ openssl x509 -in certificate_file_name -noout -hash CARevocationFile /etc/ssh/ca/ca-bundle.crl This file contain multiple "Certificate Revocation List" (CRL) of certificate signers in PEM format concatenated together. CARevocationPath /etc/ssh/ca/crl "Hash dir" with "Certificate Revocation List" (CRL) of certificate signers. Each CRL should be stored in separate file with name [HASH].r[NUMBER], where [HASH] is CRL hash value and [NUMBER] is an integer starting from zero. Hash is result from command like this: $ openssl crl -in crl_file_name -noout -hash 1.1.2.) HostKey files... Host key for protocol version 2 can contain private key plus x509 certificate in PEM format. 1.2.) append in USER_HOME/.ssh/authorized_keys a record with following format: where: KEY_TYPE:=x509v3-sign-rsa|x509v3-sign-dss (case sensitive !) WORDDN:={Distinguished Name| Distinguished-Name| Distinguished_Name| DistinguishedName| DN| Subject} WORDDNSUFF:='='|':'|'' NOTES: - WORDDN is case insensitive ! - is like output from command: $ openssl x509 -noout -subject -in A_CERTIFICATE_FILE - can be in RFC2253 format like output from command: $ openssl x509 -noout -subject -in A_CERTIFICATE_FILE -nameopt RFC2253 - Order of items in is not important and separator can be symbol "/", "," or mixed. All following subjects are equal: a)CN=OpenSSH RSA test certificate(dsa),OU=OpenSSH Testers,O=OpenSSH Test Team,ST=World,C=XX b)/C=XX/ST=World/O=OpenSSH Test Team/OU=OpenSSH Testers/CN=OpenSSH RSA test certificate(dsa) c)/O=OpenSSH Test Team/OU=OpenSSH Testers/C=XX/ST=World/CN=OpenSSH RSA test certificate(dsa) d)O=OpenSSH Test Team,OU=OpenSSH Testers/C=XX,ST=World/CN=OpenSSH RSA test certificate(dsa) Shell sample: $ printf '%s' "x509v3-sign-rsa "; openssl x509 -noout -subject \ -in A_OPENSSH_CERT_FILE \ >> $HOME/.ssh/authorized_keys NOTES: - adjust user authorized_keys file ownership - user must have at least read access. - SecSH x509v3 key type is "x509v3-sign-rsa" or "x509v3-sign-dss". 2.) client settings: 2.1.) IdentityFile Depends from client. To use X.509 certificate "OpenSSH id-file" must contain both sections - private key and certificate in PEM format: Note: Don't forget to update public key file with command: $ ssh-keygen -y -f KEY_FILE_NAME > KEY_FILE_NAME.pub Command ssh-add use public key file! 2.2.) global ssh_config or $HOME/.ssh/config Check options AllowedCertPurpose, [User]CACertificatePath, [User]CACertificateFile, [User]CARevocationFile and [User]CARevocationPath. See p. 1.1.1. All nine options are for "x509 store". "x509 store" is used to verify server hostkey. Note: When we use own CA we must import CA certificate[s] to "x509 store". More info on: http://satva.skalasoft.com/~rumen/domino_CA/#dca2bundle 3.) test x509 certificates. 3.1.) In openssh build dir run "make check". If x509 test scripts fail edit file OPENSSH_SOURCE_PATH/tests/CA/config or set some environment variables. Output from make check is in color and when is redirected to file later we can see content best with command "less -r ...". When script run a test command print star '*' followed by simple information about command. When command succeed script print at right "done" in GREEN(!) otherwise "failed" in RED(!). After failed command script show on next lines in RED(!) response, skip execution of next command/script, print message like this: .... Testing OpenSSH client with certificates finished. status: failed .... Note that failed is in RED(!) and exit code is NONZERO(!). Some command in a test script must fail. Part of "simple information" about command expected fail is in RED(!). When command fail script print "done" (THIS IS CORRECT - COMMAND MUST FAIL) and on next lines print in GREEN(!) response. Usualy this occur when server reject logon. WHEN ALL TESTS SUCCEED output is: .... Testing OpenSSH client with certificates finished. status: done .... Note that "done" is in GREEN(!) and exit code is ZERO(!). Description of variables is config file: 3.1.1) main variables: - SUDO (only in config) on some system sshd must be started as root. If necessary set variable to sudo and configure sudo'ers. - TMPDIR (environment or config) directory for temporary files. If not set its value is selected from /tmp, /var/tmp or /usr/tmp. - SSH_X509TESTS (environment or config) list with test scripts. A test script is in file with following name: test-.sh.inc. 3.1.2) openssl: - OPENSSL (environment or config) path to openssl binary. The default is result from command: `which openssl`. - RSA_DIGEST_LIST (environment or config) list with RSA digests in support of openssl. The default value is build at run time from following digest list "md5 sha1 md2 md4 rmd160" and contain only supported from openssl. 3.1.3) server section: Read sshd_config.5 manual page for valid values. - SSHD_PORT (environment or config) specifies the port number that server listens on and client connect to on localhost. The default is 20022. - SSHD_LISTENADDRESS (only in config) Same as sshd option "ListenAddress" but without(!) port number. The default is "127.0.0.1". - SSHSERVER_USEPRIVILEGESEPARATION="yes": (only in config) sshd "UsePrivilegeSeparation" option. if necessary set to "no", to disable privilege separation. - SSHSERVER_SYSLOGFACILITY=AUTH (only in config) sshd "SyslogFacility" option. - SSHSERVER_LOGLEVEL=INFO (only in config) sshd 'LogLevel' option. 3.1.4) certificates: - Variables related to test certificates and CA. (only in config) 3.1.5.) Sample commands to run tests: $ OPENSLL=/usr/local/openssl/0.9.6h/bin/openssl make check $ SSHD_PORT=1122 SSH_X509TESTS="agent blob_auth" make check $ RSA_DIGEST_LIST="md5 sha1" make check 3.2.) Current test scripts uses only rsa as server hostkey. To test sshd with x509 certificate please find in file openssh_tests.sh variable TEST_SSHD_HOSTKEY and change it. Sample: TEST_SSH_HOSTKEY="${CWD}/testhostkey_rsa-rsa_md5" 3.3.) Test SecSH from "Microsoft Windows OSes". This is not part of document. Tips: use created after make check files: - convert OPENSSH_BUILD_PATH/tests/CA/ca-test/crt/*crt.pem CA certificates from PEM to DER format and import in "Windows keystore" - import OPENSSH_BUILD_PATH/tests/CA/testid_*.p12 in "Windows keystore" - setup your client to use certificate[s](see SecSH client manuals). DON`T FORGET TO REMOVE entries from "Windows keystore" after test! 3.4.) Go to OPENSSH_BUILD_PATH/tests/CA and run command "make clean" to remove all client/server and CA files. 3.5.) files in OPENSSH_SOURCE_PATH/tests/CA directory: config : configuration file 1-cre_cadb.sh: create "Test CA" directories and files. 2-cre_cakeys.sh: create "Test CA" private keys and certificates. 3-cre_certs.sh: create client/server certificates. this command create files with mask "PATH_TO_KEYFILEn-[.]" , where is in format "rsa_" or "dsa". DIGEST are form variable "RSA_DIGEST_LIST" specified in "config" file. Files without extention are openssh identity or hostkey files. File with .pub extention contain openssh public key (BLOB format). File with .crt extention contain openssl "text output" for identity files. File with .p12 extention are for "Microsoft Windows keystore". verify.sh: to check certificates against "Test CA". Note: check only testid_*.crt and testhostkey_*.crt files in current directory. functions: common usefull functions openssh_tests.sh: main test script - call other testscripts. test-blob_auth.sh.inc, test-dn_auth_file.sh.inc, test-dn_auth_path.sh.inc, test-agent.sh.inc, test-crl.sh.inc: see DESCRIPTION in each file. Note that hostbased authentication we cannot test without to install. Generated testhostkey_* certificates are with sslserver and sslclient purposes and you can use them to test manualy hostbased authentication. Enjoy ;-)