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 defined CA(s). Only the ca-certificates 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-fqdn" pattern="client.ssh.com" /> <certificate field="altname-upn" pattern="%username-without-domain%@ssh" /> <certificate field="altname-ip" pattern="10.2.3.5" /> </selector> </authentication> <authentication action="deny" /> </authentication> </authentication-methods>
In this example, the repeat-block
attribute is set to
yes
. This causes SSH Tectia Server to 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 a
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 (distinguished name) 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.
altname-ip
: The pattern is the IP address
that must be present in the certificate as a subject alternative name.
Also a range of addresses can be given (for example,
10.1.0.11-10.1.0.61
or 10.1.0.0/8
).
altname-fqdn
: The pattern is a list of fully
qualified domain names (FQDN) that may contain glob patterns ('*' and '?').
One of the listed domain names must match with a subject alternative name of
type FQDN in the certificate.
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).
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.