Key Lifecycle

Craton HSM tracks key material through the lifecycle states defined in NIST SP 800-57 Part 1 §8. Every stored object carries an explicit state, and transitions are driven by either caller action (generation, explicit destruction, compromise flagging) or by the clock reaching the dates on CKA_START_DATE and CKA_END_DATE.

States

The state is held on the stored object as a KeyLifecycleState enum and is consulted on every cryptographic entry point.

Automated transitions

A lifecycle scan runs on token open and on each C_Initialize that finds an existing store. For each object it computes an effective state from the stored state plus the current time against CKA_START_DATE / CKA_END_DATE:

• Stored Active + future CKA_START_DATE → effective Pre-activation.
• Stored Active + past CKA_END_DATE → effective Deactivated, persisted.
• Stored Pre-activation + now ≥ CKA_START_DATE → effective Active, persisted.
• Compromised and Destroyed are terminal with respect to time — they never transition automatically.

Persisted transitions are appended to the audit log with the old and new state and the triggering date.

PKCS#11 attribute mapping

Craton HSM exposes the lifecycle through the standard PKCS#11 v3.0 attributes:

Callers set CKA_START_DATE and CKA_END_DATE at generation time, at import time via C_CreateObject, or later via C_SetAttributeValue provided CKA_MODIFIABLE is CK_TRUE.

Example: scheduling a key for rotation

import PyKCS11
import datetime

lib = PyKCS11.PyKCS11Lib()
lib.load("/opt/craton_hsm/libcraton_hsm.so")
session = lib.openSession(lib.getSlotList()[0], PyKCS11.CKF_RW_SESSION | PyKCS11.CKF_SERIAL_SESSION)
session.login("87654321")

today = datetime.date.today()
expiry = today + datetime.timedelta(days=365)

template = [
    (PyKCS11.CKA_CLASS, PyKCS11.CKO_PRIVATE_KEY),
    (PyKCS11.CKA_KEY_TYPE, PyKCS11.CKK_RSA),
    (PyKCS11.CKA_LABEL, "signing-2026"),
    (PyKCS11.CKA_SIGN, True),
    (PyKCS11.CKA_START_DATE, today.strftime("%Y%m%d")),
    (PyKCS11.CKA_END_DATE, expiry.strftime("%Y%m%d")),
]

Compromise and destruction

• Compromise is recorded by a Security Officer session setting a vendor-defined attribute (covered in Operations: key management). Once set, the state is persisted and the key cannot return to Active.
• Destruction is triggered by C_DestroyObject. The key material is zeroised in memory (via ZeroizeOnDrop), removed from persistent storage, and the destruction is logged. Objects with CKA_DESTROYABLE = CK_FALSE cannot be destroyed without first clearing that attribute (if CKA_MODIFIABLE = CK_TRUE) or at all if both are false.

Enforcement at operation time

Every cryptographic entry point (C_SignInit, C_EncryptInit, C_DecryptInit, C_VerifyInit, C_DeriveKey, C_WrapKey, C_UnwrapKey) evaluates the effective lifecycle state for the referenced key before doing anything else:

• Pre-activation → CKR_KEY_FUNCTION_NOT_PERMITTED
• Deactivated, and the operation is sign / encrypt / derive / wrap → CKR_KEY_FUNCTION_NOT_PERMITTED
• Deactivated, and the operation is verify / decrypt → permitted
• Compromised → CKR_KEY_FUNCTION_NOT_PERMITTED
• Destroyed → CKR_OBJECT_HANDLE_INVALID (the handle was freed)

Auditing

Every state transition produces an audit entry with the object handle, old state, new state, triggering cause (date, action, or compromise marking), and the wall-clock time. Entries are chained by SHA-256 so tampering with history is detectable. See Audit.

Related

• Cryptography overview
• Operations: key management runbook
• Security model