'\" te

.\" Portions Copyright (c) 2008, 2012, Oracle and/or its affiliates. All rights reserved.

.\" This manual page is derived from documentation obtained from the OpenSC organization (www.opensc-project.org). This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it is useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

.TH pam_pkcs11 5 "22 May 2012" "SunOS 5.12" "Standards, Environments, and Macros"

.SH NAME

pam_pkcs11 \- PAM Authentication Module for the PKCS#11 token libraries

.SH SYNOPSIS

.LP

.nf

\fBpam_pkcs11.so\fR [debug] [config_file=\fIfilename\fR]

.fi

.SH DESCRIPTION

.sp

.LP

The \fBpam_pkcs11\fR module implements \fBpam_sm_authenticate\fR(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 a PKCS#11 token. This module currently supports the RSA algorithm only.

.sp

.LP

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:

.RS +4

.TP

.ie t \(bu

.el o

Generate 128 random byte data

.RE

.RS +4

.TP

.ie t \(bu

.el o

Sign the random data with the private key and get a signature. This step is done in the PKCS#11 token.

.RE

.RS +4

.TP

.ie t \(bu

.el o

Verify the signature using the public key extracted from the certificate.

.RE

.sp

.LP

For the verification of the users' certificates, locally stored CA certificates as well as either online or locally accessible CRLs are used.

.SS "PAM CONFIGURATION"

.sp

.LP

The \fBpam_pkcs11.so\fR service module can be used in the \fB<auth>\fR PAM chain. The program that needs a PAM service should be configured in \fB/etc/pam.conf\fR or \fB/etc/pam.d/\fR\fIservice\fR. For details on how to configure PAM services, see \fBpam.conf\fR(4).

.sp

.LP

The following example uses only \fBpam_pkcs11\fR for authentication:

.sp

.in +2

.nf

login auth requisite pam_pkcs11.so.1

login autho required pam_unix_cred.so.1

.fi

.in -2

.sp

.LP

The following example uses \fBpam_pkcs11\fR for authentication with fallback to standard UNIX authentication:

.sp

.in +2

.nf

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

.fi

.in -2

.SS "PAM_PKCS11 CONFIGURATION"

.sp

.LP

To configure the \fBpam_pkcs11\fR module, you must have the following information:

.RS +4

.TP

.ie t \(bu

.el o

Which PKCS #11 token you are going to use

.RE

.RS +4

.TP

.ie t \(bu

.el o

Which mapper(s) you need, and if needed, how to create and edit the related mapping files

.RE

.RS +4

.TP

.ie t \(bu

.el o

The root Certificate Authority files, and if required, the Certificate Revocation Lists files

.RE

.RS +4

.TP

.ie t \(bu

.el o

The list of authorized users to login, and their corresponding certificates

.RE

.sp

.LP

To configure the \fBpam_pkcs11\fR module, you need to modify the \fBpam_pkcs11.conf\fR configuration file which is in the \fB/etc/security/pam_pkcs11\fR directory by default. For detailed information on how to configure the \fBpam_pkcs11\fR module, see the \fIPAM-PKCS11 User Manual\fR, available at the \fBhttp://www.opensc-project.org/\fR web site, under the \fBPAM PKCS#11\fR link.

.sp

.LP

The following example illustrates how to configure the \fBpam_pkcs11\fR module for a user whose certificate and private key are stored in the Solaris \fBpkcs11_softtoken\fR keystore. This example uses the default certificate verification policy. 

.RS +4

.TP

.ie t \(bu

.el o

Set up the PKCS#11 module.

.sp

On Solaris, the PKCS#11 module should be set to \fB/usr/lib/libpkcs11.so.1\fR, the PKCS#11 Cryptographic Framework library. 

.RE

.RS +4

.TP

.ie t \(bu

.el o

Set up the \fBslot_description\fR entry.

.sp

Specifies the slot to be used. For example, \fBslot_description = "Sun Crypto Softtoken"\fR. The default value for this entry is \fBnone\fR which means to use the first slot with an available token.

.sp

An administrator can use the \fBcryptoadm list -v\fRcommand to find all the available slots and their slot descriptions. For more information, see \fBlibpkcs11\fR(3LIB) and \fBcryptoadm\fR(1M).

.RE

.RS +4

.TP

.ie t \(bu

.el o

Install or create user certificates and its dedicated private keys in the specific PKCS#11 token.

.RE

.RS +4

.TP

.ie t \(bu

.el o

Set up the certificate verification policy (\fBcert_policy\fR). If needed, set up CA certificate and CRL files.

.sp

The certificate verification policy includes:

.RS

.sp

.ne 2

.mk

.na

\fB\fBnone\fR\fR

.ad

.RS 13n

.rt  

Perform no verification

.RE

.sp

.ne 2

.mk

.na

\fB\fBca\fR\fR

.ad

.RS 13n

.rt  

Perform CA check

.RE

.sp

.ne 2

.mk

.na

\fB\fBsignature\fR\fR

.ad

.RS 13n

.rt  

Perform a signature check to ensure that private and public key matches

.RE

.sp

.ne 2

.mk

.na

\fB\fBcrl_\fR\fIxxx\fR\fR

.ad

.RS 13n

.rt  

Perform various certificate revocation checking

.RE

.RE

As this example uses the default policy, \fBcert_policy = ca,signature\fR, an administer needs to set up the CA certificates.

.RS +4

.TP

.ie t \(bu

.el o

Copy the CA certificate to the \fB/etc/security/pam_pkcs11/cacerts\fR directory.

.sp

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.

.RE

.RS +4

.TP

.ie t \(bu

.el o

Make hash links for CA certificates

.sp

.in +2

.nf

$ /etc/security/pam_pkcs11/make_hash_link.sh \e

      /etc/security/pam_pkcs11/cacerts

.fi

.in -2

.sp

.RE

.RE

.RS +4

.TP

.ie t \(bu

.el o

Set up the mappers and mapfiles.

.sp

When a X509 certificate is provided, there are no direct ways to map a certificate to a login. The \fBpam_pkcs11\fR module provides a configurable way with mappers to specify \fBcert-to-user\fR mapping.

.sp

Many mappers are provided by the \fBpam_pkcs11\fR module, for example, the common name (CN) mapper, the digest mapper, the Email mapper, or the LDAP mapper. 

.sp

A user can configure a mapper list in the \fBpam_pkcs11.conf\fR file. The mappers in the list are used sequentially until the certificate is successfully matched with the user. 

.sp

The default mapper list is as follows:

.sp

.in +2

.nf

use_mappers = digest, cn, pwent, uid, mail, subject, null;

.fi

.in -2

.sp

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 in the \fB/etc/security/pam_pkcs11\fR directory.

.RE

.SH OPTIONS

.sp

.LP

The following options are supported:

.sp

.ne 2

.mk

.na

\fB\fBconfig_file=\fIfilename\fR\fR\fR

.ad

.RS 24n

.rt  

Specify the configuration file. The default value is \fB/etc/security/pam_pkcs11/pam_pkcs11.conf\fR.

.RE

.sp

.ne 2

.mk

.na

\fB\fBdebug\fR\fR

.ad

.RS 24n

.rt  

Enable debugging output.

.RE

.SH FILES

.sp

.ne 2

.mk

.na

\fB\fB/usr/lib/security/pam_pkcs11.so\fR\fR

.ad

.sp .6

.RS 4n

\fBpam_pkcs11\fR module

.RE

.sp

.ne 2

.mk

.na

\fB\fB/usr/lib/pam_pkcs11/ldap_mapper.so\fR\fR

.ad

.sp .6

.RS 4n

Mapper module.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/usr/lib/pam_pkcs11/opensc_mapper.so\fR\fR

.ad

.sp .6

.RS 4n

Mapper module.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/usr/lib/pam_pkcs11/openssh_mapper.so\fR\fR

.ad

.sp .6

.RS 4n

Mapper module.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/etc/security/pam_pkcs11/pam_pkcs11.conf\fR\fR

.ad

.sp .6

.RS 4n

Configuration file.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/etc/security/pam_pkcs11/cacerts\fR\fR

.ad

.sp .6

.RS 4n

Configuration directory. Stores the CA certificates.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/etc/security/pam_pkcs11/crls\fR\fR

.ad

.sp .6

.RS 4n

Configuration directory. Stores the CRL files.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/etc/security/pam_pkcs11/digest_mapping.example\fR\fR

.ad

.sp .6

.RS 4n

Sample mapfile.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/etc/security/pam_pkcs11/subject_mapping.example\fR\fR

.ad

.sp .6

.RS 4n

Sample mapfile.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/etc/security/pam_pkcs11/mail_mapping.example\fR\fR

.ad

.sp .6

.RS 4n

Sample mapfile.

.RE

.sp

.ne 2

.mk

.na

\fB\fB/etc/security/pam_pkcs11/make_hash_link.sh\fR\fR

.ad

.sp .6

.RS 4n

Sample script.

.RE

.SH AUTHORS

.sp

.LP

\fBPAM-pkcs11\fR was originally written by MarioStrasser , \[email protected]\fR.

.sp

.LP

Newer versions are from Juan Antonio Martinez, \[email protected]\fR

.SH ATTRIBUTES

.sp

.LP

See \fBattributes\fR(5) for a description of the following attributes:

.sp

.sp

.TS

tab() box;

cw(2.75i) |cw(2.75i) 

lw(2.75i) |lw(2.75i) 

.

ATTRIBUTE TYPEATTRIBUTE VALUE

_

AvailabilityT{

library/security/pam/module/pam-pkcs11, SUNWpampkcs11r, SUNWpampkcs11-docs

T}

_

Interface StabilityUncommitted

.TE

.SH SEE ALSO

.sp

.LP

\fBpkcs11_inspect\fR(1), \fBpklogin_finder\fR(1), \fBcryptoadm\fR(1M), \fBlibpkcs11\fR(3LIB)\fBlibpkcs11\fR(3LIB)\fBpam_sm_authenticate\fR(3PAM), \fBpam.conf\fR(4), \fBattributes\fR(5), \fBpkcs11_softtoken\fR(5)

.sp

.LP

\fIPAM-PKCS11 User Manual\fR, available at the \fBhttp://www.opensc-project.org/\fR web site, under the \fBPAM PKCS#11\fR link.