PKCS#11 module

Two modules: libroost-pkcs11.so serves the standard mechanisms (ECDSA, RSA, AES-GCM, key wrapping) that OpenSSL, Java SunPKCS11 and signing tools expect, and is the one used on the OpenSSL page. libroost-iron3.so, described below, issues and verifies sealed receipts.

The module libroost-iron3.so (Linux x86-64, Cryptoki 2.40) presents one read-only slot with one key handle. Load it with C_GetFunctionList.

Build

sudo apt-get install g++ make pkg-config libp11-kit-dev libcurl4-openssl-dev libssl-dev libjson-c-dev
make -C sdk/pkcs11 check
export ROOST_PKCS11_URL=https://roost-gateway.example
export ROOST_PKCS11_KEY_ID=release-ledger
pkcs11-tool --module "$PWD/sdk/pkcs11/libroost-iron3.so" --list-slots --list-mechanisms --list-objects

Use

Find the key by CKA_ID (the identifier's UTF-8 bytes) and CKA_CLASS=CKO_SECRET_KEY, and use vendor mechanism 0x8041584F with no parameters. A size query returns a safe upper bound; use the length returned by the successful signing call.

import os
from pathlib import Path
import PyKCS11 as p11

library = p11.PyKCS11Lib()
library.load(str(Path("libroost-iron3.so").resolve()))
slot, = library.getSlotList(tokenPresent=True)
session = library.openSession(slot)
try:
    key, = session.findObjects([(p11.CKA_CLASS, p11.CKO_SECRET_KEY),
                                (p11.CKA_LABEL, os.environ["ROOST_PKCS11_KEY_ID"])])
    mechanism = p11.Mechanism(0x8041584F, None)
    receipt = session.sign(key, b"client", mechanism)
    assert session.verify(key, b"client", receipt, mechanism)
finally:
    session.closeSession()

Result	Meaning
`CKR_OK` on verify	The quorum confirmed the seal
`CKR_SIGNATURE_INVALID`	The seal could not be confirmed by the quorum
`CKR_DEVICE_ERROR`	Transport failure

Mutual TLS

Set ROOST_PKCS11_TLS_CERT and ROOST_PKCS11_TLS_KEY to the client credentials when the gateway requires them. The platform CA trust store is used.

This profile covers IRON3 seals through the vendor mechanism. Generic tools that look for an RSA or ECDSA private key, such as OpenSC's default signing command, need the vendor-aware call shown above.

The IRON3 adapter example uses the fixture or a trusted application gateway. A managed appliance requires the application integration to obtain the Axowl authorization and supply the caller proof for each digest. TLS client authentication alone does not grant permission to use a key.

For a managed IRON3 document key, use your Axowl session to request a partition- and key-scoped signing authorization. Send the one-use authorization and proof from its ephemeral P-256 key to the assigned appliance. See managed gateway signing.