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

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:

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  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.
    
   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.
   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.
    
   Figure 4: Choose key type
10. Select the permitted key operations and click IMPORT to import the key.
    Figure 5: Import key 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.
11. The key is successfully imported.
    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:
     
12. Go to the detailed view of a “secret” object that was imported.
13. In the INFO tab, click the SHOW icon to show the value of the secret object.
     
    Figure 7: Show secret object value
14. The “secret” Object Value will be displayed.
    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.
     
    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  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.
    
   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.
   Figure 11: Key generated
6. 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. Figure 12: Enable audit log
7. Click GENERATE to generate the key. Afterwards, the key is successfully 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

Figure 13: Key Operations

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).
  Figure 14: 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.

Figure 15: 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.
     Figure 16: 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.

Figure 17: 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".

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

Figure 18: 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.
  Figure 19: PKCS#11 attributes  
  Figure 20: CNG attributes
• Custom attributes – These are user-defined SO attributes that can be added to the key’s metadata.
  Figure 21: 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.
   Figure 22: 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.
   Figure 23: 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. Figure 24: 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.
   Figure 25: Rotated key
6. Notice the new UUID of the rotated key.
   Figure 26: 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.
   Figure 27: Add key rotation policy
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.
   Figure 28: Add key rotation schedule
5. Click SAVE POLICY to save the policy. To edit the policy in the future, click the EDIT POLICY button.
   Figure 29: 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.

Figure 30: Destroy and Delete a key

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

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. Figure 31: Destroy security object
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.
   Figure 32: Destroy security object
3. Click DESTROY to enter the “destroyed” state. The user also has an option to “Cancel” the Key Destroy operation using the CANCEL button.
4. 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. Figure 33: Destroy SO from table view Figure 34: Key in destroyed state in SO table view 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.
5. 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. Figure 35: Delete security object stateFigure 36: Purge key metadata confirmation
6. 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.
7. Click PROCEED to confirm the key delete operation.

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

  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.
   Figure 37 : SO Compromised