Skip to main content

General Data Encryption

Use Vault to encrypt and decrypt data

You can use Vault keys created for encryption to encrypt and decrypt binary data or text values by converting them into a base64 string.

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 previous (non-current) 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.

Was this article helpful?

Contact us