1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<reference>
<title>SSSD Manual pages</title>
<refentry>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />
<refmeta>
<refentrytitle>sss-certmap</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>sss-certmap</refname>
<refpurpose>SSSD Certificate Matching and Mapping Rules</refpurpose>
</refnamediv>
<refsect1 id='description'>
<title>DESCRIPTION</title>
<para>
The manual page describes the rules which can be used by SSSD and
other components to match X.509 certificates and map them to
accounts.
</para>
<para>
Each rule has four components, a <quote>priority</quote>, a
<quote>matching rule</quote>, a <quote>mapping rule</quote> and a
<quote>domain list</quote>. All components are optional. A missing
<quote>priority</quote> will add the rule with the lowest priority.
The default <quote>matching rule</quote> will match certificates with
the digitalSignature key usage and clientAuth extended key usage. If
the <quote>mapping rule</quote> is empty the certificates will be
searched in the userCertificate attribute as DER encoded binary. If
no domains are given only the local domain will be searched.
</para>
</refsect1>
<refsect1 id='components'>
<title>RULE COMPONENTS</title>
<refsect2 id='priority'>
<title>PRIORITY</title>
<para>
The rules are process by priority while the number '0' (zero)
indicates the highest priority. The higher the number the lower is
the priority. A missing value indicates the lowest priority.
</para>
<para>
Internally the priority is treated as unsigned 32bit integer, using
a priority value larger than 4294967295 will cause an error.
</para>
</refsect2>
<refsect2 id='match'>
<title>MATCHING RULE</title>
<para>
The matching rule is used to select a certificate to which the
mapping rule should be applied. It uses a system similar to the one
used by <quote>pkinit_cert_match</quote> option of MIT Kerberos. It
consists of a keyword enclosed by '<' and '>' which identified
a certain part of the certificate and a pattern which should be
found for the rule to match. Multiple keyword pattern pairs can be
either joined with '&&' (and) or '||' (or).
</para>
<para>
The available options are:
<variablelist>
<varlistentry>
<term><SUBJECT>regular-expression</term>
<listitem>
<para>
With this a part or the whole subject name of the
certificate can be matched. For the matching POSIX
Extended Regular Expression syntax is used, see regex(7)
for details.
</para>
<para>
For the matching the subject name stored in the
certificate in DER encoded ASN.1 is converted into a
string according to RFC 4514. This means the most
specific name component comes first. Please note that
not all possible attribute names are covered by RFC
4514. The names included are 'CN', 'L', 'ST', 'O',
'OU', 'C', 'STREET', 'DC' and 'UID'. Other attribute
names might be shown differently on different platform
and by different tools. To avoid confusion those
attribute names are best not used or covered by a
suitable regular-expression.
</para>
<para>
Example: <SUBJECT>.*,DC=MY,DC=DOMAIN
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ISSUER>regular-expression</term>
<listitem>
<para>
With this a part or the whole issuer name of the
certificate can be matched. All comments for
<SUBJECT> apply her as well.
</para>
<para>
Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><KU>key-usage</term>
<listitem>
<para>
This option can be used to specify which key usage
values the certificate should have. The following value
can be used in a comma separate list:
<itemizedlist>
<listitem><para>digitalSignature</para></listitem>
<listitem><para>nonRepudiation</para></listitem>
<listitem><para>keyEncipherment</para></listitem>
<listitem><para>dataEncipherment</para></listitem>
<listitem><para>keyAgreement</para></listitem>
<listitem><para>keyCertSign</para></listitem>
<listitem><para>cRLSign</para></listitem>
<listitem><para>encipherOnly</para></listitem>
<listitem><para>decipherOnly</para></listitem>
</itemizedlist>
</para>
<para>
A numerical value in the range of a 32bit unsigned
integer can be used as well to cover special use cases.
</para>
<para>
Example: <KU>digitalSignature,keyEncipherment
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><EKU>extended-key-usage</term>
<listitem>
<para>
This option can be used to specify which extended key
usage the certificate should have. The following value
can be used in a comma separated list:
<itemizedlist>
<listitem><para>serverAuth</para></listitem>
<listitem><para>clientAuth</para></listitem>
<listitem><para>codeSigning</para></listitem>
<listitem><para>emailProtection</para></listitem>
<listitem><para>timeStamping</para></listitem>
<listitem><para>OCSPSigning</para></listitem>
<listitem><para>KPClientAuth</para></listitem>
<listitem><para>pkinit</para></listitem>
<listitem><para>msScLogin</para></listitem>
</itemizedlist>
</para>
<para>
Extended key usages which are not listed above can be
specified with their OID in dotted-decimal notation.
</para>
<para>
Example: <EKU>clientAuth,1.3.6.1.5.2.3.4
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN>regular-expression</term>
<listitem>
<para>
To be compatible with the usage of MIT Kerberos this
option will match the Kerberos principals in the PKINIT
or AD NT Principal SAN as <SAN:Principal> does.
</para>
<para>
Example: <SAN>.*@MY\.REALM
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:Principal>regular-expression</term>
<listitem>
<para>
Match the Kerberos principals in the PKINIT or AD NT
Principal SAN.
</para>
<para>
Example: <SAN:Principal>.*@MY\.REALM
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:ntPrincipalName>regular-expression</term>
<listitem>
<para>
Match the Kerberos principals from the AD NT Principal
SAN.
</para>
<para>
Example: <SAN:ntPrincipalName>.*@MY.AD.REALM
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:pkinit>regular-expression</term>
<listitem>
<para>
Match the Kerberos principals from the PKINIT SAN.
</para>
<para>
Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:dotted-decimal-oid>regular-expression</term>
<listitem>
<para>
Take the value of the otherName SAN component given by
the OID in dotted-decimal notation, interpret it as
string and try to match it against the regular
expression.
</para>
<para>
Example: <SAN:1.2.3.4>test
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:otherName>base64-string</term>
<listitem>
<para>
Do a binary match with the base64 encoded blob against
all otherName SAN components. With this option it is
possible to match against custom otherName components
with special encodings which could not be treated as
strings.
</para>
<para>
Example: <SAN:otherName>MTIz
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:rfc822Name>regular-expression</term>
<listitem>
<para>
Match the value of the rfc822Name SAN.
</para>
<para>
Example: <SAN:rfc822Name>.*@email\.domain
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:dNSName>regular-expression</term>
<listitem>
<para>
Match the value of the dNSName SAN.
</para>
<para>
Example: <SAN:dNSName>.*\.my\.dns\.domain
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:x400Address>base64-string</term>
<listitem>
<para>
Binary match the value of the x400Address SAN.
</para>
<para>
Example: <SAN:x400Address>MTIz
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:directoryName>regular-expression</term>
<listitem>
<para>
Match the value of the directoryName SAN. The same
comments as given for <ISSUER> and <SUBJECT>
apply here as well.
</para>
<para>
Example: <SAN:directoryName>.*,DC=com
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:ediPartyName>base64-string</term>
<listitem>
<para>
Binary match the value of the ediPartyName SAN.
</para>
<para>
Example: <SAN:ediPartyName>MTIz
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:uniformResourceIdentifier>regular-expression</term>
<listitem>
<para>
Match the value of the uniformResourceIdentifier SAN.
</para>
<para>
Example: <SAN:uniformResourceIdentifier>URN:.*
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:iPAddress>regular-expression</term>
<listitem>
<para>
Match the value of the iPAddress SAN.
</para>
<para>
Example: <SAN:iPAddress>192\.168\..*
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><SAN:registeredID>regular-expression</term>
<listitem>
<para>
Match the value of the registeredID SAN as
dotted-decimal string.
</para>
<para>
Example: <SAN:registeredID>1\.2\.3\..*
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id='map'>
<title>MAPPING RULE</title>
<para>
The mapping rule is used to associate a certificate with one or more
accounts. A Smartcard with the certificate and the matching private
key can then be used to authenticate as one of those accounts.
</para>
<para>
Currently SSSD basically only supports LDAP to lookup user
information (the exception is the proxy provider which is not of
relevance here). Because of this the mapping rule is based on LDAP
search filter syntax with templates to add certificate content to
the filter. It is expected that the filter will only contain the
specific data needed for the mapping an that the caller will embed
it in another filter to do the actual search. Because of this the
filter string should start and stop with '(' and ')' respectively.
</para>
<para>
In general it is recommended to use attributes from the certificate
and add them to special attributes to the LDAP user object. E.g. the
'altSecurityIdentities' attribute in AD or the 'ipaCertMapData'
attribute for IPA can be used.
</para>
<para>
This should be preferred to read user specific data from the
certificate like e.g. an email address and search for it in the LDAP
server. The reason is that the user specific data in LDAP might
change for various reasons would would break the mapping. On the
other hand it would be hard to break the mapping on purpose for a
specific user.
</para>
<para>
The templates to add certificate data to the search filter are based
on Python-style formatting strings. They consists of a keyword in
curly braces with an optional sub-component specifier separated by a
'.' or an optional conversion/formatting option separated by a '!'.
Allowed values are:
<variablelist>
<varlistentry>
<term>{issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}</term>
<listitem>
<para>
This template will add the full issuer DN converted to a
string according to RFC 4514. If X.500 ordering (most
specific RDN comes last) an option with the '_x500'
prefix should be used.
</para>
<para>
The conversion options starting with 'ad_' will use
attribute names as used by AD, e.g. 'S' instead of 'ST'.
</para>
<para>
The conversion options starting with 'nss_' will use
attribute names as used by NSS.
</para>
<para>
The default conversion option is 'nss', i.e. attribute
names according to NSS and LDAP/RFC 4514 ordering.
</para>
<para>
Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}</term>
<listitem>
<para>
This template will add the full subject DN converted to
string according to RFC 4514. If X.500 ordering (most
specific RDN comes last) an option with the '_x500'
prefix should be used.
</para>
<para>
The conversion options starting with 'ad_' will use
attribute names as used by AD, e.g. 'S' instead of 'ST'.
</para>
<para>
The conversion options starting with 'nss_' will use
attribute names as used by NSS.
</para>
<para>
The default conversion option is 'nss', i.e. attribute
names according to NSS and LDAP/RFC 4514 ordering.
</para>
<para>
Example: (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{cert[!(bin|base64)]}</term>
<listitem>
<para>
This template will add the whole DER encoded certificate
as a string to the search filter. Depending on the
conversion option the binary certificate is either
converted to an escaped hex sequence '\xx' or base64.
The escaped hex sequence is the default and can e.g. be
used with the LDAP attribute 'userCertificate;binary'.
</para>
<para>
Example: (userCertificate;binary={cert!bin})
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_principal[.short_name]}</term>
<listitem>
<para>
This template will add the Kerberos principal which is
taken either from the SAN used by pkinit or the one used
by AD. The 'short_name' component represent the first
part of the principal before the '@' sign.
</para>
<para>
Example: (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_pkinit_principal[.short_name]}</term>
<listitem>
<para>
This template will add the Kerberos principal which is
given by then SAN used by pkinit. The 'short_name'
component represent the first part of the principal
before the '@' sign.
</para>
<para>
Example: (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_nt_principal[.short_name]}</term>
<listitem>
<para>
This template will add the Kerberos principal which is
given by then SAN used by AD. The 'short_name' component
represent the first part of the principal before the '@'
sign.
</para>
<para>
Example: (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_rfc822_name[.short_name]}</term>
<listitem>
<para>
This template will add the string which is stored in the
rfc822Name component of the SAN, typically an email
address. The 'short_name' component represent the first
part of the address before the '@' sign.
</para>
<para>
Example: (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_dns_name[.short_name]}</term>
<listitem>
<para>
This template will add the string which is stored in the
dNSName component of the SAN, typically a fully-qualified host name.
The 'short_name' component represent the first
part of the name before the first '.' sign.
</para>
<para>
Example: (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_uri}</term>
<listitem>
<para>
This template will add the string which is stored in the
uniformResourceIdentifier component of the SAN.
</para>
<para>
Example: (uri={subject_uri})
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_ip_address}</term>
<listitem>
<para>
This template will add the string which is stored in the
iPAddress component of the SAN.
</para>
<para>
Example: (ip={subject_ip_address})
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_x400_address}</term>
<listitem>
<para>
This template will add the value which is stored in the
x400Address component of the SAN as escaped hex
sequence.
</para>
<para>
Example: (attr:binary={subject_x400_address})
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}</term>
<listitem>
<para>
This template will add the DN string of the value which
is stored in the directoryName component of the SAN.
</para>
<para>
Example: (orig_dn={subject_directory_name})
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_ediparty_name}</term>
<listitem>
<para>
This template will add the value which is stored in the
ediPartyName component of the SAN as escaped hex
sequence.
</para>
<para>
Example: (attr:binary={subject_ediparty_name})
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>{subject_registered_id}</term>
<listitem>
<para>
This template will add the OID which is stored in the
registeredID component of the SAN as as dotted-decimal
string.
</para>
<para>
Example: (oid={subject_registered_id})
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id='domains'>
<title>DOMAIN LIST</title>
<para>
If the domain list is not empty users mapped to a given certificate
are not only searched in the local domain but in the listed domains
as well as long as they are know by SSSD. Domains not know to SSSD
will be ignored.
</para>
</refsect2>
</refsect1>
</refentry>
</reference>
|