'\" t
.\" Title: sss-certmap
.\" Author: The SSSD upstream - https://pagure.io/SSSD/sssd/
.\" Generator: DocBook XSL Stylesheets v1.79.1
.\" Date: 02/21/2020
.\" Manual: File Formats and Conventions
.\" Source: SSSD
.\" Language: English
.\"
.TH "SSS\-CERTMAP" "5" "02/21/2020" "SSSD" "File Formats and Conventions"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sss-certmap \- SSSD Certificate Matching and Mapping Rules
.SH "DESCRIPTION"
.PP
The manual page describes the rules which can be used by SSSD and other components to match X\&.509 certificates and map them to accounts\&.
.PP
Each rule has four components, a
\(lqpriority\(rq, a
\(lqmatching rule\(rq, a
\(lqmapping rule\(rq
and a
\(lqdomain list\(rq\&. All components are optional\&. A missing
\(lqpriority\(rq
will add the rule with the lowest priority\&. The default
\(lqmatching rule\(rq
will match certificates with the digitalSignature key usage and clientAuth extended key usage\&. If the
\(lqmapping rule\(rq
is empty the certificates will be searched in the userCertificate attribute as DER encoded binary\&. If no domains are given only the local domain will be searched\&.
.SH "RULE COMPONENTS"
.SS "PRIORITY"
.PP
The rules are processed by priority while the number \*(Aq0\*(Aq (zero) indicates the highest priority\&. The higher the number the lower is the priority\&. A missing value indicates the lowest priority\&. The rules processing is stopped when a matched rule is found and no further rules are checked\&.
.PP
Internally the priority is treated as unsigned 32bit integer, using a priority value larger than 4294967295 will cause an error\&.
.SS "MATCHING RULE"
.PP
The matching rule is used to select a certificate to which the mapping rule should be applied\&. It uses a system similar to the one used by
\(lqpkinit_cert_match\(rq
option of MIT Kerberos\&. It consists of a keyword enclosed by \*(Aq<\*(Aq and \*(Aq>\*(Aq which identified a certain part of the certificate and a pattern which should be found for the rule to match\&. Multiple keyword pattern pairs can be either joined with \*(Aq&&\*(Aq (and) or \*(Aq||\*(Aq (or)\&.
.PP
The available options are:
.PP
regular\-expression
.RS 4
With this a part or the whole subject name of the certificate can be matched\&. For the matching POSIX Extended Regular Expression syntax is used, see regex(7) for details\&.
.sp
For the matching the subject name stored in the certificate in DER encoded ASN\&.1 is converted into a string according to RFC 4514\&. This means the most specific name component comes first\&. Please note that not all possible attribute names are covered by RFC 4514\&. The names included are \*(AqCN\*(Aq, \*(AqL\*(Aq, \*(AqST\*(Aq, \*(AqO\*(Aq, \*(AqOU\*(Aq, \*(AqC\*(Aq, \*(AqSTREET\*(Aq, \*(AqDC\*(Aq and \*(AqUID\*(Aq\&. Other attribute names might be shown differently on different platform and by different tools\&. To avoid confusion those attribute names are best not used or covered by a suitable regular\-expression\&.
.sp
Example: \&.*,DC=MY,DC=DOMAIN
.RE
.PP
regular\-expression
.RS 4
With this a part or the whole issuer name of the certificate can be matched\&. All comments for apply her as well\&.
.sp
Example: ^CN=My\-CA,DC=MY,DC=DOMAIN$
.RE
.PP
key\-usage
.RS 4
This option can be used to specify which key usage values the certificate should have\&. The following values can be used in a comma separated list:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
digitalSignature
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
nonRepudiation
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
keyEncipherment
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
dataEncipherment
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
keyAgreement
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
keyCertSign
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cRLSign
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
encipherOnly
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
decipherOnly
.RE
.sp
A numerical value in the range of a 32bit unsigned integer can be used as well to cover special use cases\&.
.sp
Example: digitalSignature,keyEncipherment
.RE
.PP
extended\-key\-usage
.RS 4
This option can be used to specify which extended key usage the certificate should have\&. The following value can be used in a comma separated list:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
serverAuth
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
clientAuth
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
codeSigning
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
emailProtection
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
timeStamping
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
OCSPSigning
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
KPClientAuth
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
pkinit
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
msScLogin
.RE
.sp
Extended key usages which are not listed above can be specified with their OID in dotted\-decimal notation\&.
.sp
Example: clientAuth,1\&.3\&.6\&.1\&.5\&.2\&.3\&.4
.RE
.PP
regular\-expression
.RS 4
To be compatible with the usage of MIT Kerberos this option will match the Kerberos principals in the PKINIT or AD NT Principal SAN as does\&.
.sp
Example: \&.*@MY\e\&.REALM
.RE
.PP
regular\-expression
.RS 4
Match the Kerberos principals in the PKINIT or AD NT Principal SAN\&.
.sp
Example: \&.*@MY\e\&.REALM
.RE
.PP
regular\-expression
.RS 4
Match the Kerberos principals from the AD NT Principal SAN\&.
.sp
Example: \&.*@MY\&.AD\&.REALM
.RE
.PP
regular\-expression
.RS 4
Match the Kerberos principals from the PKINIT SAN\&.
.sp
Example: \&.*@MY\e\&.PKINIT\e\&.REALM
.RE
.PP
regular\-expression
.RS 4
Take the value of the otherName SAN component given by the OID in dotted\-decimal notation, interpret it as string and try to match it against the regular expression\&.
.sp
Example: test
.RE
.PP
base64\-string
.RS 4
Do a binary match with the base64 encoded blob against all otherName SAN components\&. With this option it is possible to match against custom otherName components with special encodings which could not be treated as strings\&.
.sp
Example: MTIz
.RE
.PP
regular\-expression
.RS 4
Match the value of the rfc822Name SAN\&.
.sp
Example: \&.*@email\e\&.domain
.RE
.PP
regular\-expression
.RS 4
Match the value of the dNSName SAN\&.
.sp
Example: \&.*\e\&.my\e\&.dns\e\&.domain
.RE
.PP
base64\-string
.RS 4
Binary match the value of the x400Address SAN\&.
.sp
Example: MTIz
.RE
.PP
regular\-expression
.RS 4
Match the value of the directoryName SAN\&. The same comments as given for and apply here as well\&.
.sp
Example: \&.*,DC=com
.RE
.PP
base64\-string
.RS 4
Binary match the value of the ediPartyName SAN\&.
.sp
Example: MTIz
.RE
.PP
regular\-expression
.RS 4
Match the value of the uniformResourceIdentifier SAN\&.
.sp
Example: URN:\&.*
.RE
.PP
regular\-expression
.RS 4
Match the value of the iPAddress SAN\&.
.sp
Example: 192\e\&.168\e\&.\&.*
.RE
.PP
regular\-expression
.RS 4
Match the value of the registeredID SAN as dotted\-decimal string\&.
.sp
Example: 1\e\&.2\e\&.3\e\&.\&.*
.RE
.SS "MAPPING RULE"
.PP
The mapping rule is used to associate a certificate with one or more accounts\&. A Smartcard with the certificate and the matching private key can then be used to authenticate as one of those accounts\&.
.PP
Currently SSSD basically only supports LDAP to lookup user information (the exception is the proxy provider which is not of relevance here)\&. Because of this the mapping rule is based on LDAP search filter syntax with templates to add certificate content to the filter\&. It is expected that the filter will only contain the specific data needed for the mapping and that the caller will embed it in another filter to do the actual search\&. Because of this the filter string should start and stop with \*(Aq(\*(Aq and \*(Aq)\*(Aq respectively\&.
.PP
In general it is recommended to use attributes from the certificate and add them to special attributes to the LDAP user object\&. E\&.g\&. the \*(AqaltSecurityIdentities\*(Aq attribute in AD or the \*(AqipaCertMapData\*(Aq attribute for IPA can be used\&.
.PP
This should be preferred to read user specific data from the certificate like e\&.g\&. an email address and search for it in the LDAP server\&. The reason is that the user specific data in LDAP might change for various reasons would break the mapping\&. On the other hand it would be hard to break the mapping on purpose for a specific user\&.
.PP
The templates to add certificate data to the search filter are based on Python\-style formatting strings\&. They consist of a keyword in curly braces with an optional sub\-component specifier separated by a \*(Aq\&.\*(Aq or an optional conversion/formatting option separated by a \*(Aq!\*(Aq\&. Allowed values are:
.PP
{issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
.RS 4
This template will add the full issuer DN converted to a string according to RFC 4514\&. If X\&.500 ordering (most specific RDN comes last) an option with the \*(Aq_x500\*(Aq prefix should be used\&.
.sp
The conversion options starting with \*(Aqad_\*(Aq will use attribute names as used by AD, e\&.g\&. \*(AqS\*(Aq instead of \*(AqST\*(Aq\&.
.sp
The conversion options starting with \*(Aqnss_\*(Aq will use attribute names as used by NSS\&.
.sp
The default conversion option is \*(Aqnss\*(Aq, i\&.e\&. attribute names according to NSS and LDAP/RFC 4514 ordering\&.
.sp
Example: (ipacertmapdata=X509:{issuer_dn!ad}{subject_dn!ad})
.RE
.PP
{subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
.RS 4
This template will add the full subject DN converted to string according to RFC 4514\&. If X\&.500 ordering (most specific RDN comes last) an option with the \*(Aq_x500\*(Aq prefix should be used\&.
.sp
The conversion options starting with \*(Aqad_\*(Aq will use attribute names as used by AD, e\&.g\&. \*(AqS\*(Aq instead of \*(AqST\*(Aq\&.
.sp
The conversion options starting with \*(Aqnss_\*(Aq will use attribute names as used by NSS\&.
.sp
The default conversion option is \*(Aqnss\*(Aq, i\&.e\&. attribute names according to NSS and LDAP/RFC 4514 ordering\&.
.sp
Example: (ipacertmapdata=X509:{issuer_dn!nss_x500}{subject_dn!nss_x500})
.RE
.PP
{cert[!(bin|base64)]}
.RS 4
This template will add the whole DER encoded certificate as a string to the search filter\&. Depending on the conversion option the binary certificate is either converted to an escaped hex sequence \*(Aq\exx\*(Aq or base64\&. The escaped hex sequence is the default and can e\&.g\&. be used with the LDAP attribute \*(AquserCertificate;binary\*(Aq\&.
.sp
Example: (userCertificate;binary={cert!bin})
.RE
.PP
{subject_principal[\&.short_name]}
.RS 4
This template will add the Kerberos principal which is taken either from the SAN used by pkinit or the one used by AD\&. The \*(Aqshort_name\*(Aq component represents the first part of the principal before the \*(Aq@\*(Aq sign\&.
.sp
Example: (|(userPrincipal={subject_principal})(samAccountName={subject_principal\&.short_name}))
.RE
.PP
{subject_pkinit_principal[\&.short_name]}
.RS 4
This template will add the Kerberos principal which is given by the SAN used by pkinit\&. The \*(Aqshort_name\*(Aq component represents the first part of the principal before the \*(Aq@\*(Aq sign\&.
.sp
Example: (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal\&.short_name}))
.RE
.PP
{subject_nt_principal[\&.short_name]}
.RS 4
This template will add the Kerberos principal which is given by the SAN used by AD\&. The \*(Aqshort_name\*(Aq component represent the first part of the principal before the \*(Aq@\*(Aq sign\&.
.sp
Example: (|(userPrincipal={subject_principal})(samAccountName={subject_principal\&.short_name}))
.RE
.PP
{subject_rfc822_name[\&.short_name]}
.RS 4
This template will add the string which is stored in the rfc822Name component of the SAN, typically an email address\&. The \*(Aqshort_name\*(Aq component represents the first part of the address before the \*(Aq@\*(Aq sign\&.
.sp
Example: (|(mail={subject_rfc822_name})(uid={subject_rfc822_name\&.short_name}))
.RE
.PP
{subject_dns_name[\&.short_name]}
.RS 4
This template will add the string which is stored in the dNSName component of the SAN, typically a fully\-qualified host name\&. The \*(Aqshort_name\*(Aq component represents the first part of the name before the first \*(Aq\&.\*(Aq sign\&.
.sp
Example: (|(fqdn={subject_dns_name})(host={subject_dns_name\&.short_name}))
.RE
.PP
{subject_uri}
.RS 4
This template will add the string which is stored in the uniformResourceIdentifier component of the SAN\&.
.sp
Example: (uri={subject_uri})
.RE
.PP
{subject_ip_address}
.RS 4
This template will add the string which is stored in the iPAddress component of the SAN\&.
.sp
Example: (ip={subject_ip_address})
.RE
.PP
{subject_x400_address}
.RS 4
This template will add the value which is stored in the x400Address component of the SAN as escaped hex sequence\&.
.sp
Example: (attr:binary={subject_x400_address})
.RE
.PP
{subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
.RS 4
This template will add the DN string of the value which is stored in the directoryName component of the SAN\&.
.sp
Example: (orig_dn={subject_directory_name})
.RE
.PP
{subject_ediparty_name}
.RS 4
This template will add the value which is stored in the ediPartyName component of the SAN as escaped hex sequence\&.
.sp
Example: (attr:binary={subject_ediparty_name})
.RE
.PP
{subject_registered_id}
.RS 4
This template will add the OID which is stored in the registeredID component of the SAN as a dotted\-decimal string\&.
.sp
Example: (oid={subject_registered_id})
.RE
.SS "DOMAIN LIST"
.PP
If the domain list is not empty users mapped to a given certificate are not only searched in the local domain but in the listed domains as well as long as they are know by SSSD\&. Domains not know to SSSD will be ignored\&.
.SH "AUTHORS"
.PP
\fBThe SSSD upstream \- https://pagure\&.io/SSSD/sssd/\fR