Software: Apache/2.2.3 (CentOS). PHP/5.1.6 uname -a: Linux mx-ll-110-164-51-230.static.3bb.co.th 2.6.18-194.el5PAE #1 SMP Fri Apr 2 15:37:44 uid=48(apache) gid=48(apache) groups=48(apache) Safe-mode: OFF (not secure) /usr/share/doc/pam_pkcs11-0.5.3/ drwxr-xr-x |
Viewing file: pam_pkcs11.html (77.71 KB) -rw-r--r-- Select action/file-type: (+) | (+) | (+) | Code (+) | Session (+) | (+) | SDB (+) | (+) | (+) | (+) | (+) | (+) | Table of Contents
Abstract PAM-PKCS#11 is a PAM (Pluggable Authentication Module) library and related tools to perform login into Linux/UNIX systems by mean of X509 Certificates through any PKCS #11 compliant library. This manual describes how to compile, install, configure and use pam-pkcs11 PAM module and related tools.
Copyright (C) 2005 Juan Antonio Martinez
Copyright (C) 2003-2004 of Mario Strasser
ScConf library Copyright (C) Antti Tapaninen Release 0.5beta1. 30 Mar 2005 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 will be 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 pam_pkcs11 is a set of libraries and tools to controls the login process using a PKCS#11 token. The Linux-PAM login module allows a X.509 certificate based user login. The certificate and its dedicated private key are thereby accessed by means of an appropriate PKCS #11 module. For the verification of the users' certificates, locally stored CA certificates as well as either online or locally accessible CRLs are used. pkcs11_eventmgr is a tool to execute commands at insert or removal of SmartCard from reader. Alternatively, you can use the pcsc-lite's based version: card_eventmgr. pkcs11_inspect tool allows you to look at the content of a certificate, in order to help you in the process of Certificate-to-User mapping configuration. pklogin_finder tool can be used to check the pam module without need to do the entire login process, just verifying that login names are properly found and matched. Detailed information about the Linux-PAM system can be found in The Linux-PAM System Administrators' Guide, The Linux-PAM Module Writers' Guide and The Linux-PAM Application Developers' Guide. The specification of the Cryptographic Token Interface Standard (PKCS #11) is available at PKCS #11 - Cryptographic Token Interface Standard. Table of Contents Pam-pcks11 is a PAM (Pluggable Authentication Module) pluggin to allow to login into a UNIX/Linux System that supports PAM by mean of use Digital Certificates stored in a SmartCard. To do this, a PKCS #11 library is needed to access the Cards. Details on how certificates are stored/retrieved, etc are hidden to pam-pkcs11 and handled by PKCS #11 library. This allows independence of the module from a specific card. 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 [Note: This is still a work in progress, any suggestions for improvements or alternative matching algorithms are welcome.]
NOTES
Table of Contents Configuration of pam-pkcs11 involves two steps:
This chapter explains pam-pkcs11 configuration-related issues. Next chapter deals with generic PAM options. You should read this manual and study the provided configuration sample files before doing any change. You must know:
The configuration file uses the scconf library. Parameters and data are grouped into blocks. Blocks can be nested in a tree. A 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 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. 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 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 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. Table of Contents To make use of the PKCS #11 login module add the line auth sufficient pam_pkcs11.so ...
in the 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
/etc/pam_pkcs11/pam_pkcs11.conf )
The next options should be taken from the configuration file (default
Next options are PKCS #11 module specific:
Filename of the PKCS #11 module. The default value is
Note that this option takes precedence over "module" entry in proper pkcs11_module section, but this section is still needed Slot-number to use: 1 for the first, 2 for the second and so on. The default value is 0 which means to use the first slot with an available token.
Path to the directory where the CA certificates are stored. The
directory must contain an OpenSSL hash-link to each certificate.
The default value is
Pam-pkcs11 provides a utility:
Path to the directory where the CRLs are stored. The directory
must contain an openssl hash-link to each CRL. The default value
is Sets the CRL verification policy:
The default setting is 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/ 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 the configuration file is still needed to get the mapper module options and flags. Starting at pam_pkcs11-0.4.2 a new feature is provided: pam-pkcs11 can deduce the username from the user certificate without using the login prompt.
This is done when
If the finder returns with success, the found username is set to PAM
using So it is no longer needed to enter the login name if a certificate is provided and can be mapped to a user. There are to ways for using this feature:
In both cases the procedure follows as:
This feature can be used with pam-mkhomedir.so PAM session module. In this case, you can create on-the-fly accounts. This scenario is ideal for centralized auth services (Winbind, ldap, Kerberos, RDBMS auth...).
As example, here comes my tested #%PAM-1.0 auth sufficient pam_pkcs11.so debug config_file=/etc/pam_pkcs11/pam_pkcs11.conf auth required pam_env.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_mkhomedir.so skel=/etc/skel umask=0022 session optional pam_console.so
IMPORTANT NOTES:
For Improper mapper chain' configurations with unauthorized certificates can lead to the creation of fake accounts in the system if pam_mkhomedir.so module is used. So be really careful when authenticate users directly from certificates. Table of Contents PAM-PKCS11 includes several tools: card_eventmgr and pkcs11_eventmgr that can be used to monitor the status of the card reader and dispatch actions on several events. These programs can be used to several actions, like lock screen on card removal. Note that these programs have no direct interaction with pam-pkcs11 module: they are just card status monitors. It is the system administrator job to define and configure actions to take on events. card_eventmgr is a card status monitor based on the PCSC-Lite library.
To invoke the program, just type
Here is an example of configuration file. It is auto-descriptive: 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
Just add to your
Additionally you can add this line to
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:
PAM-PKCS#11 provides another tool: pklogin-finder that can be used to find Cert-to-login maps, outside the PAM environment. This tool can be used to create and test map files, or to check environment and configuration files, without need to use PAM related tools. pklogin_finder uses the same structure and configuration than pam-pkcs11 module. It reads certificate, and try all specified mappers to find a user match. When found, login name is displayed on stdout. To invoke, just type from console:
By default, debug is set to Return values are:
Starting at version 0.5 a new tool pkcs11_inspect is provided. pkcs11_inspect is a PKCS #11 based tool to explore certificate contents. It's similar to pklogin_finder, but no mapping is done at all: just load mappers chains, and in turn, try to get proper data from certificate (ie: cn_mapper looks for CN entries, and so). When desired info is found, pkcs11_inspect print found data to stdout, without doing any mapping, that is, mapfile entries in configuration file are ignored. The reason to exist for this tool is to ease the making of mapping files:
Same command line options and configuration file than
pklogin_finder applies to
pkcs11_inspect command, but note that
Table of Contents We will now describe a complete installation of pam_pkcs11 as an example case. This configuration will use a local root CA certificate and the subject mapper. Many other configurations are also possible. You should install pre-compiled binaries since that is the easiest way to install a software. See the documentation of you distribution to know how to install RPM, DEB or whatever packages. If you want to recompile from source read Chapter 4, Installation.
I used tinyCA to
generate the root CA and the user certificates. Your root CA certificate
name may be different. Make sure that all the files in
Copy the sample file:
The sample file uses the OpenSC PKCS#11 library. You may need to edit
Copy the sample file:
Then use pkcs11_inspect to get the information you need for the mapper. In our case you are looking for something like: Printing data for mapper subject: /C=ES/O=FNMT/OU=FNMT Clase 2 CA/OU=500051483/CN=NOMBRE MARTINEZ CASTA\xF1O JUAN ANTONIO - NIF 50431138G Note that this is one line but it is wrapped to be displayed here in the form of three lines.
Then edit # Mapping file for Certificate Subject # format: Certificate Subject -> login # /C=ES/O=FNMT/OU=FNMT Clase 2 CA/OU=500051483/CN=NOMBRE MARTINEZ CASTA\xF1O JUAN ANTONIO - NIF 50431138G -> jantonio Again note that the two last lines displayed should be only one. You will now configure your PAM system to use pam_pkcs11. We recommand to start with an easy to debug application like login. The advantages of login is that you can see the debug messages from pam_pkcs11.
Edit # pam_pkcs11: smart card login auth sufficient pam_pkcs11.so
Since Once your PAM configuration is tested and working you can configure all the PAM application 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 you replace sufficient by required. The authentication process will then fail if pam_pkcs11 fails. Using a smart card only login may be more secure but it may also be more dnagerous. If get 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 passwd. card_eventmgr is a helper tool to automatically launch an application 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:
Edit the configuration file to set the actions you want 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
You will see some debug messages and possibly why the commands you configured as action do not work properly.
After debuging your card_eventmgr configuration file you can start it
automatically. One solution is to create a
# 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
Table of Contents
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, that 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. Aditionally, most of simplest mappers doesn't need to be dynloaded, 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,great,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: Assumes CN field on certificate to be the login name.
In either case, if a mapfile is used, the mapper will try to map CN into a login and use it. Configuration entry is as follow: # 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" }
Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname Extract Certificate Subject and assume it as login.
In either case, if a mapfile is used, the mapper will try to map subject into a login and use it. Configuration file is like: # 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"; }
The mapping file must follow this structure: .... Certificate Subject -> login .... Note that some certificates handle strange char mappings (non utf-8) so you must ensure correct byte-to-byte match. You can use provided pkcs11_inspect tool to get and store correct data from certificate Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname
Compare CN against
Note: newer implementations of pw_mapper configuration file shows like: mapper pw { debug = true; ignorecase = false; module = internal; # module = /usr/lib/pam_pkcs11/pw_mapper.so; }
Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname Uses an ldap server to retrieve user name. An additional file tells module the mapping between Cert fields and LDAP entries. This mapper is still under development.
Search certificate in This mapper is still under development.
Search certificate public key in
When used as login finder, returns the user that owns the
When used as matcher, the module uses Configuration file entry looks like: mapper openssh { debug = false; module = /usr/lib/pam_pkcs11/openssh_mapper.so; }
NOTE: This mapper is still under development. Email mapper tries to extract an e-mail from certificate. If found does following procedures:
Once we have a mapped user, module does:
Additionally you can set Domain check (if set) is done by testing if provided email domain part (@ie.this.domain) matches host domain.
Eg Configuration file entry looks like: 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; }
Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname Try to find and use Microsoft Universal Principal Name (UPN) extension to evaluate login name.
Microsoft Universal Principal Name is a ASN1-encoded UTF8 string with
the syntax
Configuration file entry looks like: mapper ms { debug = false; module = internal; # module = /usr/lib/pam_pkcs11/ms_mapper.so; ignorecase = false; ignoredomain = false; domainname = "domain.com"; }
Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname Try to find and use Kerberos Principal Name as login name. if mapfile is specified, maps KPN into a login. NOTES:
Configuration entry: mapper krb { debug = false; module = internal; # module = /usr/lib/pam_pkcs11/krb_mapper.so; ignorecase = false; mapfile = "none"; }
Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname Use Unique ID (UID) field as login name. Similar to CN mapper, but using UID as field to find/match. Configuration entry: mapper uid { debug = false; module = internal; # module = /usr/lib/pam_pkcs11/uid_mapper.so; ignorecase = false; mapfile = "none"; }
Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname Evaluates a certificate digest, and try to map result into a login by using a mapfile. Configuration file should provide the digest algorithm. Depending on OpenSSL configuration all of listed bellow may or not be present in your system. Configuration entry: 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; }
Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname This mapper groups several mappers in one. You can select which certificate content should be used to deduce/match login, optionally perform a file mapping, and, if desired consult mapped string to NSS services to get final user login. Three arguments are needed:
Note that fields are taken literally: ie no post-processing is done, just take string "as is", and pass it to next step. So if you need some data processing (ie, use ADS name field in upn) this mapper is not for you. The first step is extract string from certificate. If a mapping file is required, the string is mapped against mapfile, obtaining a new string. If use_pwent is also required, the mapper compare last one against pw_login or pw_gecos. If a match is done, the pw_login is returned as user login. When module is user as login finder, returns result of above operations. When user as login matcher, compares provided login with above result. generic_mapper configuration file shows like: 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" or "uid" 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; }
Note: As for every other mappers, pklogin_finder tool, doesn't perform the entire process, just returns certificate contents. Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname Blind access/deny mapper.
If
If
Configuration entry: 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; }
NOTE: This mapper should be the last one in the mapper chain, as it allways return valid -althought senseless- data Starting pam-pkcs11-0.5.3 this module is now statically linked, so no need to provide library pathname Creating new mappers is easy: just retrieve and study the PAM-PKCS#11 Mapper API reference Manual You'll find there sample code, compiling instructions, and a complete list of provided library calls
Any comments, suggestions and bug reports are welcome. Please, mention the keywords 'pkcs' and 'pam' in the subject.
Juan Antonio Martinez
Mario Strasser |
:: Command execute :: | |
:: Shadow's tricks :D :: | |
Useful Commands
|
:: Preddy's tricks :D :: | |
Php Safe-Mode Bypass (Read Files)
|
--[ c999shell v. 1.0 pre-release build #16 Modded by Shadow & Preddy | RootShell Security Group | r57 c99 shell | Generation time: 0.009 ]-- |