Acala Administrator’s Guide Version 1.1
Virtual HSM
February 7, 2019
Acala 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.
Acala 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.
Acala is a 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 Acala is provided by CDK 8, ISC’s FIPS 140-2 Level 1compliant cryptographic module. In addition, Acala uses the following open source software packages redistributable under the terms of the LGPL or other licenses:
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).
Acala 1.1 Administrator’s Guide, Sixth Edition (February 2019) © 2007-2019 Information Security Corporation. All rights reserved.
Information Security Corporation Phone: +1 847-405-0500 Website: www.infoseccorp.com 1011 W. Lake Street, Suite 425 Fax: +1 708-445-9705 Email: [email protected] Oak Park, IL 60301
2 Acala Administrator’s Guide
Table of Contents
1. Introduction ...... 7 1.1. Overview ...... 7 1.2. Acala Architecture ...... 7
2. Installation ...... 9 2.1. Overview ...... 9 2.2. System Requirements ...... 10 2.3. Windows ...... 11 2.4. UNIX ...... 11
3. Acala Configuration ...... 12 3.1. Windows ...... 12 3.2. UNIX ...... 12 3.3. Controlling Certificate Visibility ...... 12 3.4. Configuration Options ...... 12 3.4.1. Audit Trail ...... 13 3.4.2. Import ...... 13 3.4.3. Export ...... 13 3.4.4. PIN ...... 13 3.4.5. PKCS#11 Library ...... 14
4. Using Acala ...... 16 4.1. Initializing Acala ...... 16 4.2. Erasing Acala Keys ...... 16 4.3. Private Key Archive ...... 16 4.3.1. Creating an Encryption Certificate ...... 16 4.3.2. Archiving a Private Key ...... 16 4.3.3. Decrypting a Key Split ...... 17 4.3.4. Restoring a Private Key ...... 18 4.1. Generating Pre-Shared Keys or Random Numbers ...... 18 4.2. Using Acala with Java Applications ...... 18 4.2.1. Via PKCS#11 ...... 18 4.2.2. Blacklists, Whitelists, and Java ...... 19 4.3. Using Acala with Apache Tomcat ...... 19 4.4. Using Acala with Stunnel ...... 19 4.5. The Acala Management Tool ...... 20
3 Acala Administrator’s Guide
4.5.1. Two Views of the Key Store ...... 22 4.5.2. Importing Credentials ...... 22 4.5.3. Exporting Credentials ...... 23 4.5.4. Deleting Credentials ...... 24 4.5.5. Changing the Acala PIN ...... 25 4.5.6. The About Dialog ...... 25 4.5.7. Terminating the Management Tool ...... 26 4.5.8. The Management Tool Command Line ...... 26 4.6. The Acala Command Line Tools ...... 26 4.6.1. Acala_cli ...... 27 4.7. The Acala Audit Trail ...... 31 4.7.1. Windows ...... 31 4.7.2. UNIX...... 31
5. Acala PIN and Key Management ...... 32 5.1. PIN Management ...... 32 5.1.1. Forced PIN Change ...... 32 5.1.2. PIN Caching ...... 32 5.2. Key Management ...... 32 5.2.1. Encrypted Memory ...... 33 5.2.1.1. Encrypted Memory on Windows Vista and Later ...... 33 5.2.1.2. Encrypted Memory on UNIX-based Systems ...... 34 5.2.2. Key Management in the Acala Management Tool ...... 34
6. Acala Libraries ...... 35 6.1. The PKCS #11 Library ...... 35
7. References ...... 36
8. Appendix A: Supported PKCS #11 Mechanisms ...... 37
9. Appendix B: The Key Storage Format ...... 38 9.1. Version 1.0 and Above ...... 38 9.1.1. Key Derivation Algorithm ...... 38 9.1.2. Linking the PDU to the Configuration Options ...... 38 9.2. PKCS #15...... 38 9.3. Object Syntax ...... 38 9.4. Confidentiality ...... 38 9.5. Integrity ...... 39 9.6. Initialization ...... 39
10. Appendix D: Acala Objects ...... 40
11. Appendix E: Acala Object Management ...... 41
4 Acala Administrator’s Guide
List of Figures
Figure 1: Acala 1.1 Architecture Diagram ...... 8
Figure 2: The Acala System Tray Menu ...... 20
Figure 3: The Acala Manager’s Main Window (Standard View) ...... 21
Figure 4: The Acala Manager’s Main Window (Advanced View) ...... 22
Figure 5: Importing a File ...... 23
Figure 6: Exporting a File ...... 24
Figure 7: Confirming Certificate Deletion ...... 24
Figure 8: Confirming Private Key Deletion ...... 24
Figure 9: Changing Your Acala PIN ...... 25
Figure 10: Viewing the About Dialog ...... 25
Figure 11: The Acala_cli Interface ...... 28
Figure 12: Object Synchronization Algorithm ...... 41
Figure 13: Object Merge Algorithm ...... 42
5 Acala Administrator’s Guide
List of Tables
Table 1: System Requirements ...... 10
Table 2: Editable Attributes ...... 22
Table 3: Management Tool Command Line Options ...... 26
Table 4: acala_cli Options ...... 30
Table 5: Proprietary PKCS #11 Attributes ...... 40
6 Acala Administrator’s Guide
1. Introduction
1.1. Overview
Acala is a software package that acts as a universal key store as well as a cryptographic service provider. At its core is an HSM emulator that:
1) maintains a central repository for private keys and X.509 certificates, and 2) provides a secure environment for cryptographic operations.
Authorized applications run on the Acala host access its services via an industry-standard PKCS#11 API.
This document contains a technical overview of Acala and covers the installation, administration, and use of the software.
1.2. Acala Architecture
The Acala system consists of three components:
a credential store: an encrypted file stored by the system on a local fixed disk, on removable media, or on a network drive a PKCS #11 library providing access to the credential store and certain private key operations a set of tools that permit the administrator to easily configure and maintain the Acala system
7 Acala Administrator’s Guide
PKCS#11-Enabled Application
(Netscape, Notes, Mozilla Firefox/Thunderbird, SecretAgent, SpyProof!, any Java application, etc.)
Administrator
Acala Manager
(command line and graphical interfaces)
PKCS #11 Library
PKCS #15 Key Store Key Stores ISC CDK 8.0 Manager
Acala Software HSM
one configurable PKCS#15 key store per system
local or network-attached, file-based key store
remote HTTPS-based key store (future enhancement)
(future extensibility)
Figure 1: Acala 1.1 Architecture Diagram
As illustrated in the above diagram, a PKCS #11 library (based on ISC’s FIPS-validated CDK 8), a PKCS #15 key store manager, and the Acala management tools represent the core components of the Acala system. These tools and the provided APIs allow administrators to easily integrate Acala into existing applications.
8 Acala Administrator’s Guide
2. Installation
2.1. Overview
Acala is available on a variety of platforms and the installation process is platform-dependent. The following files are typically installed:
the Acala management tool (acala_ui.exe or acala_ui) and, if available, its translation files (*.qm)
the Acala command line tool (acala_cli.exe or acala_cli)
the Acala PKCS #11 Library (acala.dll or libacala.so)
a Acala configuration (acala.xml) – optional
the Acala Administrator’s Guide (Acala.pdf) – optional
On Windows systems the following additional items are installed: A shortcut in the Windows Start Menu for starting the Acala management tool
9 Acala 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 Acala:
Supported Internet Explorer 7 or higher Browsers Firefox 17.0 or higher
Java Java 1.5 and higher w/PKCS #11 support (see Java PKCS #11)
Operating Windows Server 2012 (x64) Systems Windows 10 (x64) RedHat Enterprise Linux 6 or higher for x64 with rng-tools
Table 1: System Requirements
10 Acala Administrator’s Guide
2.3. Windows
Acala for Windows is distributed as standard MSI installation package that provides a wizard for individual installation as well as supporting automated installation mechanisms. The following MSI command line parameters are available (options may be combined):
Option Values Notes
INSTALLDIR
To customize Acala, edit the acala.xml file found in the installation folder after installation.
After installation on a Windows system, the Acala management tool can be run using the Start Menu. The initial PIN is PASSWORD and the first time the tool is executed it will ask to set the Acala PIN. The command line tool can also be used to initialize Acala.
2.4. UNIX
Acala for UNIX is distributed as a single compressed tar ball (acala.x.y.z.os.processor.tar.gz) that must be decompressed and untar’d. The resulting acala folder contains an INSTALL file that provides platform-specific installation tips. Typically all that is required is to move the acala folder to /opt/acala and to create the acala.xml file in /etc.
To customize the way Acala behaves, modify the options settings in acala.xml as desired. (See section 3.4 for more information.) libacala.so and all associated utilities read their program configuration data from acala.xml located in one of the following folders (in the order listed): /etc, /usr/etc.
NOTE: Acala relies on the operating system for sufficient entropy. On Linux it reads /dev/random which will block until enough entropy is available. It is highly recommended that rng-tools be installed and configured to run at startup so that /dev/random is kept full at all times.
11 Acala Administrator’s Guide
3. Acala Configuration
Acala‘s operating characteristics can be controlled by creating or modifying the acala.xml file after installation. If no acala.xml file is found, Acala will operate with its default internal settings.
3.1. Windows
On Windows, the active configuration is the one found in the installation folder.
3.2. UNIX
On UNIX, libacala.so searches the following directories, in order, for acala.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 modification.
3.3. Controlling Certificate Visibility
By default, all certificates stored within Acala 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. Acala accomplishes this by allowing an application blacklist (or whitelist) to be specified on a per-certificate basis in the Acala key store. Certificate black-/whitelists can be set either during certificate import using the Acala_cli program, or edited at a later time using the Acala 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 Acala key store.)
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 in the configuration file as BLMOZILLA=firefox.exe, thunderbird.exe, firefox, thunderbird.
Filtering can also be performed based on the Acala 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 Acala.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.4. Configuration Options
Acala supports the configuration options in the following table. These are set by editing the acala.xml file after installation using a normal text editor.
File Format:
12 Acala Administrator’s Guide
a. Any line beginning with # or ; is considered a comment. b. Blank lines are ignored. c. All other lines should be Option=Value pair.
3.4.1. Audit Trail Attribute Description
LOGLEVEL 0 (critical information only) 1 (information) 2 (debug) 3 (debug, but masking sensitive data)
LOGFILEDAILY 0 (no) 1 (yes, append today’s date when opening the log file)
LOGFILE Specify a path and filename in which to log information in LOGFILE_UNIX addition to the system event log.
3.4.2. Import Attribute Description
CAIMPORT Specifies whether or not Acala should store issuer certificates. 0 (Never import CA certificates. Effectively disables the import of anything but PKCS#12 files) 1 (Allow the import of CA certificates, but prompt for approval of root certificates) 2 (Allow the import of CA certificates without any prompting) Note, this setting affects PKCS#12 import and export with regard to prompting only.
3.4.3. Export Attribute Description
EXP_REQ_NEW_PIN 0 (no, Acala PIN can be used as the PKCS#12 export password) 1 (yes, the PKCS#12 export cannot match the Acala PIN)
3.4.4. PIN Attribute Description
PWREQALPHA 0 (no) 1 (yes, one of [a-z][A-Z] must be included)
PWREQNUM 0 (no) 1 (yes, one of [0-9] must be included)
PWREQPUNC 0 (no)
13 Acala Administrator’s Guide
1 (yes, one of [.,?!;:'"] must be included)
PWREQSPEC 0 (no) 1 (yes, one of [@#$%^&*()+=-_/><\|[]{}`~] must be included)
PWREQMIXEDCASE 0 (no) 1 (yes)
PWMINLEN The minimum PIN length allowed. The default is 15.
PW2MASK Specifies the PIN quality requirements if PW2ENABLED is set to 1. This is a | delimited string of PIN classes: U = upper case character required L = lower case character required N = number required P = punctuation required S = special character required u = upper case character forbidden l = lower case character forbidden n = number forbidden p = punctuation forbidden s = special character forbidden These can be combined to produce PIN quality requirements that require the PIN to be mixed case and contain either a number or punctuation: ULN|ULP For example: ULNP|ULNS|ULSP|Nulsp would accept PINs that matched one of: mixed case with a number and a punctuation symbol mixed case with a number and a special character mixed case with a special character a punctuation symbol only numbers
PW2REQCLASSCHG 0 (disabled) > 0 (the maximum number of consecutive characters allowed from a given character class as defined in PW2MASK)
PW2ENABLED 0 (no) 1 (yes, enforce the PW2MASK requirements)
3.4.5. PKCS#11 Library Attribute Description
P15URL C:\ProgramData\Acala\Acala.p15 P15URL_UNIX /etc/Acala/Acala.p15
INIFILE C:\ProgramData\Acala\Acala.ini INIFILE_UNIX /etc/Acala/Acala.ini
ASSERT_PROTECTED_PATH A semi-colon delimited list of executable names for which Acala should assert the CKF_PROTECTED_AUTHENTICATION_PATH flag.
CLOGIN_RET0_ALI A semi-colon delimited list of executable names for which Acala should suppress CKR_USER_ALREADY_LOGGED_IN errors.
14 Acala Administrator’s Guide
DISABLE_ECCDH A simi-colon delimited list of executable names for which Acala should suppress the CKM_ECDH1_DERIVE, CKM_ECDH1_COFACTOR_DERIVE, and CKM_EC_KEY_PAIR_GEN mechanisms. Default value is "firefox.exe;firefox;"
ECCDHSS_EXTRACTABLE 0 (no, the resulting shared secret cannot be extracted) 1 (yes, the shared secret can be extracted)
KDF_ITERATION_COUNT The number of iterations to use when deriving keys from the PIN. Must be greater than 2048. Defaults to 4096.
NSCREATETRUST 0 (no, do not create NSS trust objects for NSS-based apps) 1 (yes)
P12EXPORT 0 (no, don’t allow PKCS#12 export from the Acala tools) 1 (yes)
PDU_DIGEST_ALG 4 (SHA1) 5 (SHA2-256) 6 (SHA2-384) 7 (SHA2-512) 8 (SHA2-224)
PDU_PROT_SYSTEM 0 (no, do not tie the PDU to the computer) 1 (yes)
PROTECTED_APPS A semi-colon delimited list of executable names that Acala should treat as operating in “protected mode” on Windows.
READONLY 0 (no) 1 (yes, prevent any application other than a Acala tool from changing the key store)
15 Acala Administrator’s Guide
4. Using Acala
Acala integrates into system applications in the same manner as a smart card or HSM. Once the Acala PIN is entered, the private keys in the Acala key store are immediately available for use in decryption and/or signing operations in any configured application.
Applications using Acala through its PKCS#11 interface should use slot 1 or token label ISC Acala.
4.1. Initializing Acala
Before using Acala in applications a key store must be initialized. To do this either start the Acala Manager or run the following command line: acala_cli --initialize
4.2. Erasing Acala Keys
To destroy an Acala key store use the Acala command line tool’s initialize option: acala_cli --initialize
4.3. Private Key Archive
For private keys marked as not exportable (CKA_EXTRACTABLE=FALSE) Acala provides a split key archive mechanism for backup and recovery purposes. A 3 of 5 split key archive is used and requires 5 certificates to function.
4.3.1. Creating an Encryption Certificate
If one or more key split encryption certificates are needed for archive purposes the Acala command line tool can be used to create them and save them as PKCS#12 files. acala_cli --gen-ss “CN=Archiver1” --gen-key-type RSA2048SHA256 --exportable –f archive1.cer
This will produce two files: archive1.cer and archive1.cer.p12. To delete the private key from Acala use the --delete command in the Acala command line.
4.3.2. Archiving a Private Key
To archive a private key you must first export the certificate to a file and then run the following command. acala_cli --archive root.der -f archive1.cer -f archive2.cer -f archive3.cer -f archive4.cer -f archive5.cer --path archive
16 Acala Administrator’s Guide
Please enter the Acala PIN: Authenticating to Acala... Complete Saving archive\Root - DSNRKEKA - 2016-04-10 - 757B9A6EEC3B228E9C4B.key Saving archive\Archive1 - DSNRKEDE - 2019-04-06 - DAB5DE45E115358E2784.0.spl Saving archive\Archive2 - DSNRKEDE - 2019-04-06 - 4903430051C15062D6CF.1.spl Saving archive\Archive3 - DSNRKEDE - 2019-04-06 - 173B0BFD0A69C5C46F75.2.spl Saving archive\Archive4 - DSNRKEDE - 2019-04-06 - C8A0E2F3759C021283B8.3.spl Saving archive\Archive5 - DSNRKEDE - 2019-04-06 - 7AC3BA3B75A66D922DA4.4.spl
Each .spl file contains a key split encrypted with the matching certificate. The .key file contains the encrypted private key and matching certificate.
4.3.3. Decrypting a Key Split
In order to recover a key three of the .spl files must be decrypted using the private key matching the certificate used to encrypt the key split. Each key split is a standard RFC 5652 compliant CMS PDU and can be decrypted with any software that supports that format.
4.3.3.1. With Acala CLI
acala_cli --rec-split "archive\Archive1 - DSNRKEDE - 2019-04-06 - DAB5DE45E115358E2784.0.spl" -f archive\1.dec
Please enter the Acala PIN: Authenticating to Acala... Complete Saving archive\1.dec
4.3.3.2. With SecretAgent CLI
sa7 -d archive2_user0.cer --format 2 "archive\Archive2 - DSNRKEDE - 2019-04-06 - 4903430051C15062D6CF.1.spl"
Decrypting and/or validating User ID: archive2_user0.cer Loaded private key: archive2_user0.prv Loaded certificate: archive2_user0.cer Enter password: ****************
Decrypting
File list: .\Archive2 - DSNRKEDE - 2019-04-06 - 4903430051C15062D6CF.1
4.3.3.3. With OpenSSL
openssl smime -decrypt -in "archive\Archive3 - DSNRKEDE - 2019-04-06 - 173B0BFD0A69C5C46F75.2.spl" -inform DER -inkey archive3.pem -keyform PEM - outform DER -out archive\s3.dec
17 Acala Administrator’s Guide
4.3.4. Restoring a Private Key
Once three splits have been decrypted they need to be moved to the system on which the key will be restored. To restore the key run the following command line. acala_cli --rec-key "archive\Root - DSNRKEKA - 2016-04-10 - 757B9A6EEC3B228E9C4B.key" -f archive\1.dec -f archive\s3.dec -f "archive\Archive2 - DSNRKEDE - 2019-04-06 - 4903430051C15062D6CF.1"
Please enter the Acala PIN: Authenticating to Acala... Complete
4.1. Generating Pre-Shared Keys or Random Numbers
The Acala command line’s --gen-sym option will generate random values suitable for symmetric keys for use in a symmetric pre-shared key scheme and output them in binary, hex, or base64. acala_cli --gen-sym 32 --hex
86351AD1356CE08F652D62F8C82950C593078DFA32C95A10A193372104AF74D3
The actual value is output to stderr allowing redirection to store the value in a file acala_cli –gen-sym 32 --hex 2>key1.hex
4.2. Using Acala with Java Applications
4.2.1. Via PKCS#11
To make Acala 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 Acala folder during installation. A sample is provided below: security.provider.7=sun.security.pkcs11.SunPKCS11 c:/Program Files/Acala/java_pkcs11.cfg
To make Acala available to a Java program programmatically, insert the following lines:
String configName = "C:/Program Files/Acala/java_pkcs11.cfg"; Provider p = new sun.security.pkcs11.SunPKCS11(configName); Security.addProvider(p); KeyStore ks = KeyStore.getInstance("PKCS11"); // PIN is the Acala login PIN. ks.load(null, PIN.toCharArray());
The java_pkcs11.cfg placed in the installation folder must be edited after installation to replace the INSTALLLIB value with the actual path and library name to be used.
18 Acala Administrator’s Guide
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.
4.2.2. Blacklists, Whitelists, and Java
All Java applications appear to Acala 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 Acala library with unique names and adding them to the java.security file you can more easily use Acala’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: Copy /opt/acala/libacala.so to /opt/acala/libmyapp.so Create /opt/acala/libmyapp.cfg with the following values
name = Acala-MyApp library = /opt/acala/libmyapp.so description = ISC_Acala slot = 1 attributes = compatibility
Edit $JAVA_HOME/lib/security/java.security and add a line to the security provider list
security.provider.10=sun.security.pkcs11.SunPKCS11 /opt/acala/libmyapp.cfg
In the Acala Manager add libmyapp.so to the blacklist of certificates to hide Use javax.net.ssl.keyStoreProvider=SunPKCS11-Acala-MyApp when running the program
4.3. Using Acala with Apache Tomcat
To use Acala as the TLS key container for Apache Tomcat, the java.security file must be modified as indicated above, and the server.xml file located in
With these settings Acala 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 Acala will be accepted.
4.4. Using Acala 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
19 Acala Administrator’s Guide at https://www.stunnel.org. When configured to use Acala, Stunnel can provide a work around for programs that do not support TLS, PKCS#11, or are otherwise incompatible with Acala.
A Stunnel configuration file that uses Acala 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/Acala/libAcala.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: causes Stunnel to pass an empty PIN to Acala. key=slot_1-id_CKA_ID 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 Acala Manager by selecting the CKA_ID field of the certificate and pressing Control+C.
4.5. The Acala Management Tool
The Acala management tool is a system tray application (on systems that support the system tray concept) that allows administrators to perform common management tasks and to view the objects managed by Acala.
Figure 2: The Acala System Tray Menu
20 Acala Administrator’s Guide
The Manage Acala menu item opens the Acala Manager’s main dialog, illustrated below; the remaining menu items are simply shortcuts to identically named items in the main dialog’s menu bar.
This section explains how to use the Acala Manager (or equivalent system tray menu items) to view the certificates and other objects stored by Acala, and to import into, export from, and delete objects from, the key store. The Acala Manager supports the import and export of PKCS #12 and PKCS #7 PDUs, as well as that of (raw binary ASN.1 DER-encoded) X.509 certificate files.
Figure 3: The Acala Manager’s Main Window (Standard View)
Certificates and credentials are separated into sections. Credentials are listed in the root of the tree and are identified by an icon containing a certificate, envelope, and key. Expired credentials are identified in the same list by an icon containing a certificate with a red circle containing a white X. Certificates without a matching private key are located in one of three folders in the tree: Intermediate Issuers, Other, or Trusted Roots.
When an item is selected, details appear on the right hand side as attributes and their values. The following attribute values can be modified by selecting them and then selecting Modify Attribute from the Edit menu.
Attribute Information
CKA_LABEL The CKA_LABEL value is the PKCS#11 text label that is displayed by PKCS#11 applications. It is also the Friendly Name displayed in the Microsoft key store. The default value is the common name from the certificate. If the credential is imported from a PKCS#12 file containing a friendly name, the
21 Acala Administrator’s Guide
friendly name value will be used as the label.
Blacklisted A list of one or more application Applications names or aliases that Acala should hide this certificate from.
Whitelisted A list of one or more application Applications names or aliases that Acala should only show this certificate to. Table 2: Editable Attributes
4.5.1. Two Views of the Key Store
The Acala Manager’s main window initially lists all certificates managed by Acala; this is the default “view” of the Acala key store. When in this view, for example, you can determine if a private key is associated with a particular certificate by selecting that certificate in the left-hand pane and inspecting its Private Key property in the right-hand pane.
Selecting Advanced from the View menu causes the main window to switch from showing only certificates to displaying all objects managed by Acala. Advanced view allows you to manage individual certificates, public keys, and private keys.
Figure 4: The Acala Manager’s Main Window (Advanced View)
4.5.2. Importing Credentials
Choosing Import (Ctrl+O) from the Acala Manager’s File menu opens the following file selection dialog. Change the type of file to be imported (PKCS #12, PKCS #7, or X.509), if necessary, using the Files of
22 Acala Administrator’s Guide type drop down list, select one or more files, and click Open. (As usual in such dialogs, several files of the specified type can be selected by using the control and/or shift keys in conjunction with the left mouse button.)
Figure 5: Importing a File
When importing a private key you will be asked whether or not the private key should be exportable from Acala in the future with a yes no prompt.
4.5.3. Exporting Credentials
Selecting a certificate, then choosing Export (Ctrl+S) from the Acala Manager’s File menu opens a standard Save as dialog. Enter a filename for the file to be created, change its type (PKCS #12, PKCS #7, or X.509), if necessary, using the Save as type drop down list, then click Save. Note, only private keys whose private keys are exportable can be saved as PKCS#12 files using this method.
23 Acala Administrator’s Guide
Figure 6: Exporting a File
4.5.4. Deleting Credentials
Selecting a certificate (or key in Advanced view), and choosing Delete (Del) from the Acala Manager’s Edit menu starts the process of removing a certificate and any associated keys from the Acala key store. You will be prompted to confirm that you really want to delete the selected key or certificate.
Figure 7: Confirming Certificate Deletion
If the certificate being removed has an associated private key (which, in the standard view, will also be deleted), you will be prompted for confirmation a second time to ensure that you fully understand the consequences of your decision.
Figure 8: Confirming Private Key Deletion
24 Acala Administrator’s Guide
If you select an object in Advanced view, and choose Delete from the Edit menu, only the selected object will be removed from the Acala key store. (This is different from the behavior of Delete in the standard view where only certificates are displayed and all associated keys are deleted.)
4.5.5. Changing the Acala PIN
To change the PIN used to protect private items in Acala key store, select Change PIN from the Tools menu (or from the system tray menu).
Figure 9: Changing Your Acala PIN
The OK button in this dialog will become enabled once you have entered at least one character in all PIN fields and the new PIN satisfies any quality requirements that may be in effect pursuant to an active security policy. (The status line keeps you apprised of any requirements that remain to be satisfied.)
4.5.6. The About Dialog
Selecting About from the Help menu (or from the system tray menu) opens an informative dialog that, among other things, includes ISC support and contact information.
Figure 10: Viewing the About Dialog
25 Acala Administrator’s Guide
4.5.7. Terminating the Management Tool
Selecting Exit from the File menu (or from the system tray menu) will terminate the Acala management tool. (Closing the tool’s main dialog minimizes it to your system tray, but leaves it running.)
4.5.8. The Management Tool Command Line
The Acala management tool has limited command line functionality designed for integration with the operating system.
Switch Command Required Options Notes
--exit none none Emulate selecting Exit from the application menu to terminate the management tool.
-f
-i import file -f
--p12-pass specifies the PKCS none Allows the PKCS#12
4.6. The Acala Command Line Tools
Command line utilities allowing the scripting of certain actions are provided for use by administrators or others who want to perform certain actions automatically.
26 Acala Administrator’s Guide
4.6.1. Acala_cli
The Acala_cli command line program is the primary administrative utility and provides most of the available functionality:
Usage: acala_cli {function} [options]
Functions (specify exactly one): --archive f archive the private key for the certificate specified --check-new-pin check whether PIN meets the PIN requirements or not --check-p10 load contents of -f argument and verify that it is valid --check-pin check whether PIN is correct or not -c, --chgpin change the Acala PIN -C, --clear erase all Acala objects --clear-orphans erase all public/private keys without certificates --delete f erase the certificate/public/private objects for the certificate specified --digest d hash the contents of -f with algorithm d where d can be sha1, sha256, sha384, or sha512 -e, --export export all Acala objects; if allowed, certificates with private keys are saved as .p12 files --gen-jks generate a Java keystore file in the output file specified by the -f option and PIN in -t --gen-p10 dn generate a key pair and output a PKCS#10 certificate request with the distinguished name
Options: --base64 with (--gen-sym) base64 encode the output
--debug output additional information for operations
--exp-no-issuers with (-e, --gen-jks), do not include issuer certificates when creating JKS or PKCS #12 files
--exp-no-privates with (-e, --gen-jks), do not include private keys when creating JKS or PKCS #12 files
--exp-only-label lab with (-e, --gen-jks), only export items whose CKA_LABEL value contains lab
--exportable with (--gen-p10, --gen-ss, -i, --recover-key) allow the private key to later be exported from the Acala key file
-f file --filename file read (-i, -b) the specified file or save the output (--gen-p10, --gen-jks, --export) int the file
--gen-key-type type generate a key of type
27 Acala Administrator’s Guide
RSA2048SHA256, RSA3072, RSA4096, RSA8192, ECCp256, ECCp384, ECCp521
--hex with (--gen-sym) hex encode the output
--impersonate app with (-e, --gen-jks), use the supplied app name to filter output
--label lab append lab to the default CKA_LABEL value (with -i)
-t pin use pin as the new Acala PIN --p12pin pin use pin as the PKCS #12/JKS file PIN
-p pin use pin as the Acala PIN
-P path --path path with -e, export files to path with -i, import all PKCS #12 (.p12/.pfx) files in path --pause prompt for a key press before exiting
--replace with -i, updates attributes of existing entries as opposed to skipping the item
--scope-whitelist imported credentials visible only to these applications
--scope-blacklist imported credentials not visible to these applications using whitelist and blacklist matching
--show-all with --list show all certificates including issuers and expired certificates
--test-iter n with --test-thnet, --test-threads, iterations to run per thread --url URL with --test-thnet the URL to contact -y --yestoall suppress prompts for object deletion and file overwrite
See accompanying documentation for additional information.
Figure 11: The Acala_cli Interface
In general, commands cannot be combined on the same command line and certain options apply only to particular commands (see table below). The register and uninstall options access the configuration to determine which paths should be searched or use the default values if no paths are specified in the configuration. If the path option is supplied to register or uninstall as a semi-colon delimited list of directories, those directories are searched in addition to paths specified in the configuration.
Command Required Optional Switches Additional Information Options archive f --path, -f, -p, --pause Creates an archive of the -f, -f, -f, certificate and private key -f protected by five key splits three of which are needed to recover the private key. check-new- -p --pause Checks to see if the provided PIN pin meets the PIN quality requirements.
28 Acala Administrator’s Guide
check-p10 --filename --pause Parses the PKCS#10 input file, validates the signature, and reports whether or not it is OK. check-pin none -p, --pause Checks to see if the provided PIN can decrypt the PKCS #15 PDU. chgpin none --pause Changes the Acala PIN interactively from the command line. clear none -p, --pause, -- Erases all objects (certificates, yestoall public keys, and private keys) from the Acala store. clear- none -p, --pause Erases all public and private orphans keys for which no certificate exists. delete none -p, --pause Erases the certificate, public, filename and private key identified by the certificate in the supplied filename. digest
29 Acala Administrator’s Guide
gen-sym n none --base64, --hex, -- Generates a random symmetric key pause, of length n and outputs it to stderr. help none None Displays the information shown in the figure above. import --filename --p12pin, -p, -- With –-filename, imports a single or --path pause, --label, -- certificate, PKCS#7 or PKCS#12 delay-commit, -- file. Wildcards are supported for scope-whitelist, -- importing multiple files. scope-blacklist, -- With –-path, imports all PKCS#12 replace, -- files found in any of the paths exportable specified (on Windows multiple paths can be specified by separating them with semi- colons). The value of the --label option is appended to the CKA_LABEL values generated by Acala. The –- exp-only-label option can filter output based on this value. With --replace, existing entries are updated with new values (specifically, new labels and black-/whitelist values). With --scope-blacklist or -- scope-whitelist, specifies either a comma separated list of administratively defined TAGs or executable filenames or libraries that should either not see the certificate or that should be the only application that sees the certificate. initialize none -p, --pause Erases the existing PKCS #15 PDU and creates a new one with the provided PIN. inspect- --filename --pause Validates and displays cert information about the certificate specified. list none --pause, --show-all Displays the common name, expiration year, and CKA_ID for all certificates stored. rec-key f -f, -f, -f -p, --pause Recover the certificate and key in f using the three splits provided in the –f options as files. rec-split -f -p, --pause Decrypt the key split in the file f specified by f and save it in the file specified by the –f option. Table 4: acala_cli Options
30 Acala Administrator’s Guide
4.7. The Acala Audit Trail
Acala includes a configurable audit trail facility that supports logging events to a specified text file as well as to the system event log.
All actions that modify the key store, export private data, or are related to authentication are written to the system event log regardless of the Acala audit trail settings. This includes object creation, object modification, use of the credential export functions in the management tools, PIN entry, PIN failure, and PIN change.
If debug level logging is enabled and a log file is specified, Acala will append information to assist in troubleshooting to the log file location. Logging is configured via the Acala configuration.
4.7.1. Windows
Acala creates entries in its own Acala section of the Windows Event Log. To view the log, use the Event Viewer accessory provided by Microsoft.
4.7.2. UNIX
On UNIX, Acala uses syslog to create entries with an identifier of Acala in the system event log. You may need to configure syslog to properly capture and store these messages.
31 Acala Administrator’s Guide
5. Acala PIN and Key Management
5.1. PIN Management
PIN change is accomplished using the standard PKCS #11 C_SetPin() call. The supplied programs, Mozilla-based applications, or other PKCS #11 compliant tools can also be used to change the PIN.
5.1.1. Forced PIN Change
When Acala is first initialized the default PIN is PASSWORD. The PKCS#11 library will return CKR_PIN_EXPIRED from C_Initialize()until the PIN is changed. If the management tool detects this error, it displays the PIN change dialog.
5.1.2. PIN Caching
Future versions of Acala will support a permanent PIN cache option enabling operation without any operator intervention.
When used as the key storage device for Tara, there is a special build output of Acala called tarap11_x64.dll or libtara.so. These files are shipped with the Tara client. With this special build a permanent caching mechanism (PWCACHE=3) is supported. This mechanism is insecure and is an obfuscation effort to protect the key store from simple attacks. When this option is chosen, the key store PIN is generated programmatically by hashing parts of a key embedded in the library prepended to a concatenated list of certificates stored. An attacker can reverse engineer the logic and derive the password in the same fashion.
5.2. Key Management
Acala 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 Acala might result in unexpected behavior. For example, since most applications generate keys with CKA_EXTRACTABLE set to FALSE, it may not be possible to export such private keys from the device using a PKCS #11-enabled application.
However, for backup and recovery purposes, private keys can be extracted Acala 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 in-
32 Acala Administrator’s Guide memory 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.
5.2.1. Encrypted Memory
When logging into Acala all sensitive objects in the PKCS #15 PDU are decrypted and then stored in an object in encrypted memory.
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: CKA_APPLICATION CKA_OBJECT_ID CKA_VALUE
Other sensitive information that is encrypted while in memory: All copies of the PKCS #15 PDU PIN.
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 getrand2() method in ISC’s FIPS-validated CDK 8 after which getrand2() is called again to transition the PRNG’s state to ensure that the KEK does not remain in the PRNG’s memory space.
5.2.1.1. Encrypted Memory on Windows Vista and Later
On Windows Vista and later Acala uses the CryptProtectMemory and CryptUnprotectMemory functions to encrypt sensitive information in memory. These functions require the data to be a multiple of
33 Acala Administrator’s Guide
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 memory allocated with VirtualAlloc, marked with VirtualLock (to prevent paging), and protected with VirtualProtect (to prevent access by other programs). The KEK is used to super encrypt the output of CryptProtectMemory using the AES Key Wrap algorithm specified in RFC 3394 in order to link the Acala PIN with the encrypted memory to properly support PIN timeout in the future.
Using this scheme the PKCS #15 PDU PIN 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.
5.2.1.2. Encrypted Memory on UNIX-based Systems
On Linux, OSX, and Solaris Acala 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 PKCS #15 PDU PIN 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.
5.2.2. Key Management in the Acala Management Tool
The Acala management tool will encrypt the KEK when minimized. If the KEK is required for an operation the tool will prompt for the PIN.
34 Acala Administrator’s Guide
6. Acala Libraries
6.1. The PKCS #11 Library
Acala includes a PKCS #11 library module named Acala.dll (Windows) or libacala.so (UNIX) for use by security-enabled applications that can access PKCS #11 compliant tokens.
On Windows, this library is installed in the Acala program folder, by default C:\Program Files\Acala.
On UNIX, the default installation directory is /opt/acala.
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.
35 Acala Administrator’s Guide
7. References
FIPS 46-3 FIPS 46-3: Data Encryption Standard (DES), NIST, October 25, 1999. Archived May 19, 2005.
FIPS 180-2 FIPS 180-2: Secure Hash Standard, NIST, August 1, 2002. Archived October 2008 and superseded by FIPS 180-3.
FIPS 197 FIPS 197: Advanced Encryption Standard (AES), NIST, November 26, 2001.
Java PKCS Java™ PKCS #11 Reference Guide, Sun Microsystems, May 2004. #11
Java SSL/TLS Java™ Secure Socket Extension (JSSE) Reference Guide, Sun Microsystems, 2004.
NIST AES Key AES Key Wrap Specification, NIST, November 2001. Wrap
PKCS #5 Password-Based Encryption Standard. v2.0, RSA Laboratories, March 25, 1999.
PKCS #8 Private-Key Information Syntax Standard. v1.2, RSA Laboratories, November 1993.
PKCS #11 Cryptographic Token Interface Standard. v2.20, RSA Laboratories, June 2004.
PKCS #12 Personal Information Exchange Syntax Standard. v1.0, RSA Laboratories, June 1999.
PKCS #15 Cryptographic Token Information Syntax Standard v1.1, RSA Laboratories, June 2000.
RFC 3211 Gutmann, P., RFC 3211: Password-based Encryption for CMS, University of Auckland, December 2001.
RFC 3394 Schaad, J., and R. Housley, RFC 3394: Advanced Encryption Standard (AES) Key Wrap Algorithm, Soaring Hawk Consulting and RSA Laboratories, September 2002.
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.
RFC 3852 Housley, R., RFC 3852: Cryptographic Message Syntax (CMS), Vigil Security, July 2004.
RFC 4231 Nystrom, M., RFC 4231: Identifiers and Test Vectors for HMAC-SHA-224, HMAC- SHA-256, HMAC-SHA-384, and HMAC-SHA-512, RSA Security, December 2005.
Tomcat The Apache Tomcat 5.5 Servlet/JSP Container SSL Configuration HOW-TO, The Apache Software Foundation, 1999-2006.
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.
36 Acala Administrator’s Guide
8. Appendix A: Supported PKCS #11 Mechanisms
The following mechanisms are supported through the Acala PKCS #11 interface.
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
37 Acala Administrator’s Guide
9. Appendix B: The Key Storage Format
Acala 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 system’s file system (local disk, removable media, or network drive).
9.1. Version 1.0 and Above
9.1.1. Key Derivation Algorithm
Unless changed in the configuration settings, Acala uses SHA-2 512 and 4096 when deriving symmetric encryption keys from the Acala PIN. Details are provided in the Confidentiality section below.
9.1.2. Linking the PDU to the Configuration Options
By default, Acala adds an additional layer of encryption using platform-specific implementations. This can be disabled in the configuration file to enable the PDU to be moved to different platforms. On Windows, the PKCS#15 PDU is encrypted using CryptProtectData. On UNIX-like systems, the PDU is encrypted using CMS with a key derived from the systems CPU information.
This encryption layer is intended to make it difficult for someone to move the PDU to another computer system and use it. It is does not increase the security of the private keys or other information stored in the PDU.
9.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 Acala is presented below. For more information we refer the reader to the PKCS #15 standards document.
9.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.
9.4. Confidentiality
PKCS #15 specifies the use of CMS as defined in RFC 3852 using PINs for confidentiality. RFC 3852 specifies that a key-encryption key (KEK) be derived from a PIN and used to encrypt the content-
38 Acala Administrator’s Guide encryption key (CEK). The KEK is to be derived from a PIN according to PKCS #5 v2.0 using PBKDF2. Acala uses a salt and a default iteration count of 4096 (this value can be configured) when performing PBKDF2. The hash algorithm used is configurable using the and defaults to SHA-2 512.
Acala 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, Acala also supports the RFC 3211 mechanism for decryption.
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.
9.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. Acala uses HMAC-SHA512 (this value can be configured) 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 PIN according to PKCS #5 v2.0 and PBKDF2.)
9.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 PIN of “PASSWORD”. When the Acala management tool detects that the PIN has never been changed, it forces it to be changed before allowing any other operations. The PIN can be changed at any time using the included utilities.
39 Acala Administrator’s Guide
10. Appendix D: Acala Objects
Any key store item managed by Acala 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 one 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.
40 Acala Administrator’s Guide
11. Appendix E: Acala Object Management
Object management in Acala 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 successfully authenticated 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 If the new state results in an invalid object handle the function will fail stating such
Figure 12: Object Synchronization Algorithm
If the library cannot obtain the lock, fails to read the PDU, or if the PIN 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 token 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:
41 Acala 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 13: Object Merge Algorithm
42