Per-Key Authorization API
Design
Changes and additions to the Luna HSM firmware and libraries for the Per Key Authorization (PKA) feature were introduced to implement the feature in compliance with eIDAS standards, and to ensure co-existence of the new feature with existing behavior and use-cases.
The Luna use-case
This use-case covers traditional Luna customers who want the latest firmware and host software, but do not need the new per-key authorization and sole control functionality, and do not want to make changes to their existing applications, and yet want to be able to maintain the HSM in the Common Criteria mode of operations.
Subject to the installation of the new Client Cryptoki library and the use of regular APIs without per-key auth parameters, the existing APIs will continue to work as usual, while the new PKCS#11 APIs, attributes, and roles, related to the per-key authorization and sole-control functionality, are dealt with within the library and remain invisible to the user.
In the Luna use-case, we have
>the Crypto Officer role (CO) for creating/modifying/administering key material in an application partition
>the Crypto User role (CU) with read/use capability
The eIDAS use-case
This use-case covers all the scenarios where client applications need to take advantage of the per-key authorization and sole control (assigned keys) capabilities. It includes all eIDAS scenarios such as remote server signing/sealing with external/internal SAM, local server signing/sealing (no SAM), long-lived signing keys, single-use signing keys, etc.
In the eIDAS use-case,
>the Crypto Officer role (the CO) does much the same as in the Luna use-case, and maps to the eIDAS "Administrator" role
>a new Limited Crypto Officer role (the LCO), in line with the principle of least privilege, and mapping to the eIDAS "User" role, allows signing applications to provide key access to users, thus reserving the CO role for administrative purposes only
The CU role has insufficient capability and is not employed for the eIDAS use case.
Applications need the new firmware, new host software, and use new P11 APIs, attributes, and roles related to the per-key authorization and sole control.
Customer applications and tools explicitly use the new features:
>Applications specify the Authorization Data and Assigned Flag attributes in templates and may later change the attributes via new P11 APIs.
>Applications use new PKCS#11 API to explicitly authorize each individual key before it can be used in crypto operations.
>Applications also deal with the re-authorization logic and the authorization failure handling.
The following sections detail the changes implemented for this feature.
New Assigned Key Attribute
The Protection Profile defines two types of secret keys (PP defines “secret key” as either a symmetric or a private key), assigned and unassigned (general). Assigned keys have tighter controls around them, their security attributes are non-modifiable, and they are also non-exportable. Both key types, however, require per-key authorization.
We support the following use-cases:
>CO (Crypto Officer a.k.a. the eIDAS Administrator) generates the key unassigned, then assigns it later.
>CO (Administrator) generates the key assigned.
>Limited-CO (the eIDAS User) generates the key assigned.
>Limited-CO (User) generates the key unassigned (which might or might not be assigned by the Administrator later).
To differentiate between assigned and unassigned keys, we introduce an attribute, CKA_ASSIGNED. This attribute is initialized and modified through regular templates and commands. CKA_ASSIGNED defaults to FALSE, and as such, it does not need to be present in the templates for the Luna use-case, since we exclusively want to use unassigned keys in that use-case.
Getting Assigned Keys
There are two ways to get assigned keys:
>Direct generation of assigned keys
This is accomplished by generating keys with the CKA_ASSIGNED attribute set to TRUE. The keys must also have the following attributes:
•CKA_EXTRACTABLE set to FALSE.
•CKA_MODIFIABLE set to FALSE.
•CKA_AUTH_DATA set to some authorization data. For more information about this attribute, see New Authorization Data Attribute.
>Assignment of previously created keys
This is accomplished by performing an unassigned-to-assigned transition as the eIDAS Administrator (the CO role) and changing the CKA_ASSIGNED attribute from FALSE to TRUE by using the CA_AssignKey command (see CA_AssignKey). The keys must also have the following attributes:
•CKA_ALWAYS_SENSITIVE set to TRUE.
•CKA_NEVER_EXTRACTABLE set to TRUE.
•CKA_AUTH_DATA set to some authorization data. For more information about this attribute, see New Authorization Data Attribute.
A template for key assignment must have the following attributes:
>CKA_MODIFIABLE set to FALSE.
>CKA_ASSIGNED set to TRUE.
New Authorization Data Attribute
The authorization data is a new sensitive attribute (CKA_AUTH_DATA) on each symmetric/private key object. It is initialized through the regular means of passing in attribute values in templates during key generation. As in other sensitive attributes, it is possible to query the value. It is presented as a byte array password, therefore no multifactor quorum options are possible. This attribute is available in the eIDAS and Luna use-cases (V1 Partitions), but not in the non-PP-compatible legacy use-case (V0).
Unassigned keys use the authorization data simply to verify access rights. The initial authorization data is hashed, along with a random pepper value (stored encrypted in the partition structure with the PSK) and the hash is stored in the key object metadata. Authorization operation involves hashing of the incoming authorization data and comparing the result to the reference one in the key object.
For assigned keys, the use of the authorization data is more complex, and is detailed in the following section.
Initializing the Authorization Data
The auth data is initialized through regular means of passing in the CKA_AUTH_DATA attribute value in templates during key generation, key derivation and key unwrapping.
Modifying the Authorization Data
For authorization data modification, the Protection Profile introduces the following conditions:
>In the case of assigned keys, the auth data can be “modified only when modification operation includes successful validation of current (pre-modification) authorisation data”
>In the case of unassigned keys, the auth data can be “modified only when modification operation includes successful validation of current (pre-modification) authorisation data, that is by anybody who already has that auth data, or by an Administrator”
To this end, the following command modifies the authorization data when in possession of current auth data:
CA_SetAuthorizationData(
CK_SESSION_HANDLE hSession, // the session's handle
CK_OBJECT_HANDLE hObject, // the object's handle
CK_UTF8CHAR_PTR pOldAuthData, // the user's old/current auth data
CK_ULONG ulOldAuthDataLen // the length of the old/current auth data
CK_UTF8CHAR_PTR pNewAuthData, // the user's new auth data
CK_ULONG ulNewAuthDataLen // the length of the new auth data
)
This command will be available to all the roles without explicit requirement to have authorized first with CA_AuthorizeKey(), since the call itself will take in the current authorization data as a parameter.
On assigned keys, this command will decrypt and re-encrypt the KUSK with the new authorization data.
Resetting the Authorization Data
For authorization data modification, the Protection Profile introduces the following conditions:
>In the case of assigned keys, it can be “modified only when modification operation includes successful validation of current (pre-modification) authorisation data”
>In the case of unassigned keys, it can be “modified only when modification operation includes successful validation of current (pre-modification) authorisation data, or by an Administrator”
To this end, the following command at the PKCS#11 API level allows the CO (Administrator) to reset the authorization data on unassigned keys without having to present the current auth data:
CA_ResetAuthorizationData(
CK_SESSION_HANDLE hSession, // the session's handle
CK_OBJECT_HANDLE hObject, // the object's handle
CK_UTF8CHAR_PTR pAuthData, // the user's auth data
CK_ULONG ulAuthDataLen // the length of the auth data
)
This command is available only to the CO role, and only for unassigned keys.
This command also resets the authorization failure count (CKA_FAILED_KEY_AUTH_COUNT) for a locked-out key and unlocks it.
Authorizing/Rescinding Authorization on a Key per Session
To preserve compatibility with the PKCS#11 API, and rather than require the input of per-key authorization data on every single “keyed” operation such as sign, verify, encrypt, decrypt, derive, etc., the following command explicitly authorizes a key (assigned or unassigned) by key handle in a given session. Once authorized, the key remains authorized within that session only (meaning that the authorization is not inherited by the other sessions under that access), until authorization is explicitly rescinded. In line with PP 419 221-5, FIA_UAU.6/KeyAuth Re-authenticating, other re-authorization conditions are not supported (time/count-based, or otherwise).
CA_AuthorizeKey(
CK_SESSION_HANDLE hSession, // the session's handle
CK_OBJECT_HANDLE hObject, // the object's handle
CK_UTF8CHAR_PTR pAuthData, // the user's auth data
CK_ULONG ulAuthDataLen // the length of the auth data
)
The command above can be used only in an already authenticated session for any role, and attempts to authorize the given key. If successful it marks and stores the key's OUID in the session as authorized. Further requests to use that key within that session will simply verify that the key is still marked as authorized, and will proceed with the operation (provided that the key usage attributes are respected) without having to re-authorize.
Only one authorized key at a time is supported per session. The command can be used to overwrite the existing authorization in a session with authorization for a different key.
If the application wants to authorize a second key concurrently, a second session will be required.
The same command will also allow explicit authorization rescinding in that given session alone, if the auth data length is 0 (object handle still must be set to the correct one). Other rescinding methods include but are not limited to:
>Pull the power plug
>Decommission
>Delete the partition
>Close the session
>Logout
>Change auth data on the key (this will revoke any existing authorizations for that key in any sessions/accesses)
>Delete the key
Authorizing/Rescinding Authorization on a Key per Access
Authorization data can be directly put into the access, but only to access unassigned keys.
This is achieved, using the same API call as above, when hObject is set to CK_INVALID_HANDLE.
The provided authorization data is not immediately used as a result of that command, since the command does not specify a key at that point. Instead, the hash of the authorization data is kept in the access and is available to all of the sessions sharing the same access.
The authorization in this case is a two-step process:
1.Authorization data only is sent in
2.A “keyed” command is sent in, and the authorization data stored in the access is validated against the individual key.
If, in a given session, authorization already exists for an individual key at the session level, that is checked first, if the OUID matches the key in the command.
Note that the overall authorization process remains per individual key, and each key is individually authorized for use.
As with the authorization in the previously described session, the same command also allows explicit authorization rescinding if the auth data length is 0 (object handle is set to CK_INVALID_HANDLE). Other rescinding methods include but are not limited to:
>Pull the power plug
>Decommission
>Delete the partition
>Logout
>Change auth data on the key (this will revoke any existing authorizations for that key in any sessions/accesses)
>Delete the key
Per-Key Authorization Failure Handling
Access to keys is blocked after a set amount of authorization failures in accordance with the authentication failure handling requirements of the PP, and the CO role has the ability to unblock blocked keys.
The authorization failure count is stored as an attribute (CKA_FAILED_KEY_AUTH_COUNT) directly in the object. Another new-to-firmware 7.7.0 attribute, CKA_KEY_STATUS, contains the max allowed failed key auth attempt count, along with the current status of the key - locked or not.
Once the max failed attempt count is reached, the key is marked as locked. The CO can then reset the count to 0 (through C_SetAttributeValue()) in the attribute to unblock the access to the key.
Template Handling in the Cryptoki Library
For the Luna use-case (partition is V0 and SKS and PKA are not available), the library masks the artifacts of per-key authorization.
The C_Login() call for CO/CU is overridden to include the additional action:
1.A normal C_Login() call with all the provided parameters, followed by
2.A CA_AuthorizeKey() call with the string “Luna” passed in as authorization data to the access
The following calls that create a secret/private key are overridden, and add a CKA_AUTH_DATA attribute with the value “Luna” is added to the input template:
>C_GenerateKey()
>C_GenerateKeyPair()
>C_UnwrapKey()
>C_DeriveKey()
These modifications in the library, along with the two-step per-key authorization functionality, allow operation through the regular Luna API with no modifications required to existing applications, while still providing the ability to make use of the extended per-key auth API should the customer choose to do so.
V0 vs V1 Partitions
To support legacy client installations, the V0 and V1 partition types were introduced in Luna HSM Firmware 7.7.0 and newer, where
>the V0 partition preserves compatibility with the “legacy” Luna use-case, or keys always in hardware (whether a partition is V0 due to firmware update, or V0 due to default choice at partition creation), while
>the V1 partition supports Per Key Authorization, Scalable Key Storage, and other eIDAS-use-case functions that cannot be compatible with the previous scheme. These are indicated and selected by a new policy: “Partition Version”, which are set to 0 (the state of any pre-existing partitions after upgrade from pre-version-7.7.0 firmware, or the default setting for any newly created partitions) regular, non-legacy partitions will be version 1), and will control both internal legacy functionality (such as old HA login and old STC support), as well as govern toggling of certain other policy bits (such as per-key auth and SKS policies).
V0 partitions are not compliant with the Protection Profile, as the key objects in these partitions do not have authorization data attribute at all. This configuration is intended for customers who cannot upgrade their host-side library.
If a customer decides to move on to a PP compatible library, they can change the partition policy bit to V1. The firmware will assign the default auth data that is in the access to all of the key objects in the partition (please see section Import via V0 to V1 Partition Conversion for further considerations) . If using the:
>Luna use-case, there is nothing further to do, the objects already have the correct auth data assigned to be used
>eIDAS use-case, you can follow-up the conversion operation by a separate call to set the per-key auth data to the desired value.
Cryptoki API
This section highlights the changes at the Cryptoki API level.
CA_AuthorizeKey
CA_AuthorizeKey(
CK_SESSION_HANDLE hSession, // the session's handle
CK_OBJECT_HANDLE hObject, // the object's handle
CK_UTF8CHAR_PTR pAuthData, // the user's auth data
CK_ULONG ulAuthDataLen // the length of the auth data
)
This is a new command, as of firmware 7.7.0, to explicitly authorize a key (assigned or unassigned) by key handle in a given session. It can be used only in an already-authenticated session for any role.
CA_SetAuthorizationData
CA_SetAuthorizationData(
CK_SESSION_HANDLE hSession, // the session's handle
CK_OBJECT_HANDLE hObject, // the object's handle
CK_UTF8CHAR_PTR pOldAuthData, // the user's old/current auth data
CK_ULONG ulOldAuthDataLen // the length of the old/current auth data
CK_UTF8CHAR_PTR pNewAuthData, // the user's new auth data
CK_ULONG ulNewAuthDataLen // the length of the new auth data
)
This command modifies the authorization data for a key, and is available to all the roles without explicit requirement to have been authorized first with CA_AuthorizeKey(), since the call itself takes in the current authorization data as a parameter.
Old (current) auth data is an optional parameter. If not provided, this data is filled in by the library to the “Luna” value to accommodate the case of keys imported through the migration scenarios in section (which will have their auth data set initially from the access, hence “Luna” as well).
This case appears to the end-user as though they are setting the per-key auth of an imported key for the first time.
The following return codes are added, that can be returned by this command:
>CKR_AUTH_DATA_TOO_LARGE
>CKR_AUTH_DATA_TOO_SMALL
CA_ResetAuthorizationData
CA_ResetAuthorizationData(
CK_SESSION_HANDLE hSession, // the session's handle
CK_OBJECT_HANDLE hObject, // the object's handle
CK_UTF8CHAR_PTR pAuthData, // the user's auth data
CK_ULONG ulAuthDataLen // the length of the auth data
)
This command resets the authorization data for a key, and is available to the CO role only, and only for the unassigned keys.
This command also resets the authorization failure count (CKA_FAILED_KEY_AUTH_COUNT) for a locked out key and unlocks it.
Two new return codes can be returned by this command:
>CKR_AUTH_DATA_TOO_LARGE
>CKR_AUTH_DATA_TOO_SMALL
CA_AssignKey
CA_AssignKey(
CK_SESSION_HANDLE hSession, // the session's handle
CK_OBJECT_HANDLE hObject // the object's handle
)
This command flags a key as assigned by setting its CKA_ASSIGNED attribute to 1, and is available to the CO role only, and only for the unassigned keys.
The key has to satisfy the following conditions:
>It must have CKA_AUTH_DATA
>It must have CKA_EXTRACTABLE = false
>It must have CKA_SENSITIVE = true
>It must have CKA_MODIFIABLE = false
These new return codes can be returned by this command:
>CKR_ASSIGNED_KEY_REQUIRES_AUTH_DATA
>CKR_ROLE_CANNOT_MAKE_KEYS_ASSIGNED
>CKR_INVALID_ASSIGNED_ATTRIBUTE_TRANSITION
>CKR_ASSIGNED_KEY_FAILED_ATTRIBUTE_DEPENDENCIES
CA_IncrementFailedAuthCount
CA_IncrementFailedAuthCount(
CK_SESSION_HANDLE hSession, // the session's handle
CK_OBJECT_HANDLE hObject // the object's handle
)
This command increments the CKA_FAILED_KEY_AUTH_COUNT for a key.
It is intended to be used to keep members of an HA group in sync.
CKA_AUTH_DATA
This is a sensitive attribute on each symmetric/private key object, and holds the hashed authorization data. It is initialized through the regular means of passing in attribute values in templates during key generation, derivation, or unwrapping.
It can be modified only through the use of CA_SetAuthorizationData() (section CA_SetAuthorizationData), and CA_ResetAuthorizationData() (section CA_ResetAuthorizationData), and not through the regular C_SetAttributeValue() API, as the the current value of the auth data must be provided at the time of the modification. Having previously authenticated for per-key auth is not enough.
This is akin to the case of a user password modification/reset. Even when the user is logged in, the current password must be re-specified at the time of the password modification, with the exception of the administrator being able to reset the password.
CKA_ASSIGNED
This is an attribute on each symmetric/private key object, and indicates whether the key is an assigned key or a general key. The default value is false. It can be modified from false to true, but not the other way around.
The following are the new error codes that can be returned by an attempt to modify this attribute through C_SetAttribute() command:
>CKR_ASSIGNED_KEY_REQUIRES_AUTH_DATA
>CKR_ROLE_CANNOT_MAKE_KEYS_ASSIGNED
>CKR_INVALID_ASSIGNED_ATTRIBUTE_TRANSITION
>CKR_ASSIGNED_KEY_FAILED_ATTRIBUTE_DEPENDENCIES
CKA_KEY_STATUS
This is an attribute on each symmetric/private key object, and holds the key lock status flags and the failed per-key auth count limit. It is present only along with CKA_AUTH_DATA, otherwise never there, and never allowed.
typedef struct OH_KEY_STATUS_S {
UInt8 flags1;
UInt8 failedAuthLimt;
UInt8 reserved1;
UInt8 reserved2;
} OH_KEY_STATUS;
Flags:
>CK_KEY_STATUS_F_AUTH_DATA_SET
>CK_KEY_STATUS_F_LOCKED_DUE_TO_FAILED_AUTH
>CK_KEY_STATUS_F_LOCKED_DUE_TO_DATE
>CK_KEY_STATUS_F_LOCKED_DUE_TO_DES3_BLOCK_COUNTER
>CK_KEY_STATUS_F_LOCKED_DUE_TO_USAGE_COUNTER
CKA_FAILED_KEY_AUTH_COUNT
This is an attribute on each symmetric/private key object, and holds the number for the failed per-key auth attempts. It will be present only along with CKA_AUTH_DATA, otherwise never there, and never allowed. The CO role can modify this attribute to lock/unlock the key through C_SetAttributeValue(). It is also reset upon auth data resetting by the CO through CA_ResetAuthorizationData().
Library/Tool Considerations
Tool Changes
LunaCM/LunaSH
LunaCM changes are highlighted below, LunaSH gets similar changes.
LunaCM supports an optional flag on partition creation that can be specified to tell the HSM that the partition should be a V0 partition (through partition version) to support Luna use-case and customers with legacy applications using older libraries, or V1 Partition, supporting the eIDAS use-case (SKS, PKA, etc.).
Ckdemo
Ckdemo has added support for CKA_AUTH_DATA and CKA_ASSIGNED attributes in all required commands for:
1.Key generation/derivation/unwrap
2.Attribute setting/modification
New commands are added, to:
>Authorize keys
>Assign general keys
>Set/Reset per-key auth data for general keys
>Increment failed auth count
The following is accomplished through existing commands:
>Query key status (locked/active) – Display Key
>Unlock locked keys – Set Attribute (failed auth count)
High Availability (HA)
Mixed modes, such as the following, are not supported:
>Pre-FW7.7.0 and Luna HSM Firmware 7.7.0 partitions
>V0 and V1 partitions
HA Group Migration
HA group migration from pre-FW7.7.0 will be done in two steps:
1.Updating the group to Luna HSM Firmware 7.7.0 (starting with non-primary members), which results in all partitions being flagged as V0 Partitions.
2.If desired, converting these V0 partitions to V1 partitions that are PP 419-221.5 compliant
To update an HA group to Luna HSM Firmware 7.7.0, all the non-primary partitions must be updated to Luna HSM Firmware 7.7.0 first, to ensure that the key objects from the pre-FW7.7.0 primary can still move to the non-primaries through key cloning. Then the primary can be updated to Luna HSM Firmware 7.7.0. At the conclusion of this step, all of the existing partitions on the upgraded HSMs are flagged as V0 Partition.
In the optional next step to convert these partitions to PP 419-221.5 compliant, V1 partitions, once again, all the non-primary partitions must be converted first, and only then the primary partition can be converted.
Migration Scenarios for Per-Key Auth
All of these migration scenarios imply key objects without per-key auth data being imported into a Luna HSM Firmware 7.7.0 partition that enforces per-key authentication.
To that end, we have to consider all paths from legacy devices such as FW4, FW6, and FW7, as well as legacy partitions on the FW7 that are converted to non-legacy.
There are several migration methods to be considered that are all detailed in the following sections:
1.Cloning
2.Pre-firmware-7.7.0 SKS (a.k.a. SIM)
3.Unwrapping
4.V0 to V1 Partition Conversion
Import via Cloning
When a key object is being imported via cloning from a legacy HSM/partition, the flattened object attributes within the incoming blob will not have a CKA_AUTH_DATA attribute present. Instead, the f/w will initialize the CKA_AUTH_DATA of the imported object to the value from the access.
>In the Luna use-case where the per-key auth is not visible to the end user, this is all that is needed.
>In the eIDAS use-case, the import via cloning should be followed by an explicit call to CA_SetAuthorizationData() to reset the per-key auth of the imported object to the desired value. Please note that imported keys cannot be assigned until their per-key auth is set.
Import via Legacy SKS
When a key object is being imported via legacy SKS from a legacy HSM/partition, the flattened object attributes within the incoming blob do not have a CKA_AUTH_DATA attribute present. Instead, the firmware initializes the CKA_AUTH_DATA of the imported object to the value from the access.
>In the Luna use-case where the per-key auth is not visible to the end user, this is all that is needed.
>In the eIDAS use-case, the import via legacy SKS should be followed by an explicit call to CA_SetAuthorizationData() to reset the per-key auth of the imported object to the desired value. Please note that imported keys cannot be assigned until their per-key auth is set.
Import via Unwrapping
When a key object is being imported via unwrapping, the unwrap template will have a CKA_AUTH_DATA attribute present:
>In the eIDAS use-case, the users will set the CKA_AUTH_DATA in the template explicitly.
>In the Luna use-case, the library fills the CKA_AUTH_DATA in the template (please refer to section Template Handling in the Cryptoki Library).
Import via V0 to V1 Partition Conversion
Existing keys will not have auth-data. Consider partition conversion as import (from outside into an eIDAS compliant environment), allowing for the setting of initial per-key auth values by the Administrator.
When the PSO or the PCO flip the partition version bit to convert the V0 partition to V1, the access auth-data (which was set upon login) is applied to all objects. The setting of this per-key auth is tracked (in case it was interrupted by a power failure or otherwise h/w reset), and the partition is mostly unusable until all the objects in the partition have been successfully converted.
Only in the eIDAS use-case ( unlikely, as V0 or pre-firmware 7.7.0 devices/partitions would not have been involved in an eIDAS scenario), the conversion of the partition should be followed by an explicit call to CA_SetAuthorizationData() to reset the per-key auth of each key to the desired value. Please note that the keys on the converted partition cannot be assigned until their per-key auth is set.
Summary of New PKA Commands and Capabilities
This following table lists all of the new commands, HSM policies and APIs that are added by Luna HSM Firmware 7.7.0. It also provides a cross-reference to the section of the document with more details for the new item.
| New Item | Description | Cross-reference |
|---|---|---|
|
partition create -version |
LunaCM command enhancement |
|
|
CKA_AUTH_DATA |
New object attribute |
|
|
CKA_ASSIGNED |
New object attribute |
|
|
CKA_KEY_STATUS |
New object attribute |
|
|
CKA_FAILED_KEY_AUTH_COUNT |
New object attribute |
|
|
CA_AuthorizeKey( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_UTF8CHAR_PTR pAuthData, CK_ULONG ulAuthDataLen ) |
New Cryptoki API |
|
|
CA_SetAuthorizationData( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_UTF8CHAR_PTR pOldAuthData, CK_ULONG ulOldAuthDataLen CK_UTF8CHAR_PTR pNewAuthData, CK_ULONG ulNewAuthDataLen ) |
New Cryptoki API |
|
|
CA_ResetAuthorizationData( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_UTF8CHAR_PTR pAuthData, CK_ULONG ulAuthDataLen ) |
New Cryptoki API |
|
|
CA_AssignKey( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject |
New Cryptoki API |
|
|
CA_IncrementFailedAuthCOunt( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject ) |
New Cryptoki API |
|
|
CKR_ASSIGNED_KEY_REQUIRES_AUTH_DATA |
New return code |
|
|
CKR_ROLE_CANNOT_MAKE_KEYS_ASSIGNED |
New return code |
|
|
CKR_INVALID_ASSIGNED_ATTRIBUTE_TRANSITION |
New return code |
|
|
CKR_ASSIGNED_KEY_FAILED_ATTRIBUTE_DEPENDENCIES |
New return code |
|
|
CKR_AUTH_DATA_TOO_LARGE |
New return code |
|
|
CKR_AUTH_DATA_TOO_SMALL |
New return code |
|
|
CK_KEY_STATUS_F_AUTH_DATA_SET |
New flag |
|
|
CK_KEY_STATUS_F_LOCKED_DUE_TO_FAILED_AUTH |
New flag |
|
|
CK_KEY_STATUS_F_LOCKED_DUE_TO_DATE |
New flag |
|
|
CK_KEY_STATUS_F_LOCKED_DUE_TO_DES3_BLOCK_COUNTER |
New flag |
|
|
CK_KEY_STATUS_F_LOCKED_DUE_TO_USAGE_COUNTER |
New flag |
V0 PARTITIONS
Version zero (V0) partitions are designed to support older clients. They can be created in two ways: through firmware update (all existing partitions will be marked as legacy) and directly during partition creation. They will be marked with a new policy: “Partition Version”, which will be set to 0. The regular, non-legacy partitions will be version 1.
Firmware Update
1.During firmware update from a pre-7.7.0 version, existing partitions are always converted to V0 partitions
2.Zeroizes old STC keys as Luna HSM Firmware 7.7.0 (and newer) will not support it at all.
3.Partition v0 to v1 transition is non-destructive (both across firmware update and through normal toggling):
Existing keys will not have auth-data. The first time the CO logs in, the access auth-data is set and can be applied to all objects. A partition on an HSM updated to firmware version 7.7.0 (or newer) becomes usable when a one-time CO login is performed.
The firmware update process, in this case, is considered equivalent to “import” because the existing keys are being imported in to the ecosystem of the new firmware.
For purposes of STC: to avoid breaking the clients’ access to the partition, old STC must be disabled before firmware update, then, post-update a partition updated to V0 allows new STC setup. So the appropriate order would be to update the client first, then setup new STC, then set the partition version to V1 if desired.
Neither V0 nor V1 partitions will support old STC
Partition Creation
1.An optional flag can be specified to tell the HSM that the partition should be Partition Version v0 (supported by LUSH and LunaCM)
Normally, in the case of legacy client support, we’re talking about appliance, and partitions are created through Lush, which will be updated anyway.
2.Old clients (or old client apps + new client library) are unable to provide this, so partitions created with the old client will be v1.
As mentioned above, this should only apply to PCI case, and we don’t have to support legacy client installations there.
3.If a partition is pre-created, and it is later determined that a partition version v0 is required, HSM SO has to delete the partition and re-create a partition v0
4.Identified by “Partition Version policy”.
a.Partition Version 0 == new default or pre-existing upgraded to Luna HSM Firmware 7.7.0 (or newer), Partition Version 1 == eIDAS (SKS and PKA)
b.Policy is always destructive for V1 to V0 transition (eIDAS use-case to Luna use-case), and cannot be changed by customer via PPT (Partition Policy Template)
c.V0 to V1 (Luna use-case to eIDAS use-case), non-destructive by default, can be set to be destructive.
5.Other default partition policy settings that are forced on the legacy partition (either directly upon creation or through firmware update)
a.SKS capability/policy = 1/0 (even in the case of insertion, since pre-firmware-7.7.0 does not have any SKS support)
b.Cloning capability/policy = 1/1
c.Per-key-auth capability/policy = 1/0
d.If CKE (cloning-key-export), then remains as CKE with same SIM/Cloning settings as above.
6.For V0 partition:
a.Does not allow partition policy changes that would require new clients
i.Cannot turn SKS On (both masking and unmasking private/secret keys)
ii.Cannot turn Per-key-auth On
b.Allows user objects to be cloned off using CPV3
c.HA Login
i.v1.1 is supported on Secondary HSM
ii.v1.0 is not supported on Secondary HSM
iii.v1.0, v1.1 and v2.0 are all always supported on Primary HSMs
7.For V1 partition:
a.Per-key-auth is turned On by default, but can be turned Off for performance
b.Does not allow user objects to be cloned off
c.HA Login
i.v1.1 is not supported on Secondary HSM
ii.v1.0 is not supported on Secondary HSM
iii.Only v2.0 is supported on Secondary HSM
iv.v1.0, v1.1 and v2.0 are all always supported on Primary HSMs
Converting from V0 to V1 (changing the policy)
1.Non-destructive to the partition by default (can be changed)
2.Leaves Cloning On (but V1 does not allow cloning out, only in for migration)
3.Turn SKS On
4.Turn Per-key-auth On
Converting from V1 to V0 (changing the policy)
1.Destructive to the partition (and can’t be changed)
a.Zeroize everything except for STC keys: SMKs, etc.
2.Turn SKS Off
3.Turn Per-key-auth Off
G5 Backup HSM and Cloning Protocol
1.V0 and V1 partitions are not distinguishable, they all have CPV3 and same migration rules.
2.When cloning out of CPV3 HSM, new things like DES3 usage counters are included
i. FW7.7.0 brings updated features for FIPS compliance, so adjustment is needed to allow their backup -- FW7.7.0 update for G5 Backup HSM allows those counters to be stored in its header
3.Support for creating backup partitions with old client during partition archive command
a.Backup partitions default to a “set on first use” value for CPVx and FM-enabled
b.Then when used, (for example, CloneAsTargetInit) the CPVx (cloning protocol version) and FM-enabled values are set
c.All backup partitions are created in this way (as “set on first use”). Partition attributes are visible in LunaCM.
4.Some new things like new key types (ed25519 etc) cannot be added to Luna Backup HSM G5. That still requires moving to blob-based-backup; consider Luna Backup HSM 7.
eIDAS partitions
1.New partitions can be V1 by selecting the option at partition creation time.
2.SKS is ON
3.Per-key-auth is ON
4.No key cloning (outbound)
a.When high level CA_CloneObject() call is issued, the client library chooses cloning or SKS based on what is available at the source and target HSMs,
5.For full backward compatibility for old client applications that use the step-by-step cloning APIs, the solution is to employ cloning CPV3 APIs in the firmware to achieve key transport over SKS blobs:
a.CloneAsTargetInit always performs the regular TargetInit operation, because it does not know
i.if the source is V0 or not, or
ii.if the requested operation is a command to clone the SMK, or
iii.if the requested operation is will be an SKS extract/insert that needs to pose as cloning
iv.this adds overhead for one part of the cloning exchange, an RSA operation, which can slow applications that don’t use new SKS APIs.
b.CloneAsTarget, from V1 to V1
i.This can receive SKS blob (for key objects) or cloning blob (only for SMK)
ii.Both blobs start with SIM: [length|SIM-MECH|SMK ID], cloning: [length|legacy bit + cloning version|zSizeField]
iii.New mechanism values are used to prevent collision with cloning version
Limited Crypto Officer (LCO) role
As the name suggests, this role is between the CO and CU. It is a subset of the CO role – that is, everything LCO can do, CO can do as well but not the other way around. The relationship between LCO and CU is somewhat more complicated. For the most part, LCO is a superset of CU; however, there are some nuances with cloning – LCO does not support cloning in any way, shape, or form while CU can clone public objects. This is why
•the CO role is common both for the traditional use-cases of the Luna HSM and for the eIDAS use-case
•the CU role is retained for traditional Luna use-cases without a real place in the eIDAS use-case (which uses SKS in place of cloning)
•the LCO role is suited to the eIDAS use-case
Below are the details:
1.LCO is created by CO.
2.LCO supports password authentication and multifactor quorum authentication. For multifactor quorum authentication:
a.A new iKey can be separate from CO and CU keys;
b.MofN is supported.
3.LCO is supported by HA_Login for primary and secondary nodes.
4.CO can reset LCO’s primary credentials (password or iKey), for example lunacm role resetpw
a.This can be done regardless of the Enable SO reset of a partition PIN HSM policy 15 (contrast this to PSO resetting CO’s primary credentials).
5.CO can create LCO’s challenge (multifactor quorum authentication)
a.LCO is subject to activation (partition policy 22);
b.LCO can be deactivated (e.g., lunacm role deactivate) by any role or even w/o a session.
6.CO can reset LCO’s challenge (multifactor quorum authentication) e.g. lunacm role createChallenge
a.This can be done regardless of the Enable SO reset of a partition PIN HSM policy 15 (contrast this to PSO resetting CO’s challenge).
7.LCO, and only LCO, can change its own primary and/or secondary credentials (password or iKey and/or challenge secret); for example role changepw.
8.LCO is subject to the Enable forcing user PIN change HSM policy 21 with respect to either primary or secondary credentials (password or iKey and/or challenge secret).
9.LCO is subject to failed logins logic:
a.The Max failed user logins allowed partition policy 20;
b.Upon reaching the limit, LCO locks out; CO and CU remain operational;
c.The Partition CO can unlock the Partition Limited Crypto Officer role by resetting its credentials;
d.The Max failed challenge responses >partition policy 15;
e.HA_Login is governed by the same logic (for primary credentials; that is, challenge excluding).
10.LCO is subject to the following partition policies:
a.Minimum PIN length (25),
b.Maximum PIN length (26).
11.Pre-firmware 7.7.0 partitions or V0 partitions:
a.Luna HSM Client 10.2.0 or older: LCO role is not exposed (not visible through any tools).
b.Luna HSM Client 10.3.0 or newer: LCO role is visible but any login attempt will always fail.
12.LCO can generate keys (assigned or unassigned)
a.LCO cannot assign keys (but can generate them assigned).
13.LCO can delete keys:
a.Unlike CO, LCO has to provide per-key authorization data,
b.LCO needs to be able to delete keys to support the “single-use signing keys” scenario where a user generates a key, signs with that key, and deletes the key.
14.LCO can create and destroy private objects.
15.LCO can copy keys
a.Like CO, LCO has to provide per-key authorization data
16.LCO can copy private objects
17.LCO can modify keys
a.Like CO, LCO has to provide per-key authorization data for unassigned keys.
18.LCO can modify private objects.
19.LCO has the same rules with respect to Usage Counters as CU
a.Can increment the counter but, unlike CO, cannot change/set the limit.
20.LCO can generate domain parameters
21.LCO can authorize PKA keys
a.Same as CO, CU, SO, and AD.
22.LCO can set a new per-key authorization data (the old one must be provided)
a.Same as CO, CU, SO, and AD.
23.Unlike SO and CO, LCO cannot reset (i.e. w/o providing the old auth data) the per-key authorization data
a.SO and CO can do it for unassigned keys. Nobody can for assigned.
24.Unlike SO and CO, LCO cannot unblock blocked (due to per-key auth failures) PKA keys.
25.LCO can wrap/unwrap:
a.PKA behaviour for wrap: has to provide the per-key auth data for both the wrapping and the wrapped keys.
b.PKA behaviour for unwrap: has to provide the per-key auth data for unwrapping key and specify the per-key auth data for the unwrapped key in the template.
c.For the unwrapped key, if auth data is not in the template, the library will insert the access level auth data.
26.LCO can derive keys:
a.PKA behaviour: has to provide the per-key auth data for the key used for derivation and specify the per-key auth data for the key being derived in the template.
b.For the derived key, if auth data is not in the template, the library will insert the access level auth data.
27.LCO can derive-and-wrap
a.PKA behaviour: as per the wrap/unwrap and derive points above.
28.LCO can SIM extract/insert in all scenarios:
a.Including SKS key migration (old SKS: SIM Insert; no SIM Extract),
b.Including new SKS (SIM Extract and SIM Insert).
29.LCO cannot clone/replicate in any scenario:
a.CPV1 user key migration – no.
b.CPV3 user key migration from legacy partitions – no.
c.SMK (SKS secret) cloning (including G5 backup/restore) – no.
i.Among other things, this means that LCO is not self-sufficient to perform HA – CO is required to clone SMK(s).
d.Note that CU can do some limited cloning but LCO cannot.
30.Unlike CO, LCO cannot perform SMK rollover.
