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

RULE COMPONENTS

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
29       Internally the priority is treated as unsigned 32bit integer, using a
30       priority value larger than 4294967295 will cause an error.
31
32       If multiple rules have the same priority and only one of the related
33       matching rules applies, this rule will be chosen. If there are multiple
34       rules with the same priority which matches, one is chosen but which one
35       is undefined. To avoid this undefined behavior either use different
36       priorities or make the matching rules more specific e.g. by using
37       distinct <ISSUER> patterns.
38
39   MATCHING RULE
40       The matching rule is used to select a certificate to which the mapping
41       rule should be applied. It uses a system similar to the one used by
42       “pkinit_cert_match” option of MIT Kerberos. It consists of a keyword
43       enclosed by '<' and '>' which identified a certain part of the
44       certificate and a pattern which should be found for the rule to match.
45       Multiple keyword pattern pairs can be either joined with '&&' (and) or
46       '||' (or).
47
48       The available options are:
49
50       <SUBJECT>regular-expression
51           With this a part or the whole subject name of the certificate can
52           be matched. For the matching POSIX Extended Regular Expression
53           syntax is used, see regex(7) for details.
54
55           For the matching the subject name stored in the certificate in DER
56           encoded ASN.1 is converted into a string according to RFC 4514.
57           This means the most specific name component comes first. Please
58           note that not all possible attribute names are covered by RFC 4514.
59           The names included are 'CN', 'L', 'ST', 'O', 'OU', 'C', 'STREET',
60           'DC' and 'UID'. Other attribute names might be shown differently on
61           different platform and by different tools. To avoid confusion those
62           attribute names are best not used or covered by a suitable
63           regular-expression.
64
65           Example: <SUBJECT>.*,DC=MY,DC=DOMAIN
66
67           Please note that the characters "^.[$()|*+?{\" have a special
68           meaning in regular expressions and must be escaped with the help of
69           the '\' character so that they are matched as ordinary characters.
70
71           Example: <SUBJECT>^CN=.* \(Admin\),DC=MY,DC=DOMAIN$
72
73       <ISSUER>regular-expression
74           With this a part or the whole issuer name of the certificate can be
75           matched. All comments for <SUBJECT> apply her as well.
76
77           Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
78
79       <KU>key-usage
80           This option can be used to specify which key usage values the
81           certificate should have. The following values can be used in a
82           comma separated list:
83
84           •   digitalSignature
85
86           •   nonRepudiation
87
88           •   keyEncipherment
89
90           •   dataEncipherment
91
92           •   keyAgreement
93
94           •   keyCertSign
95
96           •   cRLSign
97
98           •   encipherOnly
99
100           •   decipherOnly
101
102           A numerical value in the range of a 32bit unsigned integer can be
103           used as well to cover special use cases.
104
105           Example: <KU>digitalSignature,keyEncipherment
106
107       <EKU>extended-key-usage
108           This option can be used to specify which extended key usage the
109           certificate should have. The following value can be used in a comma
110           separated list:
111
112           •   serverAuth
113
114           •   clientAuth
115
116           •   codeSigning
117
118           •   emailProtection
119
120           •   timeStamping
121
122           •   OCSPSigning
123
124           •   KPClientAuth
125
126           •   pkinit
127
128           •   msScLogin
129
130           Extended key usages which are not listed above can be specified
131           with their OID in dotted-decimal notation.
132
133           Example: <EKU>clientAuth,1.3.6.1.5.2.3.4
134
135       <SAN>regular-expression
136           To be compatible with the usage of MIT Kerberos this option will
137           match the Kerberos principals in the PKINIT or AD NT Principal SAN
138           as <SAN:Principal> does.
139
140           Example: <SAN>.*@MY\.REALM
141
142       <SAN:Principal>regular-expression
143           Match the Kerberos principals in the PKINIT or AD NT Principal SAN.
144
145           Example: <SAN:Principal>.*@MY\.REALM
146
147       <SAN:ntPrincipalName>regular-expression
148           Match the Kerberos principals from the AD NT Principal SAN.
149
150           Example: <SAN:ntPrincipalName>.*@MY.AD.REALM
151
152       <SAN:pkinit>regular-expression
153           Match the Kerberos principals from the PKINIT SAN.
154
155           Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM
156
157       <SAN:dotted-decimal-oid>regular-expression
158           Take the value of the otherName SAN component given by the OID in
159           dotted-decimal notation, interpret it as string and try to match it
160           against the regular expression.
161
162           Example: <SAN:1.2.3.4>test
163
164       <SAN:otherName>base64-string
165           Do a binary match with the base64 encoded blob against all
166           otherName SAN components. With this option it is possible to match
167           against custom otherName components with special encodings which
168           could not be treated as strings.
169
170           Example: <SAN:otherName>MTIz
171
172       <SAN:rfc822Name>regular-expression
173           Match the value of the rfc822Name SAN.
174
175           Example: <SAN:rfc822Name>.*@email\.domain
176
177       <SAN:dNSName>regular-expression
178           Match the value of the dNSName SAN.
179
180           Example: <SAN:dNSName>.*\.my\.dns\.domain
181
182       <SAN:x400Address>base64-string
183           Binary match the value of the x400Address SAN.
184
185           Example: <SAN:x400Address>MTIz
186
187       <SAN:directoryName>regular-expression
188           Match the value of the directoryName SAN. The same comments as
189           given for <ISSUER> and <SUBJECT> apply here as well.
190
191           Example: <SAN:directoryName>.*,DC=com
192
193       <SAN:ediPartyName>base64-string
194           Binary match the value of the ediPartyName SAN.
195
196           Example: <SAN:ediPartyName>MTIz
197
198       <SAN:uniformResourceIdentifier>regular-expression
199           Match the value of the uniformResourceIdentifier SAN.
200
201           Example: <SAN:uniformResourceIdentifier>URN:.*
202
203       <SAN:iPAddress>regular-expression
204           Match the value of the iPAddress SAN.
205
206           Example: <SAN:iPAddress>192\.168\..*
207
208       <SAN:registeredID>regular-expression
209           Match the value of the registeredID SAN as dotted-decimal string.
210
211           Example: <SAN:registeredID>1\.2\.3\..*
212
213   MAPPING RULE
214       The mapping rule is used to associate a certificate with one or more
215       accounts. A Smartcard with the certificate and the matching private key
216       can then be used to authenticate as one of those accounts.
217
218       Currently SSSD basically only supports LDAP to lookup user information
219       (the exception is the proxy provider which is not of relevance here).
220       Because of this the mapping rule is based on LDAP search filter syntax
221       with templates to add certificate content to the filter. It is expected
222       that the filter will only contain the specific data needed for the
223       mapping and that the caller will embed it in another filter to do the
224       actual search. Because of this the filter string should start and stop
225       with '(' and ')' respectively.
226
227       In general it is recommended to use attributes from the certificate and
228       add them to special attributes to the LDAP user object. E.g. the
229       'altSecurityIdentities' attribute in AD or the 'ipaCertMapData'
230       attribute for IPA can be used.
231
232       This should be preferred to read user specific data from the
233       certificate like e.g. an email address and search for it in the LDAP
234       server. The reason is that the user specific data in LDAP might change
235       for various reasons would break the mapping. On the other hand it would
236       be hard to break the mapping on purpose for a specific user.
237
238       The templates to add certificate data to the search filter are based on
239       Python-style formatting strings. They consist of a keyword in curly
240       braces with an optional sub-component specifier separated by a '.' or
241       an optional conversion/formatting option separated by a '!'. Allowed
242       values are:
243
244       {issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
245           This template will add the full issuer DN converted to a string
246           according to RFC 4514. If X.500 ordering (most specific RDN comes
247           last) an option with the '_x500' prefix should be used.
248
249           The conversion options starting with 'ad_' will use attribute names
250           as used by AD, e.g. 'S' instead of 'ST'.
251
252           The conversion options starting with 'nss_' will use attribute
253           names as used by NSS.
254
255           The default conversion option is 'nss', i.e. attribute names
256           according to NSS and LDAP/RFC 4514 ordering.
257
258           Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})
259
260       {subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
261           This template will add the full subject DN converted to string
262           according to RFC 4514. If X.500 ordering (most specific RDN comes
263           last) an option with the '_x500' prefix should be used.
264
265           The conversion options starting with 'ad_' will use attribute names
266           as used by AD, e.g. 'S' instead of 'ST'.
267
268           The conversion options starting with 'nss_' will use attribute
269           names as used by NSS.
270
271           The default conversion option is 'nss', i.e. attribute names
272           according to NSS and LDAP/RFC 4514 ordering.
273
274           Example:
275           (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
276
277       {cert[!(bin|base64)]}
278           This template will add the whole DER encoded certificate as a
279           string to the search filter. Depending on the conversion option the
280           binary certificate is either converted to an escaped hex sequence
281           '\xx' or base64. The escaped hex sequence is the default and can
282           e.g. be used with the LDAP attribute 'userCertificate;binary'.
283
284           Example: (userCertificate;binary={cert!bin})
285
286       {subject_principal[.short_name]}
287           This template will add the Kerberos principal which is taken either
288           from the SAN used by pkinit or the one used by AD. The 'short_name'
289           component represents the first part of the principal before the '@'
290           sign.
291
292           Example:
293           (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
294
295       {subject_pkinit_principal[.short_name]}
296           This template will add the Kerberos principal which is given by the
297           SAN used by pkinit. The 'short_name' component represents the first
298           part of the principal before the '@' sign.
299
300           Example:
301           (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
302
303       {subject_nt_principal[.short_name]}
304           This template will add the Kerberos principal which is given by the
305           SAN used by AD. The 'short_name' component represent the first part
306           of the principal before the '@' sign.
307
308           Example:
309           (|(userPrincipalName={subject_nt_principal})(samAccountName={subject_nt_principal.short_name}))
310
311       {subject_rfc822_name[.short_name]}
312           This template will add the string which is stored in the rfc822Name
313           component of the SAN, typically an email address. The 'short_name'
314           component represents the first part of the address before the '@'
315           sign.
316
317           Example:
318           (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
319
320       {subject_dns_name[.short_name]}
321           This template will add the string which is stored in the dNSName
322           component of the SAN, typically a fully-qualified host name. The
323           'short_name' component represents the first part of the name before
324           the first '.' sign.
325
326           Example:
327           (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
328
329       {subject_uri}
330           This template will add the string which is stored in the
331           uniformResourceIdentifier component of the SAN.
332
333           Example: (uri={subject_uri})
334
335       {subject_ip_address}
336           This template will add the string which is stored in the iPAddress
337           component of the SAN.
338
339           Example: (ip={subject_ip_address})
340
341       {subject_x400_address}
342           This template will add the value which is stored in the x400Address
343           component of the SAN as escaped hex sequence.
344
345           Example: (attr:binary={subject_x400_address})
346
347       {subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
348           This template will add the DN string of the value which is stored
349           in the directoryName component of the SAN.
350
351           Example: (orig_dn={subject_directory_name})
352
353       {subject_ediparty_name}
354           This template will add the value which is stored in the
355           ediPartyName component of the SAN as escaped hex sequence.
356
357           Example: (attr:binary={subject_ediparty_name})
358
359       {subject_registered_id}
360           This template will add the OID which is stored in the registeredID
361           component of the SAN as a dotted-decimal string.
362
363           Example: (oid={subject_registered_id})
364
365   DOMAIN LIST
366       If the domain list is not empty users mapped to a given certificate are
367       not only searched in the local domain but in the listed domains as well
368       as long as they are know by SSSD. Domains not know to SSSD will be
369       ignored.
370

AUTHORS

372       The SSSD upstream - https://github.com/SSSD/sssd/
373
374
375
376SSSD                              07/04/2022                    SSS-CERTMAP(5)
Impressum