You've already forked opencryptoki
mirror of
https://github.com/opencryptoki/opencryptoki.git
synced 2026-10-24 05:39:17 +03:00
88585c7c71
The following patch adds documentation on openCryptoki's handling of token data and adds it to the rpm specfile. Signed-off-by: Kent Yoder <key@linux.vnet.ibm.com> doc/README.token_data | 99 +++++++++++++++++++++++++++++++++++++++++++++++++ rpm/opencryptoki.spec | 2 +- 2 files changed, 100 insertions(+), 1 deletions(-)
100 lines
4.5 KiB
Plaintext
100 lines
4.5 KiB
Plaintext
|
|
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
|