See more

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

  • Last updated:
  • access_time Reading time:

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. The following diagram is a representation of the SO lifecycle:

key_states-01.png
                                         Figure 1: Security Object Lifecycle

Security Object Types

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

Import Security Objects

To import a security object:

  1. In the Fortanix DSM UI, click the Security Objects tab and click the Add.PNG button 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.
      Secret.png
                                                                      Figure 2: Import Security object
     
  3. Click IMPORT to import a security object. To import a security object from a component, refer to the article Key Components.
     
  4. Choose a type of key to import.
  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. All valid DSA key sizes are allowed during import.
  7. 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. SecretKey.png
                                                 Figure 3: Secret object attribute
     
  8. Next, enter or select a Key ID or SO name in the Select Key Encryption Key section. 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.
  9. Click UPLOAD A FILE to upload the key file in Raw, Base64, or Hex format.
      Key_Import.png
                                                                            Figure 4: Choose key type
     
  10. Select the permitted key operations and click IMPORT to import the key. HMAC2.png
                                                                            Figure 5: Import key
     
    1. The key is successfully imported. HMAC3.png
                                                                              Figure 6: Key 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:
       
    2. Go to the detailed view of a “secret” object that was imported.
    3. In the INFO tab, click the SHOW icon to show the value of the secret object.
        Secret4.png
                                                                        Figure 7: Show secret object value
       
    4. The “secret” Object Value will be displayed. Secret5.png
                                                                              Figure 8: Secret object value
       
      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.
        Secret6.png
                                                     Figure 9: Object value not shown with quorum policy

Generate Security Objects

To generate a security object:

  1. In the Fortanix DSM UI, click the Security Objects tab and click the Add.PNG button 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.
      Secret7.png
                                                                      Figure 10: Generate Security object
     
  3. Click GENERATE to generate a security object. 
  4. Choose a type of key to generate the key.
     
    NOTE
    For DSA keys 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.
     
  5. Select the permitted key operations and click GENERATE to generate the key. Afterward, the key is successfully generated. Key_Generate.png
                                                                            Figure 11: Key generated

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
13.png
                                                     Figure 12: Key Operations
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.

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).
    14.png
                                                  Figure 13: Enable/Disable SO
  • 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.

DeactivateKey.png
                                           Figure 14: SO Deactivated State

  • 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. KeyLifecycle_Compromised.png
                                                             Figure 15: SO Compromised
  • 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.

Compromise_Key.png
                                                       Figure 16: SO Compromised

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

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.

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.

Expire_key.png
                                             Figure 17: Set Deactivation Date

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. PKCS11Attribute.png
                                                                Figure 18: PKCS#11 attributes
      CNGAttribute.png
                                                                Figure 19: CNG attributes
     
  • Custom attributes – These are user-defined SO attributes that can be added to the key’s metadata. CustomAttribute.png
                                                                Figure 20: Custom attributes

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.

To rotate a key:

  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. Key_Rotation.png
                                                               Figure 21: Rotate key
     
  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. DeactivateKeyAfterRotation.png
                                                    Figure 22: Confirm 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.

    To rotate an existing key of type “Secret” and keep a history of all previous versions of the same secret:

    1. In the detailed view of the secret key that you want to rotate, click ROTATE KEY to rotate the secret.
    2. In the KEY ROTATION window, enter a new object value for the secret in Raw, Base64, or Hex This step is mandatory. Rotate_secrets.png                                                            Figure 23: Rotate Secret Key
       
    Continue to Step 4.
     
  4. 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.

  5. 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. Key_Rotation2.png
                                                               Figure 24: Rotated key
     
  6. Notice the new UUID of the rotated key. Key_Rotation3.png
                                                               Figure 25: Rotated key detailed view
     
    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.
    • For the rotation of secret keys, the automatic key rotation policies to schedule key rotation described in the next section are not applicable.

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. Key_Rotation4.png
                                                               Figure 26: Add key rotation policy
     
  3. Enter the key rotation schedule by specifying the rotation frequency, start date, and time. Key_Rotation5.png
                                                              Figure 27: Add key rotation schedule
     
  4. Click SAVE POLICY to save the policy. To edit the policy in the future, click the EDIT POLICY button. Key_Rotation6.png
                                                              Figure 28: Edit policy
     
    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.

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.

Delete_Destroy_key.png                                                           Figure 29: Destroy and Delete a key
 

Programmatic Management of Security Object States

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:

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

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

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

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

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. KeyLifecycle_Compromised.png
                                                           Figure 30 : SO Compromised