
 Send questions about this doc to opencryptoki-users@lists.sf.net.

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
