ssh_certificates - Describes the configuration files and keywords needed
when using certificates with the Secure Shell software
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
Specifies the Certificate Authority (CA) certificate (in binary or
PEM [base64] format) to be used when authenticating remote hosts.
The certificate received from the host must be issued by the speci-
fied CA and must contain an alternate, fully qualified domain name.
If the remote host name is not fully qualified, the domain speci-
fied by the DefaultDomain configuration option is appended to it
before comparing it to certificate alternate names. If no CA cer-
tificates are specified in the configuration file, the protocol
tries to do key exchange with ordinary public keys. Otherwise cer-
tificates are preferred. Multiple CAs are permitted.
Similar to HostCA, but disables Certificate Revolation List (CRL)
checking for the given ca-certificate.
CRLs are automatically retrieved from the CRL distribution point
defined in the certificate to be checked if the point exists. Oth-
erwise, the comma-separated server list given by the LdapServers
keyword is used. If intermediate 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
Specifies an external mapper program for the preceding Pki keyword.
When a certificate is received and is valid under the Pki block in
question, the external mapper is executed and the certificate 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
authentication using the certificate in question fails. The Exter-
nalMapper keyword will override all MapFile keywords for the
current (preceding) Pki keyword. If multiple ExternalMapper key-
words 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 exter-
nal 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
Works the same as in the ssh2_config wfile, but DefaultDomain is
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 corresponding HostKeyFile option. (See
sshd2_config(4).) If multiple certificates 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
mapping files are permitted for Pki keywords. The mapping file
format is described in the next section.
Enables user authentication using certificates. 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 positive result is
achieved. If the certificate is valid, the mapping files are exam-
ined to determine whether the certificate allows the user to log
in. Correct signature generated by a matching private key is always
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 certifi-
cates 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 certifi-
cate. The mapping file must contain one or more lines in the following
account-id keyword arguments
Keyword must be one of the following: Email, EmailRegex, Subject, SerialAn-
dIssuer, or SubjectRegex.
Arguments are different for each keyword. The following list describes each
Email 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.
Subject A subject name in DN notation. If the name matches the one in the
certificate, the certificate is good for logging in as user
A number and an issuer name in domain name notation. If the issuer
name and serial number match those in the certificate, the certifi-
cate 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 contains a string, %subst%, it is replaced by the first
parenthesized substring 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 certifi-
cate. Empty lines and lines beginning with the pound sign (#) are
MAPPING FILE EXAMPLE
guest email email@example.com
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=Company
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 regu-
lar expression are required to prevent the regular expression from matching
anything less than the whole string (that is, subject name). All charac-
ters 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.
SSH is a registered trademark of SSH Communication Security Ltd.
Commands: ssh2(1), sshd2(8)
Files: ssh2_config(4), sshd2_config(4)