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 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 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 The available options are:
49 <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 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 Example: <SUBJECT>.*,DC=MY,DC=DOMAIN
66 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 Example: <SUBJECT>^CN=.* \(Admin\),DC=MY,DC=DOMAIN$
72 <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 Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
78 <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 • digitalSignature
85 • nonRepudiation
87 • keyEncipherment
89 • dataEncipherment
91 • keyAgreement
93 • keyCertSign
95 • cRLSign
97 • encipherOnly
99 • decipherOnly
101 A numerical value in the range of a 32bit unsigned integer can be
103 used as well to cover special use cases.
104 Example: <KU>digitalSignature,keyEncipherment
106 <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 • serverAuth
113 • clientAuth
115 • codeSigning
117 • emailProtection
119 • timeStamping
121 • OCSPSigning
123 • KPClientAuth
125 • pkinit
127 • msScLogin
129 Extended key usages which are not listed above can be specified
131 with their OID in dotted-decimal notation.
132 Example: <EKU>clientAuth,1.3.6.1.5.2.3.4
134 <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 Example: <SAN>.*@MY\.REALM
141 <SAN:Principal>regular-expression
143 Match the Kerberos principals in the PKINIT or AD NT Principal SAN.
144 Example: <SAN:Principal>.*@MY\.REALM
146 <SAN:ntPrincipalName>regular-expression
148 Match the Kerberos principals from the AD NT Principal SAN.
149 Example: <SAN:ntPrincipalName>.*@MY.AD.REALM
151 <SAN:pkinit>regular-expression
153 Match the Kerberos principals from the PKINIT SAN.
154 Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM
156 <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 Example: <SAN:1.2.3.4>test
163 <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 Example: <SAN:otherName>MTIz
171 <SAN:rfc822Name>regular-expression
173 Match the value of the rfc822Name SAN.
174 Example: <SAN:rfc822Name>.*@email\.domain
176 <SAN:dNSName>regular-expression
178 Match the value of the dNSName SAN.
179 Example: <SAN:dNSName>.*\.my\.dns\.domain
181 <SAN:x400Address>base64-string
183 Binary match the value of the x400Address SAN.
184 Example: <SAN:x400Address>MTIz
186 <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 Example: <SAN:directoryName>.*,DC=com
192 <SAN:ediPartyName>base64-string
194 Binary match the value of the ediPartyName SAN.
195 Example: <SAN:ediPartyName>MTIz
197 <SAN:uniformResourceIdentifier>regular-expression
199 Match the value of the uniformResourceIdentifier SAN.
200 Example: <SAN:uniformResourceIdentifier>URN:.*
202 <SAN:iPAddress>regular-expression
204 Match the value of the iPAddress SAN.
205 Example: <SAN:iPAddress>192\.168\..*
207 <SAN:registeredID>regular-expression
209 Match the value of the registeredID SAN as dotted-decimal string.
210 Example: <SAN:registeredID>1\.2\.3\..*
212 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 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 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 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 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 {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 The conversion options starting with 'ad_' will use attribute names
250 as used by AD, e.g. 'S' instead of 'ST'.
251 The conversion options starting with 'nss_' will use attribute
253 names as used by NSS.
254 The default conversion option is 'nss', i.e. attribute names
256 according to NSS and LDAP/RFC 4514 ordering.
257 Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})
259 {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 The conversion options starting with 'ad_' will use attribute names
266 as used by AD, e.g. 'S' instead of 'ST'.
267 The conversion options starting with 'nss_' will use attribute
269 names as used by NSS.
270 The default conversion option is 'nss', i.e. attribute names
272 according to NSS and LDAP/RFC 4514 ordering.
273 Example:
275 (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
276 {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 Example: (userCertificate;binary={cert!bin})
285 {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 Example:
293 (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
294 {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 Example:
301 (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
302 {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 Example:
309 (|(userPrincipalName={subject_nt_principal})(samAccountName={subject_nt_principal.short_name}))
310 {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 Example:
318 (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
319 {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 Example:
327 (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
328 {subject_uri}
330 This template will add the string which is stored in the
331 uniformResourceIdentifier component of the SAN.
332 Example: (uri={subject_uri})
334 {subject_ip_address}
336 This template will add the string which is stored in the iPAddress
337 component of the SAN.
338 Example: (ip={subject_ip_address})
340 {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 Example: (attr:binary={subject_x400_address})
346 {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 Example: (orig_dn={subject_directory_name})
352 {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 Example: (attr:binary={subject_ediparty_name})
358 {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 Example: (oid={subject_registered_id})
364 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
372 The SSSD upstream - https://github.com/SSSD/sssd/
373SSSD 07/04/2022 SSS-CERTMAP(5)