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.
Using the 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"> <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, Tectia Server tries to match all certificates offered by the
client against the certificate
selectors. 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 | |
---|---|
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
|
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.
Using the Tectia Server Configuration tool, certificate authentication rules can be configured on the Authentication page. For instructions, see Configuring User Authentication with Certificates on Windows.
Run ssh-server-ctl
to take the new configuration in use. See ssh-server-ctl(8).
Click Apply to take the new settings in use.