Documentation
¶
Overview ¶
Package hsm provides PKCS#11-backed storage for FROST key shares.
In production each participant's secret share lives inside the HSM. The share is written once during the key ceremony and is never exported (CKA_EXTRACTABLE = false). All subsequent use is in-HSM: the policy engine asks the HSM to produce a partial signature; the raw scalar bytes never leave the device boundary.
For the prototype we use SoftHSM2 so the whole stack can be exercised on a developer machine without physical hardware.
Index ¶
Constants ¶
const ( ShareKeyType = pkcs11.CKK_GENERIC_SECRET ShareKeyClass = pkcs11.CKO_SECRET_KEY )
Variables ¶
ErrShareExists is returned when StoreShare is called with a label that already exists in the token. Labels are unique per ceremony+index to prevent accidental overwrite.
Functions ¶
func CeremonyID ¶
CeremonyID derives a deterministic ID from the group public key bytes so that every participant independently computes the same label without out-of-band coordination.
func ShareLabel ¶
ShareLabel builds the canonical label for a participant's share.
ceremonyID -- a short identifier for the key ceremony (e.g. "ceremony-2024-01") index -- 1-indexed participant number (matches FROST convention)
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds an open PKCS#11 session against a single token slot. One Store is created per participant during the key ceremony and re-opened at node startup.
func New ¶
New opens a PKCS#11 context against the given shared-library path (e.g. /usr/local/lib/softhsm/libsofthsm2.so), logs in with the supplied PIN, and returns a ready Store. Call Close when done.
func (*Store) DeleteShare ¶
DeleteShare removes a previously stored share by label. Used during key rotation or ceremony teardown.
func (*Store) SignHMAC ¶
SignHMAC produces an HMAC-SHA256 commitment using the stored share as the key and msg as the message. This is used in the FROST nonce-binding step: each participant commits to their nonce by signing the session transcript with their share -- without ever exposing the share bytes.
The operation is performed entirely inside the HSM via C_Sign with CKM_SHA256_HMAC. The key material never crosses the HSM boundary.
func (*Store) StoreShare ¶
StoreShare writes a 32-byte FROST secret share to the HSM as a CKO_SECRET_KEY / CKK_GENERIC_SECRET object.
label encodes "share-<ceremonyID>-<participantIndex>" so that multiple ceremonies can coexist in one token without collisions.
The object is created with:
- CKA_EXTRACTABLE = false (bytes cannot be exported via C_WrapKey)
- CKA_SENSITIVE = true (bytes will not appear in C_GetAttributeValue)
- CKA_TOKEN = true (persists across sessions)
In SoftHSM2, EXTRACTABLE=false is enforced by the library; on a real HSM it is enforced in tamper-resistant hardware.
Source Files