ssh_certificates(4)ssh_certificates(4)NAMEssh_certificates - Describes the configuration files and keywords
needed when using certificates with the Secure Shell software
DESCRIPTION
When using certificates with Secure Shell software, you need the
ssh2_config Version 1.1 and sshd2_config Version 1.1 files and one or
more special mapping files holding the user authorization data. (See
Security Administration for more information about these files.)
The following list describes the certificate-related keywords for the
ssh2_config configuration file. See ssh2_config(4) for a complete list
of keywords.
Specifies the Certificate Authority (CA) certificate (in binary or PEM
[base64] format) to be used when authenticating remote hosts. The cer‐
tificate received from the host must be issued by the specified CA and
must contain an alternate, fully qualified domain name. If the remote
host name is not fully qualified, the domain specified by the Default‐
Domain configuration option is appended to it before comparing it to
certificate alternate names. If no CA certificates are specified in
the configuration file, the protocol tries to do key exchange with
ordinary public keys. Otherwise certificates are preferred. Multiple
CAs are permitted. Similar to HostCA, but disables Certificate Revola‐
tion List (CRL) checking for the given ca-certificate. CRLs are auto‐
matically retrieved from the CRL distribution point defined in the cer‐
tificate to be checked if the point exists. Otherwise, the comma-sepa‐
rated server list given by the LdapServers keyword is used. If inter‐
mediate CA certificates are needed in certificate validity checking,
this keyword must be used or retrieving the certificates will fail.
The following list describes the certificate-related keywords for the
sshd2_config configuration file. See sshd2_config(4) for a complete
list of keywords. Specifies an external mapper program for the preced‐
ing Pki keyword. When a certificate is received and is valid under the
Pki block in question, the external mapper is executed and the certifi‐
cate is written to its standard input. The external mapper is expected
to output a newline-separated list of usernames. If the user name is
found in the list, the authentication succeeds; otherwise, the authen‐
tication using the certificate in question fails. The ExternalMapper
keyword will override all MapFile keywords for the current (preceding)
Pki keyword. If multiple ExternalMapper keywords are specified for a
Pki block, the first one is used. Specifies an external mapper timeout
for the preceding Pki keyword. If the server is unable to read the full
output from an external mapper in the given period, the operation will
fail and the external mapper program will be terminated. The default
timeout is 10 seconds. If multiple ExternalMapperTimeout keywords are
specified for a Pki block, the first one is used. Works the same as in
the ssh2_config file, but DefaultDomain is not used. Works the same as
in the ssh2_config wfile, but DefaultDomain is not used. Similar to
PublicHostKeyFile, except that the file is assumed to contain an X.509
certificate in binary format. The keyword must be paired with a corre‐
sponding HostKeyFile option. (See sshd2_config(4).) If multiple cer‐
tificates with the same public key type (dss or rsa) are specified,
only the first one is used. Works the same as in the ssh2_config file.
Specifies a mapping file for the preceding Pki keyword. Multiple map‐
ping files are permitted for Pki keywords. The mapping file format is
described in the next section. Enables user authentication using cer‐
tificates. The ca-certificate must be an X.509 certificate in binary
format. This keyword must be followed by one or more MapFile keywords.
The validity of a received certificate is checked separately
using each of the defined Pki keywords in turn until they are
exhausted (in which case the authentication fails), or a posi‐
tive result is achieved. If the certificate is valid, the map‐
ping files are examined to determine whether the certificate
allows the user to log in. Correct signature generated by a
matching private key is always required. Disables CRL checking
for the preceding Pki keyword, if argument is y. By default,
CRL checking is y. Specifies the name of a socks server. Used
when fetching certificates or CRLs from remote servers.
When certificates are used in user authentication, one or more mapping
files determine whether the user can log in to an account with a cer‐
tificate. The mapping file must contain one or more lines in the fol‐
lowing format:
account-id keyword arguments
Keyword must be one of the following: Email, EmailRegex, Subject, Seri‐
alAndIssuer, or SubjectRegex.
Arguments are different for each keyword. The following list describes
each variation: An email address in standard format. If the certificate
contains the email address as an alternate name, it is good for logging
in as user account-id. A subject name in DN notation. If the name
matches the one in the certificate, the certificate is good for logging
in as user account-id. A number and an issuer name in domain name
notation. If the issuer name and serial number match those in the cer‐
tificate, the certificate is good for logging in as user account-id. A
regular expression (egrep syntax). If it matches an alternate name (of
type email-address) in the certificate, the certificate is good for
logging in as user account-id. As a special feature, if account-id con‐
tains a string, %subst%, it is replaced by the first parenthesized sub‐
string of the regular expression before comparing it with the account
the user is trying to log in. Works identically to EmailRegex, except
it matches the regular expression to the canonical subject name in the
received certificate. Empty lines and lines beginning with the pound
sign (#) are ignored.
MAPPING FILE EXAMPLE
guest email guest@domain.org guest subject C=FI, O=Company Ltd.,
CN=Guest User guest SerialAndIssuer 123 C=FI, O=Foo\, Ltd., CN=Test CA
%subst% EmailRegex ([a-z]+)@domain\.org %subst% SubjectRegex ^C=FI,
O=Company, CN=([a-z]+)$
The EmailRegex example allows users into the account that corresponds
to the user name part of the email address if the domain address is
domain.org and the user name contains only letters.
The example SubjectRegex lets in all users with fields C=FI and O=Com‐
pany in the subject name if their CN field contains only letters and is
the account name they are trying to log in to.
The carat (^) and dollar ($) symbols at the beginning and end of the
regular expression are required to prevent the regular expression from
matching anything less than the whole string (that is, subject name).
All characters interpreted by the regular expression parser as special
characters must be escaped with a backslash (\) if they are a part of
the subject name itself. This also means that the backslash in the
SerialAndIssuer example must be escaped with another backslash if the
same subject name was used in a SubjectRegex rule.
LEGAL NOTICES
SSH is a registered trademark of SSH Communication Security Ltd.
SEE ALSO
Commands: ssh2(1), sshd2(8)
Files: ssh2_config(4), sshd2_config(4)
Security Administration
ssh_certificates(4)
