| 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 |
|