User's Guide: Fortanix Data Security Manager Key Lifecycle Management

Last Updated: May 15, 2023 06:24

FORTANIX DATA SECURITY MANAGER KEY LIFECYCLE MANAGEMENT USER GUIDE.pdf
(800 KB)

1.0 Security Object Lifecycle Management

Security objects (SO) in Fortanix Data Security Manager (DSM) follow a lifecycle that is composed of a set of states in which the object can be in. During the object's existence, the SO transitions from one state to another, according to policies or events set by the user.

1.1 Security Object Types

An SO can either be imported or generated in the Fortanix DSM UI.

1.1.1 Import Security Objects

To import a security object:

In the Fortanix DSM UI, click the Security Objects tab and click the button to add a new security object.
Enter a name for the security object and assign it to an existing group or create a new group. Refer to the Fortanix DSM Getting Started guide to learn how to create a new group.
Click IMPORT to import a security object. To import a security object from a component, refer to the article Key Components.
Choose a type of key to import.
- All valid DSA key sizes are allowed during import.
- The "SECRET" object can be used to store and export keys of any format. For easy identification, you can set any string to Attribute field while importing (optional). This field will be stored as an x-format custom attribute on a secret object and will be shown in the Info field when viewing the secret.
  You can also add these values from the detail view of a key in the ATTRIBUTES/TAGS tab.
- BIP32 is a parent key inside a Bitcoin hierarchical deterministic wallet (HD Wallet). This key can be used to recover all keys beneath it in the tree, for example: it can be used to sign transaction hashes and derive hardened and non-hardened children.
  The supported import/export formats are Base64 or Hex.
  The supported parameters are Curve: secp256k1, Path: m/0'/42/6147', Network: Mainnet or Testnet.
  The supported key operations are:
  - DERIVEKEY: Accepts an index input and creates a hardened child.
  - EXPORT: Allows to export the secret key in BIP32 format.
  - SIGN: Signs a transaction.
  - VERIFY: Verifies a transaction.
  - APPMANAGEABLE: Allows the key to be managed by a crypto application.
  - TRANSFORM: Accepts an index input and creates a non-hardened child.
  After the BIP32 key is imported, you can derive a hardened or non-hardened child using DERIVE CHILD KEY option. It expects the following inputs:
  - Index: A 32-bit integer.
  - Use the Hardened child option to create a hardened child key. If this option is not selected, it will create a non-hardened child key.
  NOTE
  - For a non-hardened child key, the Index value must be between 0 to 2^31-1 (2147483647).
  - For a hardened child key, the Index value must be 2^31 to 2^32-1 (2147483648 to 4294967295).
  - If the non-hardened child keys are leaked, then even the parent key will be leaked.
  - The BIP32 key can only be imported in Fortanix DSM. It cannot be generated. To generate a BIP32 key, use an HMAC seed and derive the BIP32 key using the Fortanix REST API.
  WARNING
  
  Before downgrading Fortanix DSM from 4.10 to any version <=4.9, remove all the BIP32 keys from the Security Objects table to avoid panic on the Security Objects page after the downgrade.
- BLS: Boneh–Lynn–Shacham is a cryptographic (digital) signature scheme allowing a user to verify that a signature over data is valid, with signature aggregation. Depending on the variant, the format of the private key used by Fortanix DSM is a big-endian secret scalar (32 bytes), followed by the serialized public key (uncompressed elliptic curve point of 97 or 192 bytes).
  The supported import key formats are Base64 or Hex.
  You can also upload a key file using the Upload a File option.
- Additionally, keys of type Korean Cryptography developed are supported in Fortanix DSM.
  - ARIA also developed by KISA, is a cipher with 128-bit data blocks and with key sizes of 128, 192, or 256 bits. The supported cipher modes of operations are ECB, CBC, CBCNOPAD, CFB, CTR, GCM, and CCM.
  - KCDSA (Korean Certificate-based Digital Signature Algorithm) is a digital signature algorithm similar to DSA and additionally involves a hash algorithm used for signature verification. It offers key sizes between 512 and 2048 bits. Imported keys can use any parameters. Key generation will use the following parameters: 2048/224/SHA224 and 2048/256/SHA256 generated by KISA.
  - EC-KCDSA is the Elliptic Curve variant of KCDSA. It is also a digital signature algorithm similar to ECDSA and involves a hash algorithm used for signature verification. It supports the use of NIST curves and SHA algorithms (for more details, refer to Algorithm Support).
  - SEED is a cipher developed by the Korea Internet and Security Agency (KISA), offering 128-bit block sizes and 128-bit key sizes. The supported modes of operation are ECB, CBC, CBCNOPAD, and CTR.
Sometimes, keys of type AES, DES, DES3, DSA, or HMAC imported from a file are already wrapped (encrypted) by a key from Fortanix DSM. This is done so the key will not go over the TLS in plain text format. In such scenarios, select the check box The key has been encrypted.
To import an encrypted key in a file or as a blob provide the following details:
1. Select the corresponding Key Encryption Key that was previously used to encrypt your target key. The selection will be used to unwrap (decrypt) the encrypted key in the file and will later be stored securely in Fortanix DSM. This key should have already been created or imported in Fortanix DSM.
2. Cipher Mode: Select the cipher mode of encryption that should be applied to the key material.
  There are three types of encryption cipher modes to choose from:
  1. ECB: In this method, plain text is divided into blocks of size 64bits each. Each such block is encrypted independently of other blocks. For all blocks, the same key is used for encryption.
  2. KW: This method uses symmetric encryption to encapsulate key material.
  3. KWP: In this method, additional padding of bits or bytes is appended to the encapsulated key material.
  NOTE
  
  A cipher mode of operation may not be available for selection based on the source and selected wrapping key combination.
Key Check Value: The KCV of the imported key is optionally added by the admin while creating the import request.
Click UPLOAD A FILE to upload the key file in Raw, Base64, or Hex format.

NOTE

For Secret security objects, you can additionally upload the key file in Text (UTF-8) format.
Select the permitted key operations. For more information on key operations, refer to Key Operations.
To add Custom Attributes, click the ADD ATTRIBUTE button. Custom attributes are user-defined attributes of security object that can be added to the key’s metadata.
Add Activation Date: The activation date of the security object can be set to a specified time in the future or activated immediately. On activation, the object goes into the "Activated" state. For more information on security object activation date, refer to Section: Activating a Security Object in Pre-Active State.
Add Deactivation Date: The deactivation date of the security object can be set to a specified time in the future, or you can expire an object immediately. For more information on security object deactivation date refer to Section: Deactivating a Security Object in Pre-Active or Active State.

NOTE

If a group-level Key metadata policy is set, you can configure certain restrictions on “metadata” associated with security objects. Here "metadata" refers to certain features of security objects that are not covered by cryptographic policies, for example, custom metadata, description, expiry, and so on. For more information about key metadata policy, refer to User's Guide: Key Metadata Policy.
To store audit logs for the object in the group, enable the toggle for Keep detailed log for the object. The initial state of the toggle is based on the parent Crypto policy if any.
Click IMPORT and the key is successfully imported.
Fortanix DSM also provides an ability to view SOs of type “secret” in the UI. This enables Fortanix DSM to be used as a secret store. To view the secret object:
1. Go to the detailed view of a “secret” object that was imported.
2. In the INFO tab, click the SHOW icon to show the value of the secret object.
3. The “secret” Object Value will be displayed.
  
  NOTE
  
  If a quorum policy is set in the group to which the “secret” object belongs, then the object value will not be displayed in the UI and an approval request is created when you click SHOW VALUE to view the secret.

1.1.2 Generate Security Objects

To generate a security object:

In the Fortanix DSM UI, click the Security Objects tab and click the button to add a new security object.
Enter a name for the security object and assign it to an existing group or create a new group. Refer to the Fortanix DSM Getting Started guide to learn how to create a new group.
Click GENERATE to generate a security object.
Choose a type of key to generate the key. For more information on the key types, refer to the previous section.

Additionally, the following keys are supported in Fortanix DSM.
- LMS: LMS is a hash-based digital signature algorithm. It manages the cryptographic keys within a cryptosystem. It deals with generating, exchanging, storing, using, and replacing keys as and when required at the user level. For more information, refer to RFC 8554
  - L1 Tree height: This indicates the height of the top-level tree.
  - L2 Tree height: This indicates the height of the secondary level tree.
  To know more about the Fortanix implementation of LMS keys, refer to LMS Keys - FAQs.
  
  NOTE
  
  Ensure that the sum of the L1 tree height and L2 tree height must not exceed 20.
- DSA: The Subgroup Size is the size of the parameter in ‘q’ bits, where ‘q’ is the parameter used in the generation of the DSA security object.
- BLS: Boneh–Lynn–Shacham is a cryptographic (digital) signature scheme allows a user to verify that a signature over data is valid, with signature aggregation.
  Fortanix DSM supports the following two variants:
  - Minimal signature size: Public keys are raw serialized points of G₂ (192 bytes), signatures are raw serialized points of G₁ (97 bytes - SEC1 sec. C.4).
  - Minimal public key size: Public keys are raw serialized points of G₁ (97 bytes), signatures are raw serialized points of G₂ (192 bytes).
  The format of the private keys used by Fortanix DSM are serialized as the big-endian secret scalar (32 bytes), followed by the serialized public key (97 or 192 bytes depending on the variant).
- is a cryptographic (digital) signature scheme allows a user to verify that a signature over data is valid, with signature aggregation.
- is a cryptographic (digital) signature scheme allows a user to verify that a signature over data is valid, with signature aggregation.
Select the permitted key operations.
Add custom attributes by clicking the ADD ATTRIBUTE.
By default, the security object is set to be activated immediately. To specify activation date to a future time period, click EDIT.
By default, the deactivation date of the security object is set to ‘Never’. To specify the deactivation date to a future time period, click EDIT.

NOTE

If a group-level Key metadata policy is set, you can configure certain restrictions on "metadata" associated with security objects. Here "metadata" refers to certain features of security objects that are not covered by cryptographic policies, for example, custom metadata, description, expiry, and so on. For more information about Key metadata policy, refer to User's Guide: Key Metadata Policy.
To store audit logs for the object in the group, enable the toggle for Keep detailed log for the object. The initial state of the toggle is based on the parent Crypto policy if any.
Click GENERATE to generate the key. Afterwards, the key is successfully generated

1.2 Security Object Operations

The SO operations can be classified into the following two groups:

Process Operations: Verify, Decrypt, UnwrapKey, MacVerify
Protect Operations: Sign, Encrypt, Wrapkey, Derivekey, MacGenerate, AgreeKey

NOTE

The set of allowed operations that a SO can perform will depend on the initial SO operations set by the user at creation time and the current state in which the SO is at.

1.3 Security Object States Descriptions

Pre-active: When the "activation_date" field of a SO is set to a future date, then the SO’s initial state will be "PreActive" state. When a SO is in "PreActive" state, no cryptographic operation can be performed with the SO.
“Pre-active” to “active” transition: When the SO reaches the "activation_date", it will automatically transition to "Active" state. Note that once the SO is active it cannot transition back to "PreActive" state.
SOs created using the Fortanix DSM GUI will set the "activation_date" to the current server time so they will automatically be initialized in "Active" state.
Active: When a SO is in "Active" state it can be used for all processes and perform cryptographic operations set by the user.
Enabled / Disabled sub-states: While an SO is in "Active" state, the user can "Enable/Disable" the SO. When the SO is in "Enabled" state, it can perform all the cryptographic operations set by the user. When the SO is in "Disabled" state the SO cannot perform any cryptographic operation.
The transition between "Enabled" and "Disabled" states is reversible. For any SO, a user can make the transition between these states an arbitrary number of times. This operation can be performed by updating the "Enabled" field of the SO to "true" (Enabled) or "false" (Disabled).
Active to deactivated transition: A security object transitions from "Active" to "Deactivated" state for the following reasons:
- When the "deactivation_date" is reached, the SO will automatically transition to “Deactivated” state. Note that once the SO is deactivated it cannot transition back to "Active" state.
- The client calls the Revoke API (see the Fortanix Data Security Manager API reference) for the SO. If the Revoke API is called, the server will automatically set the "deactivation_date" to the current server time and the SO will transition to "Deactivated" state. The Revoke operation may also be executed from the Fortanix DSM UI.

When a security object transitions to the "Deactivated" state it will also be set to "Disabled" sub-state. A user may change the SO sub-state to "Enabled". (See the "Deactivated" section).

Deactivated: When an SO is in Deactivated state, it can perform certain cryptographic operations depending on its "Enabled/Disabled" sub-state:
- Enabled: The SO can perform “Process Operations” only.
- Disabled: The SO cannot perform any cryptographic operation.
Compromised transition: A security object transitions to "Compromised" state when the client calls the Revoke API for the SO and the "reason" field in the request body is set to "COMPROMISED" (see Fortanix Data Security Manager API reference). The client can optionally set a date for the “compromised date” and if it is not provided, the server will set the time to the time when the request is received. Additionally, a user may provide a “revocation reason” string for audit purposes.
An SO can directly transition to "Compromised" state from any other state. The "Compromised" state is final and cannot transition to any other state.

To mark a security object as “Compromised” from the Fortanix DSM GUI:
1. Go to the detailed view of the security object, and in the INFO tab scroll to the bottom and click the DEACTIVATE NOW button.
Compromised: When an SO is in "Compromised" state it can perform certain cryptographic operations depending on its "Enabled/Disabled" sub-state:
- Enabled: The SO can perform “Process Operations” only.
- Disabled: The SO cannot perform any cryptographic operation.

The transition between "Enabled" and "Disabled" states is reversible. For any SO, a user can make the transition between these states an arbitrary number of times. This operation can be performed by updating the "enabled" field of the SO to "true" (Enabled) or "false" (Disabled).

1.4 Security Object Activation Date

When a SO is created, its initial state can be either: "PreActive" or "Active" depending on the value of the "activation_date" field provided in the SO creation request. The possible cases are:

"activation_date" is not provided: The activation date will be set by the server to the current time. The initial state of the SO will be "Active".
"activation_date" is provided: The activation date will be set to the one provided by the user. If the "activation_date" is in the future, the SO’s initial state will be "PreActive" while if it is in the past the initial state will be "Active".

NOTE

After the SO is created, the "activation_date" of the SO can be modified as long as the SO is still in "PreActive" state. Once the SO transitions to "Active" state the "activation_date" can no longer be modified.

1.5 Security Object Deactivation Date

A SO also contains a "deactivation_date" field that determines when the SO will transition from "Active" to "Deactivated" state. If:

The "deactivation_date" field is not set, the SO will remain in "Active" state.
The "deactivation_date" field is set, the SO will transition to “Deactivated” state upon that date.

An SO may also transition to "Deactivated" state for other type of events explained in sub-section “Active to Deactivated Transition” state under the section “Security Objects State Descriptions”.

NOTE

The "deactivation_date" field can be modified by updating this field as long as the SO is still in "Active" or "PreActive" state. The server will reject any date that is before the "activation_date". If the client sets the "deactivation_date" to a time in the past the SO will transition to "Deactivated" state.

1.6 Enabling a Deactivated Key

A deactivated key is disabled by default. You can enable a deactivated key by setting the "mark_key_disable_when_deactivated" to false as shown below:

#if the user sets the value as ‘true’, then the key will be disabled after deactivation.
  
"mark_key_disable_when_deactivated": true
  
#if the user set the value as 'false', then the key is enabled after deactivation.
  
"mark_key_disable_when_deactivated": false

The following is the sample PATCH API request:

curl -X PATCH -H "Authorization: Bearer 60_Y3sjMP9s8__nnCDKI4G8K395Nlfgtb0pLUkL50H2yFauTk5WgrN25jMgAUNfNdVzLwfVtEn_xd9qzYHeWEA" -H "Content-Type:application/json" -d '{"mark_key_disable_when_deactivated":false}' -k 'https://<cluster_ip>/api/sys/v1/accounts/dcd6fd3a-125c-46b2-946d-f9063caad5f6'

Where, the <cluster_IP> is the IP address of the cluster.

Response:

{
 "acct_id": "dcd6fd3a-125c-46b2-946d-f9063caad5f6",
 "auth_config": {
  "password": {
   "require_2fa": false,
   "administrators_only": false
}
},
  "created_at": "20230321T200950Z",
  "enabled": true,
  "logging_configs": {

},
 "mark_key_disable_when_deactivated": false,
 "max_operation": 10000,
 "name": "Navendu",
 "state": "PendingConfirmation",
 "subscription": {
 "trial": {
 "expires_at": null
}
}

1.7 Key Attributes/Tags

Every security object has attributes such as PKCS #11, CNG, and Custom attributes.

PKCS #11 and CNG attributes – These are standard attributes as for their corresponding specifications. For details see the PKCS #11/CNG specification. The SO attribute values are mapped to the corresponding name in PKCS #11/CNG.
Custom attributes – These are user-defined SO attributes that can be added to the key’s metadata.

1.8 Key Rotation

A security object can be rotated using the Fortanix DSM Key Rotation feature. A Key is rotated when you want to retire an encryption key and replace that old key by generating a new cryptographic key. Based on the business requirements, a key can be rotated at any time.

Fortanix DSM allows you to rotate the key in either of the following ways:

1.8.1 Generate New Key

Perform the following steps to rotate the key when the Generate New Key option is selected:

In the Fortanix DSM UI, go to the detailed view of a security object.
Under the name of the security object, click the ROTATE KEY link.
To deactivate the original key after the key is rotated, select the Deactivate original key after the rotation check box so that the old key will only be able to perform operations such as decrypt/verify/unwrap/mac verify. This can also be set in the “Key rotation policy”. Refer to Section 1.7.3 for more details.
NOTE
- The Deactivate original key after the rotation check box is not applicable when you are rotating keys of type “Secret”.
- This check box is disabled If the key belongs to a group with a quorum policy.
Select the Generate new key option.

To rotate an existing key of type “Secret” and keep a history of all previous versions of the same secret:
1. In the KEY ROTATION window, enter a new object value for the secret in Text (UTF-8), Raw, Base64, or Hex format. This step is mandatory.
To set the deactivation date of the newly rotated key to a future date, click EDIT.
Click ROTATE KEY in the Key Rotation window to confirm the key rotation.
If the key belongs to a group with a quorum policy, the key rotation will require quorum approval. Also, if any of the linked keys is a part of a group with a quorum policy, instead of directly rotating the key, a quorum approval request will be generated when you click on ROTATE KEY.
The key will be successfully rotated. The new key/secret will carry over the same name as the old key/secret whereas the old key/secret will be renamed with the timestamp of key rotation. A new key with a different UUID will be added to the Security Objects table. The old keys/secrets will also show under the KEY LINKS tab in the detailed view of the new rotated key/secret.
Notice the new UUID of the rotated key.
NOTE
- If the cluster is unhealthy when the key is rotated, then the key rotation job will be retried every 10 mins until the rotation is successful.
- For the rotation of secret keys, the key permissions are not editable.

1.8.2 Rotate to an Existing Key

Prerequisites for rotating an old DSM key to a new DSM key:

The key type, size, and permissions of both keys must be identical for the rotation to happen.
Both the keys involved in the rotation must belong to the same group.
Both the keys involved in the rotation must have the same padding or signature policy, key rotation policy, and key access justification policy.

Perform the following steps to rotate an old DSM key to a new DSM key when the Rotate to an existing key option is selected:

In the Fortanix DSM UI, go to the detailed view of a security object.
Under the name of the security object, click the ROTATE KEY link.
Select Rotate to existing key option.
Select the existing key that you want to rotate it with from the Select existing key drop down menu.
When you rotate an old DSM key (Key A) to a new DSM key (Key B).
- The new DSM key (Key B) will get the original name (that is, Key A), and the old DSM key (Key A) will be renamed automatically with the timestamp of key rotation.
- The UUID of the new DSM key will remain the same as before (that is, the same UUID of Key B as before).
- The key material of the new DSM key will remain the same as before (that is, the same key material of Key B as before).
- The new DSM key will link to the old DSM key so that the old DSM key can still be used for decryption operations.
- The old DSM key can be deleted, disabled, or deactivated after successful rotation.
- The Deactivate original key after rotation check box, Deactivation Date section, and EDIT permissions section will be disabled for this type of rotation.
- This feature does not apply to keys that are externally backed.
Click ROTATE KEY in the Key Rotation window to confirm the key rotation.
If the key belongs to a group with a quorum policy, the key rotation will require quorum approval. Also, if any of the linked keys is a part of a group with a quorum policy, instead of directly rotating the key, a quorum approval request will be generated when you click on ROTATE KEY.
The old DSM key will be successfully rotated. The old keys/secrets will also show under the KEY LINKS tab in the detailed view of the new rotated key/secret.
NOTE
- If the old DSM key has metadata or policies already configured, but the new DSM key does not have metadata or policies, then the metadata and policies will be copied from the old DSM key to the new DSM key.
- If the old DSM key does not have metadata or policies and the new DSM key has metadata or policies, then the rotation will be disallowed.
- If neither old DSM key nor new DSM key has metadata or policies, then the rotation will be allowed.
- If both old DSM key and new DSM key have metadata or policies but they are different, then the rotation will be disallowed.
For the rotation of secret keys, the automatic key rotation policies to schedule key rotation described in the next section are not applicable.

1.8.3 Scheduling Key Rotation

Fortanix DSM also allows key rotation to be scheduled for a future time to be done automatically by setting a key rotation policy. If the key rotation policy is set, the key will be periodically rotated as a measure of extra protection for the key material. The scheduled key rotation can be applied at a security object level by setting a time period for automatic key rotation. The time will have the following components.

Start date of the schedule (for example, start key rotation on 06/08/2020)
Frequency of rotation (rotate the key every 10 days/weeks/months/years)
Time of rotation (rotate the key every 10 days starting 06/08/2020 at 12.00 pm)

To schedule a key rotation policy for a security object:

Go to the detailed view of a security object in the Fortanix DSM UI.
In the detailed view, click the KEY ROTATION tab and click the ADD POLICY button.
Enter the key rotation schedule by specifying the rotation frequency, start date, and time.
To deactivate the old key after key rotation, select the Deactivate original key after the rotation check box.
Click SAVE POLICY to save the policy. To edit the policy in the future, click the EDIT POLICY button. TIP
- If the number of days in the frequency of rotation is greater than 28 days, use the “rotate by month” option.
- If the number of weeks in the frequency of rotation is greater than 4 weeks, use the “rotate by month” option.
- If the number of months in the frequency of rotation is greater than 12 months, use the “rotate by year” option.

2.0 Destroy and Delete Security Objects

A security object may be destroyed or deleted using the Destroy and Delete button in the detailed view of the key.

Destroy - When you destroy a key, the key loses its key material, however, it retains the key metadata. The data encrypted with the key can no longer be used once the key is destroyed. The key goes to a “disabled” state which is irreversible.
Delete – When you delete a key, the key is permanently deleted along with its metadata. This is an irreversible operation.

For more details about the Destroy and Delete behavior using the Key Undo Policy, refer to User's Guide: Key Undo Policy.

2.1 Destroy and Delete Security Objects

If you destroy a Fortanix DSM key without Key undo policy, then the key deletion is a 1-step process with a confirmation.

Go to the detailed view of the security object and click the DESTROY KEY button.
In the DESTROY KEY confirmation window, click the check box(es) which are a warning that a user should read and select before destroying the security object. Once this check box(es) are selected, it will enable the DESTROY button.

NOTE

If the Security Object has a Quorum approval policy set, then an approval request will be initiated once you click the DESTROY button in the window below. Click DESTROY to enter the “destroyed” state. The user also has an option to “Cancel” the Key Destroy operation using the CANCEL button.
You could also start the key destroy process for a key from the SO table view. Select the security object and click the DESTROY SELECTED button. Hover on the key to see that the key is in “Destroyed” state. Notice that the colour of the destroyed key icon is black to indicate that the key is destroyed and ready to be deleted.
To delete the key metadata, click the DELETE KEY button to permanently delete the key metadata. If the Key undo policy is added, then the key delete operation is reversible until the specified time period. For more details refer to the User’s Guide: Key Undo Policy.
In the DELETE SECURITY OBJECT window, select the check boxes to confirm that you do not need the key metadata anymore and want to delete the key permanently. Once the check boxes are selected it will enable the PROCEED button.
Click PROCEED to confirm the key delete operation.

3.0 Programmatic Management of Security Object States

3.1 Creating a Security Object in Pre-Active State

By default, the FortanixDSM UI creates a SO in "Active" state. Users can create SOs in "PreActive" state using the Fortanix DSM REST API by following either of the below methods:

Setting the "activation_date" to a time in the future. For example:

POST https://{{server}}/crypto/v1/keys

Request body:

 {
   "name": "mysymmkey101",
   "description": "This is symmetric key 1",
   "activation_date": "20191207T023624Z",
   "key_size": 256,
   "obj_type": "AES",
   "enabled": true,
   "custom_metadata": { "name-1": "value-1", "name-2": "value-2"},
   "attributes": {"app_manageable": true},
   "group_id": "{{grp1_id}}"
}

Explicitly setting the initial "state" of the key to "PreActive". For example:
```
POST https://{{server}}/crypto/v1/keys 
```
Request Body:
```
{
 "name": "mysymmkey102",
 "description": "This is symmetric key 1",
 "key_size": 256,
 "obj_type": "AES",
 "enabled": true,
 "custom_metadata": { "name-1": "value-1", "name-2": "value-2"},
 "attributes": {"app_manageable": true},
 "state": "PreActive",
 "group_id": "{{grp1_id}}"
}
```
In this scenario the SO will not transition to "Active" state until the user explicitly calls the "activate" API endpoint for the key, or the SO is updated with an "activation_date" that becomes current.

NOTE

Users can provide both a "state" and "activation_date" in the same request but if these two parameters are incoherent (that is, "state" being "Active" but an "activation_date" is in the future, then the backend will return a “400 - Bad Request” error code, and the key will not be created)

3.2 Activating a Security Object in Pre-Active State

An SO can be explicitly activated using the Fortanix DSM API by:

Using the following command:
POST https://{{server}}/crypto/v1/keys/{{key_id}}/activate
The "activation_date" of the SO will be set to the time at which the backend received the request.
If the SO is not in "PreActive" state, the API request will fail with “Error 400 – Bad Request”.
- Patching the "activation_date" of the SO to the current or past time. For example:
```
PATCH https://{{server}}/crypto/v1/keys/{{key_id}}
```
  Request Body:
```
{
  "activation_date": "22190411T004313Z"
}
```

4.0 Creating/Updating a Security Object With a Deactivation Date

Users can set the "deactivation_date" of a SO when it is created. For example:

POST https://{{server}}/crypto/v1/keys

Request Body:

{
  "name": "mysymmkey101",
  "description": "This is symmetric key 1",
  "deactivation_date": "20191207T023624Z",
  "key_size": 256,
  "obj_type": "AES",
  "enabled": true,
  "custom_metadata": { "name-1": "value-1", "name-2": "value-2"},
  "attributes": {"app_manageable": true},
  "group_id": "{{grp1_id}}"
}

NOTE

If the "deactivation_date" has already passed the API request will fail with “Error 400 – Bad Request”.

Users can also update a key and set/unset/modify the "deactivation_date" by sending a PATCH request. For example:
```
PATCH https://{{server}}/crypto/v1/keys/{{key_id}}
```
Request body:
```
{
  "deactivation_date": "22190411T004313Z"
}
```

5.0 Deactivating a Security Object in Pre-Active or Active State

An SO can be explicitly deactivated using the Fortanix DSM API by:

Making a "revoke" request. For example:
```
POST https://{{server}}/crypto/v1/keys/{{key_id}}/revoke
```
Request body:
```
{
  "code": "Unspecified",
  "message": "Lost it in the bus"
}
```
The request body contains the following fields:
- code: Revocation reason. It can be one of the following: Unspecified, AffiliationChange, Superseded, CessationOfOperatrion, PrivilegeWithdrawn.
- message (optional): A string for specifying a note on why this key is being deactivated.
If the SO is not in "PreActive" or "Active" state, the API request will fail with “Error 400 – Bad Request”.

When the key is “revoked” the SO will contain a "revocation_reason" field as shown below:
```
"revocation_reason": {
  "code": "Unspecified",
  "message": "Lost it in the bus",
  "compromise_occurance_date": null
 }
```

Patching the "activation_date" of the SO to the current or past time. For example:

PATCH https://{{server}}/crypto/v1/keys/{{key_id}}

Request body:

{
  "deactivation_date": "22190411T004313Z"
}

6.0 Transitioning a Security Object to Compromised State

An SO can be explicitly updated to "compromised" using the Fortanix DSM API by making a "revoke" request. For example:

POST https://{{server}}/crypto/v1/keys/{{key_id}}/revoke

Request body:

{
  "code": "KeyCompromise",
  "message": "Lost it in the bus",
  "compromise_ocurance_date": "22190411T004313Z"
}

The request body contains the following fields:

code: Revocation reason. It can be one of the following: KeyCompromise,CACompromise.
message (optional): A string for specifying a note on why this key is being deactivated.
compromise_occurance_date (optional): Date in which it was detected that the SO was compromised.

If the SO is already in "Compromised" state, the API request will fail with “Error 400 – Bad Request”.

When the SO is in "Compromised" state it will contain a "revocation_reason" field as show below:

"revocation_reason": {
  "code": "KeyCompromise",
  "message": "Lost it in the bus",
  "compromise_occurance_date": “22190411T004313Z”
}

NOTE

In all the API calls described in the previous sections, the backend will always ensure that the "activation_date" is always before the "deactivation_date" and "compromise_occurance_date". Any request that tries to violate this condition will fail with “Error 400 – Bad Request”.

To mark a security object as “Compromised” from the Fortanix DSM GUI:

1. Go to the detailed view of the security object, and in the INFO tab scroll to the bottom and click the DEACTIVATE NOW button.

1.0 Security Object Lifecycle Management

1.1 Security Object Types

1.1.1 Import Security Objects

1.1.2 Generate Security Objects

1.2 Security Object Operations

1.3 Security Object States Descriptions

1.4 Security Object Activation Date

1.5 Security Object Deactivation Date

1.6 Enabling a Deactivated Key

1.7 Key Attributes/Tags

1.8 Key Rotation

1.8.1 Generate New Key

1.8.2 Rotate to an Existing Key

1.8.3 Scheduling Key Rotation

2.0 Destroy and Delete Security Objects

2.1 Destroy and Delete Security Objects

3.0 Programmatic Management of Security Object States

3.1 Creating a Security Object in Pre-Active State

3.2 Activating a Security Object in Pre-Active State

4.0 Creating/Updating a Security Object With a Deactivation Date

5.0 Deactivating a Security Object in Pre-Active or Active State

6.0 Transitioning a Security Object to Compromised State

Related articles

Comments

1.3 Security Object States Descriptions