PAM-PKCS11 User Manual

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 ^[6] 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-loggin mapping. See Chapter 11, What is a cert mapper? section

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

Configuration file is based on the scconf library

Parameters and data are grouped into blocks. blocks can be nested in a sort of XML tree

pam-pkcs11 config 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 pam_pkcs11.conf.example file

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

PAM-pkcs11 needs a list of recognized Certificate authorities, to properly validate certificates. Same applies to Certificate Revocation Lists (if configured to use)

So the process to setup ca and crl entries is:

NOTE: Due to OpenSSL library limitations, CA entries must reside in the local filesystem, and can not be accessed from a remote server. So althought user auth can be done in a remote way, certificate validation must be done locally.

If your elected mapper module(s) uses login mapping, you'll need to create and setup mapping files. Some examples are provided in source code.

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

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

Remember that this file is parsed in order, returning on 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 the section called “How to use mapfiles” for additional info

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

auth	requisite	pam_unix2.so	...

with

auth	sufficient	pam_pkcs11.so	...

in the pam.d/serviceXXX configuration files.

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 recognised for pam-pkcs11.so:

Next options should be taken from configuration file, but is up to the user to specify them from command line. If so, it takes precedence over configuration file

Next options are pkcs11 module specific:

Here comes preferred way to insert pam-pkcs11 into pam stack:

[jantonio@jonsy pkcs11_login-0.4.1]$ cat /etc/pam.d/login
#%PAM-1.0
auth       sufficient    pam_pkcs11.so debug config_file=/etc/pkcs11/pam_pkcs11.conf
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 explicite options. This is not recommended, but still possible:

#%PAM-1.0
auth	sufficient	pam_pkcs11.so	nullok debug try_first_pass \
	config_file=/etc/pkcs11/pam_pkcs11.conf \
	pkcs11_module=/usr/lib/pkcs11/pkcs11_module.so \
	ca_dir=/etc/cacerts/ crl_dir=/etc/cacerts/ crl_policy=auto
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, configuration file is still needed to get 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 are recognized:

card_eventmgr {

	# Run in background.
	daemon = false;
	# show debug messages
	debug = false;
	# polling time in mili-seconds
	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";
	}
}

Starting pam-pkcs11-0.4.4 a new eventmgr tool is provided: pkcs11_eventmgr. It's very similar to card_eventmgr, with some improvements:

Here comes pkcs11_cardmgr sample file, with defaults

# Sample pkcs11_eventmgr configuration file
#
pkcs11_eventmgr {

	# Run in background. Implies debug=false
	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/pkcs11/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 into system. If so, note that all event commands will be executed with user privileges. So is up to the user take care that has permissions to execute desired actions

Special checks should be done when invoke setuid/segid programs: these commands usually ignore the user environment and set up their one. 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 risk on system() library call

You can use provided configuration sample file. Just add to your .xsession or KDE/GNOME Autostart directory an invocation to card_eventmgr in daemon mode

Additionally you can add this entry to /etc/pam.d/xscreensaver configuration

#%PAM-1.0

# Red Hat says this is right for them, as of 7.3:
auth       sufficient    pam_pkcs11.so debug config_file=/etc/pkcs11/pam_pkcs11.conf
auth       required	pam_stack.so service=system-auth

# This is what we were using before:
# auth       required	pam_pwdb.so shadow nullok

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:

When a X509 Certificate is providen, 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 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 aditional pam-mkhomedir.so PAM module, that can dinamically create an account

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

pam-pkcs11 implements cert mapper in form of dinamyc loaded modules. 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;
	module = /path/to/module.so;
	[ 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 reason are simple:

The mapfile scheme used in pam-pkcs11 is powerfull: 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,great,space) and a login

NOTE: It's sintactically 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 extrange behaviour may occur. See specific notes on mappers

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

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

URL is an 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 = /usr/lib/pam_pkcs11/cn_mapper.so;
	# mapfile = "file:///etc/pkcs11/cn_mapfile;
	ignorecase = false;
	mapfile = "none"
  }

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

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

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

  mapper mail {
        debug = false;
        module = /usr/lib/pam_pkcs11/mail_mapper.so;
        # MapFile to use
        mapfile = file:///etc/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 = /usr/lib/pam_pkcs11/ms_mapper.so;
        ignorecase = false;
        ignoredomain = false;
	domainname = "domain.com";
  }

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

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

  mapper digest {
        debug = false;
        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/pkcs11/digest_map;
  }

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

Creating new mappers is easy: just study mapper.h file, provide a file that exports required functions, and modify file src/mappers/Makefile.am

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

You can start by using provided src/mappers/generic_mapper.c skeleton file. Just rename, edit, set Makefile.am properly, and recompile