The PKCS #11 modules must full-fit the requirements given by the RSA Asymmetric Client Signing Profile, which has been specified in the PKCS #11: Conformance Profile Specification by RSA Laboratories.

To approve the ownership of a certificate, that is, to allow the owner of a certificate to login as a particular user, pam-pkcs11 uses several modules called mappers that perform cert-to-login mapping. See Chapter 12, What is a cert mapper? section.

[Note: This is still a work in progress, any suggestions for improvements or alternative matching algorithms are welcome.]

The configuration file uses the scconf library.

Parameters and data are grouped into blocks. Blocks can be nested in a tree.

A pam-pkcs11 configuration file looks like:

pam-pkcs11 {
	global options
	...
	use_pkcs11_module = pkcs11 module to be used

	pkcs11_module module1 {
		module1 specific options
	}

	pkcs11_module module2 {
		module2 specific options
	}

	[...]

	use_mappers = mapper1, mapper2,... ; 

	mapper mapper1 {
		mapper1 specific options
	}

	mapper mapper2 {
		mapper2 specific options
	}

	[...]
	mapper mapperN {
		mapperN specific options
	}
}

For detailed description see the pam_pkcs11.conf.example file.

Details on scconf syntax and API are provided in the src/scconf/README.scconf file.

pam-pkcs11 needs a list of recognized Certificate Authorities, to properly validate user certificates. The same applies to Certificate Revocation Lists (if configured to be used).

So the process to setup ca and crl entries is:

NOTE: Due to OpenSSL library limitations, CA root certificate entries must reside in the local file system, and cannot be accessed from a remote server. So although user auth can be done in a remote way, certificate trust chain validation must be done locally.

If your selected mapper module(s) use(s) login mapping, you'll need to create and setup mapping files. Some examples are provided with the source code.

As a general rule, a mapping file has a new line terminated list of certificate contents -> login entries:

Certificate1 data -> login1
Certificate2 data -> login2
Certificate2 data -> login3

Remember that this file is parsed from the first line to the end, and returns on the first match.

As you can see bellow, mapfile specification doesn't need to be a regular file: you can retrieve data from any legal URL. Anyway, data format must be preserved. See Section 12.3, “How to use mapfiles” for additional info.

To make use of the PKCS #11 login module add the line

auth	sufficient	pam_pkcs11.so	...

in the /etc/pam.d/serviceXXX configuration file.

Some mappers doesn't map to an existing user. To allow correct login, you may need to install also pam-mkhomedir in session PAM stack See http://www.kernel.org/pub/linux/libs/pam for details.

The following options are recognized by pam-pkcs11.so:

The next options should be taken from the configuration file (default /etc/pam_pkcs11/pam_pkcs11.conf), but is up to the user to specify them in the command line. If so, it takes precedence over the configuration file.

Next options are PKCS #11 module specific:

Here is the normal way to use pam-pkcs11 into the PAM stack. Only the first auth line is added. You configuration may be different depending on your Unix system.

#%PAM-1.0
auth       sufficient   pam_pkcs11.so
auth       required     pam_securetty.so
auth       required     pam_stack.so service=system-auth
auth       required     pam_nologin.so
account    required     pam_stack.so service=system-auth
password   required     pam_stack.so service=system-auth
session    required     pam_stack.so service=system-auth
session    optional     pam_console.so

An alternate way is to use explicit options. This is not recommended, but still possible:

#%PAM-1.0
auth       sufficient    pam_pkcs11.so	nullok debug try_first_pass \
             config_file=/etc/pam_pkcs11/pam_pkcs11.conf \
             pkcs11_module=/usr/lib/pkcs11/pkcs11_module.so \
             ca_dir=/etc/cacerts/ crl_dir=/etc/cacerts/ cert_policy=none
auth       required     pam_securetty.so
auth       required     pam_stack.so service=system-auth
auth       required     pam_nologin.so
account    required     pam_stack.so service=system-auth
password   required     pam_stack.so service=system-auth
session    required     pam_stack.so service=system-auth
session    optional     pam_console.so

In this second example the configuration file is still needed to get the mapper module options and flags.

card_eventmgr is a card status monitor based on the PCSC-Lite library.

To invoke the program, just type card_eventmgr. Several command lines options are recognized:

card_eventmgr {

	# Run in background? Implies debug=false if set to true
	daemon = false;

	# show debug messages?
	debug = false;

	# polling time in milliseconds
	timeout = 1000;

	#
	# list of events and actions

	# Card inserted
	event card_insert {
		# what to do if an action fail?
		# ignore  : continue to next action
		# return  : end action sequence
		# quit    : end program
		on_error = ignore ;

		# You can enter several, comma-separated action entries
		# they will be executed in turn
		action = "/usr/bin/play /usr/share/sounds/warning.wav",
			"/usr/X11R6/bin/xscreensaver-command -deactivate";
	}

	# Card has been removed
	event card_remove { 
		on_error = ignore;
		action = "/usr/bin/play /usr/share/sounds/error.wav",
			"/usr/X11R6/bin/xscreensaver-command -lock";
	}
}

pkcs11_eventmgr is very similar to card_eventmgr, with some improvements:

Here is a pkcs11_cardmgr sample file, with defaults

# Sample pkcs11_eventmgr configuration file
#
pkcs11_eventmgr {

	# Run in background? Implies debug=false if true
	daemon = true;

	# show debug messages?
	debug = false;
	
	# polling time in seconds
	polling_time = 1;

	# expire time in seconds
	# default = 0 (no expire)
	expire_time = 0;
	
	# pkcs11 module to use
	pkcs11_module = /usr/lib/opensc-pkcs11.so;

	#
	# list of events and actions

	# Card inserted
	event card_insert {
		# what to do if an action fail?
		# ignore  : continue to next action
		# return  : end action sequence
		# quit    : end program
		on_error = ignore ;

		# You can enter several, comma-separated action entries
		# they will be executed in turn
		action = "/usr/bin/play /usr/share/sounds/warning.wav",
			 "/usr/X11R6/bin/xscreensaver-command -deactivate";
	}

	# Card has been removed
	event card_remove { 
		on_error = ignore;
		action = "/usr/bin/play /usr/share/sounds/error.wav",
			 "/usr/X11R6/bin/xscreensaver-command -lock";
	}

	# Too much time card removed
	event expire_time { 
		on_error = ignore;
		action = "/bin/false";
	}
}

As you can see, on each event you can define a list of actions, and what to do if an action fails.

The best way to start card monitoring is at user login. If so, note that all event commands will be executed with user privileges. So it is up to the user to take care that he has permissions to execute the desired actions.

Special checks should be done when invoking setuid/segid programs: these commands usually ignore the user environment and set up their own. So these applications may not work as expected.

Command actions are executed via execve("/bin/sh","-c","provided command",null,environ) in order to avoid security risks if using system() library call.

Just add to your ~/.xsession or KDE/GNOME Autostart directory an invocation to card_eventmgr in daemon mode. Your ~/.xsession should look like: FIXME

Additionally you can add this line to /etc/pam.d/xscreensaver configuration file:

auth       sufficient   pam_pkcs11.so

In this case, when card is removed the X screen will lock. When card is re-inserted, screen will prompt for the card PIN, check it and if access granted the screen will unlock

NOTES:

You should install pre-compiled binaries since that is the easiest way to install a software. See the documentation of your distribution to know how to install RPM, DEB or whatever packages.

If you want to recompile from source read Chapter 4, Installation.

You will now configure your PAM system to use pam_pkcs11. We recommend you to start with an easy-to-debug application like login. The advantage of login is that you can see the debug messages from pam_pkcs11.

Edit /etc/pam.d/login and add, at the beginning of the file, the lines:

# pam_pkcs11: smart card login
auth       sufficient pam_pkcs11.so

Since /etc/pam_pkcs11/pam_pkcs11.conf has "debug = true" you should see lots of debug on the console you use to log in. You should also see any error that would occur. If everything works correctly you can change the configuration file and use "debug = false".

Once your PAM configuration is tested and working you can configure all the PAM applications you want to use with a smart card. A possible list is:

We used "sufficient" in the PAM configuration file. If the pam_pkcs11 module fails to authenticate the user the PAM system will go on with the next PAM module, the next PAM module should ask for a password. If you want to use the smart card only and not the password any more just replace "sufficient" by "required". The authentication process will then fail if pam_pkcs11 fails.

Note: with the "required" option, if there is a bug in any smart card related software you will not be able to log in even as root. It should be safer to keep the possibility to log in using a password but at the same time disable password login for normal users. So you will still be able to login as root with the root password.

card_eventmgr is a helper tool to automatically launch an application to lock or unlock the screen when the card is removed or inserted. A natural application is to lock the X11 screen when the card is removed.

Copy the sample file:

cp /usr/share/doc/pam-pkcs11/examples/card_eventmgr.conf.example /etc/pam_pkcs11/card_eventmgr.conf

Edit the configuration file to set the actions to be processes when the card is removed and inserted. You may have to change the command to play a sound.

You can now test your card_eventmgr configuration file by executing

card_eventmgr debug nodaemon

You will see some debug messages and, possibly, why the command you configured as action does not work properly.

After debugging your card_eventmgr configuration file you can start it automatically. One solution is to create a ~/.xsession file containing:

# start the card autolock
card_eventmgr pidfile=$HOME/.card_eventmgr.pid

# start Gnome or something else
/usr/bin/x-session-manager

# kill the card autolock
card_eventmgr kill pidfile=$HOME/.card_eventmgr.pid

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

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

pam-pkcs11 cert mappers provides several functions to:

Normal pam-pkcs11 login process involves following procedures:

An alternate way of working is by mean of not providing user name:

Last way needs an additional pam-mkhomedir.so PAM module, which can dynamically create an account.

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

pam-pkcs11 implements cert mapper in form of dynamic loaded modules. Additionally, most of simplest mappers doesn't need to be dynamically loaded, as they are already statically linked with pam-pkcs11. You can add as many modules as desired, and the system will try all of them in turn, until match is done, or end of list get reached.

The mapper list is defined in the configuration file:

pam-pkcs11 {
....
    use_mappers = mapper1 [ [[,] mapper2 ] ... ] ;
    ....
    mapper mapper1 {
	debug = false;
	# When the mapper module is to be dynamically loaded, specify path
	module = /path/to/module.so;
	# When the mapper module is statically linked set to "internal"
	# module = internal;
	[ additional mapper dependent options ]
    }
    ....
}

"module" option is mandatory: says pam_pkcs11 where to find dynamic library. Additional entries can be defined but are module dependent

Most of mappers supports the concept of mapfile, that is, a system to convert a given certificate data item to a user login. The reasons are simple:

The mapfile scheme used in pam-pkcs11 is powerful: it's not only restricted to files, so we can specify HTTP, LDAP, FTP and so connections, to retrieve mapfile. So this scheme is ideal for centralized accounting systems.

The common structure of all mapfiles is:

Certificate 1 entry data -> login1
Cert 2 data -> login2
string from -> string to

That is: a string, the sequence " -> " (space, dash, greater, space) and a login

NOTE: It's syntactically correct to specify more than one word in the right side of a map entry. But be aware that most mappers expect to be returned a single word that provides a user login. Otherwise a strange behavior may occur. See specific notes on mappers.

When a mapper module uses mapfiles, has a structure like:

...
mapper my_mapper {
	...
	mapfile = URL;
}
...

URL is a Universal Resource Locator as defined in corresponding RFC:

Note that depending on compile time options pam-pkcs11 may not support all URL syntax. See Install section and use of --use-curl configure option

Provided source code includes several example mapping files

The standard pam-pkcs11 provides following mapper modules:

  # Common Name (CN) to login mapper
  mapper cn {
        debug = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/cn_mapper.so;
	# mapfile = "file:///etc/pam_pkcs11/cn_mapfile;
	ignorecase = false;
	mapfile = "none"
  }

 # Certificate Subject to login mapper
  mapper file {
        debug = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/subject_mapper.so;
	ignorecase = true;
	# mapfile = file:///etc/pam_pkcs11/subject_map;
        mapfile = "none";
  }

....
Certificate Subject -> login
....

  mapper pw {
        debug = true;
        ignorecase = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/pw_mapper.so;
  }

  # Directory ( ldap style ) mapper
  mapper ldap {
        debug = false;
        module = /usr/lib/pam_pkcs11/ldap_mapper.so;
        ldaphost = "";
        ldapport = ;
        URI = "";
        scope = 2;
        binddn = "cn=pam,o=example,c=com";
        passwd = "";
        base = "ou=People,o=example,c=com";
        attribute = "userCertificate";
        filter = "(&(objectClass=posixAccount)(uid=%s))"
        uid_attribute = "uid";
        attribute_map = "uid=uid&mail=email", "krbprincipalname=upn";
        # SSL/TLS-Settings
        ssl = tls
        # tls_randfile = ...
        tls_cacertfile = /etc/ssl/cacert.pem
        # tls_cacertdir = ...
        tls_checkpeer = 0
        #tls_ciphers = ...
        #tls_cert = ...
        #tls_key = ...
  }

  mapper openssh {
        debug = false;
        module = /usr/lib/pam_pkcs11/openssh_mapper.so;
  }

  mapper mail {
        debug = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/mail_mapper.so;
        # MapFile to use
        mapfile = file:///etc/pam_pkcs11/mail_mapping;
        # Some certs store email in uppercase. Take care on this
        ignorecase = true;
        # Also check that host matches mx domain
        ignoredomain = false;
  }

  mapper ms {
        debug = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/ms_mapper.so;
        ignorecase = false;
        ignoredomain = false;
	domainname = "domain.com";
  }

  mapper krb {
        debug = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/krb_mapper.so;
	ignorecase = false;
	mapfile = "none";
  }

  mapper uid {
        debug = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/uid_mapper.so;
	ignorecase = false;
	mapfile = "none";
  }

  mapper digest {
        debug = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/digest_mapper.so;
	# Algorithm used to evaluate certificate digest
        # Select one of:
        # "null","md2","md4","md5","sha","sha1","dss","dss1","ripemd160"
        algorithm = "sha1";
        mapfile = file:///etc/pam_pkcs11/digest_map;
  }

  mapper generic {
        debug = true;
	module = internal;
        # module = /usr/lib/pam_pkcs11/generic_mapper.so;
	# ignore letter case on match/compare
        ignorecase = false;
	# Use one of "cn" , "subject" , "kpn" , "email" , "upn" , "uid" or "serial"
	cert_item  = cn;
	# Declare mapfile if needed, else select "none"
	mapfile = file:///etc/pam_pkcs11/generic_mapfile
	# Decide if use getpwent() to map login
	use_getpwent = false;
  }

  mapper null {
        debug = false;
	module = internal;
        # module = /usr/lib/pam_pkcs11/null_mapper.so;
        # select behaviour: always match, or always fail
        default_match = false;
	# on match, select returned user
	default_user = nobody;
  }

Creating new mappers is easy: just retrieve and study the PAM-PKCS#11 Mapper API reference Manual

You'll find sample code, compiling instructions, and a complete list of provided library calls