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   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
41       The available options are:
42
43       <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
48           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
58           Example: <SUBJECT>.*,DC=MY,DC=DOMAIN
59
60       <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
64           Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
65
66       <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
71           ·   digitalSignature
72
73           ·   nonRepudiation
74
75           ·   keyEncipherment
76
77           ·   dataEncipherment
78
79           ·   keyAgreement
80
81           ·   keyCertSign
82
83           ·   cRLSign
84
85           ·   encipherOnly
86
87           ·   decipherOnly
88
89           A numerical value in the range of a 32bit unsigned integer can be
90           used as well to cover special use cases.
91
92           Example: <KU>digitalSignature,keyEncipherment
93
94       <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
99           ·   serverAuth
100
101           ·   clientAuth
102
103           ·   codeSigning
104
105           ·   emailProtection
106
107           ·   timeStamping
108
109           ·   OCSPSigning
110
111           ·   KPClientAuth
112
113           ·   pkinit
114
115           ·   msScLogin
116
117           Extended key usages which are not listed above can be specified
118           with their OID in dotted-decimal notation.
119
120           Example: <EKU>clientAuth,1.3.6.1.5.2.3.4
121
122       <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
127           Example: <SAN>.*@MY\.REALM
128
129       <SAN:Principal>regular-expression
130           Match the Kerberos principals in the PKINIT or AD NT Principal SAN.
131
132           Example: <SAN:Principal>.*@MY\.REALM
133
134       <SAN:ntPrincipalName>regular-expression
135           Match the Kerberos principals from the AD NT Principal SAN.
136
137           Example: <SAN:ntPrincipalName>.*@MY.AD.REALM
138
139       <SAN:pkinit>regular-expression
140           Match the Kerberos principals from the PKINIT SAN.
141
142           Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM
143
144       <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
149           Example: <SAN:1.2.3.4>test
150
151       <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
157           Example: <SAN:otherName>MTIz
158
159       <SAN:rfc822Name>regular-expression
160           Match the value of the rfc822Name SAN.
161
162           Example: <SAN:rfc822Name>.*@email\.domain
163
164       <SAN:dNSName>regular-expression
165           Match the value of the dNSName SAN.
166
167           Example: <SAN:dNSName>.*\.my\.dns\.domain
168
169       <SAN:x400Address>base64-string
170           Binary match the value of the x400Address SAN.
171
172           Example: <SAN:x400Address>MTIz
173
174       <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
178           Example: <SAN:directoryName>.*,DC=com
179
180       <SAN:ediPartyName>base64-string
181           Binary match the value of the ediPartyName SAN.
182
183           Example: <SAN:ediPartyName>MTIz
184
185       <SAN:uniformResourceIdentifier>regular-expression
186           Match the value of the uniformResourceIdentifier SAN.
187
188           Example: <SAN:uniformResourceIdentifier>URN:.*
189
190       <SAN:iPAddress>regular-expression
191           Match the value of the iPAddress SAN.
192
193           Example: <SAN:iPAddress>192\.168\..*
194
195       <SAN:registeredID>regular-expression
196           Match the value of the registeredID SAN as dotted-decimal string.
197
198           Example: <SAN:registeredID>1\.2\.3\..*
199
200   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
205       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
214       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
219       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
225       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
231       {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
236           The conversion options starting with 'ad_' will use attribute names
237           as used by AD, e.g. 'S' instead of 'ST'.
238
239           The conversion options starting with 'nss_' will use attribute
240           names as used by NSS.
241
242           The default conversion option is 'nss', i.e. attribute names
243           according to NSS and LDAP/RFC 4514 ordering.
244
245           Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})
246
247       {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
252           The conversion options starting with 'ad_' will use attribute names
253           as used by AD, e.g. 'S' instead of 'ST'.
254
255           The conversion options starting with 'nss_' will use attribute
256           names as used by NSS.
257
258           The default conversion option is 'nss', i.e. attribute names
259           according to NSS and LDAP/RFC 4514 ordering.
260
261           Example:
262           (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
263
264       {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
271           Example: (userCertificate;binary={cert!bin})
272
273       {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
279           Example:
280           (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
281
282       {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
287           Example:
288           (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
289
290       {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
295           Example:
296           (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
297
298       {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
304           Example:
305           (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
306
307       {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
313           Example:
314           (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
315
316       {subject_uri}
317           This template will add the string which is stored in the
318           uniformResourceIdentifier component of the SAN.
319
320           Example: (uri={subject_uri})
321
322       {subject_ip_address}
323           This template will add the string which is stored in the iPAddress
324           component of the SAN.
325
326           Example: (ip={subject_ip_address})
327
328       {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
332           Example: (attr:binary={subject_x400_address})
333
334       {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
338           Example: (orig_dn={subject_directory_name})
339
340       {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
344           Example: (attr:binary={subject_ediparty_name})
345
346       {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
350           Example: (oid={subject_registered_id})
351
352   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

AUTHORS

359       The SSSD upstream - https://pagure.io/SSSD/sssd/
360
361
362
363SSSD                              07/01/2019                    SSS-CERTMAP(5)
Impressum