1SSS-CERTMAP(5) File Formats and Conventions SSS-CERTMAP(5)
2
6 sss-certmap - SSSD Certificate Matching and Mapping Rules
7
9 The manual page describes the rules which can be used by SSSD and other
10 components to match X.509 certificates and map them to accounts.
11 Each rule has four components, a “priority”, a “matching rule”, a
13 “mapping rule” and a “domain list”. All components are optional. A
14 missing “priority” will add the rule with the lowest priority. The
15 default “matching rule” will match certificates with the
16 digitalSignature key usage and clientAuth extended key usage. If the
17 “mapping rule” is empty the certificates will be searched in the
18 userCertificate attribute as DER encoded binary. If no domains are
19 given only the local domain will be searched.
20
22 PRIORITY
23 The rules are processed by priority while the number '0' (zero)
24 indicates the highest priority. The higher the number the lower is the
25 priority. A missing value indicates the lowest priority. The rules
26 processing is stopped when a matched rule is found and no further rules
27 are checked.
28 Internally the priority is treated as unsigned 32bit integer, using a
30 priority value larger than 4294967295 will cause an error.
31 MATCHING RULE
33 The matching rule is used to select a certificate to which the mapping
34 rule should be applied. It uses a system similar to the one used by
35 “pkinit_cert_match” option of MIT Kerberos. It consists of a keyword
36 enclosed by '<' and '>' which identified a certain part of the
37 certificate and a pattern which should be found for the rule to match.
38 Multiple keyword pattern pairs can be either joined with '&&' (and) or
39 '||' (or).
40 The available options are:
42 <SUBJECT>regular-expression
44 With this a part or the whole subject name of the certificate can
45 be matched. For the matching POSIX Extended Regular Expression
46 syntax is used, see regex(7) for details.
47 For the matching the subject name stored in the certificate in DER
49 encoded ASN.1 is converted into a string according to RFC 4514.
50 This means the most specific name component comes first. Please
51 note that not all possible attribute names are covered by RFC 4514.
52 The names included are 'CN', 'L', 'ST', 'O', 'OU', 'C', 'STREET',
53 'DC' and 'UID'. Other attribute names might be shown differently on
54 different platform and by different tools. To avoid confusion those
55 attribute names are best not used or covered by a suitable
56 regular-expression.
57 Example: <SUBJECT>.*,DC=MY,DC=DOMAIN
59 <ISSUER>regular-expression
61 With this a part or the whole issuer name of the certificate can be
62 matched. All comments for <SUBJECT> apply her as well.
63 Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
65 <KU>key-usage
67 This option can be used to specify which key usage values the
68 certificate should have. The following values can be used in a
69 comma separated list:
70 · digitalSignature
72 · nonRepudiation
74 · keyEncipherment
76 · dataEncipherment
78 · keyAgreement
80 · keyCertSign
82 · cRLSign
84 · encipherOnly
86 · decipherOnly
88 A numerical value in the range of a 32bit unsigned integer can be
90 used as well to cover special use cases.
91 Example: <KU>digitalSignature,keyEncipherment
93 <EKU>extended-key-usage
95 This option can be used to specify which extended key usage the
96 certificate should have. The following value can be used in a comma
97 separated list:
98 · serverAuth
100 · clientAuth
102 · codeSigning
104 · emailProtection
106 · timeStamping
108 · OCSPSigning
110 · KPClientAuth
112 · pkinit
114 · msScLogin
116 Extended key usages which are not listed above can be specified
118 with their OID in dotted-decimal notation.
119 Example: <EKU>clientAuth,1.3.6.1.5.2.3.4
121 <SAN>regular-expression
123 To be compatible with the usage of MIT Kerberos this option will
124 match the Kerberos principals in the PKINIT or AD NT Principal SAN
125 as <SAN:Principal> does.
126 Example: <SAN>.*@MY\.REALM
128 <SAN:Principal>regular-expression
130 Match the Kerberos principals in the PKINIT or AD NT Principal SAN.
131 Example: <SAN:Principal>.*@MY\.REALM
133 <SAN:ntPrincipalName>regular-expression
135 Match the Kerberos principals from the AD NT Principal SAN.
136 Example: <SAN:ntPrincipalName>.*@MY.AD.REALM
138 <SAN:pkinit>regular-expression
140 Match the Kerberos principals from the PKINIT SAN.
141 Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM
143 <SAN:dotted-decimal-oid>regular-expression
145 Take the value of the otherName SAN component given by the OID in
146 dotted-decimal notation, interpret it as string and try to match it
147 against the regular expression.
148 Example: <SAN:1.2.3.4>test
150 <SAN:otherName>base64-string
152 Do a binary match with the base64 encoded blob against all
153 otherName SAN components. With this option it is possible to match
154 against custom otherName components with special encodings which
155 could not be treated as strings.
156 Example: <SAN:otherName>MTIz
158 <SAN:rfc822Name>regular-expression
160 Match the value of the rfc822Name SAN.
161 Example: <SAN:rfc822Name>.*@email\.domain
163 <SAN:dNSName>regular-expression
165 Match the value of the dNSName SAN.
166 Example: <SAN:dNSName>.*\.my\.dns\.domain
168 <SAN:x400Address>base64-string
170 Binary match the value of the x400Address SAN.
171 Example: <SAN:x400Address>MTIz
173 <SAN:directoryName>regular-expression
175 Match the value of the directoryName SAN. The same comments as
176 given for <ISSUER> and <SUBJECT> apply here as well.
177 Example: <SAN:directoryName>.*,DC=com
179 <SAN:ediPartyName>base64-string
181 Binary match the value of the ediPartyName SAN.
182 Example: <SAN:ediPartyName>MTIz
184 <SAN:uniformResourceIdentifier>regular-expression
186 Match the value of the uniformResourceIdentifier SAN.
187 Example: <SAN:uniformResourceIdentifier>URN:.*
189 <SAN:iPAddress>regular-expression
191 Match the value of the iPAddress SAN.
192 Example: <SAN:iPAddress>192\.168\..*
194 <SAN:registeredID>regular-expression
196 Match the value of the registeredID SAN as dotted-decimal string.
197 Example: <SAN:registeredID>1\.2\.3\..*
199 MAPPING RULE
201 The mapping rule is used to associate a certificate with one or more
202 accounts. A Smartcard with the certificate and the matching private key
203 can then be used to authenticate as one of those accounts.
204 Currently SSSD basically only supports LDAP to lookup user information
206 (the exception is the proxy provider which is not of relevance here).
207 Because of this the mapping rule is based on LDAP search filter syntax
208 with templates to add certificate content to the filter. It is expected
209 that the filter will only contain the specific data needed for the
210 mapping and that the caller will embed it in another filter to do the
211 actual search. Because of this the filter string should start and stop
212 with '(' and ')' respectively.
213 In general it is recommended to use attributes from the certificate and
215 add them to special attributes to the LDAP user object. E.g. the
216 'altSecurityIdentities' attribute in AD or the 'ipaCertMapData'
217 attribute for IPA can be used.
218 This should be preferred to read user specific data from the
220 certificate like e.g. an email address and search for it in the LDAP
221 server. The reason is that the user specific data in LDAP might change
222 for various reasons would break the mapping. On the other hand it would
223 be hard to break the mapping on purpose for a specific user.
224 The templates to add certificate data to the search filter are based on
226 Python-style formatting strings. They consist of a keyword in curly
227 braces with an optional sub-component specifier separated by a '.' or
228 an optional conversion/formatting option separated by a '!'. Allowed
229 values are:
230 {issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
232 This template will add the full issuer DN converted to a string
233 according to RFC 4514. If X.500 ordering (most specific RDN comes
234 last) an option with the '_x500' prefix should be used.
235 The conversion options starting with 'ad_' will use attribute names
237 as used by AD, e.g. 'S' instead of 'ST'.
238 The conversion options starting with 'nss_' will use attribute
240 names as used by NSS.
241 The default conversion option is 'nss', i.e. attribute names
243 according to NSS and LDAP/RFC 4514 ordering.
244 Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})
246 {subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
248 This template will add the full subject DN converted to string
249 according to RFC 4514. If X.500 ordering (most specific RDN comes
250 last) an option with the '_x500' prefix should be used.
251 The conversion options starting with 'ad_' will use attribute names
253 as used by AD, e.g. 'S' instead of 'ST'.
254 The conversion options starting with 'nss_' will use attribute
256 names as used by NSS.
257 The default conversion option is 'nss', i.e. attribute names
259 according to NSS and LDAP/RFC 4514 ordering.
260 Example:
262 (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
263 {cert[!(bin|base64)]}
265 This template will add the whole DER encoded certificate as a
266 string to the search filter. Depending on the conversion option the
267 binary certificate is either converted to an escaped hex sequence
268 '\xx' or base64. The escaped hex sequence is the default and can
269 e.g. be used with the LDAP attribute 'userCertificate;binary'.
270 Example: (userCertificate;binary={cert!bin})
272 {subject_principal[.short_name]}
274 This template will add the Kerberos principal which is taken either
275 from the SAN used by pkinit or the one used by AD. The 'short_name'
276 component represents the first part of the principal before the '@'
277 sign.
278 Example:
280 (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
281 {subject_pkinit_principal[.short_name]}
283 This template will add the Kerberos principal which is given by the
284 SAN used by pkinit. The 'short_name' component represents the first
285 part of the principal before the '@' sign.
286 Example:
288 (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
289 {subject_nt_principal[.short_name]}
291 This template will add the Kerberos principal which is given by the
292 SAN used by AD. The 'short_name' component represent the first part
293 of the principal before the '@' sign.
294 Example:
296 (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
297 {subject_rfc822_name[.short_name]}
299 This template will add the string which is stored in the rfc822Name
300 component of the SAN, typically an email address. The 'short_name'
301 component represents the first part of the address before the '@'
302 sign.
303 Example:
305 (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
306 {subject_dns_name[.short_name]}
308 This template will add the string which is stored in the dNSName
309 component of the SAN, typically a fully-qualified host name. The
310 'short_name' component represents the first part of the name before
311 the first '.' sign.
312 Example:
314 (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
315 {subject_uri}
317 This template will add the string which is stored in the
318 uniformResourceIdentifier component of the SAN.
319 Example: (uri={subject_uri})
321 {subject_ip_address}
323 This template will add the string which is stored in the iPAddress
324 component of the SAN.
325 Example: (ip={subject_ip_address})
327 {subject_x400_address}
329 This template will add the value which is stored in the x400Address
330 component of the SAN as escaped hex sequence.
331 Example: (attr:binary={subject_x400_address})
333 {subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
335 This template will add the DN string of the value which is stored
336 in the directoryName component of the SAN.
337 Example: (orig_dn={subject_directory_name})
339 {subject_ediparty_name}
341 This template will add the value which is stored in the
342 ediPartyName component of the SAN as escaped hex sequence.
343 Example: (attr:binary={subject_ediparty_name})
345 {subject_registered_id}
347 This template will add the OID which is stored in the registeredID
348 component of the SAN as a dotted-decimal string.
349 Example: (oid={subject_registered_id})
351 DOMAIN LIST
353 If the domain list is not empty users mapped to a given certificate are
354 not only searched in the local domain but in the listed domains as well
355 as long as they are know by SSSD. Domains not know to SSSD will be
356 ignored.
357
359 The SSSD upstream - https://pagure.io/SSSD/sssd/
360SSSD 07/01/2019 SSS-CERTMAP(5)