User Authentication with Certificates

Certificate authentication is technically a part of the public-key authentication method. The signature created with the private key and the verification of the signature using the public key (contained in the X.509 certificate when doing certificate authentication) are done identically with both conventional public keys and certificates. The major difference is in determining whether a specific user is allowed to log in with a specific public key or certificate. With conventional public keys, every server must have every user's public key, whereas with certificates the users' public keys do not have to be distributed to the servers - distributing the public key of the certificate authority (CA) (self-signed certificate) is enough.

In brief, certificate authentication works the following way:

The client sends the user certificate (which includes the user's public key) to the server. The packet also contains random data unique to the session and signed by the user's private key.
The server uses the CA certificate (and external resources as required) to check that the user's certificate is valid.
The server verifies that the user has a valid private key by checking the signature in the initial packet.
The server matches the user certificate with the rules in the server configuration file to decide whether login is allowed or not.

Compared to conventional 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 to the system by revoking his or her certificate, although this does not take effect until the next CRL update and requires that every other authentication method has been disabled. The status of a certificate can be checked either by using the Online Certificate Status Protocol (OCSP) or a certificate revocation list (CRL), which can be published either in an LDAP or HTTP repository.

OCSP is used if the certificate contains a valid Authority Info Access extension or if an ocsp-responder has been defined in the ssh-server-config.xml file. If no OCSP responder is defined or the OCSP connection fails, CRLs are used. The certificate should contain a valid CRL Distribution Point extension or an LDAP server for CRL fetching should be defined in the ssh-server-config.xml file.

Configuring Certificates

To configure the server to allow user authentication with X.509 certificates, perform the following tasks:

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-keygen-g3.
Specify the CA certificate and the CRL and OCSP settings in the ssh-server-config.xml file. An example is shown below:
```
<params>
  ...
  <cert-validation socks-server-url="socks://fw.example.com:1080">
    <ldap-server address="ldap.example.com" port="389" />
    <ocsp-responder validity-period="60" url="https://ca.example.com/ocsp-1" />
    <cert-cache-file file="/var/cert-cache.dat" />
    <crl-auto-update update-before="30" minimum-interval="600" />
    <crl-prefetch interval="1800" url="http://ca.example.com/default.crl" />
    <dod-pki enable="no" />
    <ca-certificate name="exa-ca1" file="/etc/ssh2/exa-ca1.crt" />
  </cert-validation>
</params>    
```
You can define several CA certificates by using several ca-certificate elements. The server will accept only certificates issued by the defined CA(s). Only the ca-certificate elements are mandatory, all other configuration items featured above are just examples that may be used as needed.
The SOCKS server must be defined if the OCSP and CRL (LDAP) services are located behind a firewall.
On Windows, using the SSH Tectia Server Configuration tool, the corresponding settings can be made on the Certificate Validation page. See Certificate Validation.

Certificate authentication is a part of the publickey authentication method. Enable public-key authentication in the ssh-server-config.xml file and create rules that specify which certificates authorize logging into which accounts.

The following is an example of certificate authentication rules in the ssh-server-config.xml file:

<authentication-methods>
  <authentication action="allow" repeat-block="yes">
    <auth-publickey />
    <authentication action="allow">
      <selector>
        <certificate field="ca-list" pattern="exa-ca1,exa-ca2" />
        <certificate field="issuer-name" pattern="C=FI, O=SSH, CN=*" />
        <certificate field="subject-name" pattern="C=FI, O=SSH, CN=%username%" />
        <certificate field="serial-number" pattern="123456" />
        <certificate field="altname-email" pattern="%username%@ssh.com" />
        <certificate field="altname-upn" pattern="%username-without-domain%@ssh" />
        </selector>
    </authentication>
    <authentication action="deny" />
  </authentication>
</authentication-methods>

In this example, the repeat-block attribute is set to yes. This makes SSH Tectia Server try to match all certificates offered by the client against the certificate selectors. If the attribute is omitted, SSH Tectia Server will try only the first certificate, and if it does not match, the authentication ends in failure.

In this example, as the last action, access is denied for all users whose certificates were not explicitly allowed. This is not strictly needed, since the server automatically inserts an authentication block named implicit-certificate-deny after other blocks to catch all certificate authentications that do not match anything else.

In the example, users with normal public keys will cause the authentication to end in error because the allow-undefined attribute is not set. See also the section called “Authentication Examples”.

Certificate authentication can be restricted using the following field attributes:

ca-list: The pattern is a comma-separated list of CA names. The names that are defined in the ca-certificate element are used.
issuer-name: The pattern is the required certificate issuer name in LDAP DN (distinguished name) string format. The issuer name may contain glob patterns ('*' and '?') but only in the component values, not names. For example, "C=FI, O=SSH, CN=*" is a legal pattern, but "C=FI, *=SSH, CN=TestCA" is not).
subject-name: The pattern is the required subject name in LDAP DN string format. Matching is done in similar manner as with the issuer name described above.
serial-number: The pattern is the required serial number of the certificate. A combination of issuer name and serial number can be used to uniquely identify a certificate.
altname-email: The pattern is the e-mail address that must be present in the certificate as a subject alternative name.
altname-upn: The pattern is the principal name that must be present in the certificate as a subject alternative name.

The patterns of type subject-name, issuer-name, altname-email and altname-upn can also contain special strings which are processed before comparing the pattern with the user's certificate. These strings are %username% (user's login name), %username-without-domain% (Windows only, user's login name without the domain part), %homedir% (user's home directory), and %hostname% (the name of the host the user is logging from, reverse mapped from the IP).

Caution

	Caution
When creating selector lists for the public-key method, make sure that every selector ties the user name to the certificate in some way, either by including a User name field, or by putting the special substitution string `%username%` or `%username-without-domain%` to a field used to match some field in the certificate. Failing to do this may cause unintended consequences, for example, authentication can succeed with many different user names with a single certificate.

When creating selector lists for the public-key method, make sure that every selector ties the user name to the certificate in some way, either by including a User name field, or by putting the special substitution string %username% or %username-without-domain% to a field used to match some field in the certificate. Failing to do this may cause unintended consequences, for example, authentication can succeed with many different user names with a single certificate.

Similarly, when creating selector lists for the host-based method, make sure that every selector has a field that ties the certificate to the client host, using the %hostname% special substitution string.

On Windows, using the SSH Tectia Server Configuration tool, certificate authentication rules can be configured on the Authentication page. See Authentication.

Run ssh-server-config-tool to take the new configuration in use. See ssh-server-config-tool(8).
On Windows, click Apply to take the new settings in use.