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