Standards, Environments, and Macros pam_pkcs11(5)
NAME
pam_pkcs11 - PAM Authentication Module for the PKCS#11 token
librariesSYNOPSIS
pam_pkcs11.so [debug] [config_file=filename]
DESCRIPTION
The pam_pkcs11 module implements pam_sm_authenticate(3PAM),
which provides functionality to the PAM authentication stack. This module allows a user to login a system, using a X.509 certificate and its dedicated private key stored in aPKCS#11 token. This module currently supports the RSA algo-
rithm only. To verify the dedicated private key is truly associated with the X.509 certificate, the following verification procedure is performed in this module by default: o Generate 128 random byte data o Sign the random data with the private key and get asignature. This step is done in the PKCS#11 token.
o Verify the signature using the public key extracted from the certificate. For the verification of the users' certificates, locally stored CA certificates as well as either online or locally accessible CRLs are used. PAM CONFIGURATIONThe pam_pkcs11.so service module can be used in the
PAM chain. The program that needs a PAM service should be configured in the /etc/pam.conf file. For details on how to configure PAM services, see pam.conf(4).The following example uses only pam_pkcs11 for authentica-
tion:login auth requisite pam_pkcs11.so.1
login autho required pam_unix_cred.so.1
The following example uses pam_pkcs11 for authentication
with fallback to standard UNIX authentication:SunOS 5.11 Last change: 21 Jul 2008 1
Standards, Environments, and Macros pam_pkcs11(5)
login auth sufficient pam_pkcs11.so.1
login auth requisite pam_authtok_get.so.1
login auth required pam_dhkeys.so.1
login auth required pam_unix_cred.so.1
login auth required pam_unix_auth.so.1
PAM_PKCS11 CONFIGURATION
To configure the pam_pkcs11 module, you must have the fol-
lowing information:o Which PKCS #11 token you are going to use
o Which mapper(s) you need, and if needed, how to create and edit the related mapping files o The root Certificate Authority files, and if required, the Certificate Revocation Lists files o The list of authorized users to login, and their corresponding certificatesTo configure the pam_pkcs11 module, you need to modify the
pam_pkcs11.conf configuration file which is in the
/etc/security/pam_pkcs11 directory by default. For detailed
information on how to configure the pam_pkcs11 module, see
the PAM-PKCS11 User Manual, available at the
http://www.opensc-project.org/ web site, under the PAM
PKCS#11 link.
The following example illustrates how to configure thepam_pkcs11 module for a user whose certificate and private
key are stored in the Solaris pkcs11_softtoken keystore.
This example uses the default certificate verification pol-
icy.o Set up the PKCS#11 module.
On Solaris, the PKCS#11 module should be set to
/usr/lib/libpkcs11.so.1, the PKCS#11 Cryptographic
Framework library.o Set up the slot_description entry.
Specifies the slot to be used. For example,slot_description = "Sun Crypto Softtoken". The
default value for this entry is none which means to use the first slot with an available token. An administrator can use the cryptoadm listSunOS 5.11 Last change: 21 Jul 2008 2
Standards, Environments, and Macros pam_pkcs11(5)
-vcommand to find all the available slots and their
slot descriptions. For more information, see libpkcs11(3LIB) and cryptoadm(1M).o Install or create user certificates and its dedi-
cated private keys in the specific PKCS#11 token.
o Set up the certificate verification policy(cert_policy). If needed, set up CA certificate and
CRL files. The certificate verification policy includes: none Perform no verification ca Perform CA check signature Perform a signature check to ensure that private and public key matchescrl_xxx Perform various certificate revocation
checkingAs this example uses the default policy, cert_policy =
ca,signature, an administer needs to set up the CA cer-
tificates. o Copy the CA certificate to the/etc/security/pam_pkcs11/cacerts directory.
A certificate that is self-signed is its own CA
certificate. Therefore, in this example, the certificate is placed both in the Softtoken keystore and in the CA certificate directory. o Make hash links for CA certificates$ /etc/security/pam_pkcs11/make_hash_link.sh \
/etc/security/pam_pkcs11/cacerts
o Set up the mappers and mapfiles. When a X509 certificate is provided, there are no direct ways to map a certificate to a login. Thepam_pkcs11 module provides a configurable way with
SunOS 5.11 Last change: 21 Jul 2008 3
Standards, Environments, and Macros pam_pkcs11(5)
mappers to specify cert-to-user mapping.
Many mappers are provided by the pam_pkcs11 module,
for example, the common name (CN) mapper, the dig-
est mapper, the Email mapper, or the LDAP mapper. A user can configure a mapper list in thepam_pkcs11.conf file. The mappers in the list are
used sequentially until the certificate is success-
fully matched with the user. The default mapper list is as follows:use_mappers = digest, cn, pwent, uid, mail, subject, null;
Some mappers do not require the specification of a mapfile, for example, the common name mapper. Other mappers require mapfiles, for example, the digest mapper. Some sample mapping files can be found inthe /etc/security/pam_pkcs11 directory.
OPTIONS The following options are supported:config_file=filename Specify the configuration file. The
default value is/etc/security/pam_pkcs11/pam_pkcs11.conf.
debug Enable debugging output. FILES/usr/lib/security/pam_pkcs11.so
pam_pkcs11 module
/usr/lib/pam_pkcs11/ldap_mapper.so
Mapper module./usr/lib/pam_pkcs11/opensc_mapper.so
Mapper module./usr/lib/pam_pkcs11/openssh_mapper.so
Mapper module.SunOS 5.11 Last change: 21 Jul 2008 4
Standards, Environments, and Macros pam_pkcs11(5)
/etc/security/pam_pkcs11/pam_pkcs11.conf
Configuration file./etc/security/pam_pkcs11/cacerts
Configuration directory. Stores the CA certificates./etc/security/pam_pkcs11/crls
Configuration directory. Stores the CRL files./etc/security/pam_pkcs11/digest_mapping.example
Sample mapfile./etc/security/pam_pkcs11/subject_mapping.example
Sample mapfile./etc/security/pam_pkcs11/mail_mapping.example
Sample mapfile./etc/security/pam_pkcs11/make_hash_link.sh
Sample script. AUTHORSPAM-pkcs11 was originally written by MarioStrasser ,
mast@gmx.net. Newer versions are from Juan Antonio Martinez, jonsito@teleline.esATTRIBUTES
See attributes(5) for a description of the following attri-
butes:SunOS 5.11 Last change: 21 Jul 2008 5
Standards, Environments, and Macros pam_pkcs11(5)
________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| ____________________________|_________________________________|_
| Availability | library/security/pam/module/pam-|
| | pkcs11, SUNWpampkcs11r, || | SUNWpampkcs11-docs |
|_____________________________|_________________________________|
| Interface Stability | Uncommitted ||_____________________________|_________________________________|
SEE ALSO
pkcs11_inspect(1), pklogin_finder(1), cryptoadm(1M),
libpkcs11(3LIB)libpkcs11(3LIB)pam_sm_authenticate(3PAM),
pam.conf(4), attributes(5), pkcs11_softtoken(5)
PAM-PKCS11 User Manual, available at the http://www.opensc-
project.org/ web site, under the PAM PKCS#11 link.
SunOS 5.11 Last change: 21 Jul 2008 6