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.