Skip to main content

Encrypt and Decrypt

Use Vault keys for encrypting and decrypting data

You can use Vault keys specifically created for encryption to encrypt and decrypt messages. Additionally, you can encrypt and decrypt string values encapsulated within JSON.

Symmetric Encryption

Vault's /v1/key/encrypt and /v1/key/decrypt endpoints enable quick encryption and decryption of text.

Encrypt

To encrypt a message, provide the following parameters:

  • id - The ID of a key designated for encryption and stored in Vault
  • plain_text - The data to be encrypted, encoded in Base64 format

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

The encrypted message, in Base64-encoded format, will be returned under result.cipher_text in the response.

Example

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_VAULT_TOKEN="pts_zi5orj...7c6c5l"
POST/v1/key/encrypt
curl --location 'https://vault.$PANGEA_DOMAIN/v1/key/encrypt' \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "pvi_krmhcpet4nhoi5sfqkm5xaq4rauuj7tz",
  "plain_text": "bWVzc2FnZXRvZW5jcnlwdA==",
  "additional_data": "Y29udGV4dHVhbC1kYXRhCg=="
}'

The encrypted message will be returned under result.cipher_text in the response:

response
{
  "status": "Success",
  "summary": "Message encrypted",
  "result": {
      "algorithm": "AES-GCM-256",
      "cipher_text": "1tXVA5kEtK7PkQBAziI+0y7mi2qBpYiHMbH7wkjNWosB5bcBTbHtg4ZRFlc=",
      "id": "pvi_krmhcpet4nhoi5sfqkm5xaq4rauuj7tz",
      "version": 1
  },
  . . .
}

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

Decrypt

To decrypt a message, provide the following parameters:

  • id - The Vault key ID used for encrypting the message
  • cipher_text - The message encrypted by Vault

If your message was encrypted with a deactivated version of the Vault key, you must provide that 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, the decryption of messages will fail.

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

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

  • additional_data - The additional data provided during encryption

The decrypted message in Base64-encoded format will be returned under result.plain_text in the response.

Example

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_VAULT_TOKEN="pts_zi5orj...7c6c5l"
POST/v1/key/decrypt
curl --location 'https://vault.$PANGEA_DOMAIN/v1/key/decrypt' \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "pvi_krmhcpet4nhoi5sfqkm5xaq4rauuj7tz",
  "version": 1,
  "cipher_text": "1tXVA5kEtK7PkQBAziI+0y7mi2qBpYiHMbH7wkjNWosB5bcBTbHtg4ZRFlc=",
  "additional_data": "Y29udGV4dHVhbC1kYXRhCg=="
}'

The decrypted message encoded in Base64 format will be returned under result.plain_text in the response:

response
{
  "status": "Success",
  "summary": "Message decrypted",
  "result": {
      "algorithm": "AES-GCM-256",
      "id": "pvi_krmhcpet4nhoi5sfqkm5xaq4rauuj7tz",
      "plain_text": "bWVzc2FnZXRvZW5jcnlwdA==",
      "version": 1
  },
  . . .
}

Asymmetric Encryption

To delegate encryption to a third party (for example, when receiving encrypted messages from customers) you can create an asymmetric encryption key in Vault and share its public key with the encrypting party.

In the Pangea User Console , you can get the public key by following these steps:

  1. Select the asymmetric encryption key in Vault.
  2. Click on the three-dot menu icon located in the top right.
  3. Choose Copy public key.

Copy public key option selected for an asymmetric key in Pangea User Console

You can also programmatically obtain the public key, using Vault’s /v1/get endpoint:

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_VAULT_TOKEN="pts_zi5orj...7c6c5l"
POST/v1/get
curl --location 'https://vault.$PANGEA_DOMAIN/v1/get' \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "pvi_7n3op7dxt5dt66u357haf7gba6lk33dm"
}'

The key is returned in result.public_key within the response:

response
{
  "result": {
    "algorithm": "RSA-OAEP-2048-SHA1",
    "public_key": "-----BEGIN RSA PUBLIC KEY-----\nMII...QAB\n-----END RSA PUBLIC KEY-----\n",
    "state": "active",
    "version": 1,
    . . .
  },
  "item_state": "enabled",
  "purpose": "encryption",
  "type": "asymmetric_key",
  . . .
}

When you receive a message encrypted with this public key, you can decrypt it by referencing the Vault key ID at the /v1/key/decrypt endpoint, which will use the internally stored private key.

Structured Data Encryption

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 deactivated 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",
  . . .
}

Format Preserving Encryption (FPE)

FPE keeps the format of the input data in the encrypted output. Unlike traditional encryption methods that turn data into an unreadable string of a fixed length, FPE retains the original data length, character set per position, and structure, including the positions of delimiters and separators. For example, with FPE, the digits in a phone number can be encrypted, but the parentheses, spaces, and hyphens stay in their original positions.

Because the format is preserved, FPE can be used to retrofit security into existing systems, such as legacy databases and applications that expect and validate data in a specific format. It also helps meet compliance requirements where data format and structure are mandated. Common applications of FPE include maintaining the confidentiality of Personally Identifiable Information (PII), such as social security numbers, phone numbers, and credit card numbers while keeping them compatible with data systems and maintaining their appearance in logs. Additionally, in the event of a data leak, an attacker who obtains such data will not know that it is encrypted.

You can create a key for Format Preserving Encryption with one of the supported FPE algorithms on Vault's Secrets & Keys page in the Pangea User Console.

Encrypt

You can use FPE keys to encrypt a single value by using Vault’s /v1/key/encrypt/transform endpoint.

Provide the following parameters:

  • id - The ID of a key designated for Format Preserving Encryption and stored in Vault
  • plain_text - The data to be encrypted
  • alphabet - A set of characters used for format-preserving encryption. Characters not included in the selected set will remain unchanged in the encrypted output. The available choices are:
    • numeric - Numeric (0-9)
    • alphalower - Lowercase alphabet (a-z)
    • alphaupper - Uppercase alphabet (A-Z)
    • alphanumericlower - Lowercase alphabet with numbers (a-z, 0-9)
    • alphanumericupper - Uppercase alphabet with numbers (A-Z, 0-9)
    • alphanumeric - Alphanumeric (a-z, A-Z, 0-9)

Optionally, you can specify:

  • tweak - A user-provided tweak string. If a tweak value is not provided, a random string will be generated and returned in the API response.

A tweak is an additional input used alongside the plaintext and encryption key to enhance security. It makes it harder for attackers to use statistical methods to break the encryption. Different tweak values will produce different outputs for the same encryption key and data. The original tweak value used for encryption is required to decrypt the data.

The tweak value will be returned in the response from the /v1/key/encrypt/transform endpoint. If you didn't provide a custom value, save the one that was returned during encryption to decrypt the output. If you need to know or share the tweak value before the encryption, use a custom one and save it in a safe place.

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

Example

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_VAULT_TOKEN="pts_zi5orj...7c6c5l"
POST/v1/key/encrypt/transform
curl --location "https://vault.$PANGEA_DOMAIN/v1/key/encrypt/transform" \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "pvi_tcjl6nb42frvajedoeyws6ozhvkyfvdz",
  "plain_text": "(503) 404-3000",
  "alphabet": "numeric"
}'

The encrypted message and the parameters used for encryption will be returned under the "result" key in the response:

/v1/key/encrypt/transform response
{
  "result": {
      "algorithm": "AES-FF3-1-128-BETA",
      "alphabet": "numeric",
      "cipher_text": "(075) 322-4601",
      "id": "pvi_tcjl6nb42frvajedoeyws6ozhvkyfvdz",
      "tweak": "gQkPMFB",
      "version": 1
  },
  "status": "Success",
  "summary": "Message encrypted",
  ...
}
note

Using the same key version and tweak value will result in the same encrypted output:

POST/v1/key/encrypt/transform
curl --location "https://vault.$PANGEA_DOMAIN/v1/key/encrypt/transform" \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "pvi_tcjl6nb42frvajedoeyws6ozhvkyfvdz",
  "plain_text": "(503) 404-3000",
  "alphabet": "numeric",
  "tweak": "gQkPMFB",
  "version": 1
}'
/v1/key/encrypt/transform response
{
  "result": {
      "algorithm": "AES-FF3-1-128-BETA",
      "alphabet": "numeric",
      "cipher_text": "(075) 322-4601",
      "id": "pvi_tcjl6nb42frvajedoeyws6ozhvkyfvdz",
      "tweak": "gQkPMFB",
      "version": 1
  },
  "status": "Success",
  "summary": "Message encrypted",
  ...
}

Decrypt

To decrypt the encrypted message, provide the encrypted output and parameters used for encryption:

  • cipher_text - The message encrypted by Vault
  • id - The Vault key ID used for encrypting the message
  • alphabet - The set of characters used for encrypting the message
  • tweak - The tweak value used for encrypting the message

If your message was encrypted with a deactivated version of the Vault key, you must provide that 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, the decryption of messages will fail.

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

Example

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_VAULT_TOKEN="pts_zi5orj...7c6c5l"
POST/v1/key/decrypt/transform
curl --location "https://vault.$PANGEA_DOMAIN/v1/key/decrypt/transform" \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "pvi_tcjl6nb42frvajedoeyws6ozhvkyfvdz",
  "cipher_text": "(075) 322-4601",
  "alphabet": "numeric",
  "tweak": "gQkPMFB",
  "version": 1
}'

The decrypted message will be returned under result.plain_text in the response:

/v1/key/decrypt/transform response
{
  "result": {
      "algorithm": "AES-FF3-1-128-BETA",
      "id": "pvi_tcjl6nb42frvajedoeyws6ozhvkyfvdz",
      "plain_text": "(503) 404-3000",
      "tweak": "gQkPMFB",
      "version": 1
  },
  "status": "Success",
  "summary": "Message decrypted",
  ...
}

Was this article helpful?

Contact us