The following patch adds documentation on openCryptoki's handling of token data and adds it to the rpm specfile.
Signed-off-by: Kent Yoder <[email protected]> doc/README.token_data | 99 +++++++++++++++++++++++++++++++++++++++++++++++++ rpm/opencryptoki.spec | 2 +- 2 files changed, 100 insertions(+), 1 deletions(-) diff --git a/doc/README.token_data b/doc/README.token_data new file mode 100644 index 0000000..aa295d4 --- /dev/null +++ b/doc/README.token_data @@ -0,0 +1,99 @@ + + Send questions about this doc to [email protected]. + +PKCS#11 TOKEN DATA + + As PKCS#11 apps create token objects, openCryptoki stores them by +default in /var/lib/opencryptoki, in a token-specific subdirectory. +Each object is stored in its own file and given a unique name that +is never reused. Each object is stored in a binary format that gives +opencryptoki the ability to check for corruption when reading in the +object into memory. + +DATA CORRUPTION + + If corrupted token data is detected by opencryptoki, the name and +location on disk of the corrupted data is logged to syslog. You'll +notice a message something like one of the following: + +Aug 30 16:46:00 host openCryptoki[14491]: Cannot restore token object /var/lib/opencryptoki/swtok/TOK_OBJ/WJ000000 (ignoring it) +Aug 30 16:46:00 host openCryptoki[14491]: Cannot malloc 4294967290 bytes to read in token object /var/lib/opencryptoki/swtok/TOK_OBJ/WJ000000 (ignoring it) +Aug 30 16:46:00 host openCryptoki[14491]: Token object /var/lib/opencryptoki/swtok/TOK_OBJ/WJ000000 appears corrupted (ignoring it) + + This means that something about the object has changed in such a +way that makes opencryptoki unable or unwilling to process it. + +BACKING UP TOKEN DATA + + The only way to recover from corrupted token data is to maintain +backups. An admin can schedule a repeating backup of +/var/lib/opencryptoki to ensure token data can be restored if it +becomes corrupted. Token data can be restored file-by-file (for +instance, copying a backup of the WJ000000 file into the +/var/lib/opencryptoki/swtok/TOK_OBJ/ directory to use the example +log entries above), or the entire token data store can be restored +from backup at once. + + Note that NVTOK.DAT, MK_SO and MK_USER store additional state +for the token and are dependent on the SO and USER PIN state at the +time the backup was made. If you've changed your SO or USER PINs +since the last backup and then restore these files, it will +essentially roll back the PINs to their prior values. + +THE TPM TOKEN + + The TPM token is slightly different than the other tokens, in that +it stores its token data in a subdirectory for each user who runs a +PKCS#11 app. The subdirectory is the user ID of the user executing +the app, such as: + +/var/lib/opencryptoki/tpm/${USER} + + This data is not readable by other users accessing the TPM token, +unlike other opencryptoki tokens, where all apps who know the SO +or USER PIN can access all public or private token data objects +respectively. + + Keys and data generated on the TPM token will have as a parent a +migratable TPM key whose parent is an openssl-generated software +key wrapped by the TPM's Storage Root Key. These two parent keys +will be unique per user of the TPM token and so must be backed up +separately. + + The wrapped openssl keys are generated by opencryptoki as part of +initializing the token, and are stored encrypted by an AES-256 +key based on the SO and USER PINs, then stored as: + +/var/lib/opencryptoki/tpm/${USER}/PRIVATE_ROOT_KEY.pem +/var/lib/opencryptoki/tpm/${USER}/PUBLIC_ROOT_KEY.pem + + Keep in mind these are software keys encrypted by the SO and USER +PINs, which means that they'll be vulnerable to brute force +attacks on their passwords if an attacker gets access to them. These +are the only keys vulnerable to brute force attacks in the TPM +token -- all others are protected by the TPM's dictionary attack +prevention algorithms. + + If you choose not to move these keys off disk for backup, they will +be re-wrapped each time the USER or SO PIN changes, to stay in sync +with the current USER or SO PIN. + + If these keys are moved off disk for backup, be sure to remember the +SO and USER PINs at the time they were removed from disk. If your +TPM hardware fails and you're forced to migrate to a new TPM, the +PINs set at the time you backed them up will be required to decrypt +them and restore your TPM key hierarchy. + + To restore your token data on a new TPM, just make sure all token +data is installed in the /var/lib/opencryptoki/tpm/${USER} +directory and that the 2 pem files and NVTOK.DAT are present. When +you log in, the TPM key load operation will fail, since the new +TPM's Storage Root Key is different. Opencryptoki will detect this +condition, then unwrap the appropriate pem file using the supplied +PIN and re-wrap it to the new Storage Root Key. All token data +should then be available on the TPM. At this point you can remove +the pem files from disk again for backup - they aren't used during +normal operation of the token, except as we mentioned above, to +have their passwords updated each time the USER or SO PIN changes. + +EOF diff --git a/rpm/opencryptoki.spec b/rpm/opencryptoki.spec index f21e2d0..ce75978 100644 --- a/rpm/opencryptoki.spec +++ b/rpm/opencryptoki.spec @@ -174,7 +174,7 @@ gpasswd -a root pkcs11 %files %defattr(-,root,root,-) -%doc FAQ README LICENSE +%doc FAQ README LICENSE doc/README.token_data %doc doc/openCryptoki-HOWTO.pdf %{_mandir}/man*/* %{_initddir}/pkcsslotd ------------------------------------------------------------------------------ This SF.net Dev2Dev email is sponsored by: Show off your parallel programming skills. Enter the Intel(R) Threading Challenge 2010. http://p.sf.net/sfu/intel-thread-sfd _______________________________________________ Opencryptoki-tech mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opencryptoki-tech
