Capability and Policy Configuration Control Using the SafeNet API
The configuration and control of the SafeNet Luna PCIe HSM is provided by a set of capabilities and policies which you can query and set using the SafeNet API. See for more information.
HSM Capabilities and Policies
Each HSM has a set of capabilities. An HSM's capability set defines and controls the behavior of the HSM.
HSM behavior can be further modified through changing policies. The HSM Admin can refine the behavior of an HSM by changing the policy settings.
HSM Partition Capabilities and Policies
Each HSM can support one-or-more virtual HSMs called HSM Partitions (may also be called “containers” in some areas of the API), which are used by properly authenticated remote clients to perform cryptographic operations.
Each HSM Partition has a set of capabilities. An HSM Partition's capability set defines and controls the behavior of the HSM partition.
HSM Partition behavior can be further modified through changing policies. The HSM Admin can refine the behavior of an HSM Partition by changing the policy settings. Different partitions can have different values for the configuration elements which apply to specific HSM Partitions – in other words, if a policy is set to a given value for one HSM Partition, the policy can be set to a different value for another HSM Partition on the same HSM.
In some cases, a partition policy change is destructive.
Policy Refinement
For every policy set element, there is a corresponding capability set element (the reverse is not true – there can be some capability set elements that do not have corresponding policy set elements). The value of a policy set element can be modified by the HSM Admin, but only within the limitations imposed by the corresponding capability set element.
For example, there is a policy set element which determines how many failed login attempts may be made before a Partition is deleted or locked out. There is also a corresponding capability set element for the same purpose. The policy element may be modified by the HSM Admin, but may only be set to a value less than or equal to that of the capability set element. So if the capability set element has a value of 10, the HSM Admin can set the policy to a value less than or equal to 10.
In general, the HSM Admin may modify policy set elements to make the HSM or partition policy more restrictive than that imposed by the capability set elements. The HSM Admin can not make the HSM or HSM Partition policy less restrictive or enable functionality that is disabled through capability settings.
Policy Types
There are three types of policy elements, as follows:
| Normal policy elements |
May be set at any time by the HSM Admin. The values which may be set are limited only by the corresponding capability element as described in the previous section (i.e. the policy element can be set only to a value less than or equal to the capability set element). |
| Destructive policy elements |
May be set at any time, but setting them results in the erasure of any partitions and their contents. Policy elements are destructive if changing them significantly affects the security policy of the HSM. |
| Write-restricted policy elements |
Cannot be modified directly, but instead are affected by other actions that can be taken. |
Querying and Modifying HSM Configuration
The following are the relevant functions (found in sfnt_extensions.h):
>CK_RV CK_ENTRY CA_GetConfigurationElementDescription(
>CK_SLOT_ID slotID,
>CK_ULONG ulIsContainerElement,
>CK_ULONG ulIsCapabilityElement,
>CK_ULONG ulElementId,
>CK_ULONG_PTR pulElementBitLength,
>CK_ULONG_PTR pulElementDestructive,
>CK_ULONG_PTR pulElementWriteRestricted,
>CK_CHAR_PTR pDescription);
>CK_RV CK_ENTRY CA_GetHSMCapabilitySet(
>CK_SLOT_ID uPhysicalSlot,
>CK_ULONG_PTR pulCapIdArray,
>CK_ULONG_PTR pulCapIdSize,
>CK_ULONG_PTR pulCapValArray,
>CK_ULONG_PTR pulCapValSize );
>CK_RV CK_ENTRY CA_GetHSMCapabilitySetting (
>CK_SLOT_ID slotID,
>CK_ULONG ulPolicyId,
>CK_ULONG_PTR pulPolicyValue);
>CK_RV CK_ENTRY CA_GetHSMPolicySet(
>CK_SLOT_ID uPhysicalSlot,
>CK_ULONG_PTR pulPolicyIdArray,
>CK_ULONG_PTR pulPolicyIdSize,
>CK_ULONG_PTR pulPolicyValArray,
>CK_ULONG_PTR pulPolicyValSize );
>CK_RV CK_ENTRY CA_GetHSMPolicySetting (
>CK_SLOT_ID slotID,
>CK_ULONG ulPolicyId,
>CK_ULONG_PTR pulPolicyValue);
>CK_RV CK_ENTRY CA_GetContainerCapabilitySet(
>CK_SLOT_ID uPhysicalSlot,
>CK_ULONG ulContainerNumber,
>CK_ULONG_PTR pulCapIdArray,
>CK_ULONG_PTR pulCapIdSize,
>CK_ULONG_PTR pulCapValArray,
>CK_ULONG_PTR pulCapValSize );
>CK_RV CK_ENTRY CA_GetContainerCapabilitySetting (
>CK_SLOT_ID slotID,
>CK_ULONG ulContainerNumber,
>CK_ULONG ulPolicyId,
>CK_ULONG_PTR pulPolicyValue);
>CK_RV CK_ENTRY CA_GetContainerPolicySet(
>CK_SLOT_ID uPhysicalSlot,
>CK_ULONG ulContainerNumber,
>CK_ULONG_PTR pulPolicyIdArray,
>CK_ULONG_PTR pulPolicyIdSize,
>CK_ULONG_PTR pulPolicyValArray,
>CK_ULONG_PTR pulPolicyValSize );
>CK_RV CK_ENTRY CA_GetContainerPolicySetting(
>CK_SLOT_ID uPhysicalSlot,
>CK_ULONG ulContainerNumber,
>CK_ULONG ulPolicyId,
>CK_ULONG_PTR pulPolicyValue);
>CK_RV CK_ENTRY CA_SetHSMPolicy (
>CK_SESSION_HANDLE hSession,
>CK_ULONG ulPolicyId,
>CK_ULONG ulPolicyValue);
>CK_RV CK_ENTRY CA_SetDestructiveHSMPolicy (
>CK_SESSION_HANDLE hSession,
>CK_ULONG ulPolicyId,
>CK_ULONG ulPolicyValue);
>CK_RV CK_ENTRY CA_SetContainerPolicy (
>CK_SESSION_HANDLE hSession,
>CK_ULONG ulContainer,
>CK_ULONG ulPolicyId,
>CK_ULONG ulPolicyValue);
The CA_GetConfigurationElementDescription() Function
The CA_GetConfigurationElementDescription() function requires that you pass in a zero or one value to indicate whether the element you are querying is an HSM Partition (container) element or an HSM element, and another zero/one value to define whether it is a capability or policy that you are interested in. You also pass in the id of the element and a character buffer of at least 60 characters. The function then returns the size of the element value (in bits), an indication of whether the element is destructive, an indication of whether the policy (if it is a policy) is write-restricted, and it also writes the description string into the buffer that you provided.
The CA_Get{HSM|Container}{Capability|Policy}Set() Functions
The various CA_Get{HSM|Container}{Capability|Policy}Set() functions all return (in the word arrays provided) a complete list of element id/value pairs for the set specified. For example, CA_GetHSMCapabilitySet() returns a list of all HSM capability elements and their values. The parameters for these functions include a list pointer and length pointer for each of the element ids and element values. On calling the function, you should provide a buffer or a null pointer for each of the lists, and the length value should be initialized to the size of the buffer. On return, the buffer (if given) is populated, and the length is updated to the real length of the list. If the buffer is given but is not large enough, an error results.
Typically you would invoke the function twice: call the function the first time with null buffer pointers so that the real length necessary is returned, then allocate the necessary buffers and call the function a second time, giving the real buffers.
The various CA_Get{HSM|Container}{Capability|Policy}Setting() functions allow you to query a specific element value. Provide the element id and the function returns the value.
The CA_Set...() Functions
The various CA_Set...() functions allow you to set individual HSM and HSM Partition policies. There are two varieties for setting HSM policies, because changing the value of a destructive HSM policy results in the HSM being cleared of any Partitions and their contents. To make it clear when this is going to happen, the appropriate set function must be called based on whether the HSM policy is destructive or not (which you can determine with the CA_GetConfigurationElementDescription() function).
