You've already forked opencryptoki
mirror of
https://github.com/opencryptoki/opencryptoki.git
synced 2026-10-24 05:39:17 +03:00
91 lines
4.8 KiB
Plaintext
91 lines
4.8 KiB
Plaintext
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.
|
|
|
|
Starting with openCryptoki version 3.12, a new, FIPS compliant format can be used
|
|
to store the token objects. You may now want to migrate the data stores of an
|
|
EP11 token, a CCA token, an ICA token, or a Soft token to a FIPS compliant
|
|
format using the pkcstok_migrate tool. For details, please see
|
|
https://www.ibm.com/docs/en/linux-on-systems?topic=tools-pkcstok-migrate
|
|
|
|
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.
|