| 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. |