SSH

ssh_certd_config

SSH_CERTD_CONFIG(5)            SSH2           SSH_CERTD_CONFIG(5)


NAME
       ssh_certd_config - configuration file format for ssh-certd
       on z/OS


CONFIGURATION FILE
       ssh-certd     reads      configuration      data      from
       /opt/tectia/etc/ssh_certd_config  (or the  file  specified 
       with -f on the command line).  The file contains  keyword-
       value pairs, one  per  line.  For  a  description  of  the 
       configuration file format, see sshd2_config(5).

       The following keywords are allowed:


       CertCacheFile
              This  keyword  specifies the name of the file where
              the certificates and CRLs are cached when ssh-certd
              goes down.


       Cert.DODPKI
              If  set to yes, the certificates are required to be
              DoD PKI compliant.  The argument must be yes or no.
              The default is no.


       CrlAutoUpdate
              The      argument     is     of     the     format:
              {yes,no}[,update_before=seconds][,min_interval=sec-
              onds]  This  keyword  turns  on the CRL auto-update
              feature. When  it  is  on,  ssh-certd  periodically
              tries  to  download  the new CRL before the old one
              has expired. The  update_before  keyword  specifies
              how  many  seconds before the expiration the update
              takes place. The min_interval sets a limit for  the
              maximum  update frequency (default minimum interval
              is 30 seconds).


       CrlPrefetch
              The argument is of the  format:  seconds  url  This
              keyword  instructs  ssh-certd to periodically down-
              load a CRL from the specified url. The first  argu-
              ment specifies how often the CRL is downloaded.


       ExternalMapper
              This  keyword  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 username the
              user is trying to log in as is found in  the  list,
              the  authentication succeeds; otherwise authentica-
              tion 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
              This keyword specifies an external  mapper  timeout
              (in  seconds) 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  speci-
              fied for a Pki block, the first one is used.


       HostCA The   argument   is   of  the  format:  ca-certifi-
              cate[,use_expired_crls=seconds] This keyword speci-
              fies the CA certificate (in binary or PEM (base-64)
              format) to be used when authenticating users  using
              host-based    authentication.     The   certificate
              received from the client  must  be  issued  by  the
              specified  CA  and must contain a correct alternate
              name of type DNS (FQDN). 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, but only one per HostCA keyword.

              If   the   additional    comma-separated    keyword
              use_expired_crls  is  given,  expired  CRLs will be
              allowed for this  CA  for  the  specified  duration
              after  the  expiration,  if newer CRLs are unavail-
              able. WARNING:  This  feature  allows  a  malicious
              party  to force the use of expired CRLs if the said
              party  can  perform  a   denial-of-service   attack
              against the CRL distribution point.


       HostCAEkProvider
              Specifies  the  external key provider for accessing
              CA certificates that are trusted for authenticating
              users  using  host-based authentication.  The value
              is of the format "provider:initstring".  Currently,
              the  only  valid value for provider on z/OS is zos-
              saf. For the format of  the  initstring,  see  ssh-
              externalkeys(5).


       HostCAEkProviderNoCRLs
              This  keyword  is  similar to HostCAEkProvider, but
              disables  CRL  checking  for  the  CA  certificates
              defined   by  "provider:initstring".   This  option
              should be used for testing purposes only.  In  nor-
              mal  operations, it is highly recommended to always
              use CRLs.


       HostCANoCRLs
              This keyword is similar to HostCA, but disables CRL
              checking for the given ca-certificate.  This option
              should be used for testing purposes only. In normal
              operations,  it is highly recommended to always use
              CRLs.


       LdapServers
              CRLs are automatically retrieved from the CRL  dis-
              tribution  point  defined  in the certificate to be
              checked if the point exists.  Otherwise the  comma-
              separated  server  list given by option LdapServers
              is  used.   If  intermediate  CA  certificates  are
              needed   in  certificate  validity  checking,  this
              option must be used or retrieving the  certificates
              will fail.


       MapFile
              This  keyword specifies a mapping file for the pre-
              ceding Pki keyword.   Multiple  mapping  files  are
              permitted  per  one  Pki keyword.  The mapping file
              format is described in section MAPPING FILES.


       OCSPResponderURL
              Specifies the OCSP (Online Certificate Status  Pro-
              tocol)  Responder service address in URL format, in
              case OCSP should be used instead of  CRLs  and  the
              certificate itself does not contain a valid Author-
              ity Info Access extension with  an  OCSP  Responder
              URL.  Note that for the OCSP validation to succeed,
              both  the  end-entity  certificate  and  the   OCSP
              Responder  certificate  must  be issued by the same
              CA.

              If OCSP responder is defined globally or in a  cer-
              tificate, it is tried first; only if it fails, tra-
              ditional CRL checking is tried, and if that  fails,
              the certificate validation returns a failure.


       PidFile
              Specifies  the  file  where  the process ID of ssh-
              certd is written.  The default  is
              /opt/tectia/var/run/ssh-certd-listener.pid.


       Pki    The   argument   is   of  the  format:  ca-certifi-
              cate[,use_expired_crls=seconds]    This     keyword
              enables  user  authentication  using  certificates.
              ca-certificate must be a path to a  X.509  certifi-
              cate  in  binary  format. This keyword must be fol-
              lowed 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 cer-
              tificate allows the user to log in (of course,  the
              correct  signature  generated by a matching private
              key is always required in  addition  to  everything
              else).

              If    the    additional   comma-separated   keyword
              use_expired_crls is given,  expired  CRLs  will  be
              allowed  for  this  CA  for  the specified duration
              after the expiration, if newer  CRLs  are  unavail-
              able.  WARNING:  This  feature  allows  a malicious
              party to force the use of expired CRLs if the  said
              party   can   perform  a  denial-of-service  attack
              against the CRL distribution point.


       PkiDisableCrls
              If set to yes, this keyword disables  CRL  checking
              for the preceding Pki or PkiEkProvider keyword. The
              argument must be yes or no.  The default is no (CRL
              checking is on).

              Note  that  this disables only the CRL checking and
              only for the specific CA certificate in the Pki  or
              PkiEkProvider  parameter.   OCSP  checking is still
              done, but the result does  not  matter,  since  the
              fallback,  the  CRL,  is implicitly valid when this
              option is active. This option should  be  used  for
              testing  purposes only. In normal operations, it is
              highly recommended to always use CRLs.


       PkiEkProvider
              This keyword can be used in place of the  Pki  key-
              word  if the trusted CA keys are accessed from SAF.
              The value is of the  format  "provider:initstring".
              Currently,  the  only  valid  value for provider is
              zos-saf. For the format of the initstring, see ssh-
              externalkeys(5).


       QuietMode
              Nothing  is  logged in the system log, except fatal
              errors.  The argument  must  be  yes  or  no.   The
              default is no.


       RandomSeedFile
              Specifies the name of the random seed file.


       SocksServer
              With  this  option,  ssh-certd  can use a SOCKS4 or
              SOCKS5 server to connect to an LDAP server  outside
              a firewall when making CRL queries. You can specify
              whether to use SOCKS5 with the option UseSocks5.

              The   argument   syntax   is   described   in   the  
              sshd2_config(5)  man  page.


       SysLogFacility
              Gives the facility code that is used  when  logging
              messages  from ssh-certd.  The possible values are:
              DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2, LOCAL3,
              LOCAL4,  LOCAL5,  LOCAL6,  LOCAL7.   The default is
              AUTH.


       UseSocks5
              Uses SOCKS5 instead of SOCKS4 when connecting to  a
              remote  host. Note that you have to set SocksServer
              to a meaningful value.  The argument must be yes or
              no.  The default is no (i.e. use SOCKS4).


       UseSSHD2ConfigFile
              Instructs  ssh-certd  to read another configuration
              file in compatibility mode (the sshd2 configuration
              options are allowed, but ignored).


       VerboseMode
              Causes  ssh-certd to print debugging messages about
              its progress.  This is helpful in debugging connec-
              tion,  authentication,  and configuration problems.
              Also causes ssh-certd to not detach from the  shell
              to the background.


MAPPING FILES
       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  arguments: an e-mail address in standard format. If
              the  certificate  contains the e-mail address as an
              alternate name, it is good for logging in  as  user
              account-id.


       Subject
              arguments:  a  subject  name  in  DN notation (LDAP
              style). If the name matches the one in the certifi-
              cate,  the  certificate  is  good for logging in as
              user account-id.


       SerialAndIssuer
              arguments:  a number and an issuer name in DN nota-
              tion  (LDAP  style),  separated by a whitespace. If
              the issuer name and serial number  match  those  in
              the  certificate,  the certificate is good for log-
              ging in as user account-id.


       EmailRegex
              arguments:  a  regular  expression  (SSH_REGEX_SYN-
              TAX_SSH,  see  the  sshregex(1)  man  page).  If it
              matches an alternate name (of the  type  Email)  in
              the  certificate,  the certificate is good for log-
              ging 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 into.

              Note that by default, the whole  email  address  or
              subject name does not need to be matched. The regu-
              lar expression needs only to match to some part  of
              the  string  to  be matched. If the whole string is
              required to match, the  regular  expression  should
              start  with $ and end with ^, these match the start
              of the line and the end of the line,  respectively.


       SubjectRegex
              Works  identically  to  EmailRegex,  except that it
              matches the regular  expression  to  the  canonical
              subject name in the received certificate.


       Empty lines and lines beginning with '#' are ignored.


       EXAMPLE MAPPING FILE

              guest Email guest@ssh.com
              guest Subject C=FI, O=Example Ltd., CN=Guest User
              guest SerialAndIssuer 123 C=FI, O=Foo\, Ltd., 
                  CN=Test CA
              %subst% EmailRegex ([a-z]+)@example\.com
              %subst% SubjectRegex C=FI, O=Example, CN=([a-z]+)


       The  example  EmailRegex  permits  in  users  with  e-mail
       addresses with domain example.com and usernames that  con-
       tain  only  letters,  each user to the account that corre-
       sponds to the username part of the e-mail address.

       The example SubjectRegex lets in  all  users  with  fields
       C=FI  and  O=Example in the subject name if their CN field
       contains only letters and is the  account  name  they  are
       trying to log into.

       Note  also  that 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  Seri-
       alAndIssuer  example would have to be escaped with another
       backslash if the same subject name was used in  a  Subjec-
       tRegex rule.


AUTHORS
       SSH Communications Security Corporation

       For more information, see http://www.ssh.com.


SEE ALSO
       ssh-certd(8), sshd2_config(5), sshregex(1)