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

1.0 Introduction

Welcome to the Fortanix-Data-Security-Manager (DSM) User Guide for Security Controls of Application (apps) and Security Objects. This article describes the Fortanix DSM Security Object Lifecycle Management. It also contains the information related to:

• Security controls around the security object such as:  

  • Key rotation

  • Deactivation

  • Disabling and enabling keys.

• Security controls for apps on using a security object such as:

  • Quorum control

  • App permissions

2.0 Security Objects Lifecycle Management

Security objects in Fortanix DSM follow a lifecycle which is composed of a set of states in which the object can be in. During the object’s existence, the security object transitions from one state to another, according to policies or events set by the user.

2.1 Security Object Types

A security object can either be imported or generated in the Fortanix DSM user interface (UI).

2.1.1 Import Security Objects

To import a security object:

1. Navigate to Security Objects menu item in the DSM left navigation bar and click the + button on the Security Objects page to add a new Security-object.

2. 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.

3. Click IMPORT to import a security object. To import a security object from a component, refer to the article Key Components.

4. Select a type of key to import. The supported key types are AES, DES, DES3, HMAC, RSA, EC, DSA, Opaque, Secret, Certificate, BIP32, ARIA, KCDSA, EC-KCDSA, BLS, SEED, ML-KEM, and ML-DSA.

   • 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 parameters are Curve: secp256k1, Path: m/0'/42/6147', Network: Mainnet or Testnet.

     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. If this option is not selected, it will create a non-hardened child.

     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 following keys of type Korean Cryptography developed are supported in Fortanix DSM:

     • 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.

     • 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.

   • The following keys of type Post Quantum Cryptography developed are supported in Fortanix DSM:

     • ML-KEM: Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) is a security feature introduced in Fortanix DSM UI. It encompasses cryptographic algorithms designed to provide key encapsulation and exchange functionality. The supported mode of operation is FIPS 203. For more details, refer to DSM Algorithm Support Guide.

       The following parameters are supported:

       • ML-KEM-512: Denotes the ML-KEM variant with a key size of 512 bits.

       • ML-KEM-768: Denotes the ML-KEM variant with a key size of 768 bits.

       • ML-KEM-1024: Denotes the ML-KEM variant with a key size of 1024 bits.

     • ML-DSA: Module-Lattice-Based Digital Signature Algorithm (ML-DSA) (Crystals-Dilithium) is a security feature introduced in Fortanix DSM UI. It utilizes advanced cryptographic algorithms to provide digital signature functionality, ensuring the authenticity and integrity of messages.  

       The following parameters are supported:

       • ML-DSA-44: Denotes the ML-DSA variant with a key size of 44 bits.

       • ML-DSA-65: Denotes the ML-DSA variant with a key size of 65 bits.

       • ML-DSA-87: Denotes the ML-DSA variant with a key size of 87 bits.

5. 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.

6. 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, the plain text is divided into blocks of size 64 bits. Each block is encrypted independently of the other blocks. For all blocks, the same key is used for encryption.

      2. KW: It uses the symmetric encryption to encapsulate key material.

      3. KWP: In this method, the 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.

7. Key Check Value: The KCV of the imported key is optionally added by the admin while creating the import request.

   NOTE

   For AES and DES3 (168-bit) keys, you can enter either the KCV or CMAC value of the key.

8. 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.

9. Select the permitted key operations. For more information on key operations, refer to Key Operations.

10. 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.

11. 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 4.2: Activating a Security Object in Pre-Active State.

12. 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 6.0: 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.

13. 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.

14. Click IMPORT and the key is successfully imported.

NOTE

All AES and DES3 (168-bit only) will display the Cipher-based Message Authentication Code (CMAC) KCV value, in addition to the key type, size, and original KCV values.

Fortanix DSM also provides an ability to view security objects 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.  

2.1.2 Generate Security Objects

To generate a security object:

1. Navigate to Security Objects menu item in the DSM left navigation bar and click the + button on the Security Objects page to add a new Security-object.

2. 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.

3. Click GENERATE to generate a security object.

4. Select a type of key to generate the key. The supported key types are AES, DES, DES3, HMAC, RSA, EC, DSA, Tokenization, ARIA, KCDSA, EC-KCDSA, BLS, SEED, LMS, XMSS, ML-KEM, and ML-DSA.

   NOTE

   For detailed steps on how to generate a security object of type "Tokenization", refer to Security Objects Tokenization Quickstart.

   The following keys of type Post Quantum Cryptography developed 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. You can add up to 2 Tree Nodes, which indicate the height of the top and secondary level tree respectively.

     • Tree height: You can select the tree height from the available options of 5, 10, 15, and 20.

       NOTE

       Ensure that the sum of the H1 tree height and H2 tree height must not exceed 25.

     • Add tree node: Click the button to add the secondary level tree.

     • Remove node: To remove the node, click the   button.

     • Node size: You can select the size of the node from the available options as 24 and 32. The default node size is 24.

     To know more about the Fortanix implementation of LMS keys, refer to LMS Keys - FAQs.

   • ML-KEM: Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM) is a security feature introduced in Fortanix DSM UI. It encompasses cryptographic algorithms designed to provide key encapsulation and exchange functionality.
     The following parameters are supported:

     • ML-KEM-512: Denotes the ML-KEM variant with a key size of 512 bits.

     • ML-KEM-768: Denotes the ML-KEM variant with a key size of 768 bits.

     • ML-KEM-1024: Denotes the ML-KEM variant with a key size of 1024 bits.

   • ML-DSA: Module-Lattice-Based Digital Signature Algorithm (ML-DSA) (Crystals-Dilithium) is a security feature introduced in Fortanix DSM UI. It utilizes advanced cryptographic algorithms to provide digital signature functionality, ensuring the authenticity and integrity of messages.  

     The following parameters are supported:

     • ML-DSA-44: Denotes the ML-DSA variant with a key size of 44 bits.

     • ML-DSA-65: Denotes the ML-DSA variant with a key size of 65 bits.

     • ML-DSA-87: Denotes the ML-DSA variant with a key size of 87 bits.

   • XMSS: eXtended Merkle Signature Scheme (XMSS) is a hash-based digital signature algorithm that provides post-quantum security. It utilizes Merkle trees and one-time signature schemes to ensure secure and efficient digital signatures.

     • Tree height: You can select the tree height from the available options of 10, 16, and 20.

       NOTE

       Ensure that the sum of the H1 tree height and H2 tree height must not exceed 20.

     • Add tree node: Click the button to add the secondary level tree.

     • Remove node: To remove the node, click the   button.

     • Node size: You can select the size of the node from the available options as 24 and 32. The default node size is 24.

     • Hash Algorithm: XMSS supports SHA-256 and SHA3-256 as hash functions for enhanced security.

   • 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).

5. Select the permitted key operations.

6. Add custom attributes by clicking the ADD ATTRIBUTE button.

7. By default, the security object is set to be activated immediately. To specify activation date to a future time-period, click EDIT.

8. 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.

9. To store audit logs for the object in the group, enable the toggle for Keep detailed log for the object.

10. Click GENERATE to successfully generate the security object.

NOTE

All AES and DES3 (168-bit only) will display the Cipher-based Message Authentication Code (CMAC) KCV value, in addition to the key type, size, and original KCV values.

2.2 Security Object Operations

The security object 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 security object can perform will depend on the initial security object operations set by the user at creation time and the current state in which the security object is at.

2.3 Security Object States Descriptions

• Pre-active: When the "activation_date" field of a security object is set to a future date, then the SO’s initial state will be "PreActive" state. When a security object is in "PreActive" state, no cryptographic operation can be performed with the SO.

• “Pre-active” to “active” transition: When the security object reaches the "activation_date", it will automatically transition to "Active" state. Note that once the security object is active it cannot transition back to "PreActive" state.
  SOs created using the Fortanix DSM UI will set the "activation_date" to the current server time so they will automatically be initialized in "Active" state.

• Active: When a security object is in "Active" state it can be used for all processes and perform cryptographic operations set by the user.

• Enabled / Disabled sub-states: While a security object is in "Active" state, the user can "Enable/Disable" the SO. When the security object is in "Enabled" state, it can perform all the cryptographic operations set by the user. When the security object is in "Disabled" state the security object 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 security object 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 security object will automatically transition to “Deactivated” state. Note that once the security object 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 security object 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 security object sub-state to "Enabled". Refer to Section 6.0: Deactivating a Security Object in Pre-Active or Active State.

• Deactivated: When a security object is in Deactivated state, it can perform certain cryptographic operations depending on its "Enabled/Disabled" sub-state:

  • Enabled: The security object can perform “Process Operations” only. For more details on process operations, refer to Section 2.2: Security Object Operations.

  • Disabled: The security object cannot perform any cryptographic operation.

• Compromised transition: A security object transitions to "Compromised" state when the client calls the Revoke API for the security object and the "reason" field in the request body is set to "COMPROMISED" (refer tp 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.
  A security object 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 UI:

  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 a security object is in "Compromised" state it can perform certain cryptographic operations depending on its "Enabled/Disabled" sub-state:

  • Enabled: The security object can perform “Process Operations” only.

  • Disabled: The security object 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 security object to "true" (Enabled) or "false" (Disabled).

2.4 Security Object Activation Date

Depending on the value of the field "activation_date" in the request body, the initial state of the security object can be either: “PreActive” or “Active”.

• "Active": Indicates either of the following:

  • The field was omitted and is populated by the server when processing the request.

  • The field was provided, and the time was in the past.

• "PreActive": Indicated that the field was provided but is in the future.

2.5 Security Object Deactivation Date

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

• The "deactivation_date" field is not set, the security object will remain in "Active" state.

• The "deactivation_date" field is set, the security object will transition to “Deactivated” state upon that date.

A security object may also transition to "Deactivated" state for other type of events explained in sub-section “Active to Deactivated Transition” state under Section 2.3: Security Objects State Descriptions.

2.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

NOTE

For a Fortanix DSM account running on DSM version < 4.16:

• For new and existing accounts:

  • If you deactivate or expire a key, it will be disabled.

  • if you set the key's deactivation or expiration date to a future date, then after the key is deactivated or expired, it will be disabled.

  • You can enable the key using the Fortanix DSM UI manually.

For a Fortanix DSM account running on DSM version >= 4.16,

• A new flag mark_key_disable_when_deactivated is introduced. If the flag is true, the keys will become disabled upon deactivation or expiration, and if false, the keys will remain enabled upon deactivation or expiration.

• Updates to the flag are retroactive, that is, any flag change will be applied to both new and old keys.

• For new accounts:

  • The flag is set to false by default. The setting can be changed at any time by account administrators.

  • Any updates to the flag are applied to new keys at any point.

• For existing accounts (< 4.16):

  • The flag is set to true by default. The setting can be changed at any time by account administrators.

  • Any updates to the flag are applied to existing keys at any point.

• Example: In a DSM 4.16 account:

  • The mark_key_disable_when_deactivated flag is set to false.

  • Create key K1. Deactivate K1 now, K1 will be enabled afterward.

  • Change mark_key_disable_when_deactivated to true.

  • Create key K2.

  • Now, both K1 and K2 will become disabled upon deactivation.

Here K1 will become disabled because the flag change is retroactively applied to K1. However, if you manually enable K1 using the DSM UI afterward, any further changes to mark_key_disable_when_deactivated will have no effect.

For a Fortanix DSM account running on DSM version 4.19 and above

• The flag mark_key_disable_when_deactivated can be used to configure whether a key will become automatically disabled upon reaching its deactivation date. If the flag is true, the keys will become disabled upon deactivation or expiration, and if false, the keys will remain enabled upon deactivation or expiration.

• Updates to the flag are not retroactive, that is, any flag change will not be applied to existing keys and will only be applied to new keys.

• For new accounts:

  • The flag is set to false by default. The setting can be changed at any time by account administrators.

  • Any updates to the flag are applied to new keys at any point.

• For existing accounts (< 4.16):

  • The flag will be set to the last value that was set before upgrading to 4.19. The setting can be changed at any time by account administrators.

  • Any updates to the flag are not applied to existing keys at any point.

• Any updates to the flag are applied to existing keys at any point.

• Example: In a DSM 4.16 account:

  • The mark_key_disable_when_deactivated flag is set to false.

  • Create key K1. Deactivate K1 now, K1 will be enabled afterward.

  • Change mark_key_disable_when_deactivated to true.

  • Create key K2.

  • K1 will stay enabled and K2 will become disabled upon deactivation.

• For DSM 4.19 and above, the following operations will always read the current value of the flag for enabling or disabling a deactivated key:

  • Creation of new keys.

  • Updating an existing key's deactivation date using the Update endpoint, PATCH /crypto/v1/keys/:key_id

  • Explicitly deactivating an existing key using the Revoke endpoint (POST /crypto/v1/keys/:key_id/revoke)

  • Key deactivation that occurs as part of key rotation (manual or scheduled) for existing or new keys.

The following is the sample PATCH API request:

curl -X PATCH -H "Authorization: <auth_token>" -H "Content-Type:application/json" -d '{"mark_key_disable_when_deactivated":false}' -k 'https://<cluster_ip>/api/sys/v1/accounts/<account_id>'

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
}
}

2.7 Key Attributes/Tags

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

• PKCS #11 and CNG attributes – These are standard attributes for their corresponding specifications. For details see the PKCS #11/CNG specification. The security object attribute values are mapped to the corresponding name in PKCS #11/CNG.  

• Custom attributes – These are user-defined security object attributes that can be added to the key’s metadata.

2.8 Filtering Security Objects Using the Search Bar

You can use the Search bar to quickly filter and locate specific security objects from the list. The search bar allows filtering based on the following attributes:

• UUID: Filter security objects by the specific key ID.

• State: Filter by the current state of the security object. The available key states are pre-active, active, deactivated, compromised, destroyed, and deleted. The key can be filtered by their states using the following conditions:

  • is: Matches the exact specified state.

  • is not: Excludes the specified state.

  • is one of: Matches any of the listed states.

  • is none of: Excludes any of the listed states.

  For more information about these states, refer to the Section 2.3: Security Objects States Description.

• Name: Filter security objects by entering a specific key name.

• Key Ops: Filter by the key operations supported by the security object such as ENCRYPT, DECRYPT, WRAPKEY, UNWRAPKEY, DERIVEKEY, MACGENERATE, MACVERIFY, APPMANAGEABLE, SIGN, VERIFY, ENCAPSULATE, DECAPSULATE, AGREEKEY, TRANSFORM, EXPORT.

• Group: Filter security objects based on their associated group.

• Creator: Filter by the user who created the security object.

• Type: Filter based on the type of the security object. The key can be filtered by their type using the following conditions:

  • is: Matches a specific type.

  • is not: Excludes a specific type.

  • is one of: Matches any type from a selected list.

  • is none of: Excludes specific types.

  For more information about the key types, refer to the Section 2.1: Security Objects Type.

• Creator Type: Filter by the type of entities such as Application, User, or Plugin that created the security object. The key can be filtered by their creator type using the following conditions:

  • is: Matches a specific creator type.

  • is not: Excludes a specific creator type.

  • is one of: Matches any creator type from a selected list.

  • is none of: Excludes specific creator types.

• Key Size: Filter by the key size of the security object using the following comparison operators:

  • =: Filters the security objects with a key size equal to the specified value.

  • <: Filters the security objects with a key size smaller than the specified value.

  • ≤: Filters the security objects with a key size equal to or smaller than the specified value.

  • >: Filters the security objects with a key size larger than the specified value.

  • ≥: Filters the security objects with a key size equal to or larger than the specified value.

  • ≠: Filters the security objects with a key size that is not equal to the specified value.

• Elliptic Curve: Filter the EC (Elliptic Curve) keys based on the following curves:

  • SecP192K1

  • SecP224K1

  • SecP256K1

  • NistP192

  • NistP224

  • NistP256

  • NistP384

  • NistP521

  • Gost256A

  • X25519

  • X448

  • Ed25519

  The EC keys can be filtered by their curves using the following conditions:

  • is: Matches a specific elliptic curve.

  • is not: Excludes a specific elliptic curve.

  • is one of: Matches any elliptic curve from a selected list.

  • is none of: Excludes specific elliptic curves.

• Custom Attributes: Enter a custom key to filter by specific custom attributes associated with the security object.

• Created: Filter by the creation date of the security object using the following comparison operators:

  • <: Filters the security objects that were created before the specified date.

  • ≤: Filters the security objects created on or before the specified date.

  • >: Filters the security objects created after the specified date.

  • ≥: Filters the security objects created on or after the specified date.

  • Range: Allows you to specify a custom date range, displaying security objects that were created within the defined start and end date.

• Audit Log: Filter the security objects by the audit log status:

  • Enabled: Filters the security objects that has audit log in enabled state.

  • Disabled: Filters the security objects that has audit log in disabled state.

• Description: Filter by keywords or phrases from the security object description.

• Deactivated: Filter by the deactivation date of the security object using the following comparison operators:

  • <: Filters the security objects that were deactivated before the specified date.

  • ≤: Filters the security objects deactivated on or before the specified date.

  • >: Filters the security objects deactivated after the specified date.

  • ≥: Filters the security objects deactivated on or after the specified date.

  • Range: Allows you to specify a custom date range, displaying security objects that were deactivated within the defined timeframe.

For more details on filtering security objects using DSM REST API, refer to the Developer Guide: Filtering Security Objects Using Fortanix DSM REST API.

2.9 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:

2.9.1 Generate New Key

Perform the following steps to rotate a key when the Generate new key option is selected:

1. In the Fortanix DSM UI, go to the detailed view of a security object.

2. Under the name of the security object, click the ROTATE KEY link.

3. 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”. For more details, refer to Section 2.9.3: Scheduling Key Rotation.

   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.

4. 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.

5. To set the deactivation date of the newly rotated key to a future date, click EDIT.

6. Click ROTATE KEY in the Key Rotation window to confirm the key rotation.
   A cautionary message will appear on the screen, ensuring that you are fully aware of the implications of key rotation. You must select both the check boxes to enable the PROCEED button.

1. 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.

2. 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.

3. Notice the new UUID of the rotated key.

   NOTE

   • The OPAQUE and CERTIFICATE key types cannot be rotated.

   • 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.

2.9.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:

1. In the Fortanix DSM UI, go to the detailed view of a security object.

2. Under the name of the security object, click the ROTATE KEY link.

3. Select Rotate to existing key option.

4. 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.

5. 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.

   NOTE

   The "Rotate to an existing key" option is not supported for tokenization keys.

6. 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.

2.9.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:

1. Go to the detailed view of a security object in the Fortanix DSM UI.

2. In the detailed view, click the KEY ROTATION tab and click the ADD POLICY button.

3. Enter the key rotation schedule by specifying the rotation frequency, start date, and time.

4. To deactivate the old key after key rotation, select the Deactivate original key after the rotation check box.

5. 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.

NOTE

• The “deactivate on rotation” option in the Key-Rotation Policy overrides any deactivation date set on the key.

• If the key being rotated has a deactivation_date, the new key will inherit the same “activation period” (the time from creation to deactivation), even if the rotation policy would typically deactivate the key sooner.

3.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.

3.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.

1. Go to the detailed view of the security object and click the DESTROY KEY button.

2. 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.

3. You could also start the key destroy process for a key from the security object 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.

4. 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.

5. 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.

6. Click PROCEED to confirm the key delete operation.

4.0 Programmatic Management of Security Object States

4.1 Creating a Security Object in Pre-Active State

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

1. 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}}"
   }
   

2. 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 security object will not transition to "Active" state until the user explicitly calls the "activate" API endpoint for the key, or the security object 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)

4.2 Activating a Security Object in Pre-Active State

A security object can be explicitly activated using the Fortanix DSM API:

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

NOTE

The "activation_date" of the security object will be set to the time at which the backend received the request. If the security object is not in "PreActive" state, the API request will fail with “Error 400 – Bad Request”.

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

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

Request Body:

{
  "activation_date": "22190411T004313Z"
}

5.0 Creating/Updating a Security Object With a Deactivation Date

• Users can set the "deactivation_date" of a security object 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"
  }
  

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

A security object can be explicitly deactivated using the Fortanix DSM API:

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.

NOTE

If the security object is not in "PreActive" or "Active" state, the API request will fail with “Error 400 – Bad Request”.

When the key is “revoked” the security object 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 security object to the current or past time. For example:

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

Request body:

{
  "deactivation_date": "22190411T004313Z"
}

7.0 Transitioning a Security Object to Compromised State

A security object 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 security object was compromised.

NOTE

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

When the security object 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”
}

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

1. Go to the detailed view of the security object.

2. In the INFO tab scroll to the bottom and click the DEACTIVATE NOW button.