CSPid Administrator'

CSPid Administrator’s Guide
Version 5.0.0
Simplifying the Management of Cryptographic Credentials and
Enabling Role-based PKI in the Enterprise
January 8, 2016
CSPid Administrator’s Guide
Information in this document is subject to change without notice and does not represent a commitment on
the part of Information Security Corporation. The software described in this document is furnished under
a license agreement or nondisclosure agreement. The software may be used or copied only in accordance
with the terms of the agreement. No part of this manual may be reproduced or transmitted in any form or
by any means, electronic or mechanical, including photocopying and recording, for any purpose other
than the purchaser’s personal use without the prior written permission of Information Security
Corporation.
CSPid software is commercial computer software and, together with any related documentation, is subject
to the restrictions on U.S. Government use as set forth below.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is
subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software Clause at DFARS 52.227-7013. “Contractor/manufacturer” is Information Security Corporation,
1011 W. Lake Street, Suite 425, Oak Park, IL 60301.
The U.S. International Traffic in Arms Regulations (ITARs) (22 CFR 125.03) prohibits the dissemination
of certain types of technical data to foreign nationals.
Protected by U.S. Patent No. 5,699,431.
CSPid is a registered trademark of Information Security Corporation. Other product and company names
mentioned in this document may be the trademarks of their respective owners.
The cryptographic functionality of CSPid is provided by CDK 7, ISC’s FIPS 140-2 Level 1compliant
cryptographic module. In addition, CSPid uses the following open source software packages
redistributable under the terms of the LGPL or other licenses:
FLTK, Version 1.1.7: Copyright© 1998-2005 Bill Spitzak and others.
CSPid is based in part on the work of the FLTK project (http://www.fltk.org).
LogDriver, version 1.6: Copyright© 2002 Will Senn.
See the logdriver.txt file located in the installation folder for complete license information.
Qt, version 5.4.2: Copyright© 2014 Digia Plc and/or its subsidiary(-ies).
Licensed under the GNU LGPL version 2.1 (http://qt.digia.com).
pugixml, version 1.2: Copyright© 2006-2012 Arseny Kapoulkine.
See the pugixml.txt file located in the installation folder for complete license information
(http://www.pugixml.org).
CSPid 5.0.0 Administrator’s Guide, First Edition (January 2016)
© 2007-2016 Information Security Corporation. All rights reserved.
Information Security Corporation
1011 W. Lake Street, Suite 425
Oak Park, IL 60301
2
Phone: +1 847-405-0500
Fax: +1 708-445-9705
Website: www.infoseccorp.com
Email: sales_acct@infoseccorp.com
CSPid Administrator’s Guide
Table of Contents
1.
Introduction ........................................................................................................................ 8
1.1. Overview ......................................................................................................................... 8
1.2. CSPid Architecture .......................................................................................................... 8
1.3. CSPid Events ................................................................................................................ 10
1.4. CSPid DAS Support ...................................................................................................... 11
1.4.1. Notes ..................................................................................................................... 12
1.5. CCMS Integration ......................................................................................................... 12
1.6. CSPid CRL Management .............................................................................................. 12
1.7. CSPid Windows Validation Client with OCSP Support (Windows Only) ....................... 13
2.
Installation ........................................................................................................................ 14
2.1. Overview ....................................................................................................................... 14
2.2. System Requirements .................................................................................................. 15
2.3. Windows ....................................................................................................................... 16
2.4. UNIX ............................................................................................................................. 17
3.
Configuration.................................................................................................................... 18
3.1. Using CSPid with a Web Browser ................................................................................. 18
3.1.1. CAPI-based Browsers ........................................................................................... 18
3.1.2. Mozilla-based Browsers ........................................................................................ 18
3.2. Enrollment with a Web Browser ................................................................................... 18
3.2.1. CAPI-based Browsers ........................................................................................... 18
3.2.2. Mozilla-based Browsers ........................................................................................ 18
3.2.3. Other ..................................................................................................................... 18
3.3. Using CSPid with Java Applications .............................................................................. 19
3.3.1. Via Windows Native Store (CAPI) ......................................................................... 19
3.3.2. Via PKCS#11 ........................................................................................................ 19
3.3.3. Blacklists, Whitelists, and Java ............................................................................. 20
3.4. Using CSPid with Apache Tomcat ................................................................................. 20
3.5. Using CSPid with Stunnel .............................................................................................. 21
3.6. CSPid Configuration ...................................................................................................... 21
3.6.1. Windows ................................................................................................................ 22
3.6.2. UNIX ...................................................................................................................... 22
3.6.3. CSPid Events.......................................................................................................... 22
3.6.4. Controlling Certificate Visibility .............................................................................. 23
3.6.5. Updating the Configuration .................................................................................... 23
3.6.6. Password Reset Agents ........................................................................................ 25
3.6.7. Configuration Options ............................................................................................ 25
4.
CSPid Password and Key Management .......................................................................... 26
4.1. Password Management ................................................................................................ 26
3
CSPid Administrator’s Guide
4.1.1. Password History .................................................................................................. 26
4.1.2. Forced Password Change ..................................................................................... 26
4.1.3. Administrative Password Reset ............................................................................. 26
4.1.4. Password Timeout ................................................................................................. 27
4.1.5. Password Caching ................................................................................................ 27
4.2. Key Management ......................................................................................................... 28
4.2.1. Encrypted Memory ................................................................................................ 28
4.2.1.1. Encrypted Memory on Windows 2000 and Windows XP ...................................... 29
4.2.1.2. Encrypted Memory on Windows Vista and Windows 7 ......................................... 29
4.2.1.3. Encrypted Memory on UNIX-based Systems ........................................................ 30
4.2.2. Password Timeout Implementation Details ........................................................... 30
4.2.3. Key Management in the CSPid Management Tool ................................................ 30
5.
CSPid Libraries.................................................................................................................. 31
5.1. The PKCS #11 Library .................................................................................................. 31
5.2. The Microsoft Windows Library .................................................................................... 31
6.
Quality Assurance............................................................................................................ 32
6.1. Testing Methodology .................................................................................................... 32
6.2. Known Issues ............................................................................................................... 33
6.2.1. Windows ................................................................................................................ 33
6.2.2. Netscape 4.x or higher w/o PSM ........................................................................... 33
6.2.3. Netscape 4.75 or higher w/PSM 1.4 ...................................................................... 33
6.2.4. Internet Explorer .................................................................................................... 33
6.2.5. Microsoft Outlook .................................................................................................. 33
7.
Net-Centric Applications ................................................................................................. 34
7.1. Role-Based Authentication ........................................................................................... 34
7.2. Role-Based Encryption ................................................................................................. 35
7.3. Confidentiality within a Community of Interest .............................................................. 35
7.4. Expanded Storage and Enhanced Security for Private Keys ....................................... 36
7.5. Brokered Authentication - “Need-to-Know” Control Over Sensitive Resources............ 37
8.
References ........................................................................................................................ 38
9.
Appendix A: Supported PKCS #11 Mechanisms .......................................................... 40
10. Appendix B: The Key Storage Format ........................................................................... 41
10.1.
Version 5.0 and Above .............................................................................................. 41
10.1.1. Key Derivation Algorithm ....................................................................................... 41
10.1.2. Linking the PDU to the Configuration Options ....................................................... 41
10.2.
PKCS #15 ................................................................................................................. 42
10.3.
Object Syntax ............................................................................................................ 42
10.4.
Confidentiality ........................................................................................................... 42
10.5.
Integrity ..................................................................................................................... 44
10.6.
Initialization ............................................................................................................... 44
4
CSPid Administrator’s Guide
11.
Appendix C: A Sample PKCS #15 Key Store ................................................................. 45
12.
Appendix D: CSPid Objects ............................................................................................. 53
13.
Appendix E: CSPid Object Management ......................................................................... 54
5
CSPid Administrator’s Guide
List of Figures
Figure 1: CSPid 4.0 Architecture Diagram ..................................................................................... 9
Figure 2: Modifying the java.security File............................................................................ 19
Figure 3: Modifying Your Java Code ........................................................................................... 19
Figure 4: Modifying Java SSL/TLS Properties ............................................................................ 19
Figure 5: Modifying the Tomcat server.xml File ..................................................................... 20
Figure 6: Watch Officers Sign Messages with Shared Role Key on DAS Server ....................... 34
Figure 7: Commander Decrypts Documents Using Role Key on DAS Server ............................ 35
Figure 8: CoI Members Decrypt Documents Using CoI Key on DAS Server .............................. 36
Figure 9: Officer Retains Access to His Entire Key History ........................................................ 36
Figure 10: A DAS Server Used to Impose Strong "Need-to-Know" Controls over Sensitive
Resources ................................................................................................................................... 37
Figure 11: Object Synchronization Algorithm .............................................................................. 54
Figure 12: Object Merge Algorithm ............................................................................................. 55
6
CSPid Administrator’s Guide
List of Tables
Table 1: CSPid Events ................................................................................................................. 11
Table 2: System Requirements ................................................................................................... 15
Table 3: Test Configurations ....................................................................................................... 32
Table 4: Configuration options used to derive key ...................................................................... 42
Table 5: Proprietary PKCS #11 Attributes .................................................................................. 53
7
CSPid Administrator’s Guide
1. Introduction
1.1. Overview
Abstract: This document describes a platform-agnostic software product that acts as a universal key store
as well as a cryptographic service provider. Accessed via Microsoft CAPI, or via its industry standard
PKCS #11 interface, CSPid ensures that authorized security-enabled applications have instant access to the
user’s latest certificates and private keys without the need to synchronize or replicate credentials among
those applications. Using platform-independent PKCS #15 key stores, CSPid simplifies the migration of
credentials between workstations with different operating systems. After presenting a technical overview
of the product, this document covers the installation, administration, and use of CSPid.
This document describes a software package that manages a user’s X.509 credentials, securely protecting
them while making them available upon demand (with appropriate authentication) to any security-enabled
application, and allowing them to be easily migrated between workstations in an operating systemindependent manner.
CSPid is a virtual smartcard that maintains a central repository for private keys and X.509 certificates on
behalf of its owner. It provides a secure environment for cryptographic operations that applications can
access via Java, PKCS #11, or Microsoft CAPI.
The CSPid system:
1. provides a single OS-independent credential store that may be shared by all security-enabled
applications on the user’s system
2. provides superior protection for private keys and overcomes password change/reset issues with
Windows, Internet Explorer, and Mozilla
3. simplifies enterprise-wide credential management: users need not replicate keys among
applications, and may effortlessly migrate credentials between workstations
4. provides administrative control over security policy settings and can be augmented to support key
escrow, key recovery, and/or password reset functions
5. provides event hooking enabling the execution of external programs based on events
6. reduces help desk costs and PKI training requirements
A major step forward in credential management, CSPid’s programming interfaces allows administrators to
build custom, nearly user-transparent PKI enrollment, key rollover, credential backup, and other
management tools that dramatically simplify the PKI experience for an organization’s end-users.
1.2. CSPid Architecture
id
The CSP system consists of five components:

8
a credential store: an encrypted file stored by the system on a local fixed disk, on removable
media, or on a network drive
CSPid Administrator’s Guide

a PKCS #11 library providing access to the credential store and certain private key operations

a Windows Key Storage Provider (CSPid Key Generation Provider) that provides access to the
integrated PKCS #11 library to Microsoft CryptoAPI-enabled applications (such as Internet
Explorer, Microsoft Outlook, and Microsoft Outlook Express)

an optional (licensable) Windows Validation/OCSP client for Windows

an optional (licensable) DAS client to DAS-enable any application

a set of tools that permit the end-user to easily configure and maintain the CSPid system
CAPI/CNG-Enabled
Windows Application
(Microsoft Outlook, Internet Explorer,
EFS, SecretAgent, etc.)
PKCS#11-Enabled Application
(Netscape, Notes, Mozilla Firefox/Thunderbird,
SecretAgent, SpyProof!, any Java application, etc.)
End-User
Administrator
CSPid
Manager
CSPid
Events
(command line and
graphical interfaces)
(handlers for
enrollment,
renewal,
program
registry,
certificate
retrieval, etc.)
CAPI/CNG
CSPid Key Storage
Provider
PKCS #11 Library
DAS Comm.
Module
PKCS #15 Key Store
Manager
ISC CDK 7.0
Key Stores
CSPid Virtual Smartcard
Smart Card Authentication
(optional)
DAS servers to support
role-based operations
signature server
one configurable PKCS#15 key store per user
local or network-attached, file-based key store
remote HTTPS-based key store
(future enhancement)
(future extensibility)
decryption server
Figure 1: CSPid 4.0 Architecture Diagram
As illustrated in the above diagram, a PKCS #11 library (based on ISC’s FIPS-validated CDK 7), a PKCS
#15 key store manager, a Key Storage Provider, and the CSPid management tools represent the core
components of the CSPid system. These tools and the provided APIs allow users to manage their key
stores and easily integrate CSPid into existing applications. As of version 2.0, the DAS communication
module allows CSPid to provide all applications (including Outlook and Thunderbird S/MIME) high-
9
CSPid Administrator’s Guide
assurance "role-based" signature, key agreement, and decryption operations that rely on remote private
keys, possibly stored on an HSM (requires DAS 1.8 or above).
1.3. CSPid Events
CSPid exposes a portion of its programmable “event model interface” through its configuration. This
interface, fully described in Chapter 3, allows an administrator to manage an end-user’s system and
credentials by means of custom scripts that are automatically executed in response to certain trigger
events. Among the events for which such custom “handlers” can be installed are:

initial PKI enrollment or key import

certificate renewal/key rollover

certificate import

manual selection of the “Register with Applications” command

manual selection of the “Renew My Certificates” command

manual selection of the “Reset Password” command
Event Name
Triggers
Configuration Options
Start up
The CSPid Manager starts.
The CSPid Manager will execute these commands allowing
the import/removal of DAS or issuer certificates, updating
credentials from a CCMS server, or other operations that
need to occur daily.
Enrollment
The CSPid Manager starts and no
credentials are found.
CSPid provides four choices for handling this event:

contact a CCMS server and attempt to retrieve
the user’s credentials

transfer credentials from the CAPI “personal”
store

execute a script (batch file, shell script, or binary
executable embedded in the configuration)

open a URL
The options are tried in the order listed above. If there are
still no private key objects present after running the option
the next option is attempted. If there are still no private key
objects present after running all the options the Renewal
event is run.
Renewal
The CSPid Manager starts and all of the
existing signing credentials, or all of the
existing encrypting credentials, will be
invalid within a specified number of
days.
The user selects the Renew My
Certificates menu command.
cspid_ui.exe --renew is executed.
Enrollment fails to create a private key
object.
CSPid supports a single trigger setting:

lead time prior to expiration
and provides three event handling options:

contact a CCMS server and attempt to retrieve
the user’s credentials

open a URL

execute a script (batch file, shell script, or binary
executable embedded in the configuration)
New Signing
A signing certificate is imported and a
CSPid creates necessary entries in the user’s CAPI
10
CSPid Administrator’s Guide
Credential
matching private key is found in CSPid.
“personal” store; if the certificate was imported from a
third-party application, CSPid can execute a script (batch
file, shell script, or binary executable embedded in the
configuration).
New
Encryption
Credential
An encrypting certificate is imported
and a matching private key is found in
CSPid.
CSPid creates necessary entries in the user’s CAPI
“personal” store; if the certificate is imported from a thirdparty application, CSPid can execute a script (batch file,
shell script, or binary executable embedded in the
configuration).
New DAS
Signing
Credential
A DAS-enabled signing certificate is
imported and DAS support is enabled.
CSPid creates necessary entries in the user’s CAPI
“personal” store; if the certificate was imported from a
third-party application, CSPid can execute a script (batch
file, shell script, or binary executable embedded in the
configuration).
New DAS
Encryption
Credential
A DAS-enabled encrypting certificate is
imported and DAS support is enabled.
CSPid creates necessary entries in the user’s CAPI
“personal” store; if the certificate is imported from a thirdparty application, CSPid can execute a script (batch file,
shell script, or binary executable embedded in the
configuration).
Register
with
Applications
The user selects the Register with
Applications menu command.
The user imports a recently issued
PKCS #12 file and
P12IMPORTREGAPPS is non-zero.
cspid_ui.exe --register is executed.
In addition to configuring the CAPI store and Netscapebased applications, CSPid can execute a script (batch file,
shell script, or binary executable embedded in the
configuration).
Reset
Password
The user selected the Reset Password
menu command or clicks the Forgot
Password? link in the password dialog.
CSPid provides three choices for handling this event:

e-mail the password reset request file to one or
more administrators using the default mailer

execute a script (batch file, shell script, or binary
executable embedded in the configuration)

allow the user to save the file to a location of
their choice
An optional message can be displayed to the user before
any of these occur.
Table 1: CSPid Events
1.4. CSPid DAS Support
CSPid versions 1.2 and above include optional DAS support. DAS is a server-side component that
provides role-based capabilities enabling users to either sign for a role, perform key agreement, or decrypt
anything encrypted for a particular role. When C_Decrypt is called, CSPid communicates with a DAS
server in order to unwrap the symmetric key which is then rewrapped for the specific user. CSPid then
uses the user’s private key to unwrap the response from the server. When C_Sign is called CSPid
communicates with a DAS server which performs the signature operation. Support for DAS in CSPid is
accomplished by

enabling DAS operations by supplying a license key in the configuration

specifying one or more DAS server URLs in the configuration
11
CSPid Administrator’s Guide

importing one or more DAS CoI certificates into CSPid
With DAS enabled, CSPid will assert to applications that the private key for each DAS CoI certificate
resides locally and can be used via CSPid. To do this, CSPid creates a temporary private key object for
each DAS CoI certificate when C_Initialize or C_CreateObject is called. Each temporary private key
has a vendor defined attribute enabling CSPid to differentiate real private keys from DAS CoI private keys
when C_Sign or C_Decrypt are called. These objects are not permanent and will disappear if DAS is not
enabled in the configuration.
When an application asks CSPid to decrypt or sign using one of these temporary private key objects, CSPid
interacts with a DAS server to perform the operation only if the user is a member of the community. For
decrypt operations membership is checked using the encryption certificate provided to the DAS server.
DAS operations require SSL/TLS client authentication and, for unwrap requests, an encryption certificate
(see the DAS documentation for a complete description of a DAS transaction). CSPid automatically
selects the best certificates for both authentication and rewrap purposes using the notBefore date and, if
specified in the configuration, preferred issuer information. The private keys for the selected
certificates may reside either within CSPid itself (as software keys) or on a hardware token (e.g.,
CAC) specified in the configuration. In the latter scenario CSPid can store only the DAS CoI
certificates and no private keys are required to reside in CSPid. CSPid can also be configured to
utilize credentials in Microsoft CAPI for this purpose.
Inclusion of DAS support in CSPid allows any application to be DAS enabled including Microsoft
Outlook and Mozilla Thunderbird. This allows users to send S/MIME encrypted and signed e-mail in a
role based fashion rather than a user based fashion. Only members of a particular role will be able to
decrypt the e-mail messages and only members of the role will be able to sign e-mail messages as the
role. Chapter 7 provides more information on this capability and its uses.
1.4.1.Notes

If a DAS server reports that a user is not a member of the group, the COI certificate is removed
from CSPid and the user is told to try the operation again.

CSPid automatically picks the certificate for DAS authentication and group membership for the
user. This can be controlled using the configuration options to specify either an issuer DN or a
card label. Specific events related to the import of DAS COI certificates are available that mimic
the events that are associated with the import of actual credentials.
1.5. CCMS Integration
CSPid works with ISC’s CCMS (Centralized Credential Management System) to obtain user credentials in
an automated fashion. The Bagala Editor’s CCMS Client section allows an administrator to specify the
CCMS server URL and other options controlling how and when CSPid will communicate with CCMS.
Alternatively, the credential retrieval process can be launched via the CSPid command line.
1.6. CSPid CRL Management
CSPid version 5.0 and above include CRL management. One or more CRL URLs can be configured with
the Bagala Editor. On Windows, each CRL will be automatically stored in the Microsoft key stores for
12
CSPid Administrator’s Guide
use by Microsoft’s certificate validation routines. On all platforms, CSPid itself will use CRL information
when validating certificates during client authentication connection attempts.
1.7. CSPid Windows Validation Client with OCSP Support (Windows Only)
CSPid versions 5.0 and above include optional Windows Validation client that integrates with the
Microsoft certificate validation stack to support CRL checking and OCSP responders. The client may be
enabled by including a license key in the configuration using the Windows Validation Client section in
the Bagala Editor for CSPid.
The Bagala Editor also allows the administrator to specify which hosts or issuers should be checked by
the validation client and which method (none, CRL, or OCSP) should be used. The OCSP configuration
section allows the administrator to specify an OCSP server URL, certificate, and other options for each
host or issuer.
CSPid supports a local OCSP response cache that stores authentic responses from an OCSP responder.
Responses are cached even if nonce use is enabled. This is achieved because the nonce is checked in the
response from the server prior to it being cached.
13
CSPid Administrator’s Guide
2. Installation
2.1. Overview
CSPid is available on a variety of platforms and the installation process is platform-dependent. The
following files are typically installed:

the CSPid management tool (cspid_ui.exe or cspid_ui) and, if available, its translation files
(*.qm)

the CSPid command line tool (cspid_cli.exe or cspid_cli)

the CSPid PKCS #11 Library (cspid.dll or libcspid.so)

a CSPid configuration (CSPid.xml) – optional

the CSPid User’s Guide (cspid.pdf) – optional

a Firefox and Thunderbird add-on that enables them to automatically use CSPid
On Windows systems the following additional items are installed:
14

the CSPid Key Generation Provider (cspid.dll) in the Windows System folders

the CSPid Cryptographic Service Provider (isccsp.dll) in the Windows System folders

shortcuts in the Windows Start Menu for viewing this User’s Guide and starting the CSPid
management tool

a Java PKCS #11 configuration file (java_pkcs11.cfg)

the CSPid Lotus Notes command line configuration tool (cspid_ln.exe)
CSPid Administrator’s Guide
2.2. System Requirements
The following table lists the minimum version numbers for several of the most common applications that
one might wish to use with CSPid:
Supported
Browsers
Internet Explorer 7 or higher
Java
Java 1.5 and higher w/PKCS #11 support (see Java PKCS #11)
Firefox 17.0 or higher
On Windows Java’s SunMSCAPI provider can access CSPid via
its Microsoft CAPI/CNG layer
Operating
Systems
Windows XP SP 3 or higher with KB2836198 update
Windows Server 2003 (x86 & x64)
Windows Server 2008 (x86 & x64)
Windows Server 2012 (x86 & x64)
Windows Vista (x86 & x64)
Windows 7 (x86 & x64)
Windows 8 (x86 & x64)
Windows 8.1 (x86 & x64)
Windows 10 (x86 & x64)
Solaris 8 or higher for SPARC
RedHat Enterprise Linux 6 or higher for x86 or x64
Table 2: System Requirements
15
CSPid Administrator’s Guide
2.3. Windows
CSPid for Windows is distributed as standard MSI installation package that provides a wizard for
individual installation as well as supporting automated installation mechanisms. This setup program first
installs the core CSPid components; it will then install the translation files, configuration, and user’s guide
if they are present in the same folder as the MSI file. The following MSI command line parameters are
available (options may be combined):
Option
Values
Notes
CONFIGFILELOC
<path to CSPid.xml>
To specify the location of the
configuration to install execute:
msiexec.exe /I cspid.msi
CONFIGFILELOC=<path to CSPid.xml>
Examples: msiexec.exe /I cspid.msi
CONFIGFILELOC=\\server\share\configs
msiexec.exe /I cspid.msi
CONFIGFILELOC=F:\configs
ASSOCP12

0 (no)

1 (yes)
To have the installation associate .p12
and .pfx files with the CSPid Manager
execute:
msiexec.exe /I cspid.msi ASSOCP12=1

0 (no)

1 (auto-start
disabled)

2 (1 + no shortcuts)

0 (no)

1 (yes)
NOCSPIDMGR
OCSP
To prevent the CSPid Manager from
automatically starting when the user logs
into Windows:
msiexec.exe /I cspid.msi NOCSPIDMGR=1
Setting NOCSPIDMGR=2 will additionally
prevent the user’s guide and CSPid
Manager short cuts from being created.
To install the OCSP function and register
it with Windows run:
msiexec.exe /I cspid.msi OCSP=1
INSTALLDIR
<desired installation
path>
To install CSPid in a folder other than
the default Program Files folder run:
msiexec.exe /I cspid.msi
INSTALLDIR=C:\Path
FULL

0 (no)

1 (yes)
When uninstalling, set to 1 to remove
CSPid folders from all subfolders of the
Windows defined application data path.
Typically, this deletes all folders of
the form:
C:\Users\<username>\AppData\Roaming\CSPid
msiexec.exe /x cspid.msi FULL=1
To customize CSPid, create a CSPid.xml file using the Bagala Editor modifying the options settings as
desired (See section 3.6 for more information). Be sure to save the CSPid.xml file into the same folder as
the cspid.msi file. Then install the CSPid system by executing cspid.msi and following the prompts.
16
CSPid Administrator’s Guide
After installation on a Windows system, the CSPid management tool (see the CSPid User’s Guide) will
automatically start up and run in the system tray each time the user logs in (unless NOCSPIDMGR is used
during installation or Start hidden is set to yes in the configuration). The first time the tool is executed it
will ask the user to set the CSPid password if necessary (unless Auto-initialize is set to no or Exit if not
Initialized is set to yes).
2.4. UNIX
CSPid for UNIX is distributed as a single compressed tar ball (cspid.x.y.z.os.processor.tar.gz) that
must be decompressed and untar’d. The resulting cspid folder contains an INSTALL file that provides
platform-specific installation tips. Typically all that is required is to move the cspid folder to /opt/cspid
and to create the CSPid.xml file with the Bagala Editor.
To customize the way CSPid behaves, modify the options settings in CSPid.xml as desired. (See section
3.6 for more information.) libcspid.so and all associated utilities read their program configuration data
from CSPid.xml located in one of the following folders (in the order listed): /etc, /usr/etc.
Users can use the included Firefox and Thunderbird extension (cspid.xpi) to add CSPid support or
manually configure it as a PKCS#11 device.
In the event that the Renew My Certificates feature (see the CSPid User’s Guide) is not functioning, users
may need to set a BROWSER environment variable that points to the web browser to use for enrollment.
Ideally /opt/cspid/cspid_ui will be configured to automatically start when each user logs into their
desktop.
17
CSPid Administrator’s Guide
3. Configuration
3.1. Using CSPid with a Web Browser
3.1.1.CAPI-based Browsers
When CSPid is installed, the certificates in its key store are copied into the appropriate CAPI stores (and
linked to the private keys stored in CSPid) and are therefore available to any Microsoft CryptoAPI-based
application (such as Internet Explorer and Outlook). Users will be prompted to enter their CSPid password
once per application instance unless password caching is enabled.
3.1.2.Mozilla-based Browsers
CSPid must be registered with Mozilla-based programs before it can be used by them. On Windows, a
Firefox and Thunderbird compatible add-on is installed that automatically performs the required task. On
UNIX, users may manually install the add-on or an administrator can configure the system by following
the instructions in the INSTALL file included in the package.
To manually register CSPid with a Netscape-based product, just add cspid.dll or libcspid.so to its list
of supported PKCS #11 tokens by opening the product’s Preferences dialog and modifying the “Security
Devices” or “Advanced” properties.
Once CSPid has been registered, ISC CSPid should appear in its list of available cryptographic tokens and
users will be prompted for the CSPid password as needed.
3.2. Enrollment with a Web Browser
3.2.1.CAPI-based Browsers
To ensure that CSPid generates and stores users’ private keys during PKI enrollment, users should
explicitly tell the enrollment application to use the CSPid Key Storage Provider or CSPid Key Generation
Provider as its cryptographic service provider (CSP). When Internet Explorer, for example, is configured
in this way and used for PKI enrollment, it will use CSPid to generate and store private keys and to
construct certificate requests. Alternatively, the certificate authority may be capable of controlling the
CSP that is used and could be configured to only use the CSPid Key Generation Provider or CSPid Key
Storage Provider. The CSPid Key Storage Provider is preferred for RSA keys for Java compatibility.
3.2.2.Mozilla-based Browsers
To ensure that CSPid generates and stores users’ private keys during PKI enrollment, users must select
ISC CSPid as the cryptographic token to use when prompted by the browser.
3.2.3.Other
If scripting enrollment, administrators may use CSPid’s command line utility (cspid_cli) to generate
suitable certificate requests. The cspid_cli includes a --gen-p10 command that will create a PKCS#10
18
CSPid Administrator’s Guide
certificate request whose private key resides in CSPid. The request is suitable for uploading to a CA using
the --post option to submit the request or using any other means to submit the request. The issued
certificate may be picked up by the user using either Internet Explorer, Firefox, or simply by importing
the issued certificate into CSPid.
3.3. Using CSPid with Java Applications
3.3.1.Via Windows Native Store (CAPI)
On Windows, recent versions of Java include support for Microsoft CAPI as a key store. On such
systems, Java, like other CAPI-based applications, requires no additional configuration to work with
CSPid. Otherwise, some manual configuration of a system is required to use CSPid with Java applications.1
Since complete instructions are available from Sun2, only an outline of the required procedure is provided
in this section. The CSPid Key Storage Provider is preferred for RSA keys for Java compatibility.
3.3.2.Via PKCS#11
To make CSPid available to all Java programs on a system, add a line to the java.security file that
references the Java PKCS #11 configuration file, java_pkcs11.cfg, placed in the CSPid folder during
installation. A sample is provided below:
security.provider.7=sun.security.pkcs11.SunPKCS11 c:/Program
Files/CSPid/java_pkcs11.cfg
Figure 2: Modifying the java.security File
To make CSPid available to a Java program programmatically, insert the following lines:
String configName = "C:/Program Files/CSPid/java_pkcs11.cfg";
Provider p = new sun.security.pkcs11.SunPKCS11(configName);
Security.addProvider(p);
KeyStore ks = KeyStore.getInstance("PKCS11");
// PIN is the CSPid login password.
ks.load(null, PIN.toCharArray());
Figure 3: Modifying Your Java Code
To use CSPid for client authentication in SSL/TLS connections in existing programs, users may have to
set the following system properties with the –D option. See Java SSL/TLS for more information. If no key
store password is provided, CSPid will prompt the user for their password if one is required.
javax.net.ssl.keyStoreType=PKCS11
javax.net.ssl.keyStorePassword=<password>
javax.net.ssl.keyStore=NONE
javax.net.ssl.keyStoreProvider=SunPKCS11-CSPid
Figure 4: Modifying Java SSL/TLS Properties
1
Java 2 version 1.5 or above is required for native PKCS #11 support through the JDK; earlier versions of Java might be able to access CSPid on
certain platforms, but this use is not supported by ISC.
2
See http://java.sun.com/j2se/1.5.0/docs/guide/security/p11guide.html
19
CSPid Administrator’s Guide
A sample Java program, cspid.java, that illustrates how CSPid may be used programmatically from
within Java code is included in the installation.
Please note that 64-bit Java running on Windows does NOT support 64-bit PKCS#11 libraries. This is a
Java limitation. Also, there are several defects in the Java PKCS#11 support with respect to certain
characters in paths. Notably, ‘(‘ and ‘)’ cannot be in the path. On 64-bit Windows systems where CSPid
installs in to Program Files (x86) Java will refuse to work with the cspid.dll in the installation
folder. Using the cspid.dll file in C:\Windows\SysWow64 is recommended.
3.3.3.Blacklists, Whitelists, and Java
All Java applications appear to CSPid as java or java.exe and thus it is difficult to effectively use the
Blacklist or Whitelist functionality with Java applications. Java’s native SSL and some other applications
allow for the specification of the key store to use. By creating multiple instances of the CSPid library with
unique names and adding them to the java.security file you can easily use CSPid’s ability to base the
blacklist or whitelist decision on the library name and effectively control which certificates are available
to the Java application. An example:
1. Copy /opt/cspid/libcspid.so to /opt/cspid/libmyapp.so
2. Create /opt/cspid/libmyapp.cfg with the following values
name = CSPid-MyApp
library = /opt/cspid/libmyapp.so
description = ISC_CSPid
slot = 1
attributes = compatibility
3. Edit $JAVA_HOME/lib/security/java.security and add a line to the security provider list
security.provider.10=sun.security.pkcs11.SunPKCS11 /opt/cspid/libmyapp.cfg
4. In the CSPid Manager add libmyapp.so to the blacklist of certificates to hide
5. Use javax.net.ssl.keyStoreProvider=SunPKCS11-CSPID-MyApp when running the program
3.4. Using CSPid with Apache Tomcat
To use CSPid as the TLS key container for Apache Tomcat, the java.security file must be modified as
indicated in Figure 2 above, and the server.xml file located in <Tomcat Home>/conf/server.xml must
be changed so that it looks roughly as follows:
<Connector port="443" scheme="https" secure="true" clientAuth="false"
sslProtocol="TLS" keystoreType="PKCS11" keystorePass="PASSWORD" />
Figure 5: Modifying the Tomcat server.xml File
With these settings CSPid will be used as the server’s keystore and trust keystore.
If TLS client authentication is enabled by setting clientAuth=“true” in the server.xml file, only client
certificates subordinate to a root certificate stored in CSPid will be accepted.
20
CSPid Administrator’s Guide
3.5. Using CSPid with Stunnel
Stunnel is an open source product that adds TLS encryption to existing clients and servers that lack that
capability natively. It requires no changes to the existing program’s code. More information can be found
at https://www.stunnel.org. When configured to use CSPid, Stunnel can provide a work around for
programs that do not support TLS, PKCS#11, or are otherwise incompatible with CSPid.
A Stunnel configuration file that uses CSPid for client authentication would look like:
cert=/home/user/user.pem
client=yes
fips=yes # note requires the installed version of OpenSSL to be FIPS enabled
engine=dynamic
engineCtrl=SO_PATH:/usr/lib/openssl/engines/engine_pkcs11.so
engineCtrl=ID:pkcs11
engineCtrl=LIST_ADD:1
engineCtrl=LOAD
engineCtrl=MODULE_PATH:/opt/cspid/libcspid.so
engineCtrl=INIT
engineCtrl=PIN:
pid=/home/user/stunnel.pid
verify=2
CAFile=/home/user/cacerts.pem
foreground=yes
[server1]
accept=127.0.0.1:9999
connect=server1.isc.com:443
engineNum=1
key=slot_1-id_CKA_ID
Where:

engineCtrl=PIN:

key=slot_1-id_CKA_ID
causes Stunnel to pass an empty password to CSPid which will prompt for a
password if one is needed.
specifies the PKCS#11 slot and CKA_ID of the certificate to use. The
slot will always be 1. The CKA_ID varies for each certificate and can be copied from the CSPid
Manager by selecting the CKA_ID field of the certificate and pressing Control+C.
3.6. CSPid Configuration
CSPid‘s operating characteristics can be controlled by creating or modifying the CSPid.xml file before or
after installation. If no CSPid.xml file is found, CSPid will operate with its default internal settings.
Starting with version 3.5.0 the CSPid.xml file should be created using ISC’s Bagala Editor which outputs
a base XML file. This tool allows you to create both the initial policy and update policies to be placed on
ISC’s Bagala configuration server and downloaded by CSPid.
NOTE: CSPid will accept a file URL as the Bagala Server URL. It is expected that the file URL will
reference a complete path and filename. For example: file://Z:\cspid\cspid.xml or
file://\\192.168.1.1\share\cspid\cspid.xml. CSPid will copy this file instead of contacting a Bagala Server
to obtain an update.
21
CSPid Administrator’s Guide
3.6.1.Windows
On Windows, the active configuration is the one found in the installation folder unless a valid updated
configuration (either from the Bagala server or from a file server) is found in the user’s profile folder.
On Windows systems, CSPid expands the JAVA_HOME and CSPID_HOME environment variables with
appropriate values prior to running event handler scripts.
3.6.2.UNIX
On UNIX, libcspid.so searches the following directories, in order, for CSPid.xml: /etc, /usr/etc.
Searching these system directories should ensure that only a configuration installed by an administrator is
used. Administrators should ensure that the configuration files are properly secured on the system to
prevent user modification. The active configuration is the one found in the folders above unless a valid
updated configuration (either from the Bagala server or from a file server) is found in
$HOME/.cspid/policies.
3.6.3.CSPid Events
Before delving into the details of CSPid Events, consider this practical scenario where an administrator
wants to facilitate PKI enrollment and application configuration for end users by performing the
following, fairly typical, tasks:
1. have a user who has no existing credentials obtain a signing certificate from the enterprise CA
using his default web browser,
2. use the signing certificate just obtained to download via client-authenticated SSL a PKCS#12
PDU containing (a possibly escrowed) encryption key,
3. import the PKCS#12 PDU into CSPid and then delete it,
4. publish the user’s new credentials to the Exchange Global Address List (GAL), and
5. configure Microsoft Outlook to use the new credentials for S/MIME.
Employing CSPid event handlers (along with cmu, ISC’s Credential Management Utility), an administrator
can accomplish these five steps by:
i. adding the following URL to the CSPid.xml configuration using the Bagala Editor to cause each
occurrence of an Enrollment event (an event triggered by the user starting CSPid with no
credentials in their active key store) to be handled by opening the specified webpage in the user’s
default browser:
Enrollment, open URL
http://ca1.yourorganization.com/enroll
ii. adding the following five lines into a batch file and import it into the New signature certificate,
run command in the Bagala Editor:
“C:\CMU\cmu.exe” d “%TEMP%\temp.p12”
“C:\Program Files\CSPid\cspid_ui.exe” -i -f "%TEMP%\temp.p12"
del “%TEMP%\temp.p12”
“C:\CMU\cmu.exe” p
22
CSPid Administrator’s Guide
“C:\CMU\cmu.exe” m
This handler, whose execution is triggered by the retrieval of a new signing certificate (possibly caused
by the completion of the enrollment process handled in step i), invokes cmu several times to download the
user’s escrowed encrypting PKCS #12 file, install it into their key store, publish the new credentials to
GAL, and configure their default MAPI provider.
3.6.4.Controlling Certificate Visibility
By default, all certificates stored within CSPid are visible to all applications. However, it is possible to
hide specific certificates from certain applications if this is desired or required for security reasons. CSPid
accomplishes this by allowing an application blacklist (or whitelist) to be specified on a per-certificate
basis in the CSPid key store. Certificate black-/whitelists can be set either during certificate import using
the cspid_cli program, or edited at a later time using the CSPid Manager. These lists may consist of
actual application names or admin-defined tags that refer to applications specified in the configuration.
(The tag method is preferred as it enables the lists to be changed without modifying the CSPid key store.)
The special tag value CAPI represents the Microsoft Windows CAPI store and all applications that use it.
For example, to prevent Firefox and Thunderbird from using a particular certificate, set its blacklist to
some admin-defined tag, say, MOZILLA, and add a corresponding tag specifying the comma-delimited list
of proscribed applications using the Bagala Editor (firefox.exe, thunderbird.exe, firefox, thunderbird).
Similarly, to allow only CAPI-enabled applications to see a particular certificate, set its whitelist to an
admin-defined tag, say, CAPIONLY, and add a corresponding tag specifying CAPI using the Bagala Editor.
Filtering can also be performed based on the CSPid library name in those situations in which application
names are not unique (as is typically the case for Java-based applications). In these situations, a copy of
cspid.dll can be made with a new name, an application is configured to use the newly-named library,
and this new library name is used in a whitelist or blacklist.
3.6.5.Updating the Configuration
As described above, an initial configuration is usually installed on each system on which the CSPid
software is installed. To facilitate the subsequent modification of configuration settings, CSPid supports
ISC’s Bagala configuration server for retrieving updated configuration information. When CSPid connects
to the server it checks the validity of the server’s certificate and, if it is valid, CSPid attempts to retrieve an
updated configuration to use in place of the initial configuration. Updates may be performed manually
using the cspid_cli tool or set to run periodically using the CSPid Manager. The Windows Task
Scheduler (or UNIX cron command) can also be used to run cspid_cli on a scheduled basis.
By default, the CSPid Manager checks for updated files only when it starts, so if a user never logs out
updates will not occur. To check for updates on a regular basis, use the Update duration setting.
Updates are cached locally in an encrypted file in the folder specified by the Local Store setting. The local
cache is used if it is valid and will completely override all settings enabling administrators to update the
password reset agents, trust anchors and all other options from a central location.
When an update occurs, CSPid uses DN information – first the user’s, if allowed and determinable, then
the Update Distinguished Name value in the last valid configuration– to locate update files on the server.
23
CSPid Administrator’s Guide
The Bagala Server converts the DN to lowercase and successively truncates leading RDNs until either an
update is found or the DN is empty.
If the configuration enables the use of the user’s DN for updates (Use User’s DN set to yes) then CSPid
will attempt to determine the user’s DN (by locating the most recently issued certificate with a private key
in CSPid itself using the DAS configuration options for AKI, Issuer DN, and Label, or, failing that,
finding the most recently issued certificate with a private key in a configured PKCS #11 device with the
same algorithm). The first update always uses the initial configuration’s Update Distinguished Name
because the software doesn’t know the user’s DN at that point.
If an invalid configuration is downloaded or if the local cache is corrupt, it will be ignored and the
installed configuration will be used. Updates and the ancillary information are stored in the location
specified by Local store. This is usually located in a subfolder of the path containing the PKCS #15 PDU
(%APPDATA%\CSPid\policies on Windows or $HOME/.cspid/policies on UNIX), but can be
independently specified. Deleting the items in this folder will cause CSPid to revert to the installed initial
configuration and reset the update process.
This mechanism enables administrators to create policies at the organization, group, or individual level.
3.6.5.1. Creating a machine configuration enabling updates
The following items must be present in the initial (installed) configuration in order to enable the use of
updated configuration:

Bagala Server URL

Update Distinguished Name

Update Duration

Trust Model
The Trust Model setting indicates how the client should trust the Bagala Server holding updated
configurations. Setting it to Native OS will use Microsoft Windows’ built in certificate validation routines
and trust anchors and is recommended. For UNIX systems or to restrict the list of trusted certificates you
can set the trust model to Trusted Certificate or Trusted Issuer DN. Setting this value to Trusted
Certificate requires that an X.509 trust anchor be specified in the Trusted Certificate option. Only server
certificates whose certificate path ends with this certificate will be trusted for configuration updates.
Setting the value to Trusted Issuer DN requires that a subject DN be specified in the Trusted Issuer DN
option. Only server certificates whose certificate path ends in a certificate whose issuer DN matches this
value will be trusted for configuration updates.
3.6.5.2. Creating an updated configuration
An administrator should use the Bagala Editor and create a new product configuration specifying the DN
to which it should apply. Once completed, configuration can be published to a Bagala Server using the
Bagala Editor’s Publish current configuration DN option.
24
CSPid Administrator’s Guide
3.6.5.3. Running a manual update
A user can initiate an update by using the cspid_cli --cfg-update command. This will force the
application to attempt to download and use an updated configuration.
3.6.6.Password Reset Agents
Password reset agents can be specified using the Bagala Editor.
3.6.7.Configuration Options
Configuration options are detailed in the Bagala Editor.
25
CSPid Administrator’s Guide
4. CSPid Password and Key Management
4.1. Password Management
Password change is accomplished using the standard PKCS #11 C_SetPin() call. Users can use the
supplied programs, Mozilla-based applications, or other PKCS #11 compliant tools to change their
passwords.
4.1.1.Password History
The configuration options support the prevention of password re-use. The administrator can specify the
number of unique passwords a user must use before they can re-use a past password. The password
history is stored by CSPid in the PKCS #15 PDU as a string. The first 8 bytes of the string are the salt
chosen the first time the password was set. The remaining values are the hash values for each password
that the user has used. The string is truncated at each password change to contain only the last X password
hash values where X is the number specified in the configuration. An iteration count of 512 is used along
with the salt to help ensure that it is not possible to do easy table lookups of the hash to password by
attackers. As of version 5.0 the algorithm used is PBKDF2 with SHA-512 producing 32 bytes for each
password.
4.1.2.Forced Password Change
If the configuration has specified password change requirements based on time (i.e. that users must
change their passwords every X days) the library will enforce this requirement by returning a vendor
defined error code when the C_Initialize() function is called (0x82050112 is returned in this case). In
fact, the C_Initialize() function has succeeded but well behaved applications will detect the error code
and fail. A message box is displayed by the library alerting the user. If the management tool detects this
error it displays the password change dialog to allow the user to easily change their password. For the 10
days preceding a required password change users are asked if they would like to change it when the
management tool starts. The date and time of the last password change is stored in the PKCS #15 PDU.
4.1.3.Administrative Password Reset
When the administrative password reset feature is enabled and the user sets, resets, or changes their
password, CSPid will:
1. generate (in a FIPS 140 compliant manner) a pseudorandom string of at least 8 bytes
2. base64-encode the random string generated in 1 to create a new reset password
3. encrypt as a CMS PDU the reset password under the user password, the reset password itself, and
each PRA certificate, and store the result in the user’s active key store (the PKCS #15 PDU)
4. use the reset password as a “PBE-recipient” key during re-encryption of all private objects
5. use the reset password as a PBE-recipient key when generating an HMAC-based CMS
authentication wrapper for the PKCS #15 PDU
Because of point number 4, the reset password and user password are on an equal footing with respect to
their ability to unwrap private objects, but unlike the user password, the reset password can be recovered
(i.e., decrypted) using an administrator private key.
26
CSPid Administrator’s Guide
NOTE: administrators cannot recover the actual user password which protects the user in case they have
used that password for other purposes.
In order for the reset password to be recoverable by any PRA, as well as available at runtime to encrypt
new or changed private objects, it is stored in the PKCS #15 PDU encrypted under itself, the user
password, and all PRA certificates. When the user logs in with either their own password or the reset
password provided by a PRA, the system can, in either case, easily recover the reset password and
determine which of the two passwords was entered. If the user entered the reset password, they are forced
to change their password (thereby generating a new reset password unknown to any PRA).
4.1.4.Password Timeout
When the password timeout feature is enabled, CSPid will require the user to reenter their password after
the specified period of inactivity has passed. The method used to cause the calling application to prompt
for the password varies depending on how the calling application accesses the library:

Via PKCS #11, the information returned from the library’s C_GetSessionInfo function will
indicate a state of CKS_RW_PUBLIC_SESSION which tells applications that the card is in the
logged out state when timeout has occurred. The calling application can then call C_Login to
authenticate to the library. If the calling application fails to call C_Login the library will prompt
the user for their password if a sensitive value is required.

If an application attempts an operation that requires the KEK but fails to test and re-authenticate
to the library, the library itself will display a password prompt. This is the method that the CSPid
Management Tool and the Windows KSP/CSP use.
NOTE: When used with a web browser, the server’s SSL/TLS server side timeout value may be greater
than the CSPid timeout value in which case no prompting will occur because the server does not require
the user to authenticate again. Sensitive web sites should have a timeout value that is less than or equal to
the timeout value set in CSPid.
4.1.5.Password Caching
On Windows, CSPid supports per-session and permanent password caching. UNIX-based systems support
only per-session password caching. Both work using the same mechanism. On Windows, the cached
password is encrypted using CryptProtectData and stored in the cspid.ini file and in the CSPid P15
PDU. On UNIX-based systems, an AES key is derived from the user’s login ID and used to encrypt the
password. If per-session caching is enabled, this value is deleted when the CSPid system tray application
exits and is only created if the CSPid system tray application is active. If permanent caching is enabled,
this entry is never deleted. In essence, this method ensures that only applications run within the user’s
own credential space can obtain the password. The MSDN documentation on CryptProtectData provides
excellent details and should be consulted if more information is required.
If permanent password caching is enabled and the user wants or is required to change their CSPid
password, they may enter their current Windows password in place of the current CSPid password in the
password change dialog. Similarly, users may enter their current Windows password in place of the
current CSPid password when exporting private keys. In both cases the Windows login password is
confirmed and if correct the cached password is retrieved and used.
27
CSPid Administrator’s Guide
4.2. Key Management
CSPid stores certificates, public keys, private keys, and PKCS #11 data objects (CKO_DATA). Following
PKCS #11 specifications, objects that are marked CKA_PRIVATE, TRUE have strong restrictions on which
of their attributes are exposed and which can be changed. Similarly, objects marked CKA_EXTRACTABLE,
FALSE cannot be extracted from the token. Finally, certain object attributes can be changed in only one
direction. For example, the attribute CKA_SENSITIVE can be changed from FALSE to TRUE, but not from
TRUE to FALSE.
NOTE: The correct handling of such restrictions by CSPid might result in unexpected behavior. For
example, since most applications generate keys with CKA_EXTRACTABLE set to FALSE, users may not be
able to export such private keys from the device using a PKCS #11-enabled application.
However, for backup and recovery purposes, users can extract their private keys from the CSPid system
using the integrated management tools; both a graphical user interface and a command line program are
supplied. (These tools do not use standard PKCS #11 API calls but operate directly on the active key store
as a PKCS #15 PDU.)
Private objects are stored in the active key store as encrypted objects. When in memory, all data is stored
in ISC CDK strings or Key objects, both of which meet the FIPS 140-1/2 level 1 requirements for inmemory storage of keying material. When C_Login is called successfully the encrypted objects in the
PKCS #15 PDU are decrypted into encrypted memory. Memory related to specific objects is decrypted
temporarily when required to perform operations.
4.2.1.Encrypted Memory
When a user logs into CSPid all sensitive objects in the PKCS #15 PDU are decrypted and then stored in
an object in memory. Prior to version 2.1 this information was stored in memory in plaintext. Beginning
with version 2.1, the in memory storage object encrypts sensitive items.
For RSA private keys the following PKCS #11 values are encrypted while in memory:

CKA_PRIVATE_EXPONENT

CKA_PRIME_1

CKA_PRIME_2

CKA_EXPONENT_1

CKA_EXPONENT_2

CKA_COEFFICIENT
For ECC private key objects the following values are encrypted while in memory:

CKA_VALUE
For secret key objects (resulting from ECDH computations for example) the following values are
encrypted while in memory:

CKA_VALUE
For data objects that are marked private (resulting from Lotus Notes storing the user’s password) the
following values are encrypted while in memory:
28
CSPid Administrator’s Guide

CKA_APPLICATION

CKA_OBJECT_ID

CKA_VALUE
Other sensitive information that is encrypted while in memory:

All copies of the PKCS #15 PDU password

All copies of the (optional) password reset password

Temporary values computed when calling C_Decrypt with a NULL buffer in order to obtain the
size of the result.
The encryption scheme varies by platform as discussed below, but always uses a 32-byte key encryption
key (KEK) generated at random and stored in memory that cannot be written to the Windows page file,
UNIX swap partitions or accessed by other processes. The KEK is generated using the getrand3() method
in ISC’s FIPS-validated CDK 7 after which getrand3() is called again to transition the PRNG’s state to
ensure that the KEK does not remain in the PRNG’s memory space.
4.2.1.1.
Encrypted Memory on Windows 2000 and Windows XP
On Windows 2000 and Windows XP, CSPid uses CryptProtectData and CryptUnprotectData functions to
encrypt sensitive information in memory. The KEK is stored in memory allocated with VirtualAlloc,
marked with VirtualLock (to prevent paging), and protected with VirtualProtect (to prevent access by
other programs). The KEK is passed into the CryptProtectData and CryptUnprotectData data functions
via the optional entropy parameter in order to protect against other processes obtaining the encrypted
memory and using CryptUnprotectData.
Using this scheme the PKCS #15 PDU passwords and sensitive keying material are protected against the
following:
1. Other programs running on the system cannot access the process’ memory and decrypt the in
memory information because the KEK is protected and is inaccessible to other applications.
2. Someone in possession of the Windows hibernation file cannot decrypt the in memory
information because when Windows hibernates or sleeps it clears information required by the
CryptUnprotectData function to decrypt.
NOTE: When Windows is run inside a virtual machine and that virtual machine is “suspended” the KEK
will be accessible (as will sensitive operating system protected information) in a file on the host machine
that contains the system’s memory. In such instances, ISC recommends using the password timeout
option with a short timeout period in order to clear the KEK from memory as soon as possible.
4.2.1.2.
Encrypted Memory on Windows Vista and Windows 7
On Windows Vista/7 CSPid uses the CryptProtectMemory and CryptUnprotectMemory functions to
encrypt sensitive information in memory. These functions require the data to be a multiple of
CRYPTPROTECTMEMORY_BLOCK_SIZE (currently 16) and PKCS#5 padding is used to expand
plaintext as necessary. CryptProtectMemory is called with the
CRYPTPROTECTMEMORY_SAME_PROCESS flag to prevent other processes from decrypting the
memory. The KEK is stored in protected memory as described for Windows 2000/XP. The KEK is used
to super encrypt the output of CryptProtectMemory using the AES Key Wrap algorithm specified in RFC
29
CSPid Administrator’s Guide
3394 in order to link the user’s password with the encrypted memory to properly support password
timeout. In this way, it is more difficult to recover the encrypted memory when the password has timed
out.
Using this scheme the user’s PKCS #15 PDU password and sensitive keying material is protected against
the following:
1. Other programs running on the system cannot access the process’ memory and decrypt the in
memory information because the CRYPTPROTECTMEMORY_SAME_PROCESS flag restricts
access to the original process.
2. Someone in possession of the Windows hibernation file cannot decrypt the in memory
information because when Windows hibernates or sleeps it clears information required by the
CryptUnprotectMemory function to decrypt.
NOTE: When Windows is run inside a virtual machine and that virtual machine is “suspended” the KEK
will be accessible (as will sensitive operating system protected information) in a file on the host machine
that contains the system’s memory. In such instances, ISC recommends using the password timeout
option with a short timeout period in order to clear from memory the KEK which is required to remove
the super encryption prior to calling CryptUnprotectMemory.
4.2.1.3.
Encrypted Memory on UNIX-based Systems
On Linux, OSX, and Solaris CSPid uses the AES Key Wrap algorithm specified in RFC 3394 to encrypt
sensitive information in memory which is padded according to PKCS#5. As on Windows, the KEK is
generated and stored in protected memory (mlock is used to prevent it from being swapped; mprotect is
used to prevent access by other processes).
Using this scheme the user’s PKCS #15 PDU password and sensitive keying material is protected against
an attacker accessing the process’ memory and decrypting the in memory information. However, not all
platforms behave in a consistent manner with regards to the mlock and mprotect functions. Notably,
Solaris 8 requires root access to use the mlock function. Thus, it is possible that the KEK could be written
to the swap partition. In general, on UNIX-based systems ISC recommends using the password timeout
option with a value appropriate to the sensitivity of the keys.
4.2.2.Password Timeout Implementation Details
When the C_Login function is first called the library spawns a thread that waits for the specified time of
inactivity to pass and then encrypts the KEK value with the PKCS #15’s password. The encryption
algorithm used is the same algorithm used when encrypting private information for storage in the PKCS
#15 (see section 10.4). When the user re-enters their password, the KEK is decrypted and placed back into
protected memory. Thus, when password timeout is enabled all sensitive information is encrypted and the
PKCS #15 PDU password is required to decrypt.
4.2.3.Key Management in the CSPid Management Tool
Prior to version 2.1 the CSPid Management Tool would keep all keys in memory in plaintext form when
running. Beginning with version 2.1, in addition to storing the keys in encrypted memory, the CSPid
management tool will encrypt the KEK, using the same method as described in 4.2.2, when minimized. If
the KEK is required for an operation the tool will prompt the user for the password.
30
CSPid Administrator’s Guide
5. CSPid Libraries
5.1. The PKCS #11 Library
CSPid includes a PKCS #11 library module named CSPid.dll (Windows) or libcspid.so (UNIX) for
use by security-enabled applications that can access PKCS #11 compliant tokens.
On Windows, this library is installed in the CSPid program folder, by default C:\Program Files\CSPid,
and is automatically registered in any Mozilla-based profiles the next time the user logs in.
On UNIX, the default installation directory is /opt/cspid.
Manual configuration is normally required for non-Mozilla-based applications and most Java
applications. See Chapter 3 for more detailed information.
The PKCS #11 library publishes its capabilities via the C_GetMechanismInfo() function. The current list
of supported mechanisms can be found in Appendix A: Supported PKCS #11 Mechanisms.
See “CSPid API Developer’s Guide, Version 5.0.0” for more information.
5.2. The Microsoft Windows Library
CSPid can integrate with any application that uses the native cryptographic framework on a supported
Windows platform (e.g., Internet Explorer, Outlook, Outlook Express) through their CryptoAPI (CAPI)
or “Cryptography API: Next Generation” (CNG) interfaces. This is accomplished by installing a Key
Storage Provider (KSP) and Cryptographic Service Provider (CSP) adhering to Microsoft specifications,
and then registering CSPid with the system.
When configuring Windows applications to use CSPid for PKI enrollment purposes, users and
administrators must select either the CSPid Key Storage Provider or CSPid Key Generation Provider to
ensure that all keys are generated and stored by CSPid. The CSPid Key Storage Provider is preferred for
RSA keys for Java compatibility.
31
CSPid Administrator’s Guide
6. Quality Assurance
6.1. Testing Methodology
On Windows, CSPid was tested against the following system and applications software, to ensure that it
correctly performed the indicated tasks with all applications:
Software
Tasks Executed
Windows
Certificate enrollment
Internet Explorer
Client-authenticated SSL/TLS
Microsoft Outlook
S/MIME sign/decrypt
Firefox
Memory scanning for sensitive
material
Thunderbird
JRE
Lotus Notes
Cisco VPN Client
Table 3: Test Configurations
See the CSPid Test Plan document for detailed information on the range of tests that were performed.
32
CSPid Administrator’s Guide
6.2. Known Issues
6.2.1.Windows

Uninstalling CSPid may leave links in CAPI between certificates and the removed CSPid.dll. If
the user attempts to use a private key associated with one of these certificates, they will be shown
an error message. Reinstalling CSPid and “clearing” it using the command line management
utility will resolve this issue. Alternatively, the user can delete the affected certificates from the
CAPI store using Internet Explorer.

If the user is roaming from machine to machine, deleting certificates on one machine will leave
entries in the Microsoft CAPI store on a previously used machine. When the user goes back to
that machine and uses an application that is CAPI-based they may receive an error. This is
usually fixed when the CSPid system tray application starts. In cases where it is not automatically
fixed, the user may run the Register with Applications command which will remove stranded
entries.
6.2.2.Netscape 4.x or higher w/o PSM

Currently none.
6.2.3.Netscape 4.75 or higher w/PSM 1.4

Importing a certificate (as part of a PKI enrollment process) and then immediately using the
personal security manager (PSM) to view available certificates causes it to crash, requiring the
user to restart Netscape.
6.2.4.Internet Explorer

When running in Internet Explorer's "protected mode" CSPid is unable to make changes to disk. If
password caching is enabled and the first password prompt occurs in Internet Explorer when in
"protected mode" the password will not be cached.
6.2.5.Microsoft Outlook

Currently none.
33
CSPid Administrator’s Guide
7. Net-Centric Applications
CSPid can be deployed in conjunction with DAS and your company's existing security-enabled
applications (e.g., Microsoft Outlook S/MIME) to support enhanced security protocols, such as role-based
signing and decryption that were previously impossible to implement with conventional PKI-based tools.
In fact, the combination of CSPid and DAS allows you to leverage security tools based on today's
standards to provide functionality that some vendors would have you believe can only be obtained using
more recent schemes such as identity-based encryption (IBE) for which standards have not yet been
established.
The following scenarios illustrate four of the possible applications of CSPid/DAS in a 'net-centric'
environment:
7.1. Role-Based Authentication
PROBLEM: A group of watch officers are to sign messages that recipients can validate as having been
issued by some authorized group member. (In this scenario, recipients don't care which individual signed
a given message, they only need assurance that an authorized member of the group did so.)
SOLUTION SETUP: An asymmetric key pair is generated for the watch officer role, a special role
certificate is issued on the public component, and the role private key is put under the control of a DAS
server that is configured to perform signing operations with that key only for individuals on the active
duty roster for this role. The role certificate is loaded into the CSPid clients on all watch officer systems
and CSPid is registered with all security-enabled client applications on those systems. (In fact, all watch
officer logins may be hosted on a single system.)
OPERATION: When a watch officer attempts to sign an outgoing message using the role credentials with
any security-enabled client application on his system, his CSPid client automatically establishes a TLSsecured connection (with client authentication) to the appropriate DAS server where the signature
computation is performed using its protected role private key. As usual, recipients use the watch officer
role certificate to validate all signed messages.
watch officers
watch officer
role
CSPid
(role certificate)
1
Application requests role signature
2
CSPid contacts server w/ client credentials
3
Server authenticates client, returns signature to CSPid
3
CSPid returns signature to application as if it was signed locally
HSM
(optional)
net-centric
environment
(TLS w/ client auth.)
duty roster
DAS server
(watch officer private key
and duty roster/ACL)
Figure 6: Watch Officers Sign Messages with Shared Role Key on DAS Server
RESULT: Recipients can be assured that an authorized watch officer issued each validly-signed message
while the DAS server’s audit trail keeps track of the identities of the individuals who actually performed
each signing operation. Since the watch officer private key is securely protected by the DAS server
(possibly on an independent HSM), at no time is it available for compromise even by authorized signers.
34
CSPid Administrator’s Guide
7.2. Role-Based Encryption
PROBLEM: Documents and e-mail messages encrypted for a particular commander (e.g., CMDR
CENTCOM) must be available (without re-keying) to his successor in that role.
SOLUTION SETUP: An asymmetric key pair is generated for the commander, a special role certificate is
issued on the public component, and the private component is put under the control of a DAS server that
is configured to perform decrypt operations with that key only for the active commander. The certificate
is loaded into the CSPid client on the commander's system and CSPid is registered with all securityenabled client applications. All documents and e-mail messages are encrypted for the commander using
the role certificate.
OPERATION: When the commander attempts to decrypt a document or e-mail message encrypted with
the role certificate, the CSPid client on his system automatically establishes a TLS-secured connection
(with client authentication) to the appropriate DAS server where the required asymmetric key unwrapping
operation is performed using its protected private key. When the commander is replaced, an administrator
need only update the access control list (ACL) for the corresponding DAS account.
Commander
id
CSP
(role certificate)
1
Application requests unwrapping of session key
2
CSPid contacts server w/ client credentials
3
Server authenticates client, returns to CSPid session key
rewrapped with client certificate
3
CSPid unwraps session key (using client private key) and returns it to
application as if it was unwrapped locally
net-centric
environment
(TLS w/ client auth.)
HSM
(optional)
DAS server
(role private key)
Figure 7: Commander Decrypts Documents Using Role Key on DAS Server
RESULT: All sensitive documents and e-mail messages remain encrypted under a single certificate and
can only be decrypted by the current commander after strong authentication using his current individual
credentials (e.g., CAC card). No re-keying is necessary as different individuals inherit the commander
role and the critical private key is securely stored on a DAS server or, even more securely, on an attached
HSM. The DAS server's audit trail provides a centralized record of all decrypt operations and, optionally,
of the true identity of the individual who performed them.
7.3. Confidentiality within a Community of Interest
PROBLEM: Sensitive documents must be security shared among the members of a community of interest
(CoI) with a dynamic membership roster.
SOLUTION SETUP: An asymmetric key pair is generated for the CoI, a special group certificate is
issued on the public component, and the private component is put under the control of a DAS server that
is configured to perform decrypt operations with that key only for active CoI members. The certificate is
loaded into the CSPid client on the systems of all CoI members, and CSPid is registered with all securityenabled client applications on those systems. All sensitive documents and e-mail messages intended for
the CoI are encrypted under the group certificate.
OPERATION: When a CoI member attempts to decrypt a document or e-mail message encrypted with
the group certificate, the CSPid client on his system automatically establishes a TLS-secured connection
35
CSPid Administrator’s Guide
(with client authentication) to the appropriate DAS server where the required asymmetric key unwrapping
operation is performed using its protected private key. When the CoI membership roster changes, an
administrator need only update the access control list (ACL) for the corresponding DAS account.
Co
CoI member
1
Application requests unwrapping of session key
2
CSPid contacts server w/ client credentials
3
Server authenticates client, returns to CSPid session key
rewrapped with client certificate
CSPid
(CoI certificate)
membership
roster
DAS server
(CoI private key and
membership roster ACL)
id
3
HSM
(optional)
net-centric
environment
(TLS w/ client auth.)
CSP unwraps session key (using client private key) and returns it to
application as if it was unwrapped locally
Figure 8: CoI Members Decrypt Documents Using CoI Key on DAS Server
RESULT: All sensitive documents and e-mail messages remain encrypted under a single certificate and
can only be decrypted by active CoI members after strong authentication using their current individual
credentials. No re-keying is necessary as changes are made to the CoI membership roster. The critical
private key is securely stored on a DAS server or, even more securely, on an attached HSM. The DAS
server's audit trail provides a centralized record of all decrypt operations and, optionally, of the identities
of the individual CoI members who performed them.
7.4. Expanded Storage and Enhanced Security for Private Keys
PROBLEM: Key rollover results in a new certificate and private key being loaded onto a high-ranking
officer's smartcard where limited storage causes an older certificate and private key to be displaced.
Suddenly the officer has lost the ability to decrypt documents and e-mail messages encrypted with the
older credentials.
SOLUTION SETUP: Load the officer's entire key history into an account on a DAS server and install his
certificate history into a CSPid client on his own system.
OPERATION: Once CSPid has been registered with all security-enabled applications on the officer's
system, they will use his smartcard for cryptographic operations requiring his latest private key but
transparently establish a TLS-secured CSPid/DAS connection when access to an older private key is
required. Going forward, key rollover simply involves moving the officer's retiring certificate to
CSPid and the corresponding key pair to his account on the DAS server.
Officer
1
Application requests crypto operation using old private key
2
CSPid contacts server w/ current client credentials
3
Server authenticates client, performs private key operation
and returns to CSPid result encrypted under user’s current
credentials
3
CSPid applies user’s current private key to unwrap result and returns it
to application as if old private key operation was performed locally
CAC
(newest keys)
id
CSP
(old certificates)
net-centric
environment
(TLS w/ client auth.)
Figure 9: Officer Retains Access to His Entire Key History
36
HSM
(optional)
DAS server
(old private keys)
CSPid Administrator’s Guide
RESULT: By relying on the virtually unlimited storage of the DAS server (and the potentially greater
security of its key store which may be located on an HSM), an (on-line) user can maintain use of his
entire key history. He thereby retains access to all encrypted documents and e-mail messages ever sent to
him in a completely seamless manner.
7.5. Brokered Authentication - “Need-to-Know” Control Over Sensitive Resources
PROBLEM: Access to a sensitive resource needs to be controlled with a set of finely-tuned access control
rules that might vary over time.
SOLUTION SETUP: Generate a "resource key pair," obtain a "resource certificate" on the public key,
and distribute it to all users who might require access to that resource; ensure that the certificate is loaded
into the CSPid client on each user's system (this step may be automated in several ways). Create a DAS
account for the resource and install its certificate and private key along with a custom "authenticator" that
implements the access control rules. (An authenticator is a simple Java function that implements the
access control predicate: it takes as input the user's credentials and returns a Boolean response indicating
whether the user should be allowed or denied access to the requested resource. Sample predicates based
on LDAP group membership, certificate extension and/or attribute values, etc., can be provided.)
OPERATION: When an application attempts to access the sensitive resource, CSPid will be asked to
provide authentication (which normally takes the form of a "proof of possession" of the resource private
key — typically a digital signature). CSPid will then attempt to obtain this signature from the appropriate
DAS server as illustrated in the following diagram:
User
CSPid
(resource certificate)
1
Application requests authentication for resource access
2
CSPid contacts server w/ client credentials
3
If server authenticates client, resource authentication result is
returned to CSPid
3
If available, CSPid provides authentication to application, otherwise
access fails.
net-centric
environment
(TLS w/ client auth.)
HSM
(optional)
DAS server
(Resource private key and
custom “authenticator”)
Figure 10: A DAS Server Used to Impose Strong "Need-to-Know" Controls over Sensitive
Resources
Only if the user's credentials pass the custom authenticator's test will the DAS server provide the required
signature for resource access.
RESULT: Together, CSPid and DAS provide assurance that the sensitive resource is securely protected.
Maintenance of the entire system is simplified by reliance on a custom "authenticator" that may be easily
modified whenever access control policies change. A single DAS server can be used to protect an
unlimited number of sensitive resources in this way.
37
CSPid Administrator’s Guide
8. References
CSPid API
CSPid API Developer’s Guide, v 4.1.0, Information Security Corporation, February
2015.
CSPid Test Plan
CSPid Test Plan, v 3.0.3, Information Security Corporation, September 2013.
FIPS 46-3
FIPS 46-3: Data Encryption Standard (DES), NIST, October 25, 1999. Archived
May 19, 2005. http://csrc.nist.gov/publications/PubsFIPSArch.html
FIPS 180-2
FIPS 180-2: Secure Hash Standard, NIST, August 1, 2002. Archived October 2008
and superseded by FIPS 180-3. http://csrc.nist.gov/publications/PubsFIPS.html
FIPS 197
FIPS 197: Advanced Encryption Standard (AES), NIST, November 26, 2001.
http://csrc.nist.gov/publications/PubsFIPS.html
Java PKCS #11
Java™ PKCS #11 Reference Guide, Sun Microsystems, May 2004.
http://java.sun.com/j2se/1.5.0/docs/guide/security/p11guide.html
Java SSL/TLS
Java™ Secure Socket Extension (JSSE) Reference Guide, Sun Microsystems, 2004.
http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html
NIST AES Key
Wrap
AES Key Wrap Specification, NIST, November 2001.
http://csrc.nist.gov/groups/ST/toolkit/documents/kms/AES_key_wrap.pdf
PCSC
Basko, Dmitry, Development of PC/SC compatible driver for WINDOWS (MS
VC++.NET), 2003. http://www.bds.dogma.net/pc_sc.htm
PKCS #5
Password-Based Encryption Standard. v2.0, RSA Laboratories, March 25, 1999.
http://www.rsasecurity.com/rsalabs/node.asp?id=2127
PKCS #8
Private-Key Information Syntax Standard. v1.2, RSA Laboratories, November
1993. http://www.rsasecurity.com/rsalabs/node.asp?id=2130
PKCS #11
Cryptographic Token Interface Standard. v2.20, RSA Laboratories, June 2004.
http://www.rsasecurity.com/rsalabs/node.asp?id=2133
PKCS #12
Personal Information Exchange Syntax Standard. v1.0, RSA Laboratories, June
1999. http://www.rsasecurity.com/rsalabs/node.asp?id=2138
PKCS #15
Cryptographic Token Information Syntax Standard v1.1, RSA Laboratories, June
2000. http://www.rsasecurity.com/rsalabs/node.asp?id=2141
RFC 3211
Gutmann, P., RFC 3211: Password-based Encryption for CMS, University of
Auckland, December 2001. http://tools.ietf.org/html/rfc3211
RFC 3394
Schaad, J., and R. Housley, RFC 3394: Advanced Encryption Standard (AES) Key
Wrap Algorithm, Soaring Hawk Consulting and RSA Laboratories, September
2002. http://tools.ietf.org/html/rfc3394
RFC 3565
Schaad, J., RFC 3565: Use of the Advanced Encryption Standard (AES) Encryption
Algorithm in Cryptographic Message Syntax (CMS), Soaring Hawk Consulting,
July 2003. http://tools.ietf.org/html/rfc3565
38
CSPid Administrator’s Guide
RFC 3852
Housley, R., RFC 3852: Cryptographic Message Syntax (CMS), Vigil Security,
July 2004. http://tools.ietf.org/html/rfc3852
RFC 4231
Nystrom, M., RFC 4231: Identifiers and Test Vectors for HMAC-SHA-224, HMACSHA-256, HMAC-SHA-384, and HMAC-SHA-512, RSA Security, December 2005.
http://tools.ietf.org/html/rfc4231
Tomcat
The Apache Tomcat 5.5 Servlet/JSP Container SSL Configuration HOW-TO, The
Apache Software Foundation, 1999-2006. http://tomcat.apache.org/tomcat-5.5doc/ssl-howto.html
X.680
Information Technology – Abstract Syntax Notation One (ASN.1): Specification of
Basic Notation, ITU-T, July 2002.
X.690
Information Technology – ASN.1 Encoding Rules: Specification of Basic Encoding
Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules
(DER), ITU-T, July 2002.
39
CSPid Administrator’s Guide
9. Appendix A: Supported PKCS #11 Mechanisms
The following mechanisms are supported through the CSPid PKCS #11 interface.
40

CKM_RSA_X_509

CKM_RSA_PKCS

CKM_RSA_PKCS_KEY_PAIR_GEN

CKM_ECDH1_DERIVE

CKM_ECDH1_COFACTOR_DERIVE

CKM_EC_KEY_PAIR_GEN

CKM_ECDSA

CKM_SHA_1

CKM_SHA256

CKM_SHA384

CKM_SHA512

CKM_AES_CBC

CKM_AES_ECB
CSPid Administrator’s Guide
10. Appendix B: The Key Storage Format
CSPid maintains a key store consisting of a single PKCS #15 PDU containing certificates, private keys,
public keys, and their associated attributes. This PDU is currently stored on the user’s file system (local
disk, removable media, or network drive). Future versions of CSPid may allow the key store PDU to be
stored in alternate locations (such as in a network-accessible database).
10.1.
Version 5.0 and Above
10.1.1. Key Derivation Algorithm
Versions 5.0 and above support additional options governing the protection of the PDU including support
of SHA-2 and a configurable iteration count for password based key derivation. Details are provided in
the Confidentiality section below.
10.1.2. Linking the PDU to the Configuration Options
Versions 5.0 and above also support an additional layer of encryption using a key derived from the
configuration file in use. This encryption layer is intended to make it difficult for someone to use the PDU
with a different configuration file. It is does not increase the security of the private keys or other
information stored in the PDU.
This option can be configured using the Bagala Editor (General CSPid, CSP, Tie PDU to configuration).
Enabling this option will cause the entire PDU to be encrypted with a key derived using the configuration
options in the table below. The encryption is done using AES key wrapping per RFC 3394 using AES256. When the PDU is loaded, the AES key is derived using the current configuration settings and if it
can’t decrypt the file, CSPid refuses to use the PDU. The first time CSPid is invoked after the option has
been enabled it will encrypt the PDU with the current configuration. Afterwards the configuration options
used can be changed as noted below and CSPid will update the encryption key and layer (i.e., if password
caching is changed from per-session to never).
Option
Restrictions
General CSPid, CSP, Allow
export of private
attributes
If the option has been
disabled it must remain
disabled for the PDU to be
used.
General CSPid, CSP, ECDH
results extractable
If the option has been
disabled it must remain
disabled for the PDU to be
used.
General CSPid, CSP,
Enforce CKA_EXTRACTABLE
If the option has been enabled
it must remain enabled for the
PDU to be used.
General CSPid,
If the option has been
41
CSPid Administrator’s Guide
Import/Export, Enable
PKCS#12/PFX private key
export
disabled it must remain
disabled for the PDU to be
used.
General CSPid, Password
Control, Advanced
password quality (APQ)
If the option has been enabled
it must remain enabled for the
PDU to be used.
General CSPid, Password
Control, Caching
If the option has been
disabled it must remain
disabled for the PDU to be
used.
General CSPid, Password
Control, Minimum Length
If the option has been enabled
it must remain enabled for the
PDU to be used.
General CSPid, Password
Control, Reset agents
If the option has been enabled
it must remain enabled for the
PDU to be used.
General CSPid, Password
Control, Timeout (in
seconds)
If the option has been enabled
it must remain enabled for the
PDU to be used.
Table 4: Configuration options used to derive key
10.2.
PKCS #15
PKCS #15 specifies syntax for storage of objects, syntax for protecting the confidentiality of sensitive
objects, and a method to ensure the integrity of these objects. A brief summary of those aspects of the
standard used by CSPid is presented below. For more information we refer the reader to the PKCS #15
standards document.
10.3.
Object Syntax
PKCS #15 specifies an ASN.1 encoding format for all objects. For software-tokens a single flat file
containing an ASN.1 DER-encoded sequence of objects is generated. This object is defined as a
PKCS15Token. It is made up of a list of key IDs and a list of objects. The key IDs uniquely label the
encrypted objects. A sample PKCS #15 PDU is presented in Appendix C: A Sample PKCS #15 Key Store.
10.4.
Confidentiality
PKCS #15 specifies the use of CMS as defined in RFC 3852 using passwords for confidentiality. RFC
3852 specifies that a key-encryption key (KEK) be derived from a password and used to encrypt the
content-encryption key (CEK). The KEK is to be derived from a password according to PKCS #5 v2.0
using PBKDF2. CSPid uses a salt and a default iteration count of 2048 (beginning with version 5.0 this
42
CSPid Administrator’s Guide
value can be configured in the Bagala Editor in the Internal Use section) when performing PBKDF2. The
hash algorithm used is configurable using the Bagala Editor (General CSPid, CSP, KDF Digest
Algorithm) and defaults to SHA-1 which is compatible with all versions of CSPid. Starting with version
5.0 SHA-2 algorithms are supported but are not compatible with older versions.
CSPid deviates slightly from PKCS #15 and PKCS #5 by using AES-256 in CBC mode (rather than
TDES) for encryption of private objects within the PKCS #15 PDU as specified by RFC 3565 and RFC
3394. RFC 3394 is based on the NIST AES Key Wrap specification. For compatibility with the only
known third party implementation of PKCS #15, CSPid will also support the RFC 3211 mechanism for
decryption only.
Private key objects are encrypted using the algorithms and formats described in the previous paragraph.
The output produced is a CMS EnvelopedData structure that is included, with additional information, in
the eventual PKCS15Token PDU that is saved in the active key store.
43
CSPid Administrator’s Guide
10.5.
Integrity
PKCS #15 stipulates the use of CMS as defined in RFC 3852 for assuring the integrity of the PDU.
Specifically, it requires the creation of a CMS enveloped authenticatedData PDU containing both the
PDU and a computed MAC value over it. CSPid uses HMAC-SHA512 as defined in RFC 4231 with a
random key for the MAC operation, and then wraps the random HMAC key using AES-256 in the same
manner as for the CEK as described above (i.e., with a key derived from the user’s password according to
PKCS #5 v2.0 and PBKDF2.)
10.6.
Initialization
When first started, or when the active key store cannot be opened, the PKCS #11 library creates an empty
PKCS #15 PDU and appropriate enveloped authenticatedData structure with a default password of
“PASSWORD”. When the CSPid management tool detects that the user has not previously set a password, it
forces the user to do so. The user can subsequently use the included utilities to change their password.
44
CSPid Administrator’s Guide
11. Appendix C: A Sample PKCS #15 Key Store
This appendix contains a sample CSPid key store file. The original binary PKCS #15 PDU has been
“pretty printed” using GUIDumpASN.1.
0000
0004
0011
0015
0019
001C
001E
0020
0023
0025
0030
0032
003C
0040
0042
004D
004F
0079
007B
0085
0087
0089
0094
0096
009A
00A6
00AA
00AE
00BA
00BE
00C2
00C5
00C9
00CD
00D1
00D5
00D7
0101
0105
0107
30
06
A0
30
02
31
A3
02
A0
06
30
04
96F: SEQUENCE {
B:
OBJECT IDENTIFIER authData (1 2 840 113549 1 9 16 1 2)
95E:
[0] {
95A:
SEQUENCE {
1:
INTEGER 0
5B:
SET {
59:
[3] {
1:
INTEGER 0
1B:
[0] {
9:
OBJECT IDENTIFIER pkcs5PBKDF2 (1 2 840 113549 1 5 12)
E:
SEQUENCE {
8:
OCTET STRING
:
FD D3 C8 2D E1 60 08 AC
02
2:
INTEGER 2048
:
}
:
}
30
D:
SEQUENCE {
06
9:
OBJECT IDENTIFIER '2 16 840 1 101 3 4 1 45'
05
0:
NULL
:
}
04
28:
OCTET STRING
:
1A 2A 61 A5 79 09 15 0E 72 14 D5 9A BB 31 1B 1D
:
9D B0 C8 B2 3A 85 A4 84 70 60 FC B8 D4 EE 43 54
:
ED 5A FC C9 56 F8 8E 91
:
}
:
}
30
C:
SEQUENCE {
06
8:
OBJECT IDENTIFIER '1 2 840 113549 2 11'
05
0:
NULL
:
}
A1
D:
[1] {
06
9:
OBJECT IDENTIFIER sha-512 (2 16 840 1 101 3 4 2 3)
05
0:
NULL
:
}
30 897:
SEQUENCE {
06
A:
OBJECT IDENTIFIER pkcs15content (1 2 840 113549 1 15 3 1)
A0 887:
[0] {
30 883:
SEQUENCE {
06
A:
OBJECT IDENTIFIER
:
pkcs15content (1 2 840 113549 1 15 3 1)
A0 873:
[0] {
30 86F:
SEQUENCE {
02
1:
INTEGER 0
30 868:
SEQUENCE {
A0 36C:
[0] {
A0 368:
[0] {
30 364:
SEQUENCE {
30
2E:
SEQUENCE {
0C
28:
UTF8String
'90c72555f6a105c071ec670be04120b4350831a3'
03
2:
BIT STRING 7 unused bits
:
'1'B (bit 0)
:
}
30
21:
SEQUENCE {
04
14:
OCTET STRING
45
CSPid Administrator’s Guide
011D 03
0121 01
0124 03
0128
012C
0130
0134
0137
0139
013B
013E
0140
A1
30
A2
02
31
A3
02
A0
06
1 5 12)
014B 30
014D 04
0157 02
015B 30
015D 06
101 3 4
0168 05
016A 04
0194 30
0198 06
01A3 30
01A5 06
4 1 42)
01B0 04
01C2 80
0436 02
46
:
:
2:
:
1:
2:
:
:
30D:
309:
302:
1:
5B:
59:
1:
1B:
9:
:
90 C7 25 55 F6 A1 05 C0 71 EC 67 0B E0 41 20 B4
35 08 31 A3
BIT STRING 5 unused bits
'110'B
BOOLEAN FALSE
BIT STRING 4 unused bits
'1001'B
}
[1] {
SEQUENCE {
[2] {
INTEGER 2
SET {
[3] {
INTEGER 0
[0] {
OBJECT IDENTIFIER
pkcs5PBKDF2 (1 2 840 113549
E:
8:
:
2:
:
:
D:
9:
1 45'
0:
:
28:
:
:
:
:
:
29E:
9:
:
1D:
9:
:
SEQUENCE {
OCTET STRING
46 B7 36 0C F7 84 7B C7
INTEGER 2048
}
}
SEQUENCE {
OBJECT IDENTIFIER '2 16 840 1
10:
:
:
270:
:
:
:
:
:
:
:
:
:
:
:
1:
:
:
:
:
NULL
}
OCTET STRING
EF CC 57 56 44 9A 51 AD FC 4F 6B E6 2D
A9 28 D6 F0 D8 70 CD 99 12 90 4A 61 43
08 37 91 26 00 40 E5 89
}
}
SEQUENCE {
OBJECT IDENTIFIER
data (1 2 840 113549 1
SEQUENCE {
OBJECT IDENTIFIER
aes256-CBC (2 16 840
OCTET STRING
E3 A4 4E 34 FB 0F AF A1 43 92 FD D6
}
[0]
0E E4 36 24 12 77 55 BE 0E 24 CA F1
96 1B B6 F1 1B 6E 71 F1 CD 97 D9 F1
E6 B7 98 9A C8 7F 4E 17 15 5C CF F3
62 AE B0 BA 31 72 E4 FC 6C 3A 69 AF
54 CB F1 01 F2 EA 4E 87 BB DB BD D7
F3 54 1D A4 6F 47 07 D1 D9 75 64 A5
6A EC 51 41 E8 3D 02 3B 8E F6 B7 7D
09 65 30 B3 38 91 D2 4C 70 5E 57 3C
[ Another 496 bytes skipped
}
}
INTEGER 0
}
}
}
}
34 69 0A
D3 63 ED
7 1)
1 101 3
B6 FA 2E B9
B2
4B
C7
BB
E8
EF
08
21
]
7C
E1
39
9B
7F
D4
28
38
6F
D5
D3
43
38
66
03
40
AE
30
2B
54
AF
10
72
DC
CSPid Administrator’s Guide
:
}
A1 105:
[1] {
A0 101:
[0] {
30
FE:
SEQUENCE {
30
2A:
SEQUENCE {
0C
28:
UTF8String
'90c72555f6a105c071ec670be04120b4350831a3'
:
}
0470 30
21:
SEQUENCE {
0472 04
14:
OCTET STRING
:
90 C7 25 55 F6 A1 05 C0 71 EC 67 0B E0 41 20 B4
:
35 08 31 A3
0488 03
2:
BIT STRING 1 unused bits
:
'1000001'B
048C 01
1:
BOOLEAN FALSE
048F 03
2:
BIT STRING 4 unused bits
:
'1000'B (bit 3)
:
}
0493 A1
AC:
[1] {
0496 30
A9:
SEQUENCE {
0499 A0
A2:
[0] {
049C 30
9F:
SEQUENCE {
049F 30
D:
SEQUENCE {
04A1 06
9:
OBJECT IDENTIFIER
:
rsaEncryption (1 2 840 113549
1 1 1)
04AC 05
0:
NULL
:
}
04AE 03
8D:
BIT STRING 0 unused bits,
encapsulates {
04B2 30
89:
SEQUENCE {
04B5 02
81:
INTEGER
:
00 CB 62 73 50 C9 5D 79 71 64 E9 D1 87 07 D3 88
:
AB D6 A1 57 4D CF 34 C2 B8 04 E2 F4 3E EA 71 B4
:
1E 47 9F F3 3E 6C AD A6 9E 26 E4 F4 08 52 A1 E6
:
37 A7 02 B9 24 3E A3 47 5B 95 EB 8A 5F A4 C7 8B
:
79 DC BB D6 30 22 AB 10 B4 5E 05 1A 84 A7 4B 9F
:
CF 8E 15 C8 6F 0B D4 75 63 A0 A6 C9 8C BD 96 6D
:
0B 9B 63 5C A3 2B 20 6F 55 98 27 88 91 49 1A E3
:
D5 11 30 9E 09 3A 46 91 00 4F 9F 45 10 B5 5C 44
:
[ Another 1 bytes skipped ]
0539 02
3:
INTEGER 65537
:
}
:
}
:
}
:
}
053E 02
2:
INTEGER 1024
:
}
:
}
:
}
:
}
:
}
0542 A4 3EB:
[4] {
0546 A0 3E7:
[0] {
054A 30 3E3:
SEQUENCE {
054E 30
2A:
SEQUENCE {
0550 0C
28:
UTF8String
'90c72555f6a105c071ec670be04120b4350831a3'
:
}
057A 30
16:
SEQUENCE {
057C 04
14:
OCTET STRING
:
90 C7 25 55 F6 A1 05 C0 71 EC 67 0B E0 41 20 B4
:
35 08 31 A3
0439
043D
0441
0444
0446
47
CSPid Administrator’s Guide
:
39B:
397:
393:
27B:
3:
1:
:
05A7 02
14:
:
:
05BD 30
D:
05BF 06
9:
:
840 113549 1 1 5)
05CA 05
0:
:
05CC 30
B2:
05CF 31
B:
05D1 30
9:
05D3 06
3:
:
05D8 13
2:
:
:
05DC 31
B:
05DE 30
9:
05E0 06
3:
:
4 8)
05E5 13
2:
:
:
05E9 31
23:
05EB 30
21:
05ED 06
3:
:
10)
05F2 13
1A:
'Information Security Corp.'
:
:
060E 31
11:
0610 30
F:
0612 06
3:
:
0617 13
8:
:
:
0621 31
21:
0623 30
1F:
0625 06
3:
:
5 4 11)
062A 13
18:
and Development'
:
:
0644 31
14:
0646 30
12:
0648 06
3:
:
0592
0596
059A
059E
05A2
05A4
48
A1
30
30
30
A0
02
}
[1] {
SEQUENCE {
SEQUENCE {
SEQUENCE {
[0] {
INTEGER 2
}
INTEGER
08 16 D8 EA 0C 26 68 6B 7F 5F F6 9D D6 52 F0 B2
58 A4 74 EB
SEQUENCE {
OBJECT IDENTIFIER
sha1withRSAEncryption (1 2
NULL
}
SEQUENCE {
SET {
SEQUENCE {
OBJECT IDENTIFIER
countryName (2 5 4 6)
PrintableString 'US'
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
stateOrProvinceName (2 5
PrintableString 'IL'
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
organizationName (2 5 4
PrintableString
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
localityName (2 5 4 7)
PrintableString 'Oak Park'
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
organizationalUnitName (2
PrintableString 'Research
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
commonName (2 5 4 3)
CSPid Administrator’s Guide
064D 13
CA'
B:
:
:
065A 31
25:
065C 30
23:
065E 06
9:
:
113549 1 9 1)
0669 16
16:
'testca@infoseccorp.com'
:
:
:
0681 30
1E:
0683 17
D:
0692 17
D:
:
06A1 30
B5:
06A4 31
B:
06A6 30
9:
06A8 06
3:
:
06AD 0C
2:
:
:
06B1 31
29:
06B3 30
27:
06B5 06
3:
:
10)
06BA 0C
20:
Security Corporation'
:
:
06DC 31
1E:
06DE 30
1C:
06E0 06
3:
:
5 4 11)
06E5 0C
15:
assurance CA)'
:
:
06FC 31
12:
06FE 30
10:
0700 06
3:
:
5 4 11)
0705 0C
9:
:
:
0710 31
18:
0712 30
16:
0714 06
3:
:
0719 0C
F:
Import'
:
:
072A 31
2D:
072C 30
2B:
072E 06
9:
PrintableString 'ISC Test
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
emailAddress (1 2 840
IA5String
}
}
}
SEQUENCE {
UTCTime '061109000000Z'
UTCTime '071109000000Z'
}
SEQUENCE {
SET {
SEQUENCE {
OBJECT IDENTIFIER
countryName (2 5 4 6)
UTF8String 'US'
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
organizationName (2 5 4
UTF8String 'Information
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
organizationalUnitName (2
UTF8String 'R&D (no
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
organizationalUnitName (2
UTF8String 'Test CA 1'
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
commonName (2 5 4 3)
UTF8String 'Test P12
}
}
SET {
SEQUENCE {
OBJECT IDENTIFIER
49
CSPid Administrator’s Guide
:
113549 1 9 1)
0739 16
1E:
'tech@infoseccorp.com'
:
:
:
0759 30
9F:
075C 30
D:
075E 06
9:
:
113549 1 1 1)
0769 05
0:
:
076B 03
8D:
encapsulates {
076F 30
89:
0772 02
81:
:
:
:
:
:
:
:
:
:
07F6 02
3:
:
:
:
07FB A3
20:
07FD 30
1E:
07FF 30
E:
0801 06
3:
:
0806 01
1:
0809 04
4:
{
080B 03
2:
bits
:
:
:
080F 30
C:
0811 06
3:
:
19)
0816 01
1:
0819 04
2:
{
081B 30
0:
:
:
:
:
:
081D 30
D:
081F 06
9:
:
113549 1 1 5)
082A 05
0:
:
50
emailAddress (1 2 840
IA5String
}
}
}
SEQUENCE {
SEQUENCE {
OBJECT IDENTIFIER
rsaEncryption (1 2 840
NULL
}
BIT STRING 0 unused bits,
00
AB
1E
37
79
CF
0B
D5
CB
D6
47
A7
DC
8E
9B
11
62
A1
9F
02
BB
15
63
30
73 50 C9
57 4D CF
F3 3E 6C
B9 24 3E
D6 30 22
C8 6F 0B
5C A3 2B
9E 09 3A
[ Another
SEQUENCE {
INTEGER
5D 79 71 64 E9 D1
34 C2 B8 04 E2 F4
AD A6 9E 26 E4 F4
A3 47 5B 95 EB 8A
AB 10 B4 5E 05 1A
D4 75 63 A0 A6 C9
20 6F 55 98 27 88
46 91 00 4F 9F 45
1 bytes skipped ]
INTEGER 65537
}
}
87
3E
08
5F
84
8C
91
10
07
EA
52
A4
A7
BD
49
B5
D3
71
A1
C7
4B
96
1A
5C
88
B4
E6
8B
9F
6D
E3
44
}
[3] {
SEQUENCE {
SEQUENCE {
OBJECT IDENTIFIER
keyUsage (2 5 29 15)
BOOLEAN TRUE
OCTET STRING, encapsulates
BIT STRING 3 unused
'10111'B
}
}
SEQUENCE {
OBJECT IDENTIFIER
basicConstraints (2 5 29
BOOLEAN TRUE
OCTET STRING, encapsulates
SEQUENCE {}
}
}
}
}
}
SEQUENCE {
OBJECT IDENTIFIER
sha1withRSAEncryption (1 2 840
NULL
}
CSPid Administrator’s Guide
082C 03
2BBF A7
2BC2 A0
2BC5 30
2BC8 30
2BCA 0C
Object'
2BEB
2BED
2BF0
2BF3
2BF5
30
A1
30
30
04
2BF8 04
2BFE 30
2C00 04
2C03 04
2C06 30
2C08 04
2C0B 04
Options
2C2C 30
2C2E 04
2C32 04
2C48 30
2C4A 04
2C4E 04
2C51 30
2C53 04
2C57 04
101:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
EB:
E8:
E5:
21:
1F:
:
0:
BD:
BA:
9:
1:
:
4:
:
:
6:
1:
:
1:
:
:
24:
1:
:
1F:
Object'
:
1A:
2:
:
14:
:
:
:
7:
2:
:
1:
:
:
7:
2:
:
1:
:
:
12
27
5D
00
5B
42
A4
5F
18
5A
D4
EA
FA
B8
AF
CB
BIT STRING 0 unused bits
5F 0D 48 F9 EA E7 46 07 2D E5
DB 5C EC 11 86 F4 D0 56 D4 EE
86 30 F3 1F 36 4D 72 0D 70 A4
49 C0 0A A8 72 74 E3 FE 53 28
14 FF 1C 59 17 F3 0D 15 A7 40
96 85 15 BD F0 8E 2B E1 BE 00
22 98 C0 98 F9 4B 3B F3 E1 E7
A4 12 0F EA 86 6A 69 2D 47 A1
[ Another 128 bytes skipped ]
}
}
}
19
94
E0
85
B0
75
B0
98
DB
BB
98
96
74
67
4C
D0
AE
6E
3F
46
3F
BB
58
61
8C
7F
C7
87
BB
77
B3
D0
}
}
}
[7] {
[0] {
SEQUENCE {
SEQUENCE {
UTF8String 'CSPid P15 Stored Options
}
SEQUENCE {}
[1] {
SEQUENCE {
SEQUENCE {
OCTET STRING
00
OCTET STRING
09 01 05 82
}
SEQUENCE {
OCTET STRING
01
OCTET STRING
01
}
SEQUENCE {
OCTET STRING
03
OCTET STRING 'CSPid P15 Stored
}
SEQUENCE {
OCTET STRING
01 02
OCTET STRING
31 CD 33 B7 F0 6E 12 7E 05 F3 9C BF 73 BC C5 5F
F2 2C BA AB
}
SEQUENCE {
OCTET STRING
01 64
OCTET STRING
01
}
SEQUENCE {
OCTET STRING
01 65
OCTET STRING
00
}
51
CSPid Administrator’s Guide
2C5A 30
2C5C 04
2C62 04
2C64 17
2C73 30
2C75 04
2C7B 04
0931 04
52
17:
4:
:
F:
D:
:
:
38:
4:
:
30:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
40:
:
:
:
:
:
:
:
SEQUENCE {
OCTET STRING
10
OCTET STRING, encapsulates {
UTCTime '061218153524Z'
}
}
SEQUENCE {
OCTET STRING
11
OCTET STRING
63 60 78 DE FB 5F C8 A0 3E 2F 9F E3 A9
79 FF 24 57 71 A9 BA 4B 23 90 31 BB 86
3F D2 28 2B 59 D6 9B 1C 54 39 5E 0B 37
}
}
82 05 01
82 05 01
51 AB B9
D1 0B C1
92 73 13
}
}
}
}
}
}
}
}
}
}
OCTET STRING
A8 43 47 83
3D 66 40 FA
75 92 AA 55
4B 62 99 8D
}
}
}
D3
96
17
B7
03
76
1D
DA
24
10
CF
5E
7D
58
11
E5
BA
2D
48
40
25
B6
C0
40
99
4A
3E
39
31
E4
2B
E5
FA
2D
FB
0F
E5
FA
75
18
D0
53
00
86
00
91
31
8B
CSPid Administrator’s Guide
12. Appendix D: CSPid Objects
Any key store item managed by CSPid is represented at runtime by an in-memory map of attribute, value
pairs. As such, an object is simply a collection of named values. A value is a byte array stored in an ISC
CDK string object (which clears memory upon destruction, thereby erasing any key material). Some
attributes have special properties that prevent them from being exposed (), define the type of the object (),
or indicate that the object is only visible once the user has authenticated to the token and should be stored
in encrypted form ().
Certificates, private keys and public keys are serialized into PKCS #15 objects, while data objects which
do not directly translate into PKCS #15 are serialized as sequences of attribute/value pairs with attributes
and values encoded as octet strings.
Private objects (i.e., objects on the private list) make use of two special, vendor-defined, attributes. These
attributes are inaccessible to calling applications (the PKCS #11 function refuses to return these
attributes). They are:
Attribute
Use
ISC_OBJECT_STORE_ID
Contains a unique ID linking the public object to its counterpart
in the encrypted list.
ISC_ENCRYPTED_OBJECT
Contains the encrypted form of a private object.
Table 5: Proprietary PKCS #11 Attributes
These attributes are used when storing private objects. The object is first serialized as per PKCS #15 and
then encrypted. A new object is then produced containing the ISC_OBJECT_STORE_ID,
ISC_ENCRYPTED_OBJECT, and other non-sensitive attributes (the private key values are removed from the
object). This object is placed on the private list.
Whenever an object changes (i.e., is created, destroyed, or modified) a new PKCS #15 PDU is created
and saved as the active key store.
53
CSPid Administrator’s Guide
13. Appendix E: CSPid Object Management
Object management in CSPid is handled at the PKCS #11 library layer which sits on top of a key store
manager. There is a global object manager that retrieves all objects from the active key store upon
initialization of the library through the C_Initialize() function. Public and private objects (which are
encrypted) are loaded into two internal in-memory lists.
When the user successfully authenticates to the token via the C_Login() function, objects on the private
list are decrypted and placed on the in-memory public list with the index of the private object stored in the
public object’s ISC_OBJECT_STORE_ID attribute. When the C_Logout() function is called, all objects on
the public list whose CKA_PRIVATE value is TRUE are removed from the public list leaving only encrypted
information in-memory and on disk.
When an object is destroyed it is removed from the appropriate lists and from the active key store.
Similarly, when an object is added it is added to the appropriate lists and to the active key store. The key
store manager is responsible for providing a method to track if the active key store has been modified.
The file based key store maintains a copy of the PKCS #15 PDU it last read/wrote as a file and compares
the one on disk to the one in memory to determine if a change has occurred.
When an object is accessed through one of the PKCS #11 init functions (C_DecryptInit(),
C_SignInit(), etc.) or an attribute is requested (C_GetAttributeValue() or C_FindObjects()) the
object manager queries the key store to determine whether or not the in-memory object store is current. If
the in-memory store is not current, the library resyncs itself with the key store.
Obtain a lock on the PKCS#15 PDU
Read the PKCS#15 PDU into temporary in-memory lists
Check if any items have been added
Check if any items have been removed
Check if any item has been changed
Release the lock on the PKCS#15 PDU
The in-memory state should match the PKCS#15 state in the PDU Error! Reference source
ot found.
If the new state results in an invalid object handle the function will fail stating
such
Figure 11: Object Synchronization Algorithm
If the library cannot obtain the lock, fails to read the PDU, or if the password was changed and the library
is unable to decrypt the PKCS #15 PDU, it will return CKR_DEVICE_REMOVED.
In the event that an object is added, removed, or modified the following additional step of applying the
change (add/remove/modify) will occur between steps 5 and 6 above. The algorithm to merge the key
store with the in-memory contents is:
Call the existing in-memory vectors A and B
Convert the PKCS #15 PDU into in-memory vectors called C and D
If the user is logged, in decrypt D into C
Set B equal to D
For each object a in A
Determine if a is in C in identical fashion
If a is in C and it’s a private key, copy the ISC_OBJECT_STORE_ID value from the
object in C to the object in A so that it links to the proper entry in B.
If a isn’t in C in identical fashion, do a fuzzy search using the following PKCS #11
immutable attributes:
54
CSPid Administrator’s Guide
CKA_VALUE, CKA_CLASS, CKA_CERTIFICATE_TYPE, CKA_KEY_TYPE, CKA_LOCAL, CKA_MODULUS,
CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1,
CKA_EXPONENT_2, CKA_COEFFICIENT
If a matches in a fuzzy fashion set the object in A to be equal to the object in C.
If a doesn’t match in a fuzzy fashion, delete the object from A
For each object c in C
Determine if c is in A in identical fashion
If c is not, then add it to A
Figure 12: Object Merge Algorithm
55
Download PDF
Similar pages