'\" 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