1SSS-CERTMAP(5)           File Formats and Conventions           SSS-CERTMAP(5)
2
3
4

NAME

6       sss-certmap - SSSD Certificate Matching and Mapping Rules
7

DESCRIPTION

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
12       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
21       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
28       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

RULE COMPONENTS

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
40       Internally the priority is treated as unsigned 32bit integer, using a
41       priority value larger than 4294967295 will cause an error.
42
43       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
50   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
59       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
64       The available options are:
65
66       <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
71           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
81           Example: <SUBJECT>.*,DC=MY,DC=DOMAIN
82
83           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
87           Example: <SUBJECT>^CN=.* \(Admin\),DC=MY,DC=DOMAIN$
88
89       <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
93           Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
94
95       <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
100           •   digitalSignature
101
102           •   nonRepudiation
103
104           •   keyEncipherment
105
106           •   dataEncipherment
107
108           •   keyAgreement
109
110           •   keyCertSign
111
112           •   cRLSign
113
114           •   encipherOnly
115
116           •   decipherOnly
117
118           A numerical value in the range of a 32bit unsigned integer can be
119           used as well to cover special use cases.
120
121           Example: <KU>digitalSignature,keyEncipherment
122
123       <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
128           •   serverAuth
129
130           •   clientAuth
131
132           •   codeSigning
133
134           •   emailProtection
135
136           •   timeStamping
137
138           •   OCSPSigning
139
140           •   KPClientAuth
141
142           •   pkinit
143
144           •   msScLogin
145
146           Extended key usages which are not listed above can be specified
147           with their OID in dotted-decimal notation.
148
149           Example: <EKU>clientAuth,1.3.6.1.5.2.3.4
150
151       <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
156           Example: <SAN>.*@MY\.REALM
157
158       <SAN:Principal>regular-expression
159           Match the Kerberos principals in the PKINIT or AD NT Principal SAN.
160
161           Example: <SAN:Principal>.*@MY\.REALM
162
163       <SAN:ntPrincipalName>regular-expression
164           Match the Kerberos principals from the AD NT Principal SAN.
165
166           Example: <SAN:ntPrincipalName>.*@MY.AD.REALM
167
168       <SAN:pkinit>regular-expression
169           Match the Kerberos principals from the PKINIT SAN.
170
171           Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM
172
173       <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
178           Example: <SAN:1.2.3.4>test
179
180       <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
186           Example: <SAN:otherName>MTIz
187
188       <SAN:rfc822Name>regular-expression
189           Match the value of the rfc822Name SAN.
190
191           Example: <SAN:rfc822Name>.*@email\.domain
192
193       <SAN:dNSName>regular-expression
194           Match the value of the dNSName SAN.
195
196           Example: <SAN:dNSName>.*\.my\.dns\.domain
197
198       <SAN:x400Address>base64-string
199           Binary match the value of the x400Address SAN.
200
201           Example: <SAN:x400Address>MTIz
202
203       <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
207           Example: <SAN:directoryName>.*,DC=com
208
209       <SAN:ediPartyName>base64-string
210           Binary match the value of the ediPartyName SAN.
211
212           Example: <SAN:ediPartyName>MTIz
213
214       <SAN:uniformResourceIdentifier>regular-expression
215           Match the value of the uniformResourceIdentifier SAN.
216
217           Example: <SAN:uniformResourceIdentifier>URN:.*
218
219       <SAN:iPAddress>regular-expression
220           Match the value of the iPAddress SAN.
221
222           Example: <SAN:iPAddress>192\.168\..*
223
224       <SAN:registeredID>regular-expression
225           Match the value of the registeredID SAN as dotted-decimal string.
226
227           Example: <SAN:registeredID>1\.2\.3\..*
228
229   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
234       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
243       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
248       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
254       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
263       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
269       {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
274           The conversion options starting with 'ad_' will use attribute names
275           as used by AD, e.g. 'S' instead of 'ST'.
276
277           The conversion options starting with 'nss_' will use attribute
278           names as used by NSS.
279
280           The default conversion option is 'nss', i.e. attribute names
281           according to NSS and LDAP/RFC 4514 ordering.
282
283           Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})
284
285       {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
290           The conversion options starting with 'ad_' will use attribute names
291           as used by AD, e.g. 'S' instead of 'ST'.
292
293           The conversion options starting with 'nss_' will use attribute
294           names as used by NSS.
295
296           The default conversion option is 'nss', i.e. attribute names
297           according to NSS and LDAP/RFC 4514 ordering.
298
299           Example:
300           (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
301
302       {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
309           Example: (userCertificate;binary={cert!bin})
310
311       {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
317           Example:
318           (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
319
320       {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
325           Example:
326           (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
327
328       {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
333           Example:
334           (|(userPrincipalName={subject_nt_principal})(samAccountName={subject_nt_principal.short_name}))
335
336       {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
342           Example:
343           (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
344
345       {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
351           Example:
352           (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
353
354       {subject_uri}
355           This template will add the string which is stored in the
356           uniformResourceIdentifier component of the SAN.
357
358           Example: (uri={subject_uri})
359
360       {subject_ip_address}
361           This template will add the string which is stored in the iPAddress
362           component of the SAN.
363
364           Example: (ip={subject_ip_address})
365
366       {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
370           Example: (attr:binary={subject_x400_address})
371
372       {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
376           Example: (orig_dn={subject_directory_name})
377
378       {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
382           Example: (attr:binary={subject_ediparty_name})
383
384       {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
388           Example: (oid={subject_registered_id})
389
390       LDAPU1 extension
391           The following template are available when using the 'LDAPU1'
392           extension:
393
394           {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
399               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
407               Example: LDAPU1:(serial={serial_number})
408
409           {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
414               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
421               Example: LDAPU1:(ski={subject_key_id})
422
423           {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
428               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
435               Example: LDAPU1:(dgst={cert!sha256})
436
437           {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
442               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
451               Example: LDAPU1:(uid={subject_dn_component.uid})
452
453           {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
457               See 'subject_dn_component' for details about the attribute name
458               and position specifiers.
459
460               Example:
461               LDAPU1:(domain={issuer_dn_component.[-2]}.{issuer_dn_component.dc[-1]})
462
463           {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
469               Example: LDAPU1:(objectsid={sid})
470
471   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

AUTHORS

478       The SSSD upstream - https://github.com/SSSD/sssd/
479
480
481
482SSSD                              11/15/2023                    SSS-CERTMAP(5)
Impressum