Filtering Security Objects Using Fortanix DSM REST API

1.0 Introduction

The Filtering Security Objects Using Fortanix-Data-Security-Manager (DSM) REST API developer article describes how to filter security objects using the DSM REST API, enabling you to retrieve specific security objects based on various query attributes.

It also covers the following key topics:

• Filter syntax, rules, and generic filter operators

• Filter examples

• Supported fields for filtering security objects in Fortanix DSM

2.0 Filter Query language

The queries used for filtering are JavaScript Object Notation (JSON) based expressions that define specific conditions to filter items within a data collection. This JSON-based syntax is similar to MongoDB’s Query Language (MQL).

Using composition of specific queries, you can construct filters that target particular attributes, perform comparisons, and combine multiple conditions.

Examples:

• The {} represents an empty filter, which matches all items without any specific conditions.

• The following query retrieves the keys that are less than or equal to 256 in size:

  {"key_size":{"$lte":256}}

2.1 Filter Structure

Filters are composed of conditions that specify how security objects should be matched.

These conditions use the basic structure: field_name operator value

• field_name: The attribute of the security object to filter by. For example: name, type, or created_at.

  • Field names are essentially values but can optionally start with a $ symbol, which must be escaped with a backslash (\\$) to avoid confusion with operator names.

  • Backus-Naur Form (BNF) rule: <field_name> ::= <value> | "\\$" <value>

• operator: The comparison operator used to compare the field value. For example, eq, ne, gt,lt.

  For more details, refer to Section 3.0: Supported Filter Operators and Examples.

  • These are always prefixed with a $, followed by a value. This convention distinguishes operator names from field names.

  • BNF Rule: <operator> ::= "$" <value>

• value: The value to compare the field against. For example, a string, number, or date.

  • It can follow different naming conventions such as snake_case, kebab-case, camelCase, or PascalCase.

  • Special characters like $ and _ are reserved for specific purposes.

  • BNF rule: <value> ::= /[a-zA-Z][a-zA-Z0-9_-]*/

2.2 Filter Syntax

The filter query language in Fortanix DSM primarily consists of two types of syntactical classes:

2.2.1 Literal

A literal is a JSON value that is treated as-is and is not interpreted further.

In Fortanix DSM, a literal could be a string, number, boolean, or any other valid JSON value used as part of a filter query.

• Example 1: String Literal

  If you want to filter security objects by a specific name, you can use a string literal.

  {"name": "MyEncryptionKey"}

  This is a literal value "MyEncryptionKey" that matches the name field of the security objects.

• Example 2: Number Literal

  If you want to filter security objects by a specific numeric value such as kid, you could use a number literal.

  {"kid": "1234"}

  This filter retrieves the key where the kid field exactly matches "1234".

2.2.2 Predicate<T>

A predicate is a condition that evaluates to a boolean based on the type of the input (T).

The predicates in Fortanix DSM filters are usually represented as JSON objects with a single operator applied to an operand.

• Example 1: Predicate with eq Operator

  If you want to filter security objects where the status is equal to active, the predicate is:

  {"status": {"$eq": "active"}}

  This predicate checks if the status field is "active."

• Example 2: Predicate with in Operator

  If you want to filter security objects where the type is one of a list of values, you can use the in operator.

  For example, to filter for objects where type is either "RSA" or "AES", the predicate is:

  {"type": {"$in": ["RSA", "AES"]}}

  This predicate checks if the type field is either "RSA" or "AES".

2.3 Syntax Sugar in Filter Queries

In the Fortanix DSM REST API filtering, syntax sugar refers to making the process of writing queries simpler and more intuitive. Instead of manually writing detailed operators, the system automatically wraps them for you, making the queries more concise and easier to construct.

Refer to the following syntax sugar rules:

1. Implicit $eq Operator

   When a Predicate<T> is expected, but a JSON value of a type other than an object is provided, it is automatically wrapped in an $eq operator.

   Example:

   Input: 42

   Expanded: { "$eq": 42 }

2. Implicit $match Operator

   When a <Predicate<T>> is expected, but a JSON object is found that does not follow the predicate syntax (that is, it doesn't have a single $-prefixed key), the object is automatically wrapped in a $match operator.

   Examples:

   • Input: {}

     Expanded: { "$match": {} }

   • Input: { "key_size": { "$gte": 256 } }

     Expanded: { "$match": { "key_size": { "$gte": 256 } } }

These rules allow for more concise and readable filter queries by automatically wrapping values in the appropriate operators when necessary.

3.0 Supported Filter Operators and Examples

The Fortanix DSM REST API supports a variety of operators for filtering Fortanix DSM security objects.

This section provides descriptions of each operator, along with relevant examples.

3.1 AND

The and operator is used to combine multiple conditions, ensuring that all specified conditions must be true to obtain the desired result.

'filter: {"$and":[{"obj_type":{"$in":["AES","DES3"]}},{"creator_type":{"$eq":"User"}}, {"state":{"$ne":"Compromise"}}, {"creator_id":{"$text":{"$search":"542c9eeb-333c-4b30-b0c6-b73260866cfb"}}}]}'

This query retrieves a list of keys that meet all of the following conditions:

• The object type is either "AES" or "DES3".

• The creator is a "User".

• The key state is not "Compromised".

• The creator ID is "542c9eeb-333c-4b30-b0c6-b73260866cfb".

3.2 OR

The or operator is used to combine multiple conditions, ensuring that at least one of the conditions must be true to obtain the desired result.

{"key_ops":{"$any":{"$or":[{"$eq":"ENCRYPT"},{"$eq":"DECRYPT"},{"$eq":"WRAPKEY"},{"$eq":"UNWRAPKEY"}]}}}

This query retrieves the keys that have at least one of the ENCRYPT, DECRYPT, WRAPKEY, or UNWRAPKEY operations.

3.3 NOT

The not operator is used to negate a condition. It returns the result that do not match the given condition.

{"$not": { "status": { "$eq": "active" }}}

This query retrieves the keys where the status is not "active."

3.4 Exists

The exists operator checks whether a specific field is present, regardless of its value. It is helpful for finding objects that either have a value or lack one.

{"state": { "$exists": true }}

This query retrieve keys where the state field exists.

3.5 Text

The text operator is used to perform a full-text search on string fields. It allows you to search for an object containing specific text in a field. This is especially useful for fields with large amounts of text.

{
  "name": {
    "$text": {
      "$search": "encryption"
    }
  }
}

This query retrieves keys whose name contains "encryption" (upper or lower case) anywhere.

3.6 Range

The range operator is used to filter objects by a range of values, typically for numerical or date fields. It allows you to specify both a lower and upper bound for the field.

{ "created_at": { "$range": { "$gte": "2025-01-01T00:00:00Z", "$lte": "2025-12-31T23:59:59Z" } }}

This query retrieves keys where the creation date falls between January 1, 2025, and December 31, 2025.

3.7 Match

The match operator is used to perform an exact match against a field value. It is similar to eq but is specifically designed to handle cases where exact values need to be matched for multiple operands.

{
  "$match": {
    "first_name": {
      "$eq": "John"
    },
    "user_email": {
      "$eq": "[email protected]"
    }
  }
}

This query retrieves the objects that contain a field first_name with value "John" and a field user_email that is "[email protected]".

3.8 All

The all operator is used to filter objects where all specified conditions must be true, similar to and, but typically used when applied to array fields or multiple conditions inside a single field.

{ "status": { "$all": ["active", "preactive"] }}

This query retrieves both active and pre-active keys.

3.9 Any

The any operator checks if any of the specified conditions are true for the given field. It is commonly used when working with array fields to match if at least one value from a list is present.

{ "status": { "$any": ["active", "preactive"] }}

This query retrieves either active or pre-active or both keys.

3.10 Size

The size operator is used to filter objects based on the length or size of an array or string field. It allows you to retrieve objects where the specified field has a certain number of elements or characters.

{"key_ops": {"$size": 3}}

This query retrieves the keys that have exactly three permissions in the key_ops field.

3.11 Equals (eq)

The eq operator is used to check if a field's value equals the specified value. It returns objects where the field value is exactly the same as the given value.

{"creator_type":{"$eq":"User"}}

This query retrieves the keys whose creator is a "User".

3.12 Not Equals (ne)

The ne operator checks if a field's value is not equal to the specified operand. It returns objects where the field value differs from the operand.

{"state":{"$ne":"Compromised"}}

This query retrieves the keys whose key state is not "Compromised".

3.13 In List (in)

The in operator is used to check if a field's value is contained within a list of values. It allows filtering objects based on multiple possible values for a field.

{"obj_type":{"$in":["AES","DES3"]}}

This query retrieves the keys whose object type is either AES or DES3.

3.14 Not in List (nin)

The nin operator is used to check if a field's value is not contained within a list of values. It returns objects where the field value does not match any of the values in the specified list.

{"obj_type":{"$nin":["LMS","XMSS","MLKEM","MLDSA"]}}

This query retrieves keys that are not of the LMS, XMSS, MLKEM, or MLDSA object types.

3.15 Less Than (lt)

The lt operator checks if a field's value is less than the specified value. It is useful for numerical or date-based comparisons.

{"created_at":{"$lt":"20250311T053633Z"}}

This query retrieves the keys created before 11 March 2025, at 5:36:33 am UTC.

3.16 Less Than or Equal To (lte)

The lte operator checks if a field's value is less than or equal to the specified value. It is useful when you want to include the boundary value in the query.

{"key_size":{"$lte":256}}

This query retrieves the keys that are less than or equal to 256 in size.

3.17 Greater Than (gt)

The gt operator checks if a field's value is greater than the specified value. It is useful for numerical or date-based comparisons.

{"expires":{"$gt":"20240311T053633Z"}}

This query retrieves the keys with expiry dates later than 11 March 2024, at 5:36:33 am UTC.

3.18 Greater Than or Equal To (gte)

The gte operator checks if a field's value is greater than or equal to the specified value. It is useful when you want to include the boundary value in the query.

{"key_size":{"$gte":128}}

This query retrieves the keys that are greater than or equal to 128 in size.

4.0 Available Filter Attributes

Refer to the following list of filter attributes available for security objects, along with their corresponding filter elements in the Fortanix DSM user interface (UI):

• name: The unique name of the key.

• kid: The key ID, which corresponds to "UUID" in the UI.

• wrapping_key: This functionality is not currently available in the UI.

  • It refers to the Group Key Encryption Key (KEK) feature, which allows users to protect keys in a group with another key from a different group.

  • It allows searching for keys whose KEK matches a provided UUID.

• group_name: The name of the group, which corresponds to "Group" in the UI.

• group_id: This does not correspond to "Group" in the UI. It is similar to group_name but accepts the group’s UUID.

• obj_type: The type of the key, corresponding to "Type" in the UI.

• creator_name: The person who created the key, corresponding to "Creator" in the UI.

• creator_id: The creator’s ID, which accepts the creator's UUID.

• creator_type: The type of the key creator, corresponding to "Creator Type" in the UI.

• created_at: The date and time when the key was created, corresponding to "Created" in the UI. The timestamp should be specified in ISO format, with the timezone as "Z" (UTC time).

• enabled: Indicates whether the key is enabled.

• key_ops: The operations supported by the key, corresponding to "Key Ops" in the UI.

• key_size: The available key size, corresponding to "Key Size" in the UI.

• elliptic_curve: Corresponds to "Elliptic Curve" in the UI.

• description: The key’s description, corresponding to "Description" in the UI.

• expires: The key's expiry state, corresponding to "Deactivated" in the UI. The timestamp should also be in ISO format with timezone "Z".

  NOTE

  At the key level, the field is called deactivation_date, but for filtering, the term expires should be used.

• state: The current state of the key, corresponding to "State" in the UI.

• custom_attributes: This refers to "Custom Attributes" in the UI, where an attribute is a user-defined key-value pair (for example, "custom_key").

  In the API, this is represented as custom_attributes.custom_key.

  Example:

  {"custom_attributes.custom_key": {"$text": {"$search": "1"}}}

  This query retrieves security objects where the custom attribute "custom_key" contains a value that includes "1".

For more details on filtering security objects using UI, refer to the User's Guide: Fortanix Data Security Manager Key Lifecycle Management.

5.0 Best Practices

The following are some of the best practices for filtering security objects using Fortanix DSM REST API:

• Use Specific Filters: Narrow down your search with specific filters to avoid retrieving unnecessary data.

  For example, if you are only interested in "active" keys, filter by the status field.

• Combine Filters: You can combine multiple conditions using logical operators such as and, or.

  For example, filter by both type and status to get more refined results.

• Use Date Filters: When working with sensitive data or rotating keys, date-based filtering (for example, created_at) can help you find objects created or modified within a specific time range.

• Use Wildcards for String Matching: When working with string fields such as name, use the like operator with wildcards (for example, % for partial matching) to find objects that partially match a pattern.