File ocki-3.1_08_0002-Add-documentation-pkcscca-manp... of Package openCryptoki

Overview Repositories Revisions Requests Users Attributes Meta

File ocki-3.1_08_0002-Add-documentation-pkcscca-manpage-and-README.cca_std.patch of Package openCryptoki

From 13eda6d102b8c44f85cf4eac094ff8a964c630f4 Mon Sep 17 00:00:00 2001
From: Joy Latten <jmlatten@linux.vnet.ibm.com>
Date: Mon, 1 Sep 2014 22:46:37 -0500
Subject: [PATCH 2/2] Add documentation (pkcscca manpage and README.cca_stdll)
 to assist in migrating cca private token objects from v2 to v3.

Signed-off-by: Joy Latten <jmlatten@linux.vnet.ibm.com>
---
 configure.in          |   1 +
 doc/README.cca_stdll  | 175 ++++++++++++++++++++++++++++++++++++++++++++++----
 man/man1/Makefile.am  |   2 +-
 man/man1/pkcscca.1.in |  45 +++++++++++++
 4 files changed, 209 insertions(+), 14 deletions(-)
 create mode 100644 man/man1/pkcscca.1.in

diff --git a/configure.in b/configure.in
index f3fbe70..3e7e5e8 100644
--- a/configure.in
+++ b/configure.in
@@ -843,6 +843,7 @@ AC_CONFIG_FILES([Makefile usr/Makefile \
 	  man/man1/Makefile \
 	  man/man1/pkcsconf.1 \
 	  man/man1/pkcsicsf.1 \
+	  man/man1/pkcscca.1 \
 	  man/man1/pkcsep11_migrate.1 \
 	  man/man5/Makefile \
 	  man/man5/opencryptoki.conf.5 \
diff --git a/doc/README.cca_stdll b/doc/README.cca_stdll
index f535dfa..a0d13f1 100644
--- a/doc/README.cca_stdll
+++ b/doc/README.cca_stdll
@@ -1,24 +1,173 @@
+CCA TOKEN
 
-README for the CCA secure-key token
+OverView
+--------
+The CCA token is a secure key token.
+A Secure key - key value does not exist in the clear outside of the HSM
+(secure, tamper-resistent boundary of the card). It is a clear key wrapped
+with the appropriate MasterKey that has been installed into the secure hardware.
+A clear key is generated in the hardware, wrapped with the appropriate
+master key that has been installed into the hardware. The wrapped key is then
+passed back to the invoker. Upon an encryption and/or decryption request,
+the wrapped key and the data to be encrypted are passed into the hardware.
+The wrapped key is verified, and the clear key is used to encrypt and/or
+decrypt the data. All this is done in the CCA hardware.
 
-Kent Yoder <yoder1@us.ibm.com>
+Within opencryptoki, this wrapped key value is stored in the CKA_IBM_OPAQUE
+attribute rather than the CKA_VALUE attribute.
 
-  The key used to encrypt private objects on disk is a secure key.
+Pre-requisites:
+The CCA token requires cca library, libcsulcca.so, which is part of the
+csulcca rpm.
+It also requires proper configuration and installation of the MK keys into
+the hardware which is outside the scope of this document.
 
-  The key used to encrypt that secure key is based on the hash of the
-USER and SO pins.  Therefore it is a clear key and software is used to
-do the encryption/decryption of the secure key.
+Configuration
+-------------
 
-MK_USER: The secure key used for internal on-disk encryption, encrypted
+To use the CCA token a slot entry must be defined in the
+opencryptoki.conf configuration file that sets the stdll attribute to
+libcsulcca.so.
+
+The CCA token also requires that the appropriate master keys have
+been installed into the hardware. The corresponding driver must also be
+loaded, i.e. modprobe z90crypt.
+
+CCA Token Objects
+-------------------------
+
+Opencryptoki stores token objects on disk. Public token objects are not
+encrypted. Private token objects are encrypted.
+Versions of opencryptoki prior to version 3, used a CCA generated secure key
+(des3 key) and the crypto adapter to encrypt the private token object's data.
+In version 3, a clear key (des3 key) and software crypto (openssl) are used
+to encrypt this data.
+
+Migration Information
+---------------------
+
+Migrating version 2 private token objects to version 3 is ONLY required if
+the system will run opencryptoki version 3 and will use private token
+objects saved or preserved from version 2.
+Note, public token objects do not need to be migrated.
+If there are no private token objects from version 2, then the version 3
+does not require any migrating.
+
+In version 2 private token objects are encrypted and decrypted with a secure
+key in the crypto adapter. In version 3, this encryption and decryption is
+done with a clear key using software crypto. Therefore, opencryptoki
+version 3, will not succesfully decrypt a version 2 private token object.
+
+Version 2 private token objects must be "migrated" to version 3 so that
+opencryptoki version 3 can access these objects. This migration will
+decrypt the objects using the CCA call, CSNBDEC and the current
+opencryptoki key stored in MK_USER. The objects will then be re-encrypted
+using software crypto. The key bits that are stored in MK_USER will then be
+used as a clear key.
+
+Once the migration has completed, these private token objects should then be
+accessable to version 3.
+
+Migration Steps
+---------------
+
+1. Either update or install version 3.
+a. Update to opencryptoki version 3. In most linux distributions, an update
+from version 2 to version 3 will preserve the contents of the CCA data-store.
+
+b. Install opencryptoki version 3. In most distributions, an install will
+remove the contents of the CCA data-store. You will essentially be starting
+from the beginning and have to initialize the CCA token.
+
+In this scenario, if a prior version of opencryptoki had been running on the
+system, and you wanted to preserve your token objects, you will have saved
+or backed them up somewhere.
+
+2. Backup the CCA data-store before migrating. It is always a good idea to
+back up the data in case the migration is unsuccessful or data is corrupted.
+The data-store is the directory in which the CCA token information is stored
+on disk. In most distributions it can be found in /var/lib/opencryptoki/ccatok.
+Within this directory there is,
+
+MK_USER: The des3 key used for internal on-disk encryption, encrypted
          under the USER's PIN by software routines
 
-MK_SO: The secure key used for internal on-disk encryption, encrypted
+MK_SO: The des3 key used for internal on-disk encryption, encrypted
          under the SO's PIN by software routines
 
-So, MK_USER and MK_SO contain the same key, encrypted under different PINs
+NKTOK.DAT: Token information.
+
+TOK_OBJ: The directory in which token objects are stored.
+
+TOK_OBJ/OBJ.IDX: A list of current token objects.
+
+**NOTE: MK_USER and MK_SO contain the same key, encrypted under
+different PINs
+
+3. Ensure no opencryptoki processes are running. Stop the pkcsslotd daemon
+if it is running.
+
+4.  Run the pkcscca tool to perform the migration.
+For example,
+	pkcscca -m v2objectsv3 -v
+
+Note that the "-v" option will allow you to see which objects did and did not
+get migrated. Specify the "-d" flag if you wish to migrate CCA token objects
+stored in a data-store different from the default, /var/lib/opencryptoki/ccatok.
+
+5. (Optional) Removing shared memory may be required to pick up
+the newly migrated objects.
+
+CCA token's shared memory segment tracks its token objects.
+Token objects stored on disk are only loaded into shared memory
+when the shared memory is created. The shared memory is usually
+created after a reboot, an install, or an update of the opencryptoki package.
+
+If another opencryptoki process accessed the CCA token after install
+or update, then opencryptoki will have loaded all the token objects into
+shared memory, except for the private token objects requiring migration,
+since they will have failed decryption. Subsequent calls to the 
+opencryptoki api will not find these objects since they have not
+been loaded into shared memory. Opencryptoki won't read the
+objects from disk and load into shared memory again until the next time
+shared memory is created. 
+
+So, in this case, shared memory must be removed and created again so 
+that opencryptoki can successfuly load all the token objects including the 
+newly migrated private token objects into CCA token's shared memory segment.
+
+Remove shared memory if,
+ - after updating or installing, any opencryptoki processes or tools tried
+   to access the CCA token before migrating CCA token's private token
+   objects. For example, the pkcsconf command was run.
+
+   The pre-migrated objects will have failed decryption and not
+   been loaded into shared memory. A reboot or removing shared memory
+   will cause the token to create shared memory again and load the newly
+   migrated private token objects into it.
+
+CCA's shared memory can be removed two ways.
+	1. a reboot
+
+	2. remove the shared memory file,
+ 	   i.e. "rm  /dev/shm/var.lib.opencryptoki.ccatok"
+
+	   Notes: (1). Ensure that no opencryptoki processes are running
+	   before removing the shared memory. Otherwise, you risk corrupting
+	   any running opencryptoki processes.
+	   (2). If you have installed opencryptoki manually (not via a distro
+	   rpm) the CCA token shared memory segment may be named 
+	   usr.local.var.lib.opencryptoki.ccatok.
+	   
+The next opencryptoki process to run will cause opencryptoki to create
+a shared memory segment for the token and load the newly migrated objects
+as well as any other token objects for the token.
 
-PKCS#11 Notes:
+6. After a successful migration, the CCA private token objects should be
+encrypted and ready to be accessed by opencryptoki version 3.
 
-DES/3DES PKCS#11 key objects have the CCA key identifier stored in the CKA_VALUE
-attribute.  Usually the CKA_VALUE attribute would hold a plaintext key, however
-in this case, the id used to reference the secure key is stored here.
+TroubleShooting:
+1. If version 3 cannot find the newly migrated CCA private token objects,
+reboot or remove the shared memory file. This will cause token to create
+shared memory again and load the newly migrated private token objects
+into shared memory.
diff --git a/man/man1/Makefile.am b/man/man1/Makefile.am
index c4b4d95..f2274d7 100644
--- a/man/man1/Makefile.am
+++ b/man/man1/Makefile.am
@@ -1,3 +1,3 @@
-man1_MANS=pkcsconf.1 pkcsicsf.1 pkcsep11_migrate.1
+man1_MANS=pkcsconf.1 pkcsicsf.1 pkcsep11_migrate.1 pkcscca.1
 EXTRA_DIST = $(man1_MANS)
 CLEANFILES = $(man1_MANS)
diff --git a/man/man1/pkcscca.1.in b/man/man1/pkcscca.1.in
new file mode 100644
index 0000000..c6e49d6
--- /dev/null
+++ b/man/man1/pkcscca.1.in
@@ -0,0 +1,45 @@
+.TH PKCSCCA 1 "September 2014" "@PACKAGE_VERSION@" "openCryptoki"
+.SH NAME
+pkcscca \- configuration utility for the CCA token
+
+.SH SYNOPSIS
+\fBpkcscca\fP
+[\fB-h\fP]
+[\fB-m v2objectsv3\fP]
+[\fIOPTIONS\fP]
+
+.SH DESCRIPTION
+The \fBpkcscca\fP utility assists in administering the CCA token. Currently it
+migrates opencryptoki version 2 private token objects to the encryption
+method used in opencryptoki version 3.
+
+In verion 2 of opencryptoki, CCA private token objects were encrypted in CCA
+hardware. In version 3 these objects are encrypted in software. The
+\fBv2objectsv3\fP migration option migrates these version 2 objects by
+decrypting them in CCA hardware using a secure key and then re-encrypting
+them in software using a software key. Afterwards, v2 objects can be accessed
+in version 3.
+
+.SH "FLAGS"
+.IP "\fB-h\fP" 10
+show usage information
+.IP "\fB-m\fP" 10
+perform a migration. \fBv2objectsv3\fP is currently the only type of migration
+supported and must be specified along with this flag.
+
+.SH "MIGRATION OPTIONS"
+.IP "\fB-d|--datastore\fP \fIdirectory\fp" 10
+the directory where the CCA token information is kept. This directory will be
+used to locate the private token objects to be migrated. i.e. /var/lib/opencryptoki/ccatok
+.IP "\fB-v|--verbose\fP" 10
+provide detailed output during migration
+
+.SH "FILES"
+.IP "/var/lib/opencryptoki/ccatok/TOK_OBJ/OBJ.IDX"
+contains current list of public and private token objects for the CCA token.
+
+.SH SEE ALSO
+.PD 0
+.TP
+\fBREADME.cca_stdll\fP (in system's doc directory)
+.PD
-- 
1.8.1.4

Places

File ocki-3.1_08_0002-Add-documentation-pkcscca-manpage-and-README.cca_std.patch of Package openCryptoki

Places