Luna Extensions to PKCS#11
The following table provides a list of the Luna PKCS#11 C-API extensions.
Firmware Dependencies
Some functions are firmware-dependent, as indicated. Where there is a firmware dependency, the specified firmware version applies to all minor revisions of the firmware. In the following table, if no firmware version/series is mentioned, then the extension applies to all. If a firmware version is mentioned, then the extension applies to that firmware series, but not to others. A function that applies to Firmware 4 (example: CA_CloneModifyMofN) works with firmware versions 4.xx.xx, but not with firmware 6.xx.xx nor firmware 7.xx.xx.
Other APIs
These commands and functions can also be used as extensions to other Application Programming Interfaces (for example, OpenSSL).
Cryptoki Version Supported
The current release of Luna Toolkit provides the Chrystoki library supporting version 2.20 of the Cryptoki standard.
Luna Extensions
| Extension | Description |
|---|---|
| CA_ActivateMofN | Activates a token that has the secret sharing feature enabled. |
| CA_AssignKey | See CA_AssignKey. |
| CA_AuthorizeKey | See CA_AuthorizeKey. |
| CA_Bip32ExportPublicKey | Retrieve public BIP32 key attributes and returned serialized format (base58 encoded). |
| CA_Bip32ImportPublicKey | Import BIP32 serialized format (base58 encoded) and create BIP32 public key object. |
| CA_CapabilityUpdate | Apply configuration update file as Security Officer only. |
| CA_CheckOperationState | Checks if the specified cryptographic operation (encrypt, decrypt, sign, verify,digest) is in progress or not in the given session. |
| CA_CloneAsSource | Refer to Luna HSM Cloning API CPv1 - Extensions to PKCS #11, Luna HSM Cloning API CPv3 - Extensions to PKCS #11, and Luna HSM Cloning API CPv4 Extensions to PKCS#11 |
| CA_CloneAsTarget | Refer to Luna HSM Cloning API CPv1 - Extensions to PKCS #11, Luna HSM Cloning API CPv3 - Extensions to PKCS #11, and Luna HSM Cloning API CPv4 Extensions to PKCS#11 |
| CA_CloneAsTargetInit | Refer to Luna HSM Cloning API CPv1 - Extensions to PKCS #11, Luna HSM Cloning API CPv3 - Extensions to PKCS #11, and Luna HSM Cloning API CPv4 Extensions to PKCS#11 |
| CA_CloneModifyMofN | Firmware 4. Cloning of M of N. |
| CA_CloneMofN | Firmware 4 cloning of M of N. Copy a cloneable secret-splitting vector from one token to another. |
| CA_CloneMofN_Common | Firmware 4 cloning of M of N. |
| CA_CloneObject | Refer to Luna HSM Cloning API CPv1 - Extensions to PKCS #11, Luna HSM Cloning API CPv3 - Extensions to PKCS #11, and Luna HSM Cloning API CPv4 Extensions to PKCS#11 |
| CA_ClonePrivateKey | Permits the secure transfer a private key (RSA) between a source token and a target token. |
| CA_CloseApplicationID | Deactivate an application identifier. |
| CA_CloseApplicationIDForContainer | Deactivate an application identifier for a container. |
| CA_CloseSecureToken | Firmware 6. Close context for an SFF token. |
| CA_ConfigureRemotePED | Configure the given slot to use the provided remote PED information (appliance slot only). |
| CA_CreateContainer | Create a partition for non-PPSO users. |
| CA_CreateContainerLoginChallenge | Create a challenge for a role on a partition. |
| CA_CreateContainerWithPolicy | Firmware 6. Create a partition with per-partition template data. |
| CA_CreateLoginChallenge | Create a login challenge for the specified user. |
| CA_Deactivate | Deactivate a partition. |
| CA_DeactivateMofN | Firmware 4. Deactivate M of N. |
| CA_DeleteContainer | Delete a partition. |
| CA_DeleteContainerWithHandle | Delete a partition. |
| CA_DeleteRemotePEDVector | Delete the Remote PED vector. |
| CA_DeriveKeyAndWrap | This is an optimization of C_DeriveKey with C_Wrap, merging the two functions into one (the in and out constraints are the same as for the individual functions). A further optimization is applied when mechanism CKM_ECDH1_DERIVE is used with CA_DeriveKeyAndWrap. |
| CA_DestroyMultipleObjects | Delete multiple objects. |
| CA_DismantleRemotePED | Inverse of CA_ConfigureRemotePED(). Delete remote PED configuration information. |
| CA_DuplicateMofN | Create duplicates (copies) of all MofN secret splits. |
| CA_EncodeECChar2Params | Encode EC curve parameters for user defined curves. |
| CA_EncodeECParamsFromFile | Encode EC curve parameters for user defined curves. |
| CA_EncodeECPrimeParams | Encode EC curve parameters for user defined curves. |
| CA_Extract | Extract a SIM3 blob. |
| CA_FactoryReset | Factory Reset the HSM. |
| CA_FindAdminSlotForSlot | Get the Admin slot for the current slot. |
| CA_FirmwareRollback | Rollback firmware. |
| CA_FirmwareUpdate | Firmware 4. Firmware update for Firmware 4 (only used in Luna SA 4.x). |
| CA_GenerateCloneableMofN | Create a cloneable secret-splitting vector on a token. |
| CA_GenerateCloningKEV | Refer to Luna HSM Cloning API CPv1 - Extensions to PKCS #11, Luna HSM Cloning API CPv3 - Extensions to PKCS #11, and Luna HSM Cloning API CPv4 Extensions to PKCS#11 |
| CA_GenerateMofN | Generate the secret information on a token. |
| CA_GenerateMofN_Common | Refer to the M of N document. |
| CA_Get | Get HSM parameters such as serial numbers, and certificates. |
| CA_GetApplicationID | Get an application's accessID. |
| CA_GetConfigurationElementDescription | Get capability / policy description and properties. |
| CA_GetContainerCapabilitySet | Get all partition capability values. |
| CA_GetContainerCapabilitySetting | Get a single partition capability value. |
| CA_GetContainerList | Get the list of all partitions on a slot. |
| CA_GetContainerName | Get the name of a specific partition. |
| CA_GetContainerPolicySet | Get all partition policy values. |
| CA_GetContainerPolicySetting | Get a single partition policy value. |
| CA_GetContainerStatus | Get partition status, which returns authentication status flags. |
| CA_GetContainerStorageInformation | Get partition storage information such as size, usage, and number of objects. |
| CA_GetCurrentHAState() | Get HA status from the application perspective. Same functional behavior as CA_Get HAState, but uses parallel checks of members, avoids delays once a peer is found unreachable, and returns all member statuses within 3 seconds (*). |
| CA_GetDefaultHSMPolicyValue | Get the default value of a single HSM policy. |
| CA_GetDefaultPartitionPolicyValue | Get the default value of a single partition policy. |
| CA_GetFirmwareVersion | Get the vendor-specific firmware version of the Luna HSM. |
| CA_GetHAState | Get HA status from the application perspective. |
| CA_GetHSMCapabilitySet | Get all HSM capability values. |
| CA_GetHSMCapabilitySetting | Get a single HSM capability value. |
| CA_GetHSMPolicySet | Get all HSM policy values. |
| CA_GetHSMPolicySetting | Get a single HSM policy value. |
| CA_GetHSMStats | Get HSM usage stats such as operational counters and how busy the HSM is. |
| CA_GetHSMStorageInformation | Get HSM storage information such as storage and usage. |
| CA_GetMofNStatus | Retrieve the MofN structure of the specified token. |
| CA_GetNumberOfAllowedContainers | Get the number of allowed partitions depending on the partition license count. |
| CA_GetObjectHandle | Get the object handle for a given OUID. |
| CA_GetObjectUID | Get the OUID for a given object handle. |
| CA_GetPartitionPolicyTemplate | Firmware 6. Gets default partition policy template data from HSM. |
| CA_GetPedId | Get the PED ID. |
| CA_GetRemotePEDVectorStatus | Get the status of the RPV, created or not. |
| CA_GetRollbackFirmwareVersion | Get the available rollback version. |
| CA_GetSecureElementMeta | Get META data for objects on an SFF backup token. (Deprecated) |
| CA_GetServerInstanceBySlotID | Get the instance # in the chrystoki.conf (crystoki.ini) file for the appliance/server the specified slot maps to. |
| CA_GetSessionInfo | Gets the session info that includes vendor specific information such as authentication state and container handle. |
| CA_GetSlotIdForContainer | Return a slot for a given container handle. |
| CA_GetSlotIdForPhysicalSlot | Return a slot for a given physical slot. |
| CA_GetSlotListFromServerInstance | Get the list of slots for the specified appliance/server instance #, as defined in the chrystoki.conf (crystoki.ini) file. |
| CA_GetTime | Get the HSM time. |
| CA_GetTokenCapabilities | Get the capabilities for the specified partition. |
| CA_GetTokenCertificateInfo | Get the cloning certificate. |
| CA_GetTokenCertificates | Get all HSM certificates. Token Wrapping Certificates are used for cloning. [ See * below table ] |
| CA_GetTokenInsertionCount | Get the insertion or reset count of HSM in the given slot. |
| CA_GetTokenObjectHandle | Retrieves a partition's handle, if there is a partition security officer. Firmware 6.22.0 or higher for Luna Devices. Same as CA_GetObjectHandle. |
| CA_GetTokenObjectUID | Retrieves a partition's OUID, if there is a partition security office. Firmware 6.22.0 or higher for Luna Devices. Same as CA_GetObjectOUID. |
| CA_GetTokenPolicies | Get partition policies. |
| CA_GetTokenStatus | Get partition status. |
| CA_GetTokenStorageInformation | Get partition storage information. |
| CA_GetTunnelSlotNumber | Get the tunnel slot number for a given slot number. |
| CA_HAActivateMofN | See CA_HAActivateMofN(). |
| CA_HAAnswerLoginChallenge | See CA_HAAnswerLoginChallenge(). |
| CA_HAAnswerMofNChallenge | See CA_AnswerMofNChallenge(). |
| CA_HAGetLoginChallenge | See CA_HAGetLoginChallenge(). |
| CA_HAGetMasterPublic | See CA_HAGetMasterPublic(). |
| CA_HAInit | See CA_HAInit(). |
| CA_HALogin | See High Availability Indirect Login. |
| CA_IncrementFailedAuthCount | See CA_IncrementFailedAuthCount. |
| CA_InitAudit | Initialize the Auditor role. |
| CA_InitializeRemotePEDVector | Create the Remote PED Vector. |
| CA_InitRolePIN | Initialize a role on the current slot. |
| CA_InitSlotRolePIN | Initialize a role on a different slot. |
| CA_InitToken | Same as CA_Init_token with PPT support. |
| CA_Insert | Insert a SIM3 blob. |
| CA_IsMofNEnabled | Firmware 4. Queries M of N status. |
| CA_IsMofNRequired | Firmware 4. Queries M of N status. |
| CA_ListSecureTokenInit | Retrieve information from an SFF backup token. |
| CA_ListSecureTokenUpdate | Continue retrieving information from a backup SFF token. |
| CA_LogExportSecret | Export (backup) the audit log HMAC key. |
| CA_LogExternal | Log external message - pushes an application-provided message to the HSM and logs it via the audit log. |
| CA_LogGetConfig | Get the audit log configuration. |
| CA_LogGetStatus | Get the audit log status (audit role, logs needing export, HSM to PedClient communication status). |
| CA_LogImportSecret | Restore the audit log HMAC key. |
| CA_LogSetConfig | Modify the audit log configuration. |
| CA_LogVerify | Verify the audit log record(s). |
| CA_LogVerifyFile | Verify the audit log record file. |
| CA_ManualKCV | Set the key cloning vector (KCV) (sets the domain). |
| CA_ModifyMofN | Modify the secret-splitting vector on a token. |
| CA_ModifyUsageCount | Modify key usage count (Crypto Officer). |
| CA_MTKGetState | Firmware 6. Get the master tamper key (MTK) state (tampered or not). |
| CA_MTKResplit | Generate new MTK split, new purple key value. |
| CA_MTKRestore | Return MTK, provide purple key to recover from tamper. |
| CA_MTKSetStorage | Create purple key, enables STM/SRK. |
| CA_MTKZeroize | Erase the MTK, user invoked tamper. Puts HSM in to transport mode. |
| CA_OpenApplicationID | Activate an application identifier, independent of any open sessions. |
| CA_OpenApplicationIDForContainer | Same as CA_OpenApplicationID, but partition specific. |
| CA_OpenSecureToken | Firmware 6. Open context for an SFF token. |
| CA_OpenSession | Same as C_OpenSession, but lets you specify partition. |
| CA_OpenSessionWithAppID | Same as CA_OpenSession, but lets you specify an application ID (AppID) |
| CA_PerformSelfTest | Invoke a self test on HSM (RNG statistics, Cryptographic Algorithms). |
| CA_QueryLicense | Get License/CUF information. |
| CA_RandomizeApplicationID | Set an application accessID to a random value. |
| CA_ResetAuthorizationData | See CA_ResetAuthorizationData. |
| CA_ResetDevice | Reset the HSM . |
| CA_ResetPIN | SO reset of a CO role PIN (if "SO can reset PIN" policy is on). |
| CA_Restart | Clean up all sessions for a given slot. |
| CA_RestartForContainer | Clean up all sessions for a given partition. |
| CA_RetrieveLicenseList | Get a list of all Licenses/CUFs. |
| CA_RoleStateGet | Get the state of a role (initialized, activated, failed logins, challenge created, etc). |
| CA_SetApplicationID | Set the application's identifier. |
| CA_SetAuthorizationData | See CA_SetAuthorizationData. |
| CA_SetCloningDomain | Set the domain string used during token initialization. |
| CA_SetContainerPolicies | Set multiple partition policies. |
| CA_SetContainerPolicy | Set single partition policy. |
| CA_SetContainerSize | Set container storage size. |
| CA_SetDestructiveHSMPolicies | Set multiple destructive HSM policies. |
| CA_SetDestructiveHSMPolicy | Set single destructive HSM policy. |
| CA_SetHSMPolicies | Set multiple HSM policies. |
| CA_SetHSMPolicy | Set single HSM policy. |
| CA_SetKCV | Set KCV (domain). |
| CA_SetLKCV | Set a legacy KCV (legacy domain). |
| CA_SetMofN | Set the security policy for the token to use the secret sharing feature. |
| CA_SetPedId |
Set the PED ID for a specific slot. |
| CA_SetRDK | Set the RDK (role specific KCV) for the current role. |
| CA_SetTokenPolicies | Set partition policies for given slot (PPSO only) |
| CA_SetUserContainerName | Set the name the library should use for the user partition on non-PPSO partitions. |
| CA_SIMExtract | SIM2, SKS, firmware 4.x, firmware 6.x. Extract SIM2 blob. |
| CA_SIMInsert | SIM2, SKS, firmware 4.x, firmware 6.x. Insert SIM2 blob. |
| CA_SIMMultiSign | SIM2, SKS, firmware 4.x, firmware 6.x. Sign multiple data blobs with multiple keys provided as SIM2 blobs. |
| CA_SMKRollover | Invoke once to move current SMK to RolloverSMK slot and create new PrimarySMK - allows insertion/decrypting of existing blobs with Rollover SMK and re-encryption/extraction with new Primary - then invoke again to end. |
| CA_SpRawRead | PED key migration - read PED key value from DataKey PED Key. |
| CA_SpRawWrite | PED key migration - store PED key value to iKey PED Key. |
| CA_STCClearCipherAlgorithm | Remove the specified Cipher Algorithm from use with STC for the specified slot. |
| CA_STCClearDigestAlgorithm | Remove the specified Digest Algorithm from use with STC for the specified slot. |
| CA_STCDeregister | Remove STC registration of a client from the specified slot. |
| CA_STCGetAdminPubKey | Get the public key for the Admin slot's STC identity RSA keypair. |
| CA_STCGetChannelID | Get the Secure Trusted Channel ID for the current slot. |
| CA_STCGetCipherAlgorithm | Get all the valid cipher suites allowed for the specified slot. |
| CA_STCGetCipherID | Get the ID for the cipher currently in use on active STC to this slot. |
| CA_STCGetCipherIDs | Get all cipher IDs valid for use with STC to the specified slot. |
| CA_STCGetCipherNameByID | Get the readable name string for the specified Cipher ID. |
| CA_STCGetClientInfo | Get the STC registration details (name, public key, active access) about the specified client on the specified slot. |
| CA_STCGetClientsList | Get the list of all STC clients registered to the specified slot. |
| CA_STCGetCurrentKeyLife | Get the remaining lifetime (in operations) for the active negotiated STC session key. |
| CA_STCGetDigestAlgorithm | Get all the valid digest algorithms allowed for the specified slot. |
| CA_STCGetDigestID | Get the ID for the digest currently in use on active STC to this slot. |
| CA_STCGetDigestIDs | Get all digest IDs valid for use with STC to the specified slot. |
| CA_STCGetDigestNameByID | Get the readable name string for the specified Digest ID. |
| CA_STCGetKeyActivationTimeOut | Get the amount of time allowed between the initiation and completion of STC session negotiation. |
| CA_STCGetKeyLifeTime | Get the configured session key lifetime (in operations) for the specified slot. |
| CA_STCGetPartPubKey | Get the public key for the specified slot STC identity RSA keypair. |
| CA_STCGetPubKey | Get the specified slot's public key. |
| CA_STCGetSequenceWindowSize | Get the replay window size for the specified slot. |
| CA_STCGetState | Get the STC state of the specified slot. |
| CA_STCIsEnabled | Determine if STC is configured for the specified slot. |
| CA_STCRegister | Register a client for STC to the specified slot. |
| CA_STCSetCipherAlgorithm | Set a cipher algorithm as valid for use with STC on the specified slot. |
| CA_STCSetDigestAlgorithm | Set a digest algorithm as valid for use with STC on the specified slot. |
| CA_STCSetKeyActivationTimeOut | Set the amount of time allowed between the initiation and completion of STC session negotiations for the specified slot. |
| CA_STCSetKeyLifeTime | Set how long a STC key can live before STC rekeying occurs. |
| CA_STCSetSequenceWindowSize | Set the replay window size for the specified slot. |
| CA_STMGetState | Firmware 7. Get STM state (enabled or disabled). |
| CA_STMToggle | Enter, or recover from, Secure Transport Mode. |
| CA_TamperClear | Firmware 7. Used by the SO to clear tamper status. |
| CA_TimeSync | Synchronize the HSM time with the host time. |
| CA_TokenDelete | SO can delete a partition (PPSO only). |
| CA_TokenZeroize | Zeroize a PPSO partition. |
| CA_ValidateContainerPolicySet | Firmware 7. Validate partition policy settings prior to calling SetPolicies. |
| CA_ValidateHSMPolicySet | Firmware 7. Validate HSM policy settings prior to calling SetPolicies. |
| CA_WaitForSlotEvent | For PCMCIA HSMs, extends C_WaitForSlotEvent and provides some history of events. |
| CA_Zeroize | Zeroize the HSM. |
(* The 3 seconds is expected to be achievable for an HA group up to 32 members and is verified in supportive conditions, meaning in laboratory-like conditions, when not affected by appliance CPU, memory, network, or HSM bottlenecks that are outside the control of the cryptographic module and its host. The CA_GetCurrentHaState() function, along with CKDemo option 49, is available starting at Luna HSM Client version 10.7.0.)
Luna Keyring Extensions
The following custom PKCS#11 extensions apply to Luna keyrings only (see Cluster Extensions). Thales recommends Luna Appliance Software 7.8.3 with cluster package 1.0.3, Luna HSM Firmware 7.8.2,
| Extension | Description |
|---|---|
| CA_GetSlotId | Resolve the ID of the token(s) from the given label. |
| CA_GetUnassignedSlot | Get the ID of the next unassigned token from the unordered list of created tokens in the system. |
| CA_LockClusteredSlot | Lock the specified keyring. |
| CA_UnlockClusteredSlot | Unlock the specified keyring. It might have been locked deliberately using CA_LockClusteredSlot or CA_GetUnassignedSlot. |
