unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



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

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

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

  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	exam-
	  ined 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 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
  format:

  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
  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 certifi-
	  cate 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 certifi-
	  cate.	 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 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.

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