|
|
ssh_certificates(4)
Contents
|
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 keywords.
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 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 DefaultDomain 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
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. Otherwise, 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 keywords. 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 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 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 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 certificate. The mapping file must
contain one or more lines in the following format:
account-id keyword arguments
Keyword must be one of the following: Email, EmailRegex,
Subject, SerialAndIssuer, 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 certificate, 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 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 certificate.
Empty lines and lines beginning with the pound
sign (#) are ignored.
MAPPING FILE EXAMPLE [Toc] [Back]
guest email [email protected] guest subject C=FI, O=Company
Ltd., CN=Guest User guest SerialAndIssuer 123 C=FI,
O=Foo\, Ltd., CN=Test CA %subst% EmailRegex ([az]+)@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 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.
SSH is a registered trademark of SSH Communication Security
Ltd.
Commands: ssh2(1), sshd2(8)
Files: ssh2_config(4), sshd2_config(4)
Security Administration
ssh_certificates(4)
[ Back ] |
