Index for Section 4

Alphabetical listing for S

Bottom of page

ssh_certificates(4)
NAME
  ssh_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.

  HostCA ca-certificate
	  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.

  HostCANoCRLs ca-certificate
	  Similar to HostCA, but disables Certificate Revolation List (CRL)
	  checking for the given ca-certificate.

  LdapServers ldap://server.domain-name:389
	  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.

  ExternalMapper filename
	  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.

  ExternalMapperTimeout seconds
	  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.

  HostCA ca-certificate
	  Works the same as in the ssh2_config file, but DefaultDomain is not
	  used.

  HostCANoCRLs ca-certificate
	  Works the same as in the ssh2_config wfile, but DefaultDomain is
	  not used.

  HostCertificateFile ca-certificate
	  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.

  LdapServers ldap://server.domain-name:389
	  Works the same as in the ssh2_config file.

  MapFile filename
	  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.

  Pki ca-certificate
	  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.

  PkiDisableCrls argument
	  Disables CRL checking for the preceding Pki keyword, if  argument
	  is y.	 By default, CRL checking is y.

  SocksServer socks_server_name
	  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:

  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
	  account-id.

  SerialAndIssuer
	  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.

  EmailRegex
	  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.

  SubjectRegex
	  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=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.

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

Index for Section 4

Alphabetical listing for S

Top of page