[Contents] [Index]

About This Document>>     Introduction to SSH Secure Shell >>     Configuring SSH Secure Shell >>     Authentication >>         Server Authentication>>         User Authentication>>             Password Authentication             Public-Key Authentication             Host-Based Authentication             Certificate Authentication             Kerberos Authentication             Pluggable Authentication Module (PAM)             SecurID         Keyboard-Interactive Authentication >>     Log Messages >>     Using SSH Secure Shell >>     Tool Syntax>>     Technical Specifications >>

Certificate Authentication

The commercial version of SSH Secure Shell includes support for certificate authentication.

Also certificate authentication is performed via the public-key authentication method. Instead of the client sending just a public key, it sends a certificate containing a public key.

In brief, certificate authentication works in the following way:

• The client sends the user certificate (which inludes the user's public key) to the server.
• The server uses the CA certificate to check that the user's certificate is valid.
• The server uses the user certificate to check from its mapping file(s) whether login is allowed or not.
• Finally, if connection is allowed, the server makes sure that the user has a valid private key by using a challenge.

Compared to traditional public-key authentication, this method is more secure because the system checks that the user certificate was issued by a trusted CA. In addition, certificate authentication is more convenient because no local database of user public keys is required on the server.

It is also easy to deny a user's access the system by revoking his or her certificate. The status of a certificate can be checked either by using the Online Certificate Status Protocol (OCSP) or Certificate Revocation Lists (CRLs), which can be published either to a Lightweight Directory Access Protocol (LDAP) or HTTP repository.

OCSP is used if the certificate contains a valid authority info access extension. Correspondingly, CRLs are used if the certificate contains a valid CRL distribution point extension. If LDAP is used as the CRL publishing method, the LDAP repository location can be also defined in the sshd2_config file (see below).

Server-Side Configuration

To configure the server, perform the following tasks:

1. Acquire the CA certificate and copy it to the server machine. You can either copy the X.509 certificate(s) as such or you can copy a PKCS #7 package including the CA certificate(s). Certificates can be extracted from a PKCS #7 package by specifying the -7 flag with ssh-keygen2.
2. Certificate authentication is a part of the publickey authentication method. Make sure that you have enabled it in the sshd2_config file:

   AllowedAuthentications   publickey
   

3. Specify the CA certificate and the mapping file(s) in the sshd2_config file:

   Pki <ca-cert-path>
   MapFile <map-file-path>
   

   You can disable the use of CRLs by adding the PkiDisableCRLs keyword below the Pki keyword.

   PkiDisableCRLs  yes
   

   Note: CRL usage should only be disabled for testing purposes. Otherwise it is highly recommended to always use CRLs. You can define several CA certificates by using several Pki keywords.

   Pki <ca-cert-path1>
   MapFile <map-file-path1>
   Pki <ca-cert-path2>
   MapFile <map-file-path1>
   MapFile <map-file-path2>
   

   Note that multiple MapFile keywords are permitted per Pki keyword. Also, if no mapping file is defined, all connections are denied even if user certificates can be verified using the defined CA certificate. Server will accept only certificates issued by defined CA(s).
4. Also define the LDAP server(s) in the sshd2_config file.

   LDAPServers ldap://server1.domain1:port1,ldap://server2.domain2:port2,...
   

5. If necessary, define also the SOCKS server in the sshd2_config file.

   SocksServer socks://socks_server:port/network/netmask,network/netmask...
   

   The SOCKS server must be defined if CA services (OCSP and CRLs) are located behind a firewall.
6. Next you need to create the map file. It specifies which certificates authorize logging into which accounts. The format of the file is the following:

   <account-id> <keyword> <argument>
   

   The keyword can be either Email, Subject, SerialAndIssuer, EmailRegex, or SubjectRegex. The arguments depend on the keyword.
   • Email: The argument is the email address which must be present in the certificate.
   • Subject: The argument is the required subject name in LDAP DN (distinguished name) string format.
   • SerialAndIssuer: The argument is the required serial number and issuer name in LDAP DN string format, separated by spaces or tabs.
   • EmailRegex: The argument is the regular expression which must match an email address in the certificate. If account-id contains the string %subst%, it is substituted with the first parenthesized part of the regular expression.The patterns are matched using SSH_REGEX_SYNTAX_EGREP.
   • SubjectRegex: The argument is the regular expression which must match a subject name in the certificate. If account-id contains the string %subst%, it is substituted with the first parenthesized part of the regular expression. The patterns are matched using SSH_REGEX_SYNTAX_EGREP.
   Examples The following are examples of different map file definitions:

    testuser email testuser@ssh.com
    testuser subject C=FI,O=SSH,CN=Secure Shell Tester
    testuser serialandissuer 1234 C=FI,O=SSH,CN=Secure Shell Tester
    %subst% subjectregex C=FI, O=SSH, CN=([a-z]+)         
    %subst% emailregex ([a-z]+)@ssh\.com
   

   The last line permits logging with any email address with only letters in the user name. See man sshregex for more information on the regular expression syntax.

Client-Side Configuration

Configure the client side according to the certificate storage method used; a software or a PKCS #11 token (for example, a smart card).

Software Certificates

To configure the system for software certificates, perform the following tasks:

1. Enroll a certificate for yourself. Example: Enrollment using ssh-certenroll2

   $ /ssh-certenroll2 -g -p id:key -e 
   -s "C=FI,O=SSH,CN=user;email=user@trusted.org"  
   -a "http://test-ca.trusted.org:8080/pkix/" 
   -o /home/user/.ssh2/user_rsa /etc/ssh2/test-ca-certificate.crt
   Generated 1024 bit private key saved to file 
                                   /home/user/.ssh2/user_rsa.prv.
   

   Remember to define also the SOCKS server (with the -S flag) or an HTTP proxy (with the -P flag), if necessary.
2. The private key must be in the ssh2 format. To convert X.509 keys to ssh2 format, specify the -x flag with ssh-keygen2:

   $ ssh-keygen2 -x <keyname>
   Private key imported from X.509 format
   Successfully saved private key to <keyname>_ssh2
   

   Also PKCS #12 keys can be converted to ssh2 format. This is done by specifying the -k flag with ssh-keygen2.

   $ ssh-keygen2 -k <keyname>
   Password needed for PFX integrity check : 
   Integrity check ok.
   Got shrouded key.
   New passphrase for private key : 
   Again                          : 
   Successfully saved private key to <keyname>_ssh2
   Safe decrypted succesfully.
   Got certificate.
   Certificate written to file <keyname>_ssh2.crt
   

3. Make sure that public-key authentication is enabled in the ssh2_config file.

   AllowedAuthentications   publickey
   

4. Specify the private key of your software certificate in the ~/.ssh2/identification file.

   CertKey <private-key-path>
   

   The certificate itself will be read from private-key-path.crt.

PKCS #11 Tokens

To configure the system for PKCS #11 tokens (for example smart cards), perform the following tasks:

1. Enable public-key authentication in the ssh2_config file.

   AllowedAuthentications   publickey
   

2. Also define the external key provider and the initial string.

   EkProvider <provider-name>
   EkInitString <init-string>
   

   The above-mentioned options can be also defined using the - E and -I flags with ssh2, respectively.