ssh_certd_config

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=seconds]

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 download a CRL from the specified URL. The first argument 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 user names. If the user name the user is trying to log in as is found in the list, the authentication succeeds; otherwise 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

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 specified for a Pki block, the first one is used.

HostCA

The argument is of the format: ca-certificate[,use_expired_crls=seconds]

This keyword specifies 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 unavailable.

Caution

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

Note

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 distribution 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 preceding Pki keyword. Multiple mapping files are permitted per one Pki keyword. The mapping file format is described in the section called “Mapping Files”.

OCSPResponderURL

Specifies the OCSP (Online Certificate Status Protocol) Responder service address in URL format, in case OCSP should be used instead of CRLs and the certificate itself does not contain a valid Authority 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 certificate, it is tried first; only if it fails, traditional 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-certificate[,use_expired_crls=seconds]

This keyword enables user authentication using certificates. ca-certificate must be a path to a 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 (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 unavailable.

Caution

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.

Note

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

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 connection, authentication, and configuration problems. Also causes ssh-certd to not detach from the shell to the background.

WTORoutingCodes

Specifies the z/OS routing codes for WTO messages. Valid values for routing codes are from 1 to 128. The default is 1,11.

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 certificate, the certificate is good for logging in as user account-id.

SerialAndIssuer

Arguments: a number and an issuer name in DN notation (LDAP style), separated by a whitespace.

If the issuer name and serial number match those in the certificate, the certificate is good for logging in as user account-id.

If it matches an alternate name (of the type Email) 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 sub-string 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 regular 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.

The example EmailRegex permits in users with e-mail addresses with domain example.com and usernames that contain only letters, each user to the account that corresponds to the user name 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 SerialAndIssuer example would have to be escaped with another backslash if the same subject name was used in a SubjectRegex rule.