Skip to main content

Encrypt and Decrypt

Use Vault keys for Encryption and Decryption

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.

Encryption​

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 within the response.

Decryption​

To decrypt a message, provide the following parameters:

  • id - The Vault key ID that was 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 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 assumed. If the provided version does not match the one used for encryption, 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 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.

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

Example​

  1. Encrypt a message:

    POST/v1/key/encrypt
    curl --location 'https://vault.aws.us.pangea.cloud/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 within 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.

  2. Decrypt the encrypted message:

    POST/v1/key/decrypt
    curl --location 'https://vault.aws.us.pangea.cloud/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 within 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:

POST/v1/get
curl --location 'https://vault.aws.us.pangea.cloud/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.

Encrypting and Decrypting Structured Data​

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.

Structured Data Encryption​

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 within the response.

Structured Data Decryption​

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 assumed. 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 within the response.

Example​

  1. Perform a bulk encryption on user data:

    POST/v1/key/encrypt/structured
    curl --location 'https: //vault.dev.aws.pangea.cloud/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 within 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.

  2. Perform bulk decryption on user data:

    POST/v1/key/decrypt/structured
    curl --location 'https: //vault.dev.aws.pangea.cloud/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 within 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