[Contents] [Index]

About This Document >>     Installing SSH Tectia Server for IBM z/OS >>     Using SSH Tectia Server for IBM z/OS >>     Configuring the Server >>     Configuring the Client >>     Authentication >>     Troubleshooting SSH Tectia Server for IBM z/OS >>     Examples of Use >>     Man Pages >>         scp2         sftp2         ssh-add2         ssh-agent2         ssh-certd         ssh_certd_config         ssh-certview >>         ssh-cmpclient >>         ssh-dummy-shell         ssh-ekview         ssh-externalkeys         ssh-keygen2         ssh-probe2         ssh-scepclient >>         ssh-sft-stage         ssh2         ssh2_config         sshd-check-conf         sshd2         sshd2_config         sshd2_subconfig         sshregex     Log Messages >>

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 /etc/ssh2/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 configura- tion file format, see ssh2_config(5). However, configura- tion blocks are not allowed in sshd_certd_config. 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. 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 ssh2_con- fig(5) man page. (Note, however, that ssh-certd does not use the SSH_SOCKS_SERVER environment vari- able, it only uses the configuration option (and the ./configure time --with-socks-server option). 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=Company Ltd., CN=Guest User guest SerialAndIssuer 123 C=FI, O=Foo\, Ltd., CN=Test CA %subst% EmailRegex ([a-z]+)@ssh\.com %subst% SubjectRegex C=FI, O=Company, CN=([a-z]+) The example EmailRegex permits in users with e-mail addresses with domain ssh.com and usernames that contain only letters, each user to the account that corresponds to the username part of the e-mail address. 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 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 Corp. For more information, see http://www.ssh.com. SEE ALSO ssh-certd(8), sshregex(1)