What is a cert mapper?
----------------------

When an X509 Certificate is provided, there are no direct way to map
a cert to a login. With a certificate we can check validity and
revocation, but user mapping depends entirely on the certificate content.

So we need a configurable, stackable, and definable way to specify
cert-to-user mapping.

pam-pkcs11 cert mappers provides several functions:

1- Deduce a login from certificate
2- Test if a login and a certificate match
3- Look into the certificate for an specific data

Normal pam-pkcs11 login process involves the following procedures
    - Enter login
    - Ask for PIN
    - Open and validate certificate
    - Map certificate into an user (*)
    - Check if login and user matches (**)

An alternate way of working is by mean of not providing user name:
    - Detect if a card is inserted
    - Ask for PIN
    - Open and validate certificate
    - Map certificate into an user (*)
    - open session for deduced login

Last way needs an aditional pam-mkhomedir.so PAM module, that can
dinamically create an account.

Operations (*) and (**) are the reason for cert-mappers to exist.


Implementation of cert mappers in pam-pkcs11
--------------------------------------------

pam-pkcs11 implements cert mapper in form of several stackable modules.
Most of them are statically linked; those that depends on external
libraries are provided as dynamic loadable ones

You can add as many modules as desired, and the system will try all
of them in turn, until a match succeed, or end of list is reached.

the mapper list is defined in the configuration file:

pam-pkcs11 {
    ....
    mapper_list = mapper1 [ [[,] mapper2 ] ... ] ;

    mapper mapper1 {
        module = /path/to/module.so;
        [ additional mapper dependent options ]
    }
}

Unless you are going to use an internal (static) module with
default values, you should provide a entry for every declared mapper

"module" entry is mandatory: is tells pam_pkcs11 where to find the
dynamic library (or equals to "internal" if static module is used). 
Additional entries can be defined but are module dependent.


Provided Mappers
----------------

Actually pam_opensc provides the following mapper modules:

cn     - Assumes CN field on certificate to be the login name
		* When used as finder, the module returns the first CN field
		  found or NULL
		* When used as matcher, it parses the certificate and compare
		  all CN fields found against the provided login name, returning
		  OK if a match is found

file   - Parse a file to get a list of CN -> login pairs
		* When used as finder, retrieve first CN field on certificate,
		  and use it to read provided file to get a CN to login mapping
		* When used as matcher, maps every CN entry on the certificate
		  to a login, and compare this login with provided by PAM

pw     - Compare CN against getpwent() "login" or "gecos" fields to match
         user login
        * When used as finder use getpwent() system call to retrieve every
          users on the system. if pw_name or pw_gecos fields match with CN
          pw_name is returned as login name
        * When used as matcher, maps CN to an user with via the finder
          and matches result with login name provided by PAM, returning the
          result (match or not)

        Note: newer implementations of getpwent() libraries, use an
        additional Name Service Switch (NSS) infrastructure, that
        allows admins to specify how to obtain the requested data.
        This means you can setup /etc/nsswitch.conf password entries
        to lookup in to /etc/passwd, or ldap/kerberos/NIS+/YP services

ldap   - Uses an ldap server to retrieve user name. An aditional file tells
         module the mapping between Cert fields and LDAP entries

        This mapper is still under development. Provided one just search
	for certificates, incoming one will ask for "any" certificate
	content

opensc - Search the certificate ${HOME}/.ssh/autorized_certificates 
	in a similar way as OpenSC does.

openssh - Search the certificate public key in
	 ${HOME}/.ssh/autorized_keys in a similar way as OpenSSH does.

mail   - Try to extract an e-mail from the certificate. If found,
         analyze it against an "aliases" (email to login) list

        if "use_alias" is set an aliases file is provided, the module 
        tries to map the email field from the certificate to a user 
        (or alternate email).

        if use_alias is not set, just use email addres from certificate
        to perform find/match.

        * When used as finder, just return email or mapped email/user
          (see above)
		* When used as matcher, compare found email/user against
		  provided by pam. Additionaly you can set "ignorecase" or
		  "ignoredomain" flags

        domain check (if set) is done by testing if provided email domain
        part (@ie.this.domain) matches host domain. 
        Eg "user@my.company.com" email in host "ahost.in.my.company.com" 
        host matches domain

       (NOTE: at version 0.4.1 use_alias is still under development)

ms     - Try to find and use Microsoft Universal Principal Name extension 
         as login name
        * When used as finder, returns UPN as login name
        * when used as matcher compares UPN against PAM provided login

krb    - Try to find and use Kerberos Principal Name as login name

uid    - Use Unique ID field (if found) as login name

        Similar to CN mapper, but using UID as field to find/match

null   - blind access/deny mapper. 

        If "allways_match" is set to true:
        * When used as finder allways returns "nobody"
        * When used as matcher allways returns OK

        If "allways_match" is set to false:
        * When used as finder allways returns NULL
        * When used as matcher allways returns FAIL

See the provided pam_pkcs11.conf.example file to see module flags


Adding new mappers
------------------

Creating new mappers is easy: just read provided Mapper API file, 
edit skeleton sample files and follow instructions on how to compile
and link

Mapper.h provides default implementation for required some functions. 
They should be overriden by user code, but can be used for testing purposes

Wish list
---------

- Implement PKINIT draft protocol for talking to a kerberos server
- Use MS Universal Principal Name to autenticate against an MS Active
  directory server
- Implement mail_aliases parsing for mail mapper module

Further information
-------------------
Please, send mail with patches, comments and suggestions to
Juan Antonio Martinez <jonsito@teleline.es> or even better, to
OpenSC development mailing list opensc-devel@list.opensc.org