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 To allow extensions or completely different style of rule the “mapping”
22 and “matching rules” can contain a prefix separated with a ':' from the
23 main part of the rule. The prefix may only contain upper-case ASCII
24 letters and numbers. If the prefix is omitted the default type will be
25 used which is 'KRB5' for the matching rules and 'LDAP' for the mapping
26 rules.
27 The 'sssctl' utility provides the 'cert-eval-rule' command to check if
29 a given certificate matches a matching rules and how the output of a
30 mapping rule would look like.
31
33 PRIORITY
34 The rules are processed by priority while the number '0' (zero)
35 indicates the highest priority. The higher the number the lower is the
36 priority. A missing value indicates the lowest priority. The rules
37 processing is stopped when a matched rule is found and no further rules
38 are checked.
39 Internally the priority is treated as unsigned 32bit integer, using a
41 priority value larger than 4294967295 will cause an error.
42 If multiple rules have the same priority and only one of the related
44 matching rules applies, this rule will be chosen. If there are multiple
45 rules with the same priority which matches, one is chosen but which one
46 is undefined. To avoid this undefined behavior either use different
47 priorities or make the matching rules more specific e.g. by using
48 distinct <ISSUER> patterns.
49 MATCHING RULE
51 The matching rule is used to select a certificate to which the mapping
52 rule should be applied. It uses a system similar to the one used by
53 “pkinit_cert_match” option of MIT Kerberos. It consists of a keyword
54 enclosed by '<' and '>' which identified a certain part of the
55 certificate and a pattern which should be found for the rule to match.
56 Multiple keyword pattern pairs can be either joined with '&&' (and) or
57 '||' (or).
58 Given the similarity to MIT Kerberos the type prefix for this rule is
60 'KRB5'. But 'KRB5' will also be the default for “matching rules” so
61 that "<SUBJECT>.*,DC=MY,DC=DOMAIN" and
62 "KRB5:<SUBJECT>.*,DC=MY,DC=DOMAIN" are equivalent.
63 The available options are:
65 <SUBJECT>regular-expression
67 With this a part or the whole subject name of the certificate can
68 be matched. For the matching POSIX Extended Regular Expression
69 syntax is used, see regex(7) for details.
70 For the matching the subject name stored in the certificate in DER
72 encoded ASN.1 is converted into a string according to RFC 4514.
73 This means the most specific name component comes first. Please
74 note that not all possible attribute names are covered by RFC 4514.
75 The names included are 'CN', 'L', 'ST', 'O', 'OU', 'C', 'STREET',
76 'DC' and 'UID'. Other attribute names might be shown differently on
77 different platform and by different tools. To avoid confusion those
78 attribute names are best not used or covered by a suitable
79 regular-expression.
80 Example: <SUBJECT>.*,DC=MY,DC=DOMAIN
82 Please note that the characters "^.[$()|*+?{\" have a special
84 meaning in regular expressions and must be escaped with the help of
85 the '\' character so that they are matched as ordinary characters.
86 Example: <SUBJECT>^CN=.* \(Admin\),DC=MY,DC=DOMAIN$
88 <ISSUER>regular-expression
90 With this a part or the whole issuer name of the certificate can be
91 matched. All comments for <SUBJECT> apply her as well.
92 Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
94 <KU>key-usage
96 This option can be used to specify which key usage values the
97 certificate should have. The following values can be used in a
98 comma separated list:
99 • digitalSignature
101 • nonRepudiation
103 • keyEncipherment
105 • dataEncipherment
107 • keyAgreement
109 • keyCertSign
111 • cRLSign
113 • encipherOnly
115 • decipherOnly
117 A numerical value in the range of a 32bit unsigned integer can be
119 used as well to cover special use cases.
120 Example: <KU>digitalSignature,keyEncipherment
122 <EKU>extended-key-usage
124 This option can be used to specify which extended key usage the
125 certificate should have. The following value can be used in a comma
126 separated list:
127 • serverAuth
129 • clientAuth
131 • codeSigning
133 • emailProtection
135 • timeStamping
137 • OCSPSigning
139 • KPClientAuth
141 • pkinit
143 • msScLogin
145 Extended key usages which are not listed above can be specified
147 with their OID in dotted-decimal notation.
148 Example: <EKU>clientAuth,1.3.6.1.5.2.3.4
150 <SAN>regular-expression
152 To be compatible with the usage of MIT Kerberos this option will
153 match the Kerberos principals in the PKINIT or AD NT Principal SAN
154 as <SAN:Principal> does.
155 Example: <SAN>.*@MY\.REALM
157 <SAN:Principal>regular-expression
159 Match the Kerberos principals in the PKINIT or AD NT Principal SAN.
160 Example: <SAN:Principal>.*@MY\.REALM
162 <SAN:ntPrincipalName>regular-expression
164 Match the Kerberos principals from the AD NT Principal SAN.
165 Example: <SAN:ntPrincipalName>.*@MY.AD.REALM
167 <SAN:pkinit>regular-expression
169 Match the Kerberos principals from the PKINIT SAN.
170 Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM
172 <SAN:dotted-decimal-oid>regular-expression
174 Take the value of the otherName SAN component given by the OID in
175 dotted-decimal notation, interpret it as string and try to match it
176 against the regular expression.
177 Example: <SAN:1.2.3.4>test
179 <SAN:otherName>base64-string
181 Do a binary match with the base64 encoded blob against all
182 otherName SAN components. With this option it is possible to match
183 against custom otherName components with special encodings which
184 could not be treated as strings.
185 Example: <SAN:otherName>MTIz
187 <SAN:rfc822Name>regular-expression
189 Match the value of the rfc822Name SAN.
190 Example: <SAN:rfc822Name>.*@email\.domain
192 <SAN:dNSName>regular-expression
194 Match the value of the dNSName SAN.
195 Example: <SAN:dNSName>.*\.my\.dns\.domain
197 <SAN:x400Address>base64-string
199 Binary match the value of the x400Address SAN.
200 Example: <SAN:x400Address>MTIz
202 <SAN:directoryName>regular-expression
204 Match the value of the directoryName SAN. The same comments as
205 given for <ISSUER> and <SUBJECT> apply here as well.
206 Example: <SAN:directoryName>.*,DC=com
208 <SAN:ediPartyName>base64-string
210 Binary match the value of the ediPartyName SAN.
211 Example: <SAN:ediPartyName>MTIz
213 <SAN:uniformResourceIdentifier>regular-expression
215 Match the value of the uniformResourceIdentifier SAN.
216 Example: <SAN:uniformResourceIdentifier>URN:.*
218 <SAN:iPAddress>regular-expression
220 Match the value of the iPAddress SAN.
221 Example: <SAN:iPAddress>192\.168\..*
223 <SAN:registeredID>regular-expression
225 Match the value of the registeredID SAN as dotted-decimal string.
226 Example: <SAN:registeredID>1\.2\.3\..*
228 MAPPING RULE
230 The mapping rule is used to associate a certificate with one or more
231 accounts. A Smartcard with the certificate and the matching private key
232 can then be used to authenticate as one of those accounts.
233 Currently SSSD basically only supports LDAP to lookup user information
235 (the exception is the proxy provider which is not of relevance here).
236 Because of this the mapping rule is based on LDAP search filter syntax
237 with templates to add certificate content to the filter. It is expected
238 that the filter will only contain the specific data needed for the
239 mapping and that the caller will embed it in another filter to do the
240 actual search. Because of this the filter string should start and stop
241 with '(' and ')' respectively.
242 In general it is recommended to use attributes from the certificate and
244 add them to special attributes to the LDAP user object. E.g. the
245 'altSecurityIdentities' attribute in AD or the 'ipaCertMapData'
246 attribute for IPA can be used.
247 This should be preferred to read user specific data from the
249 certificate like e.g. an email address and search for it in the LDAP
250 server. The reason is that the user specific data in LDAP might change
251 for various reasons would break the mapping. On the other hand it would
252 be hard to break the mapping on purpose for a specific user.
253 The default “mapping rule” type is 'LDAP' which can be added as a
255 prefix to a rule like e.g. 'LDAP:(userCertificate;binary={cert!bin})'.
256 There is an extension called 'LDAPU1' which offer more templates for
257 more flexibility. To allow older versions of this library to ignore the
258 extension the prefix 'LDAPU1' must be used when using the new templates
259 in a “mapping rule” otherwise the old version of this library will fail
260 with a parsing error. The new templates are described in section the
261 section called “LDAPU1 extension”.
262 The templates to add certificate data to the search filter are based on
264 Python-style formatting strings. They consist of a keyword in curly
265 braces with an optional sub-component specifier separated by a '.' or
266 an optional conversion/formatting option separated by a '!'. Allowed
267 values are:
268 {issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
270 This template will add the full issuer DN converted to a string
271 according to RFC 4514. If X.500 ordering (most specific RDN comes
272 last) an option with the '_x500' prefix should be used.
273 The conversion options starting with 'ad_' will use attribute names
275 as used by AD, e.g. 'S' instead of 'ST'.
276 The conversion options starting with 'nss_' will use attribute
278 names as used by NSS.
279 The default conversion option is 'nss', i.e. attribute names
281 according to NSS and LDAP/RFC 4514 ordering.
282 Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})
284 {subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
286 This template will add the full subject DN converted to string
287 according to RFC 4514. If X.500 ordering (most specific RDN comes
288 last) an option with the '_x500' prefix should be used.
289 The conversion options starting with 'ad_' will use attribute names
291 as used by AD, e.g. 'S' instead of 'ST'.
292 The conversion options starting with 'nss_' will use attribute
294 names as used by NSS.
295 The default conversion option is 'nss', i.e. attribute names
297 according to NSS and LDAP/RFC 4514 ordering.
298 Example:
300 (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
301 {cert[!(bin|base64)]}
303 This template will add the whole DER encoded certificate as a
304 string to the search filter. Depending on the conversion option the
305 binary certificate is either converted to an escaped hex sequence
306 '\xx' or base64. The escaped hex sequence is the default and can
307 e.g. be used with the LDAP attribute 'userCertificate;binary'.
308 Example: (userCertificate;binary={cert!bin})
310 {subject_principal[.short_name]}
312 This template will add the Kerberos principal which is taken either
313 from the SAN used by pkinit or the one used by AD. The 'short_name'
314 component represents the first part of the principal before the '@'
315 sign.
316 Example:
318 (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
319 {subject_pkinit_principal[.short_name]}
321 This template will add the Kerberos principal which is given by the
322 SAN used by pkinit. The 'short_name' component represents the first
323 part of the principal before the '@' sign.
324 Example:
326 (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
327 {subject_nt_principal[.short_name]}
329 This template will add the Kerberos principal which is given by the
330 SAN used by AD. The 'short_name' component represent the first part
331 of the principal before the '@' sign.
332 Example:
334 (|(userPrincipalName={subject_nt_principal})(samAccountName={subject_nt_principal.short_name}))
335 {subject_rfc822_name[.short_name]}
337 This template will add the string which is stored in the rfc822Name
338 component of the SAN, typically an email address. The 'short_name'
339 component represents the first part of the address before the '@'
340 sign.
341 Example:
343 (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
344 {subject_dns_name[.short_name]}
346 This template will add the string which is stored in the dNSName
347 component of the SAN, typically a fully-qualified host name. The
348 'short_name' component represents the first part of the name before
349 the first '.' sign.
350 Example:
352 (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
353 {subject_uri}
355 This template will add the string which is stored in the
356 uniformResourceIdentifier component of the SAN.
357 Example: (uri={subject_uri})
359 {subject_ip_address}
361 This template will add the string which is stored in the iPAddress
362 component of the SAN.
363 Example: (ip={subject_ip_address})
365 {subject_x400_address}
367 This template will add the value which is stored in the x400Address
368 component of the SAN as escaped hex sequence.
369 Example: (attr:binary={subject_x400_address})
371 {subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
373 This template will add the DN string of the value which is stored
374 in the directoryName component of the SAN.
375 Example: (orig_dn={subject_directory_name})
377 {subject_ediparty_name}
379 This template will add the value which is stored in the
380 ediPartyName component of the SAN as escaped hex sequence.
381 Example: (attr:binary={subject_ediparty_name})
383 {subject_registered_id}
385 This template will add the OID which is stored in the registeredID
386 component of the SAN as a dotted-decimal string.
387 Example: (oid={subject_registered_id})
389 LDAPU1 extension
391 The following template are available when using the 'LDAPU1'
392 extension:
393 {serial_number[!(dec|hex[_ucr])]}
395 This template will add the serial number of the certificate. By
396 default it will be printed as a hexadecimal number with
397 lower-case letters.
398 With the formatting option '!dec' the number will be printed as
400 decimal string. The hexadecimal output can be printed with
401 upper-case letters ('!hex_u'), with a colon separating the
402 hexadecimal bytes ('!hex_c') or with the hexadecimal bytes in
403 reverse order ('!hex_r'). The postfix letters can be combined
404 so that e.g. '!hex_uc' will produce a colon-separated
405 hexadecimal string with upper-case letters.
406 Example: LDAPU1:(serial={serial_number})
408 {subject_key_id[!hex[_ucr]]}
410 This template will add the subject key id of the certificate.
411 By default it will be printed as a hexadecimal number with
412 lower-case letters.
413 The hexadecimal output can be printed with upper-case letters
415 ('!hex_u'), with a colon separating the hexadecimal bytes
416 ('!hex_c') or with the hexadecimal bytes in reverse order
417 ('!hex_r'). The postfix letters can be combined so that e.g.
418 '!hex_uc' will produce a colon-separated hexadecimal string
419 with upper-case letters.
420 Example: LDAPU1:(ski={subject_key_id})
422 {cert[!DIGEST[_ucr]]}
424 This template will add the hexadecimal digest/hash of the
425 certificate where DIGEST must be replaced with the name of a
426 digest/hash function supported by OpenSSL, e.g. 'sha512'.
427 The hexadecimal output can be printed with upper-case letters
429 ('!sha512_u'), with a colon separating the hexadecimal bytes
430 ('!sha512_c') or with the hexadecimal bytes in reverse order
431 ('!sha512_r'). The postfix letters can be combined so that e.g.
432 '!sha512_uc' will produce a colon-separated hexadecimal string
433 with upper-case letters.
434 Example: LDAPU1:(dgst={cert!sha256})
436 {subject_dn_component[(.attr_name|[number]]}
438 This template will add an attribute value of a component of the
439 subject DN, by default the value of the most specific
440 component.
441 A different component can it either selected by attribute name,
443 e.g. {subject_dn_component.uid} or by position, e.g.
444 {subject_dn_component.[2]} where positive numbers start
445 counting from the most specific component and negative numbers
446 start counting from the least specific component. Attribute
447 name and the position can be combined as e.g.
448 {subject_dn_component.uid[2]} which means that the name of the
449 second component must be 'uid'.
450 Example: LDAPU1:(uid={subject_dn_component.uid})
452 {issuer_dn_component[(.attr_name|[number]]}
454 This template will add an attribute value of a component of the
455 issuer DN, by default the value of the most specific component.
456 See 'subject_dn_component' for details about the attribute name
458 and position specifiers.
459 Example:
461 LDAPU1:(domain={issuer_dn_component.[-2]}.{issuer_dn_component.dc[-1]})
462 {sid[.rid]}
464 This template will add the SID if the corresponding extension
465 introduced by Microsoft with the OID 1.3.6.1.4.1.311.25.2 is
466 available. With the '.rid' selector only the last component,
467 i.e. the RID, will be added.
468 Example: LDAPU1:(objectsid={sid})
470 DOMAIN LIST
472 If the domain list is not empty users mapped to a given certificate are
473 not only searched in the local domain but in the listed domains as well
474 as long as they are know by SSSD. Domains not know to SSSD will be
475 ignored.
476
478 The SSSD upstream - https://github.com/SSSD/sssd/
479SSSD 11/15/2023 SSS-CERTMAP(5)