Smart Key Attributes

This page describes how to use Smart Key Attributes (SKA) via the PKCS#11 API. For the full C definitions, please see the pkcs11.h header file that is part of the Primus PKCS#11 Provider download.

Full code samples are available on GitHub.

Mechanisms

Use these mechanisms to generate an SKA key with the standard C_GenerateKeyPair.

• CKM_SKA_RSA_PKCS_KEY_PAIR_GEN
• CKM_SKA_DSA_KEY_PAIR_GEN
• CKM_SKA_EC_KEY_PAIR_GEN
• CKM_SKA_EC_EDWARDS_KEY_PAIR_GEN

Attributes

The following attributes are for the private key template during SKA key pair generation. The public key template can stay as with a normal non-SKA key. When generating a key pair, you must set all four policies on the private key template.

Attribute	Description
CKA_SKA_BLOCKED	Whether the private SKA key is blocked. Default CK_FALSE.
CKA_SKA_SENSITIVE_PUBLIC_KEY	If the public key is sensitive. Default CK_FALSE.
CKA_SKA_CRYPTO_CURRENCY_TYPE	Specifies the cryptocurrency for which it is used. Not set by default.
CKA_SKA_TIMESTAMP_SIGN	If the key can be used to create signed timestamps. Default CK_FALSE.
CKA_SKA_USAGE_ACCESS_BLOB	Serialized policy of who can approve key usage.
CKA_SKA_BLOCK_ACCESS_BLOB	Serialized policy of who can approve key blocking.
CKA_SKA_UNBLOCK_ACCESS_BLOB	Serialized policy of who can approve key unblocking.
CKA_SKA_MODIFY_ACCESS_BLOB	Serialized policy of who can approve key policy modification.

Structs

The following structs are used for building SKA policies. See the SKA documentation for an explanation of policies.

• CK_SKA_POLICY: A list of tokens.
• CK_SKA_TOKEN: A name, a timelock (delay), a timeout, and a list of groups.
• CK_SKA_GROUP: A name, a quorum, and a list of approvers.
• CK_SKA_APPROVER: A name, a type (public key or certificate), and the public key/certificate data.

Functions

The Primus PKCS#11 Provider defines the following functions for working with SKA keys.

As usual with PKCS#11, callers can pass NULL for any of the output buffers to request the size that the output would have.

Main Functions

All of the following main SKA functions take an approval token and an list of approvals as inputs. The approval token contains the payload (the message to be signed, the message to be decrypted, or the key to be unwrapped), as well as additional metadata. An approval is a signature over the approval token.

• C_SKASign, C_SKADecrypt, C_SKAUnwrapKey
  • Similar to the standard C_Sign, C_Decrypt, and C_UnwrapKey.
  • They are called directly with the SKA private key handle, the approval token (the payload to be signed/decrypted/unwrapped), and the list of approvals. There is no Init/Final.
• C_SKABlock, C_SKAUnblock, C_SKAModify
  • Functions to block/unblock the SKA key or modify its policy.
  • They don't return any data.

Helper Functions

The following helper functions are needed when working with SKA keys. They help you in creating the policies, approval tokens, and signed approvals in the correct serialization format.

• C_SerializePolicy
  • Serializes a CK_SKA_POLICY struct. For example, this is needed because the private key template during key generation expects a buffer with a serialized policy.
• C_GetTimeStamp
  • Gets a signature over a payload and the current timestamp from the HSM. This requires a timestamp key, which needs to have been generated previously.
  • A signed timestamp is needed when the SKA key is protected with a timelock or a timeout. The signed timestamp will be included in the approval token. For details, see the SKA Timestamps documentation.
• C_CreateApprovalToken
  • Creates the approval token, which the approvers will sign.
  • The payload differs depending on the specified key usage type:
    • Block/unblock: No payload needed.
    • Sign: The payload should be the message.
    • Unwrap/modify: The payload should be created using the helper functions below.
  • The timestamp and the timestamp signature are optional. They are needed when the key's policy specifies a timeout or timelock.
• C_CreateUnwrapPayload
  • Creates the payload of an approval token for unwrapping a key.
  • Input: Wrapped key and attribute template for the unwrapped key.
  • Output: The payload.
• C_CreateModifyPayload
  • Creates the payload of an approval token for modifying a key's policy.
  • Input: The new policies (between just one and all four of them). If one of the policies is NULL, it is unchanged.
  • Output: The payload.
• C_SignApprovalToken

  • Signs an approval token with an approver's private key.

    danger

    C_SignApprovalToken is intended as a helper function for testing! It takes the private key directly as raw bytes!

    In a production deployment, approver keys are often stored remotely, such as in the Secure Element of a smartphone or on a USB security key. Your application should use that system's signing mechanism instead of this function.