Marcus Meissner
bbdcb346df
Fixed several bugs and cleaned up changes and specfile OBS-URL: https://build.opensuse.org/request/show/247627 OBS-URL: https://build.opensuse.org/package/show/security/openCryptoki?expand=0&rev=21
282 lines
11 KiB
Diff
282 lines
11 KiB
Diff
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
|
|
|