Debian Codegraph @

doc/README.token_data

raw
1 PKCS#11 TOKEN DATA
2
3 As PKCS#11 apps create token objects, openCryptoki stores them by default in
4 /var/lib/opencryptoki, in a token-specific subdirectory. Each object is stored
5 in its own file and given a unique name that is never reused. Each object is
6 stored in a binary format that gives openCryptoki the ability to check for
7 corruption when reading in the object into memory.
8
9 Starting with openCryptoki vesion 3.12, a new, FIPS compliant format can be used
10 to store the token objects. You may now want to migrate the data stores of an
11 EP11 token, a CCA token, an ICA token, or a Soft token to a FIPS compliant
12 format using the pkcstok_migrate tool. For details, please see
13 https://www.ibm.com/docs/en/linux-on-systems?topic=tools-pkcstok-migrate
14
15 DATA CORRUPTION
16
17 If corrupted token data is detected by openCryptoki, the name and location on
18 disk of the corrupted data is logged to syslog. You'll notice a message
19 something like one of the following:
20
21 Aug 30 16:46:00 host openCryptoki[14491]: Cannot restore token object /var/lib/opencryptoki/swtok/TOK_OBJ/WJ000000 (ignoring it)
22 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)
23 Aug 30 16:46:00 host openCryptoki[14491]: Token object /var/lib/opencryptoki/swtok/TOK_OBJ/WJ000000 appears corrupted (ignoring it)
24
25 This means that something about the object has changed in such a way that makes
26 openCryptoki unable or unwilling to process it.
27
28 BACKING UP TOKEN DATA
29
30 The only way to recover from corrupted token data is to maintain backups. An
31 admin can schedule a repeating backup of /var/lib/opencryptoki to ensure token
32 data can be restored if it becomes corrupted. Token data can be restored
33 file-by-file (for instance, copying a backup of the WJ000000 file into the
34 /var/lib/opencryptoki/swtok/TOK_OBJ/ directory to use the example log entries
35 above), or the entire token data store can be restored from backup at once.
36
37 Note that NVTOK.DAT, MK_SO and MK_USER store additional state for the token and
38 are dependent on the SO and USER PIN state at the time the backup was made. If
39 you've changed your SO or USER PINs since the last backup and then restore these
40 files, it will essentially roll back the PINs to their prior values.
41
42 THE TPM TOKEN
43
44 The TPM token is slightly different than the other tokens, in that it stores
45 its token data in a subdirectory for each user who runs a PKCS#11 app. The
46 subdirectory is the user ID of the user executing the app, such as:
47
48 /var/lib/opencryptoki/tpm/${USER}
49
50 This data is not readable by other users accessing the TPM token, unlike other
51 openCryptoki tokens, where all apps who know the SO or USER PIN can access all
52 public or private token data objects respectively.
53
54 Keys and data generated on the TPM token will have as a parent a migratable TPM
55 key whose parent is an openssl-generated software key wrapped by the TPM's
56 Storage Root Key. These two parent keys will be unique per user of the TPM token
57 and so must be backed up separately.
58
59 The wrapped openssl keys are generated by openCryptoki as part of initializing
60 the token, and are stored encrypted by an AES-256 key based on the SO and USER
61 PINs, then stored as:
62
63 /var/lib/opencryptoki/tpm/${USER}/PRIVATE_ROOT_KEY.pem
64 /var/lib/opencryptoki/tpm/${USER}/PUBLIC_ROOT_KEY.pem
65
66 Keep in mind these are software keys encrypted by the SO and USER PINs, which
67 means that they'll be vulnerable to brute force attacks on their passwords if an
68 attacker gets access to them. These are the only keys vulnerable to brute force
69 attacks in the TPM token -- all others are protected by the TPM's dictionary
70 attack prevention algorithms.
71
72 If you choose not to move these keys off disk for backup, they will be
73 re-wrapped each time the USER or SO PIN changes, to stay in sync with the
74 current USER or SO PIN.
75
76 If these keys are moved off disk for backup, be sure to remember the SO and
77 USER PINs at the time they were removed from disk. If your TPM hardware fails
78 and you're forced to migrate to a new TPM, the PINs set at the time you backed
79 them up will be required to decrypt them and restore your TPM key hierarchy.
80
81 To restore your token data on a new TPM, just make sure all token data is
82 installed in the /var/lib/opencryptoki/tpm/${USER} directory and that the 2 pem
83 files and NVTOK.DAT are present. When you log in, the TPM key load operation
84 will fail, since the new TPM's Storage Root Key is different. openCryptoki will
85 detect this condition, then unwrap the appropriate pem file using the supplied
86 PIN and re-wrap it to the new Storage Root Key. All token data should then be
87 available on the TPM. At this point you can remove the pem files from disk again
88 for backup - they aren't used during normal operation of the token, except as we
89 mentioned above, to have their passwords updated each time the USER or SO PIN
90 changes.