Mercurial Mercurial > upstream > oracle > userland-gate / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
components/pam_pkcs11/files/pam_pkcs11.5
changeset 2008 fbb3d4972042 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/components/pam_pkcs11/files/pam_pkcs11.5	Wed Jul 23 14:53:41 2014 -0700
@@ -0,0 +1,413 @@
+'\" 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.
upstream/oracle/userland-gate