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.