======================================================================= Latest version is "15.3" and location is: "https://roumenpetrov.info/secsh/README.x509v3" Main page is "https://roumenpetrov.info/secsh/" Readme file for this version follow after separator: ======================================================================= Roumen Petrov Sofia, Bulgaria Tue Jun 11 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.) AllowedCertPurpose sslclient The intended use off the X.509 client certificate. 1.1.2.) "X509 store". Server use "X509 store" to verify client keys. 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.3.) HostKey files... Host key for protocol version 2 can contain private key plus x509 certificate in PEM format. 1.1.4.) X509rsaSigType=md5 Specifies prefered signature digest type for "x509v3-sign-rsa" keys. The possible values are "md5" and "sha1". When X.509 certificate signature blob fail with specified value, server try other and print log message like this: ... X509COMPAT: RSA succeed for sha1 digest ... This options is intended to collect information about default signature digest type in other SecSH implementations. When you see this PLEASE send a EMAIL with "X509COMPAT" lines from log files. 1.2.) append in USER_HOME/.ssh/authorized_keys a record with following format: {|CertBlob} 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=dsa test certificate,OU=OpenSSH Testers,O=Test Team,ST=World,C=XX b)/C=XX/ST=World/O=Test Team/OU=OpenSSH Testers/CN=dsa test certificate c)/O=Test Team/OU=OpenSSH Testers/C=XX/ST=World/CN=dsa test certificate d)O=Test Team,OU=OpenSSH Testers/C=XX,ST=World/CN=dsa test certificate - CertBlob is uuencoded sequence of bytes in only one line. Shell sample: - "Distinguished Name" format: $ ( printf 'x509v3-sign-rsa '; openssl x509 -noout -subject \ -in A_OPENSSH_IDENTITY_FILE \ ) >> $HOME/.ssh/authorized_keys - "blob" format: $ cat A_OPENSSH_IDENTITY_FILE.pub \ >> $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". - When OpenSSH is build with "--disable-x509store" YOU CANNOT USE "Distinguished Name" format. You shold use ONLY "blob" format. 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 IDENTITY_FILE > IDENTITY_FILE.pub Command ssh-add use public key file! 2.2.) global ssh_config, $HOME/.ssh/config or command line 2.2.1.) AllowedCertPurpose sslserver The intended use off the X.509 server certificate. 2.2.2.) "X509 store". Client use "x509 store" to verify server hostkey. Check options: - [User]CACertificatePath; - [User]CACertificateFile; - [User]CARevocationFile; - [User]CARevocationPath. See p. 1.1.2.). Note: When we use own CA we must import CA certificate[s] to "x509 store". More info on: http://roumenpetrov.info/domino_CA/#dca2bundle 2.2.3.) X509rsaSigType=md5 Temporary option. Specifies signature digest type for 'x509v3-sign-rsa' keys. The possible values are "md5" and "sha1". Use this option only in session with other SecSH servers with X.509 certificates as identity or host key. When ssh print message like this ... X509COMPAT: RSA succeed for sha1 digest ... PLEASE send a EMAIL with this message. When you cannot use X.509 certificate as identity in session with other SecSH implementations try this option. Example: $ ssh -o X509rsaSigType=sha1 .... non_openssh_host Note: ssh-agent use only md5 digest for X.509 certificates. 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 to fail is in RED(!). When command fail script print "done" (THIS IS CORRECT - COMMAND MUST FAIL) and on next lines print in GREEN(!) response. Usually 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(!). 3.1.1.) Description of variables in Makefile file: - SHELL Used shell to run tests. Supported shell are bash, ksh, zsh and ash. Example: $ make check SHELL=/bin/zsh 3.1.2.) Description of variables in config file: 3.1.2.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.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.2.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.2.4.) certificates: - Variables related to test certificates and CA. (only in config) 3.1.3.) Sample commands to run tests: $ OPENSSL=/usr/local/ssl/bin/openssl make check $ SSHD_PORT=1122 SSH_X509TESTS="agent blob_auth" make check $ RSA_DIGEST_LIST="md5 sha1" make check $ make check SHELL=/bin/ksh When check fail see "Troubleshooting" later in document. 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. Files with .p12 extention are for "Microsoft Windows keystore". Note: .p12 = .pfx for Windows. 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 manually hostbased authentication. 4.) Troubleshooting make check fails on: 4.1.) "... 1-cre_cadb.sh: local: not found" try other shell: [ENVSETTINGS] make check SHELL=/bin/ksh 4.2.) "generating a new ... private key for the TEST CA ..." Usually this happen on system without /dev/{u}random. In file [BUILDDIR]/tests/CA/openssh_ca-2.log we can see a message: "... PRNG not seeded ...". Read again WARNING.RNG from OpenSSH sourcedir and/or http://www.openssl.org/support/faq.html 4.2.1.) reconfigure your system and/or openssl 4.2.2.) or do next 4.2.2.1.) install OpenSSH :-( otherwise later "make check" (ssh-keygen) fail with message: "couldn't exec '.../libexec/ssh-rand-helper': ..." and second ./ssh-rand-helper fail with message: "couldn't read entropy commands file ../ssh_prng_cmds: ..." Tip: configure OpenSSH with prefix for example $HOME/test 4.2.2.2.) run: ssh-rand-helper rm -f $HOME/.rnd ln -s .ssh/prng_seed $HOME/.rnd 4.2.2.3.) test openssl with command: /usr/local/ssl/bin/openssl genrsa -des3 -passout pass:change_it Tip: before to create every key with OpenSSL run ssh-rand-helper ! 4.2.2.4.) run again "... make check ..." 4.3.) fail on first check: "* rsa_md5 valid blob failed" Usually SUDO command is not set. See p. 3.1.2.1. Enjoy ;-)