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 configura-
tion 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 sect1ion 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_con-
fig(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
Tectia Corporation
For more information, see http://www.tectia.com.
SEE ALSO
ssh-certd(8), sshd2_config(5), sshregex(1)
2011 Tectia Corporation