Documentation files were scattered across different places. Consolidate them in doc/ to make packaging easier, while avoiding collisions.
Signed-off-by: Klaus Heinrich Kiwi <[email protected]> --- doc/README-IBM_CCA_users | 184 +++++++++++++++++++++++ doc/README.cca_stdll | 24 +++ doc/README.pkcscca_migrate | 92 +++++++++++ doc/README.tpm_stdll | 57 +++++++ usr/lib/pkcs11/cca_stdll/Makefile.am | 2 - usr/lib/pkcs11/cca_stdll/README-IBM_CCA_users | 184 ----------------------- usr/lib/pkcs11/cca_stdll/README.cca_stdll | 24 --- usr/lib/pkcs11/tpm_stdll/README | 57 ------- usr/sbin/pkcscca_migrate/README.pkcscca_migrate | 92 ----------- 9 files changed, 357 insertions(+), 359 deletions(-) create mode 100644 doc/README-IBM_CCA_users create mode 100644 doc/README.cca_stdll create mode 100644 doc/README.pkcscca_migrate create mode 100644 doc/README.tpm_stdll delete mode 100644 usr/lib/pkcs11/cca_stdll/README-IBM_CCA_users delete mode 100644 usr/lib/pkcs11/cca_stdll/README.cca_stdll delete mode 100644 usr/lib/pkcs11/tpm_stdll/README delete mode 100644 usr/sbin/pkcscca_migrate/README.pkcscca_migrate diff --git a/doc/README-IBM_CCA_users b/doc/README-IBM_CCA_users new file mode 100644 index 0000000..8bdd5cd --- /dev/null +++ b/doc/README-IBM_CCA_users @@ -0,0 +1,184 @@ + +openCryptoki CCA Token README +Kent Yoder <[email protected]> + + + The purpose of this README is to document the differences between setting up +the openCryptoki token for the IBM CCA (Common Cryptographic Architecture) and +setting up other tokens, such as the ICA (IBM Crypto Accelerator) token. The main +difference is that the CCA libraries are available for 64bit s390x only, whereas +all other openCryptoki tokens can be used 32 or 64bit. This means that the +PKCS#11 setup utility used by openCryptoki, pkcsconf, cannot be used, since its +compiled 32bit by default. In order to work around this limitation, a version +of pkcsconf has been included in the 64bit openCryptoki package to configure the +CCA token. This version is named 'pkcsconf64', and is installed in /usr/sbin, +alongside the 32bit pkcsconf. Note that pkcsconf64 can be used to configure +any openCryptoki token, since they all support 64bit apps. + + +After installing these RPMs, the setup process is: + +STEP 1: + + # /etc/init.d/pkcsslotd start + + This should start the pkcsslotd daemon. You can check this with: + + # ps -auwx | grep pkcsslotd + + You should see something like: + + root 8914 0.0 0.3 3220 1552 ? Ss 23:31 0:00 /usr/sbin/pkcsslotd + +STEP 2: + + Check that all the libraries are in the right places. Do: + + # /usr/sbin/pkcsconf64 -t + + You should see: + + Token #0 Info: + Label: IBM ICA PKCS #11 + Manufacturer: IBM Corp. + Model: IBM ICA + Serial Number: 123 + Flags: 0x880045 (RNG|LOGIN_REQUIRED|CLOCK_ON_TOKEN|USER_PIN_TO_BE_CHANGED|SO_PIN_TO_BE_CHANGED) + Sessions: -1/-1 + R/W Sessions: -1/-1 + PIN Length: 4-8 + Public Memory: 0xFFFFFFFF/0xFFFFFFFF + Private Memory: 0xFFFFFFFF/0xFFFFFFFF + Hardware Version: 1.0 + Firmware Version: 1.0 + Token #1 Info: + Label: IBM PKCS#11 for CCA + Manufacturer: IBM Corp. + Model: IBM CCA Token + Serial Number: 123 + Flags: 0x880045 (RNG|LOGIN_REQUIRED|CLOCK_ON_TOKEN|USER_PIN_TO_BE_CHANGED|SO_PIN_TO_BE_CHANGED) + Sessions: -1/-1 + R/W Sessions: -1/-1 + PIN Length: 4-128 + Public Memory: 0xFFFFFFFF/0xFFFFFFFF + Private Memory: 0xFFFFFFFF/0xFFFFFFFF + Hardware Version: 1.0 + Firmware Version: 1.0 + Time: 23:33:41 + + Token #0 is the ICA token, driven by the libica package. If libica or its device driver + isn't installed, you may only see Token #1. + + If you get the following message: + + C_GetSlotCount returned 0 slots. Check that your tokens are installed correctly. + + several things could be wrong. Check that: + + 1) The master keys for the CCA's crypto card have been loaded. + + If the master keys have not yet been loaded, a message will appear in the + system log whenever pkcsconf is run that looks like: + + openCryptoki(CCA)[5294]: cca_specific.c Warning: CCA master key is not yet loaded + + Please follow any instructions or procedures you may have been given on + loading master keys. + + 2) The device driver for the CCA hardware is loaded. This module may be called + "zsecrypt" or "z90crypt" and may not have been loaded by the /etc/init.d/pkcsslotd + script. + + 3) The CCA libraries are installed correctly. openCryptoki requires the following + libraries: + + library source package + ----------------------------------- + libcsulcall.so xcryptolinz + libcsulsapi.so xcryptolinz + libcsulsecy.so xcryptolinz + libds30.so xcryptolinz + libxcryp.so xcryptolinz + libcrypto.so openssl + + When a token is detected by the startup scripts run by /etc/init.d/pkcsslotd, an + entry is made in the /var/lib/opencryptoki/pk_config_data file. This file will + contain 1 line per token. + +STEP 3: + + Initialize the CCA token. + + # /usr/sbin/pkcsconf64 -I -c 1 + + You should see: + + Enter the SO PIN: + - Enter the default SO PIN here, which is "87654321". + Enter a unique token label: + - Enter any string here, such as "My token init string" + + Another call to pkcsconf64 should reflect the token label change: + + # /usr/sbin/pkcsconf64 -t + Token #1 Info: + Label: My token init string + Manufacturer: IBM Corp. + Model: IBM CCA Token + Serial Number: 123 + Flags: 0x880445 (RNG|LOGIN_REQUIRED|CLOCK_ON_TOKEN|TOKEN_INITIALIZED|USER_PIN_TO_BE_CHANGED|SO_PIN_TO_BE_CHANGED) + Sessions: -1/-1 + R/W Sessions: -1/-1 + PIN Length: 4-128 + Public Memory: 0xFFFFFFFF/0xFFFFFFFF + Private Memory: 0xFFFFFFFF/0xFFFFFFFF + Hardware Version: 1.0 + Firmware Version: 1.0 + Time: 23:38:48 + +STEP 4: + + Set the Security Officer's (SO) Password. This should be a secret known only to + the system admin. + + # /usr/sbin/pkcsconf64 -P -c 1 + Enter the SO PIN: ******** + - This should be the default SO PIN, "87654321" + Enter the new SO PIN: ******** + Re-enter the new SO PIN: ******** + - Enter the new SO PIN here twice for verification + + +STEP 5: + + Set the PKCS#11 User Password. This will be a secret known to all users/apps of the + PKCS#11 interface. + + # /usr/sbin/pkcsconf64 -u -c 1 + Enter the SO PIN: ******** + - This should be the SO PIN you set in STEP 4. + Enter the new user PIN: ********** + Re-enter the new user PIN: ********** + - This should be a new secret, known to all users of the token. + +STEP 6: + + Make sure applications will have access to PKCS#11. + + All processes that would like to use PKCS#11 need to be in the 'pkcs11' group. So, + if java needs to access PKCS#11, then edit /etc/group: + + # vim /etc/group + + Look for the line: + + pkcs11:!:64:root + + and add the java uid to that line: + + pkcs11:!:64:root,java + + /etc/init.d/pkcsslotd creates the 'pkcs11' group when its first run. + +Send questions to [email protected]. +EOF diff --git a/doc/README.cca_stdll b/doc/README.cca_stdll new file mode 100644 index 0000000..f535dfa --- /dev/null +++ b/doc/README.cca_stdll @@ -0,0 +1,24 @@ + +README for the CCA secure-key token + +Kent Yoder <[email protected]> + + The key used to encrypt private objects on disk is a secure key. + + 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. + +MK_USER: The secure 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 + under the SO's PIN by software routines + +So, MK_USER and MK_SO contain the same key, encrypted under different PINs + +PKCS#11 Notes: + +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. diff --git a/doc/README.pkcscca_migrate b/doc/README.pkcscca_migrate new file mode 100644 index 0000000..2eddd51 --- /dev/null +++ b/doc/README.pkcscca_migrate @@ -0,0 +1,92 @@ + +README for the CCA secure-key token migration utility + +The CCA secure-key token migration utility consists of two programs: + + pkcscca_migrate.sh A shell script that invokes the pkcscca_migrate + utility. The script does some data location + validation, token validation and token data + backup. It is recommended that this script be + used to perform the migration. + + pkcscca_migrate A utility that will migrate all of the CCA + token data to the new CCA master key. + +To use the migration utility, make sure that there are no applications +actively using the PKCS#11 interface to the CCA secure-key token by stopping +any applications that use the PKCS#11 interface to the CCA secure-key token. + + +Using the pkcsconf64 utility, find/verify the slot number of the CCA secure-key +token: + + pkcsconf64 -s + pkcsconf64 -t + +The CCA secure-key token will have "(CCA)" at the end of the slot description +and the token information will identify the token as the "IBM CCA Token." + + +Once you have determined the proper slot number of the CCA secure-key token, +invoke the CCA secure-key token migration script: + + pkcscca_migrate.sh --slot-id X + where "X" is the slot number of the CCA secure-key token + +Optionally, you can specify the "--dry-run" and/or "-v" options on the script +invocation. + + --dry-run This will cause the migration utility to perform all + of the steps in the migration but will not commit the + changes needed to run under the new CCA master key. + Any errors encountered will be reported. + + -v This will increase the verbosity of the migration + utility. Multiple "-v" arguments can be specified to + increase the amount of verbose information displayed. + + +Using the pkcscca_migrate.sh script will create a backup copy of the CCA secure-key +token data in the openCryptoki main data store directory. Should any errors +be encountered during the migration, the original data will be restored. + +Here is a description of the steps involved in the migration: + + - The script will check to see if you are running as root or that you are + a member of the "pkcs11" group. If neither of these is the case, the + script will exit. + + - The script will look for the pkcsconf64 utility in two locations: + /usr/lib/pkcs11/methods or /usr/sbin + If the utility is not found, the script will exit. + + - The script will look for the CCA token data store in two locations: + /etc/pkcs11/ccatok or /var/lib/opencryptoki/ccatok + If the data store is not found, the script will exit. + + - The script will then validate the slot number: + - If a slot number has been supplied as an argument to the script, + it will be verified as a valid slot number. + + - If a slot number was not supplied as an argument to the script, + then the pkcsconf64 utility will be used to display a list of + valid slots. You must then choose the slot you wish to migrate. + + - The Security Office (SO) pin and the User pin are both required for the + migration. You will be prompted for both of these pins. + + - The selected slot information will be displayed and you will be prompted + to verify that you want to perform the migration. + + - The current CCA token data store will be backed up in the current directory. + Be sure that you have write access to the current directory. If the backup + file cannot be created, the script will exit. + + - The migration utility, pkcscca_migrate, will be invoked to perform the + actual migration. Any errors encountered will be reported. + + - Should an error have been encountered during the migration, the CCA token + data store will be restored from the backup that was created earlier. + + - If no errors have been encountered, then the migration has been successful. + diff --git a/doc/README.tpm_stdll b/doc/README.tpm_stdll new file mode 100644 index 0000000..fc3f159 --- /dev/null +++ b/doc/README.tpm_stdll @@ -0,0 +1,57 @@ + +TPM STDLL README +Kent Yoder <[email protected]> + +Current architecture: + + SRK + | + + User Root Key (URK) + | | + | + [1..N] User Base Key (UBK) + | | + | + Migratable Leaf Key (MLK) + | | | + | | + Auth Data for User Created Keys + | | + | + [1..N] User Created Keys + | + + Migratable Root Key (MRK) + | + + Migratable Leaf Key (MLK) + + + +1. When the SO logs in: + A) its verified that she is root (currently commented out) + B) the token searches for the User Root Key (URK), and if found, the SO's key + chain is loaded, up to the SO's protection key. Some junk data is encrypted + and decrypted to challenge the auth data passed in and if that test passes, + the SO is logged in + C) if the URK isn't found, its assumed that the SO is logging in for the + first time, and + i. The URK is generated in software + ii. The URK's private key is wrapped with the public key of the SRK, and + TSS and PKCS#11 objects are created for it, storing it in the PKCS#11 + data store + D) i and ii are repeated for the Migratable Root Key (MRK) + E) The Protection Key is generated by the TPM as a child of the MRK + F) Some junk data is encrypted and decrypted to challenge the auth data passed + in and if that test passes, the SO is logged in + +2. When the USER logs in: + A) The URK is searched for and if not found, failure (The SO has not + initialized the token) + B) If the URK is found, the User's Base Key (UBK) is searched for and if found, + the user's key chain is loaded, up to the USER's protection key. Some junk + data is encrypted and decrypted to challenge the auth data passed in and if + that test passes, the USER is logged in + C) if the UBK is not found: + i. The UBK is generated in software + ii.The UBK's private key is wrapped with the public key of the URK, and + TSS and PKCS#11 objects are created for it, storing it in the PKCS#11 + data store + D) The User's Protection Key is generated by the TPM as a child of the UBK + E) Some junk data is encrypted and decrypted to challenge the auth data + passed in and if that test passes, the USER is logged in + diff --git a/usr/lib/pkcs11/cca_stdll/Makefile.am b/usr/lib/pkcs11/cca_stdll/Makefile.am index d6db694..f0b5a6a 100644 --- a/usr/lib/pkcs11/cca_stdll/Makefile.am +++ b/usr/lib/pkcs11/cca_stdll/Makefile.am @@ -6,8 +6,6 @@ # nobase_lib_LTLIBRARIES=opencryptoki/stdll/libpkcs11_cca.la -pkgdata_DATA=README.cca_stdll README-IBM_CCA_users - # Not all versions of automake observe libname_CFLAGS opencryptoki_stdll_libpkcs11_cca_la_CFLAGS = -DLINUX -DSPINXPL -DNOCDMF \ -DNODSA -DNODH -DNOECB \ diff --git a/usr/lib/pkcs11/cca_stdll/README-IBM_CCA_users b/usr/lib/pkcs11/cca_stdll/README-IBM_CCA_users deleted file mode 100644 index 8bdd5cd..0000000 --- a/usr/lib/pkcs11/cca_stdll/README-IBM_CCA_users +++ /dev/null @@ -1,184 +0,0 @@ - -openCryptoki CCA Token README -Kent Yoder <[email protected]> - - - The purpose of this README is to document the differences between setting up -the openCryptoki token for the IBM CCA (Common Cryptographic Architecture) and -setting up other tokens, such as the ICA (IBM Crypto Accelerator) token. The main -difference is that the CCA libraries are available for 64bit s390x only, whereas -all other openCryptoki tokens can be used 32 or 64bit. This means that the -PKCS#11 setup utility used by openCryptoki, pkcsconf, cannot be used, since its -compiled 32bit by default. In order to work around this limitation, a version -of pkcsconf has been included in the 64bit openCryptoki package to configure the -CCA token. This version is named 'pkcsconf64', and is installed in /usr/sbin, -alongside the 32bit pkcsconf. Note that pkcsconf64 can be used to configure -any openCryptoki token, since they all support 64bit apps. - - -After installing these RPMs, the setup process is: - -STEP 1: - - # /etc/init.d/pkcsslotd start - - This should start the pkcsslotd daemon. You can check this with: - - # ps -auwx | grep pkcsslotd - - You should see something like: - - root 8914 0.0 0.3 3220 1552 ? Ss 23:31 0:00 /usr/sbin/pkcsslotd - -STEP 2: - - Check that all the libraries are in the right places. Do: - - # /usr/sbin/pkcsconf64 -t - - You should see: - - Token #0 Info: - Label: IBM ICA PKCS #11 - Manufacturer: IBM Corp. - Model: IBM ICA - Serial Number: 123 - Flags: 0x880045 (RNG|LOGIN_REQUIRED|CLOCK_ON_TOKEN|USER_PIN_TO_BE_CHANGED|SO_PIN_TO_BE_CHANGED) - Sessions: -1/-1 - R/W Sessions: -1/-1 - PIN Length: 4-8 - Public Memory: 0xFFFFFFFF/0xFFFFFFFF - Private Memory: 0xFFFFFFFF/0xFFFFFFFF - Hardware Version: 1.0 - Firmware Version: 1.0 - Token #1 Info: - Label: IBM PKCS#11 for CCA - Manufacturer: IBM Corp. - Model: IBM CCA Token - Serial Number: 123 - Flags: 0x880045 (RNG|LOGIN_REQUIRED|CLOCK_ON_TOKEN|USER_PIN_TO_BE_CHANGED|SO_PIN_TO_BE_CHANGED) - Sessions: -1/-1 - R/W Sessions: -1/-1 - PIN Length: 4-128 - Public Memory: 0xFFFFFFFF/0xFFFFFFFF - Private Memory: 0xFFFFFFFF/0xFFFFFFFF - Hardware Version: 1.0 - Firmware Version: 1.0 - Time: 23:33:41 - - Token #0 is the ICA token, driven by the libica package. If libica or its device driver - isn't installed, you may only see Token #1. - - If you get the following message: - - C_GetSlotCount returned 0 slots. Check that your tokens are installed correctly. - - several things could be wrong. Check that: - - 1) The master keys for the CCA's crypto card have been loaded. - - If the master keys have not yet been loaded, a message will appear in the - system log whenever pkcsconf is run that looks like: - - openCryptoki(CCA)[5294]: cca_specific.c Warning: CCA master key is not yet loaded - - Please follow any instructions or procedures you may have been given on - loading master keys. - - 2) The device driver for the CCA hardware is loaded. This module may be called - "zsecrypt" or "z90crypt" and may not have been loaded by the /etc/init.d/pkcsslotd - script. - - 3) The CCA libraries are installed correctly. openCryptoki requires the following - libraries: - - library source package - ----------------------------------- - libcsulcall.so xcryptolinz - libcsulsapi.so xcryptolinz - libcsulsecy.so xcryptolinz - libds30.so xcryptolinz - libxcryp.so xcryptolinz - libcrypto.so openssl - - When a token is detected by the startup scripts run by /etc/init.d/pkcsslotd, an - entry is made in the /var/lib/opencryptoki/pk_config_data file. This file will - contain 1 line per token. - -STEP 3: - - Initialize the CCA token. - - # /usr/sbin/pkcsconf64 -I -c 1 - - You should see: - - Enter the SO PIN: - - Enter the default SO PIN here, which is "87654321". - Enter a unique token label: - - Enter any string here, such as "My token init string" - - Another call to pkcsconf64 should reflect the token label change: - - # /usr/sbin/pkcsconf64 -t - Token #1 Info: - Label: My token init string - Manufacturer: IBM Corp. - Model: IBM CCA Token - Serial Number: 123 - Flags: 0x880445 (RNG|LOGIN_REQUIRED|CLOCK_ON_TOKEN|TOKEN_INITIALIZED|USER_PIN_TO_BE_CHANGED|SO_PIN_TO_BE_CHANGED) - Sessions: -1/-1 - R/W Sessions: -1/-1 - PIN Length: 4-128 - Public Memory: 0xFFFFFFFF/0xFFFFFFFF - Private Memory: 0xFFFFFFFF/0xFFFFFFFF - Hardware Version: 1.0 - Firmware Version: 1.0 - Time: 23:38:48 - -STEP 4: - - Set the Security Officer's (SO) Password. This should be a secret known only to - the system admin. - - # /usr/sbin/pkcsconf64 -P -c 1 - Enter the SO PIN: ******** - - This should be the default SO PIN, "87654321" - Enter the new SO PIN: ******** - Re-enter the new SO PIN: ******** - - Enter the new SO PIN here twice for verification - - -STEP 5: - - Set the PKCS#11 User Password. This will be a secret known to all users/apps of the - PKCS#11 interface. - - # /usr/sbin/pkcsconf64 -u -c 1 - Enter the SO PIN: ******** - - This should be the SO PIN you set in STEP 4. - Enter the new user PIN: ********** - Re-enter the new user PIN: ********** - - This should be a new secret, known to all users of the token. - -STEP 6: - - Make sure applications will have access to PKCS#11. - - All processes that would like to use PKCS#11 need to be in the 'pkcs11' group. So, - if java needs to access PKCS#11, then edit /etc/group: - - # vim /etc/group - - Look for the line: - - pkcs11:!:64:root - - and add the java uid to that line: - - pkcs11:!:64:root,java - - /etc/init.d/pkcsslotd creates the 'pkcs11' group when its first run. - -Send questions to [email protected]. -EOF diff --git a/usr/lib/pkcs11/cca_stdll/README.cca_stdll b/usr/lib/pkcs11/cca_stdll/README.cca_stdll deleted file mode 100644 index f535dfa..0000000 --- a/usr/lib/pkcs11/cca_stdll/README.cca_stdll +++ /dev/null @@ -1,24 +0,0 @@ - -README for the CCA secure-key token - -Kent Yoder <[email protected]> - - The key used to encrypt private objects on disk is a secure key. - - 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. - -MK_USER: The secure 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 - under the SO's PIN by software routines - -So, MK_USER and MK_SO contain the same key, encrypted under different PINs - -PKCS#11 Notes: - -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. diff --git a/usr/lib/pkcs11/tpm_stdll/README b/usr/lib/pkcs11/tpm_stdll/README deleted file mode 100644 index fc3f159..0000000 --- a/usr/lib/pkcs11/tpm_stdll/README +++ /dev/null @@ -1,57 +0,0 @@ - -TPM STDLL README -Kent Yoder <[email protected]> - -Current architecture: - - SRK - | - + User Root Key (URK) - | | - | + [1..N] User Base Key (UBK) - | | - | + Migratable Leaf Key (MLK) - | | | - | | + Auth Data for User Created Keys - | | - | + [1..N] User Created Keys - | - + Migratable Root Key (MRK) - | - + Migratable Leaf Key (MLK) - - - -1. When the SO logs in: - A) its verified that she is root (currently commented out) - B) the token searches for the User Root Key (URK), and if found, the SO's key - chain is loaded, up to the SO's protection key. Some junk data is encrypted - and decrypted to challenge the auth data passed in and if that test passes, - the SO is logged in - C) if the URK isn't found, its assumed that the SO is logging in for the - first time, and - i. The URK is generated in software - ii. The URK's private key is wrapped with the public key of the SRK, and - TSS and PKCS#11 objects are created for it, storing it in the PKCS#11 - data store - D) i and ii are repeated for the Migratable Root Key (MRK) - E) The Protection Key is generated by the TPM as a child of the MRK - F) Some junk data is encrypted and decrypted to challenge the auth data passed - in and if that test passes, the SO is logged in - -2. When the USER logs in: - A) The URK is searched for and if not found, failure (The SO has not - initialized the token) - B) If the URK is found, the User's Base Key (UBK) is searched for and if found, - the user's key chain is loaded, up to the USER's protection key. Some junk - data is encrypted and decrypted to challenge the auth data passed in and if - that test passes, the USER is logged in - C) if the UBK is not found: - i. The UBK is generated in software - ii.The UBK's private key is wrapped with the public key of the URK, and - TSS and PKCS#11 objects are created for it, storing it in the PKCS#11 - data store - D) The User's Protection Key is generated by the TPM as a child of the UBK - E) Some junk data is encrypted and decrypted to challenge the auth data - passed in and if that test passes, the USER is logged in - diff --git a/usr/sbin/pkcscca_migrate/README.pkcscca_migrate b/usr/sbin/pkcscca_migrate/README.pkcscca_migrate deleted file mode 100644 index 2eddd51..0000000 --- a/usr/sbin/pkcscca_migrate/README.pkcscca_migrate +++ /dev/null @@ -1,92 +0,0 @@ - -README for the CCA secure-key token migration utility - -The CCA secure-key token migration utility consists of two programs: - - pkcscca_migrate.sh A shell script that invokes the pkcscca_migrate - utility. The script does some data location - validation, token validation and token data - backup. It is recommended that this script be - used to perform the migration. - - pkcscca_migrate A utility that will migrate all of the CCA - token data to the new CCA master key. - -To use the migration utility, make sure that there are no applications -actively using the PKCS#11 interface to the CCA secure-key token by stopping -any applications that use the PKCS#11 interface to the CCA secure-key token. - - -Using the pkcsconf64 utility, find/verify the slot number of the CCA secure-key -token: - - pkcsconf64 -s - pkcsconf64 -t - -The CCA secure-key token will have "(CCA)" at the end of the slot description -and the token information will identify the token as the "IBM CCA Token." - - -Once you have determined the proper slot number of the CCA secure-key token, -invoke the CCA secure-key token migration script: - - pkcscca_migrate.sh --slot-id X - where "X" is the slot number of the CCA secure-key token - -Optionally, you can specify the "--dry-run" and/or "-v" options on the script -invocation. - - --dry-run This will cause the migration utility to perform all - of the steps in the migration but will not commit the - changes needed to run under the new CCA master key. - Any errors encountered will be reported. - - -v This will increase the verbosity of the migration - utility. Multiple "-v" arguments can be specified to - increase the amount of verbose information displayed. - - -Using the pkcscca_migrate.sh script will create a backup copy of the CCA secure-key -token data in the openCryptoki main data store directory. Should any errors -be encountered during the migration, the original data will be restored. - -Here is a description of the steps involved in the migration: - - - The script will check to see if you are running as root or that you are - a member of the "pkcs11" group. If neither of these is the case, the - script will exit. - - - The script will look for the pkcsconf64 utility in two locations: - /usr/lib/pkcs11/methods or /usr/sbin - If the utility is not found, the script will exit. - - - The script will look for the CCA token data store in two locations: - /etc/pkcs11/ccatok or /var/lib/opencryptoki/ccatok - If the data store is not found, the script will exit. - - - The script will then validate the slot number: - - If a slot number has been supplied as an argument to the script, - it will be verified as a valid slot number. - - - If a slot number was not supplied as an argument to the script, - then the pkcsconf64 utility will be used to display a list of - valid slots. You must then choose the slot you wish to migrate. - - - The Security Office (SO) pin and the User pin are both required for the - migration. You will be prompted for both of these pins. - - - The selected slot information will be displayed and you will be prompted - to verify that you want to perform the migration. - - - The current CCA token data store will be backed up in the current directory. - Be sure that you have write access to the current directory. If the backup - file cannot be created, the script will exit. - - - The migration utility, pkcscca_migrate, will be invoked to perform the - actual migration. Any errors encountered will be reported. - - - Should an error have been encountered during the migration, the CCA token - data store will be restored from the backup that was created earlier. - - - If no errors have been encountered, then the migration has been successful. - -- 1.7.1.1 ------------------------------------------------------------------------------ This SF.net email is sponsored by Sprint What will you do first with EVO, the first 4G phone? Visit sprint.com/first -- http://p.sf.net/sfu/sprint-com-first _______________________________________________ Opencryptoki-tech mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opencryptoki-tech
