'\" t
.\" Title: sss-certmap
.\" Author: The SSSD upstream - https://github.com/SSSD/sssd/
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 02/04/2024
.\" Manual: File Formats and Conventions
.\" Source: SSSD
.\" Language: English
.\"
.TH "SSS\-CERTMAP" "5" "02/04/2024" "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\&.
.PP
To allow extensions or completely different style of rule the
\(lqmapping\(rq
and
\(lqmatching rules\(rq
can contain a prefix separated with a \*(Aq:\*(Aq from the main part of the rule\&. The prefix may only contain upper\-case ASCII letters and numbers\&. If the prefix is omitted the default type will be used which is \*(AqKRB5\*(Aq for the matching rules and \*(AqLDAP\*(Aq for the mapping rules\&.
.PP
The \*(Aqsssctl\*(Aq utility provides the \*(Aqcert\-eval\-rule\*(Aq command to check if a given certificate matches a matching rules and how the output of a mapping rule would look like\&.
.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\&.
.PP
If multiple rules have the same priority and only one of the related matching rules applies, this rule will be chosen\&. If there are multiple rules with the same priority which matches, one is chosen but which one is undefined\&. To avoid this undefined behavior either use different priorities or make the matching rules more specific e\&.g\&. by using distinct patterns\&.
.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
Given the similarity to MIT Kerberos the type prefix for this rule is \*(AqKRB5\*(Aq\&. But \*(AqKRB5\*(Aq will also be the default for
\(lqmatching rules\(rq
so that "\&.*,DC=MY,DC=DOMAIN" and "KRB5:\&.*,DC=MY,DC=DOMAIN" are equivalent\&.
.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
.sp
Please note that the characters "^\&.[$()|*+?{\e" have a special meaning in regular expressions and must be escaped with the help of the \*(Aq\e\*(Aq character so that they are matched as ordinary characters\&.
.sp
Example: ^CN=\&.* \e(Admin\e),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 default
\(lqmapping rule\(rq
type is \*(AqLDAP\*(Aq which can be added as a prefix to a rule like e\&.g\&. \*(AqLDAP:(userCertificate;binary={cert!bin})\*(Aq\&. There is an extension called \*(AqLDAPU1\*(Aq which offer more templates for more flexibility\&. To allow older versions of this library to ignore the extension the prefix \*(AqLDAPU1\*(Aq must be used when using the new templates in a
\(lqmapping rule\(rq
otherwise the old version of this library will fail with a parsing error\&. The new templates are described in section
the section called \(lqLDAPU1 extension\(rq\&.
.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: (|(userPrincipalName={subject_nt_principal})(samAccountName={subject_nt_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
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBLDAPU1 extension\fR
.RS 4
.PP
The following template are available when using the \*(AqLDAPU1\*(Aq extension:
.PP
.PP
{serial_number[!(dec|hex[_ucr])]}
.RS 4
This template will add the serial number of the certificate\&. By default it will be printed as a hexadecimal number with lower\-case letters\&.
.sp
With the formatting option \*(Aq!dec\*(Aq the number will be printed as decimal string\&. The hexadecimal output can be printed with upper\-case letters (\*(Aq!hex_u\*(Aq), with a colon separating the hexadecimal bytes (\*(Aq!hex_c\*(Aq) or with the hexadecimal bytes in reverse order (\*(Aq!hex_r\*(Aq)\&. The postfix letters can be combined so that e\&.g\&. \*(Aq!hex_uc\*(Aq will produce a colon\-separated hexadecimal string with upper\-case letters\&.
.sp
Example: LDAPU1:(serial={serial_number})
.RE
.PP
{subject_key_id[!hex[_ucr]]}
.RS 4
This template will add the subject key id of the certificate\&. By default it will be printed as a hexadecimal number with lower\-case letters\&.
.sp
The hexadecimal output can be printed with upper\-case letters (\*(Aq!hex_u\*(Aq), with a colon separating the hexadecimal bytes (\*(Aq!hex_c\*(Aq) or with the hexadecimal bytes in reverse order (\*(Aq!hex_r\*(Aq)\&. The postfix letters can be combined so that e\&.g\&. \*(Aq!hex_uc\*(Aq will produce a colon\-separated hexadecimal string with upper\-case letters\&.
.sp
Example: LDAPU1:(ski={subject_key_id})
.RE
.PP
{cert[!DIGEST[_ucr]]}
.RS 4
This template will add the hexadecimal digest/hash of the certificate where DIGEST must be replaced with the name of a digest/hash function supported by OpenSSL, e\&.g\&. \*(Aqsha512\*(Aq\&.
.sp
The hexadecimal output can be printed with upper\-case letters (\*(Aq!sha512_u\*(Aq), with a colon separating the hexadecimal bytes (\*(Aq!sha512_c\*(Aq) or with the hexadecimal bytes in reverse order (\*(Aq!sha512_r\*(Aq)\&. The postfix letters can be combined so that e\&.g\&. \*(Aq!sha512_uc\*(Aq will produce a colon\-separated hexadecimal string with upper\-case letters\&.
.sp
Example: LDAPU1:(dgst={cert!sha256})
.RE
.PP
{subject_dn_component[(\&.attr_name|[number]]}
.RS 4
This template will add an attribute value of a component of the subject DN, by default the value of the most specific component\&.
.sp
A different component can it either selected by attribute name, e\&.g\&. {subject_dn_component\&.uid} or by position, e\&.g\&. {subject_dn_component\&.[2]} where positive numbers start counting from the most specific component and negative numbers start counting from the least specific component\&. Attribute name and the position can be combined as e\&.g\&. {subject_dn_component\&.uid[2]} which means that the name of the second component must be \*(Aquid\*(Aq\&.
.sp
Example: LDAPU1:(uid={subject_dn_component\&.uid})
.RE
.PP
{issuer_dn_component[(\&.attr_name|[number]]}
.RS 4
This template will add an attribute value of a component of the issuer DN, by default the value of the most specific component\&.
.sp
See \*(Aqsubject_dn_component\*(Aq for details about the attribute name and position specifiers\&.
.sp
Example: LDAPU1:(domain={issuer_dn_component\&.[\-2]}\&.{issuer_dn_component\&.dc[\-1]})
.RE
.PP
{sid[\&.rid]}
.RS 4
This template will add the SID if the corresponding extension introduced by Microsoft with the OID 1\&.3\&.6\&.1\&.4\&.1\&.311\&.25\&.2 is available\&. With the \*(Aq\&.rid\*(Aq selector only the last component, i\&.e\&. the RID, will be added\&.
.sp
Example: LDAPU1:(objectsid={sid})
.RE
.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://github\&.com/SSSD/sssd/\fR