Debian Codegraph @

doc/README.mappers

raw
1 What is a cert mapper?
2 ----------------------
3
4 When an X509 Certificate is provided, there are no direct way to map
5 a cert to a login. With a certificate we can check validity and
6 revocation, but user mapping depends entirely on the certificate content.
7
8 So we need a configurable, stackable, and definable way to specify
9 cert-to-user mapping.
10
11 pam-pkcs11 cert mappers provides several functions:
12
13 1- Deduce a login from certificate
14 2- Test if a login and a certificate match
15 3- Look into the certificate for an specific data
16
17 Normal pam-pkcs11 login process involves the following procedures
18 - Enter login
19 - Ask for PIN
20 - Open and validate certificate
21 - Map certificate into an user (*)
22 - Check if login and user matches (**)
23
24 An alternate way of working is by mean of not providing user name:
25 - Detect if a card is inserted
26 - Ask for PIN
27 - Open and validate certificate
28 - Map certificate into an user (*)
29 - open session for deduced login
30
31 Last way needs an additional pam-mkhomedir.so PAM module, that can
32 dynamically create an account.
33
34 Operations (*) and (**) are the reason for cert-mappers to exist.
35
36
37 Implementation of cert mappers in pam-pkcs11
38 --------------------------------------------
39
40 pam-pkcs11 implements cert mapper in form of several stackable modules.
41 Most of them are statically linked; those that depends on external
42 libraries are provided as dynamic loadable ones
43
44 You can add as many modules as desired, and the system will try all
45 of them in turn, until a match succeed, or end of list is reached.
46
47 the mapper list is defined in the configuration file:
48
49 pam-pkcs11 {
50 ....
51 mapper_list = mapper1 [ [[,] mapper2 ] ... ] ;
52
53 mapper mapper1 {
54 module = /path/to/module.so;
55 [ additional mapper dependent options ]
56 }
57 }
58
59 Unless you are going to use an internal (static) module with
60 default values, you should provide a entry for every declared mapper
61
62 "module" entry is mandatory: is tells pam_pkcs11 where to find the
63 dynamic library (or equals to "internal" if static module is used).
64 Additional entries can be defined but are module dependent.
65
66
67 Provided Mappers
68 ----------------
69
70 Actually pam_opensc provides the following mapper modules:
71
72 cn - Assumes CN field on certificate to be the login name
73 * When used as finder, the module returns the first CN field
74 found or NULL
75 * When used as matcher, it parses the certificate and compare
76 all CN fields found against the provided login name, returning
77 OK if a match is found
78
79 file - Parse a file to get a list of CN -> login pairs
80 * When used as finder, retrieve first CN field on certificate,
81 and use it to read provided file to get a CN to login mapping
82 * When used as matcher, maps every CN entry on the certificate
83 to a login, and compare this login with provided by PAM
84
85 pw - Compare CN against getpwent() "login" or "gecos" fields to match
86 user login
87 * When used as finder use getpwent() system call to retrieve every
88 users on the system. if pw_name or pw_gecos fields match with CN
89 pw_name is returned as login name
90 * When used as matcher, maps CN to an user with via the finder
91 and matches result with login name provided by PAM, returning the
92 result (match or not)
93
94 Note: newer implementations of getpwent() libraries, use an
95 additional Name Service Switch (NSS) infrastructure, that
96 allows admins to specify how to obtain the requested data.
97 This means you can setup /etc/nsswitch.conf password entries
98 to lookup in to /etc/passwd, or ldap/kerberos/NIS+/YP services
99
100 ldap - Uses an ldap server to retrieve user name. An additional file tells
101 module the mapping between Cert fields and LDAP entries
102
103 This mapper is still under development. Provided one just search
104 for certificates, incoming one will ask for "any" certificate
105 content
106
107 opensc - Search the certificate ${HOME}/.ssh/autorized_certificates
108 in a similar way as OpenSC does.
109
110 openssh - Search the certificate public key in
111 ${HOME}/.ssh/autorized_keys in a similar way as OpenSSH does.
112
113 mail - Try to extract an e-mail from the certificate. If found,
114 analyze it against an "aliases" (email to login) list
115
116 if "use_alias" is set an aliases file is provided, the module
117 tries to map the email field from the certificate to a user
118 (or alternate email).
119
120 if use_alias is not set, just use email address from certificate
121 to perform find/match.
122
123 * When used as finder, just return email or mapped email/user
124 (see above)
125 * When used as matcher, compare found email/user against
126 provided by pam. Additionally you can set "ignorecase" or
127 "ignoredomain" flags
128
129 domain check (if set) is done by testing if provided email domain
130 part (@ie.this.domain) matches host domain.
131 Eg "[email protected]" email in host "ahost.in.my.company.com"
132 host matches domain
133
134 (NOTE: at version 0.4.1 use_alias is still under development)
135
136 ms - Try to find and use Microsoft Universal Principal Name extension
137 as login name
138 * When used as finder, returns UPN as login name
139 * when used as matcher compares UPN against PAM provided login
140
141 krb - Try to find and use Kerberos Principal Name as login name
142
143 uid - Use Unique ID field (if found) as login name
144
145 Similar to CN mapper, but using UID as field to find/match
146
147 null - blind access/deny mapper.
148
149 If "always_match" is set to true:
150 * When used as finder always returns "nobody"
151 * When used as matcher always returns OK
152
153 If "always_match" is set to false:
154 * When used as finder always returns NULL
155 * When used as matcher always returns FAIL
156
157 See the provided pam_pkcs11.conf.example file to see module flags
158
159
160 Adding new mappers
161 ------------------
162
163 Creating new mappers is easy: just read provided Mapper API file,
164 edit skeleton sample files and follow instructions on how to compile
165 and link
166
167 Mapper.h provides default implementation for required some functions.
168 They should be overridden by user code, but can be used for testing purposes
169
170 Wish list
171 ---------
172
173 - Implement PKINIT draft protocol for talking to a kerberos server
174 - Use MS Universal Principal Name to authenticate against an MS Active
175 directory server
176 - Implement mail_aliases parsing for mail mapper module
177
178 Further information
179 -------------------
180 Please, send mail with patches, comments and suggestions to
181 Juan Antonio Martinez <[email protected]> or even better, to
182 OpenSC development mailing list [email protected]
183