User's Guide: Group Key Metadata Policy

Prev Next

1.0 Introduction

This article describes the Key Metadata Policy feature in Fortanix-Data-Security-Manager (DSM), which allows users to set key metadata policies for Fortanix DSM groups.

Fortanix DSM supports key metadata policies that can be configured at the group-level to enforce restrictions on the metadata associated with security objects. Here “metadata” refers to elements of security objects that are not governed by cryptographic policies, such as custom metadata, descriptions, expiry dates, and so on. The policy can specify that certain metadata “must be present”, “must not be present”, or “must be present and have a certain value”.

2.0 Key Metadata Policy Behavior

Key metadata policies can be configured at both the account-level and group-level. When a Key metadata policy is set at the account-level, the DSM user interface (UI) evaluates the configuration set at the group-level against the existing account-level configuration.

This section explains the expected behavior of DSM UI under various configuration scenarios:

2.1 Use Case 1: Account-Level Policy Configured Before Group-Level Policy

  • Same Key Metadata Policy settings at both account and group levels:
    • If the Key description, Activation date, and Deactivation date are all set to Optional at both account and group levels, DSM UI saves the group-level configuration without error.
    • When all three fields are set to Required at both account and group levels, DSM UI saves the group-level configuration without error.
    • If the Deactivation date is set to Forbid, and Key description and Activation date are set to Optional/Required at both levels, DSM UI saves the group-level configuration without error.

      Account-level Setting

      Group-level Setting

      Security Object Creation

      Optional

      Optional

      Optional

      Required

      Required

      Required

      Forbid (Deactivation date)

      Forbid (Deactivation date)

      Forbid (Deactivation 
      date)

  • Different Key Metadata Policy settings at both account and group levels:
    • If the Deactivation date is set to Forbid at the account-level and Required at the group-level, the DSM UI displays a validation error and does not save the group-level policy. The error indicates that both levels define conflicting constraints for the same field.
    • If the Deactivation date is set to Forbid at the account-level and Optional at the group-level, the DSM UI allows the group-level policy to be saved without any error.
    • If the Deactivation date is set to Required at the account-level and Forbid at the group-level, the DSM UI displays a validation error and does not save the group-level policy. The error indicates that both levels define conflicting constraints for the same field.
    • If the Deactivation date/Activation date/Key description are set to Required at the account-level and Optional at the group-level, the DSM UI allows the group-level policy to be saved without any error.
    • If the Deactivation date is set to Optional at the account-level and Forbid at the group-level, the DSM UI allows the group-level policy to be saved without any error.
    • If the Deactivation date/Activation date/Key description is set to Optional at the account-level and Required at the group-level, the DSM UI allows the group-level policy to be saved without any error.

      Setting

      Account-level Setting

      Group-level Setting

      Security Object Creation

      Key description

      Optional

      Required

      Required

      Required

      Optional

      Required

      Key activation

      Optional

      Required

      Required

      Required

      Optional

      Required

      Key deactivation

      Optional

      Required

      Required

      Required

      Optional

      Required

      Optional

      Forbid

      Forbid

      Forbid

      Optional

      Forbid

      Required

      Forbid

      Required

      Forbid

      Required

      Forbid

2.2 Use Case 2: Group-Level Policy Configured Before Account-Level Policy

  • Same Key Metadata Policy settings at both account and group levels:
    • If the Key description, Activation date, and Deactivation date are all set to Optional at both account and group levels, DSM UI saves the account-level policy without error.
    •  When all three fields are set to Required at both group and account levels, DSM UI saves the account-level configuration without error.
    • If the Deactivation date is set to Forbid, and Key description and Activation date are set to Optional/Required at both levels, DSM UI saves the account-level configuration without error.

      Account-level Setting

      Group-level Setting

      Security Object Creation

      Optional

      Optional

      Optional

      Required

      Required

      Required

      Forbid (Deactivation date)

      Forbid (Deactivation date)

      Forbid (Deactivation 
      date)

  • Different Key Metadata Policy settings at both group and account levels:
    • If the Deactivation date is set to Forbid at the group-level and Required at the account-level, the DSM UI displays a validation error and does not save the account-level policy. The error indicates that both levels define conflicting constraints for the same field.
    • If the Deactivation date is set to Forbid at the group-level and Optional at the account-level, the DSM UI allows the account-level policy to be saved without any error.
    • If the Deactivation date is set to Required at the group-level and Forbid at the account-level, the DSM UI displays a validation error and does not save the account-level policy. The error indicates that both levels define conflicting constraints for the same field.
    • If the Deactivation date/Activation date/Key description is set to Required at the group-level and Optional at the account-level, the DSM UI allows the account-level policy to be saved without any error.
    • If the Deactivation date is set to Optional at the group-level and Forbid at the account-level, the DSM UI allows the account-level policy to be saved without any error.
    • If the Deactivation date/Activation date/Key description is set to Optional at the group-level and Required at the account-level, the DSM UI allows the group-level policy to be saved without any error.

      Setting

      Group-level Setting

      Account-level Setting

      Security Object Creation

      Key description

      Optional

      Required

      Required

      Required

      Optional

      Required

      Key activation

      Optional

      Required

      Required

      Required

      Optional

      Required

      Key deactivation

      Optional

      Required

      Required

      Required

      Optional

      Required

      Optional

      Forbid

      Forbid

      Forbid

      Optional

      Forbid

      Required

      Forbid

      Required

      Forbid

      Required

      Forbid

3.0 Adding a Key Metadata Policy at Group-Level

A group-level Key metadata policy allows you to configure specific restrictions on the “metadata” associated with security objects, such as key descriptions, activation and deactivation dates, custom attributes, and so on.

Perform the following steps to add a Key metadata policy at the group-level:

  1. Navigate to the detailed view of a group, and under the INFO tab, click ADD POLICY in the Key metadata policy section.

    Figure 1: Add key metadata policy for group

  2. On the Key metadata policy page, configure the following metadata settings for the group:

    1. Key description: Set the rule as either Optional or Required by selecting the corresponding radio button.

    2. Activation date: Set the rule as either Optional or Required by selecting the appropriate radio button.

      • Optionally, to enforce a specific activation window for the key, select the Required radio button. Then, select the optional check box User must specify an activation date within [X] and [Y] (seconds/minutes/hours/days) of the security object's creation time to define the allowed activation range for the key.

        For example, the user can specify an activation date between 20 hours and 10 days from the time the security object is created.

        Figure 2: Activation date

        NOTE

        [X] defines the lower limit, and [Y] defines the upper limit of the time range within which the security object must be activated.

    3. Deactivation date: Set the Deactivation date rule to Optional, Required, or Forbid by selecting the corresponding radio button.

      • Optionally, to enforce a specific deactivation window for the key, select the check box  User must specify a deactivation date within [X] and [Y] (seconds/minutes/hours/days) of the security object's creation time to configure the time period during which the security object should be deactivated.

        For example, the user can specify a deactivation date between 10 hours and 1 day after the security object’s creation time. This means that the security object can be deactivated any time after 10 hours of its creation and before 24 hours from its creation.

        Figure 3: Deactivation date option 1

        NOTE

        • [X] sets the lower limit, and [Y] sets the upper limit of the time range within which the security object will be deactivated.

        • If you did not enable the option User must specify a deactivation date within [X] and [Y] (seconds/minutes/hours/days) of the security object's creation time at the account-level, the setting will only apply to the group in which it is enabled.

        • If you enabled the option User must specify a deactivation date within [X] and [Y] (seconds/minutes/hours/days) of the security object's creation time at the account-level and disabled the setting for a group, then the account-level setting will apply to the group. When creating a security object in this group, the deactivation date must fall within the maximum allowed range set at the account-level.

        • If the User must specify a deactivation date within [X] and [Y] (seconds/minutes/hours/days) of the security object's creation time at the account-level differs from that at the group-level:

          • If the account-level date range is higher than the group-level date range, the group-level date range will take precedence for that specific group.

          • If the account-level date range is lower than the group-level date range, the account-level date range will take precedence for that specific group.

      • Optionally, select the check box Default deactivation date for new Objects [Z] (seconds/minutes/hours/days) after creation time to set a default deactivation date for the security object during its creation.

        For example, the user can specify the default deactivation date of 2 days after security object’s creation time.

        Figure 4: Deactivation date option 2

        NOTE

        • If you have already specified a deactivation date window using the User must specify a deactivation date within a time range option, the default value [Z] must fall within the [X] to [Y] window. Otherwise, the default value [Z] can be any valid duration after creation.

        • If you did not enable the option Default deactivation date for new Objects [Z] (seconds/minutes/hours/days) after creation time at the account-level, the setting will only apply to the group in which it is enabled.

        • If you enabled the option Default deactivation date for new Objects [Z] (seconds/minutes/hours/days) after creation time at the account-level and disabled the setting for a group, then the account-level setting will apply to the group. When creating a security object in this group, you can modify the deactivation date provided it falls within the maximum allowed date range if set at the account-level.

        • If the Default deactivation date for new Objects [Z] (seconds/minutes/hours/days) after creation time at the account-level differs from that at the group-level:

          • If the account-level default deactivation date is higher than the group-level date range, the group-level default deactivation date will take precedence for that specific group.

          • If the account-level default deactivation date is lower than the group-level date range, the group-level default deactivation date will take precedence for that specific group.

        For example, consider a scenario where the Key metadata policy is configured at the account-level first, then at the group-level:

        • Account A has the “deactivation date range” set to “0 to 15 days” and “default deactivation date” set to 10 days.

        • Group G1 has the “deactivation date range” set to “0 to 10 days” and “default deactivation date” set to 5 days.

        • Group G2 has both the “deactivation date range” and “default deactivation date” disabled.

        • Group G3 has no Key metadata policy set.

        In this case,

        • G2 will use the account-level deactivation date setting for the security objects in its group.

        • G3 will use the account-level deactivation date setting for the security objects in its group.

      • If you select the Forbid radio button, deactivating the key is not allowed.

    4. Custom Attribute: These are user-defined attributes that can be added to a security object's metadata. You can configure each attribute as either required or forbidden. Enter the attribute name (for example, Country) and specify whether the attribute should be required or forbidden by selecting the option Required or Forbid.

      • If you select Required, you can optionally configure the following settings:

        • The value cannot be blank (empty or only containing whitespace): If selected, the user must enter a non-blank value, which means empty or whitespace-only entries are not allowed.

        • Restrict value to one of the following values: If selected, you must provide a list of pre-defined values that the user must choose from.

          • Allow the value to be empty: Enter comma-separated values. For example, India, Australia, China, the US, and so on.

          • If you want to allow a blank value, select the Allow empty values check box. This permits an empty string as the attribute value when creating a security object.

            NOTE

            If The value cannot be blank check box is selected, it overrides the Allow empty values option and disallows empty values.

        • To configure additional custom attributes, click ADD ATTRIBUTE.

          Figure 5: Add custom attributes

      • If you select Forbid, the attribute specified in the Attribute name field cannot be added.

        Figure 6: Custom attributes forbid

  3. Click SAVE POLICY to apply the changes.

NOTE

  • If a Key metadata policy was set at the account-level before the group-level, refer to Section 2.0: Key Metadata Policy Behavior to understand how the DSM UI evaluates the configuration set at the existing account-level against the group-level configuration.

  • If a group-level Key metadata policy conflicts with the account-level policy, a validation error and does occurs, and the conflicting policy cannot be saved.

    Figure 7: Group-level policy error

4.0 Overriding Key Metadata Policy for Selected Key Types

By default, all types of keys are selected for Key metadata policy: AES, DES3, HMAC, OPAQUE, RSA, DSA, DES, EC, SECRET, LMS, XMSS, MLKEM, MLKEMBETA, MLDSA, MLDSABETA, CERTIFICATE, BIP32, ECKCDSA, KCDSA, SEED, ARIA, BLS.

Perform the following steps to override the default Key metadata policy for selected key types:

  1. Click OVERRIDE FOR KEY TYPES.

    Figure 8: Override for key types

  2. Select the key types from the drop down menu that should be overridden by the default Key metadata policy.

  3. To configure the metadata of security objects such as key description, activation date, deactivation date, and custom attribute applicable to the selected key types, refer to Section 3.0: Adding a Key Metadata Policy at Group-Level.

4.1 Handling Existing Non-Compliant Keys

  • All new keys will be allowed or denied based on the Key metadata policy rules.

  • Any existing keys that do not comply with the policy will remain in the group. However, these keys will be marked separately as policy-violating keys. For more information on the conditions applicable to policy violating keys, refer to the User's Guide: Group Cryptographic Policy.

    Figure 9: Handling existing non-compliant keys

When a key metadata policy is created at the group-level, three options are provided to handle non-compliant keys.  These options are described below:

  • Accept: Accept non-compliant objects even though they violate the current policy. If this option is selected, you may continue to use existing non-compliant keys, but you may not generate or import new non-compliant objects.

  • Forbid to use: Forbid any use of non-compliant objects. If this option is selected, you are not allowed to use non-compliant keys for any operation.

  • Limit usage: Restrict non-compliant objects so that they may only be used for “process operations” (DECRYPT, UNWRAPKEY, VERIFY, and MACVERIFY) on existing objects that violate these restrictions “Protect operations” (ENCRYPT, SIGN, WRAPKEY, DERIVEKEY, and MACGENERATE) are forbidden.

NOTE

If the non-compliance setting for account-level Key metadata policy is different from the group-level Key metadata policy, then the setting which is more restrictive is applied for the existing keys.

5.0 Delete A Group-Level Key Metadata Policy

Perform the following steps to edit or delete a group-level key metadata policy:

  1. Go to the detailed view of a group, and in the INFO tab, click EDIT POLICY for Key metadata policy.

  2. Scroll to the end of the screen, click DELETE POLICY to delete the Key metadata policy.

NOTE

If an account-level Key metadata policy was set, then the account Key metadata policy rules will be applicable for the group, even after deleting the group Key metadata policy.