Skip to main content

Structured Data Encryption

Use Vault to encrypt and decrypt string values within JSON

You can encrypt or decrypt a specific field within a data structure by using Vault’s /v1/key/encrypt/structured and /v1/key/decrypt/structured endpoints. These endpoints accept a JSON as the structured_data parameter and a JSONPath expression as the filter parameter. By using this filter, you can specify which field in the JSON should be encrypted or decrypted.

Encrypt​

note

Only string values within a JSON can be encrypted.

Provide the following parameters:

  • id - The ID of a key designated for encryption and stored in Vault
  • structured_data - A JSON containing string values to be encrypted
  • filter - A JSONPath expression referencing a field to be encrypted within the JSON structure

Some algorithms may accept specific parameters. For example, GCM mode supports an optional additional_data parameter:

  • additional_data - The additional data provided during encryption, which will also be required during decryption to ensure message integrity, encoded in Base64 format

A JSON with the encrypted values will be returned under result.structured_data in the response.

Example​

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_VAULT_TOKEN="pts_zi5orj...7c6c5l"
POST/v1/key/encrypt/structured
curl --location 'https: //vault.$PANGEA_DOMAIN/v1/key/encrypt/structured' \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
  "structured_data": {
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "Resources": [
      {
        "id": "u1",
        "emails": [
          {
            "value": "john.doe@example.com",
            "type": "work",
            "primary": true
          }
        ]
      },
      {
        "id": "u2",
        "emails": [
          {
            "value": "jane.smith@example.com",
            "type": "work",
            "primary": true
          }
        ]
      }
    ]
  },
  "id": "pvi_krmhcpet4nhoi5sfqkm5xaq4rauuj7tz",
  "filter": "$.Resources[*].emails[*].value"
}'

The fields referenced from the JSONPath expression provided in the request filter parameter will be encrypted with the specified Vault key and returned under result.structured_data in the response:

response
{
  "request_id": "prq_yifhbs4rhmqvjj42q6bkqon5zpeoha2z",
  "result": {
    "algorithm": "AES-GCM-256",
    "id": "pvi_krmhcpet4nhoi5sfqkm5xaq4rauuj7tz",
    "structured_data": {
      "Resources": [
        {
          "emails": [
            {
              "primary": true,
              "type": "work",
              "value": "Wq7uYNtTYtaDdwTw+ZJSl99qVJoWF2qN/kId58SVKtP02+qJZjgODx2SJ8ZnKpdm"
            }
          ],
          "id": "u1"
        },
        {
          "emails": [
            {
              "primary": true,
              "type": "work",
              "value": "lbzMbpmp8rYtY5YG3ofaDz/8O3FP6qJMm7gRqptCjLP6LyGjDitYN6i0R7iNb6DXhy0="
            }
          ],
          "id": "u2"
        }
      ],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ]
    },
    "version": 1
  },
  "status": "Success",
  "summary": "Message encrypted",
  . . .
}

Note that the key ID and its version are also included in the response.

Decrypt​

Provide the following parameters:

  • id - The Vault key ID that was used for encrypting the data
  • structured_data - A JSON with values encrypted by Vault
  • filter - A JSONPath expression referencing a field to be decrypted within the JSON structure

If the original data was encrypted with a previous (non-current) version of the Vault key, you must provide this specific version number during decryption:

  • version - An integer representing the version of the key used for encryption. If you omit the version in the request parameters, the default (current) version will be used. If the provided version does not match the one used for encryption, decryption of the encrypted values will fail.

    This situation may occur if the Vault key used for encryption has been rotated, and the current version no longer corresponds to this key.

If any additional data was used for encryption, it must also be provided during decryption:

  • additional_data - The additional data provided during encryption

A JSON with the decrypted values will be returned under result.structured_data in the response.

Example​

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_VAULT_TOKEN="pts_zi5orj...7c6c5l"
POST/v1/key/decrypt/structured
curl --location 'https: //vault.$PANGEA_DOMAIN/v1/key/decrypt/structured' \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "pvi_krmhcpet4nhoi5sfqkm5xaq4rauuj7tz",
  "version": 1,
  "structured_data": {
    "Resources": [
      {
        "emails": [
          {
            "primary": true,
            "type": "work",
            "value": "Wq7uYNtTYtaDdwTw+ZJSl99qVJoWF2qN/kId58SVKtP02+qJZjgODx2SJ8ZnKpdm"
          }
        ],
        "id": "u1"
      },
      {
        "emails": [
          {
            "primary": true,
            "type": "work",
            "value": "lbzMbpmp8rYtY5YG3ofaDz/8O3FP6qJMm7gRqptCjLP6LyGjDitYN6i0R7iNb6DXhy0="
          }
        ],
        "id": "u2"
      }
    ],
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User"
    ]
  },
  "filter": "$.Resources[*].emails[*].value"
}'

The fields referenced from the JSONPath expression provided in the request filter parameter will be decrypted with the specified Vault key and returned under result.structured_data in the response:

response
{
  "request_id": "prq_lb3njyts5i2h2rl4lu4cktrfrpakr4tk",
  "result": {
    "algorithm": "AES-GCM-256",
    "id": "pvi_krmhcpet4nhoi5sfqkm5xaq4rauuj7tz",
    "structured_data": {
      "Resources": [
        {
          "emails": [
            {
              "primary": true,
              "type": "work",
              "value": "john.doe@example.com"
            }
          ],
          "id": "u1"
        },
        {
          "emails": [
            {
              "primary": true,
              "type": "work",
              "value": "jane.smith@example.com"
            }
          ],
          "id": "u2"
        }
      ],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ]
    },
    "version": 1
  },
  "status": "Success",
  "summary": "Structured data decrypted",
  . . .
}

Was this article helpful?

Contact us