Encryption and Decryption

The following keys can perform encryption and decryption tasks:

• AES-256-GCM

• ChaCha20

• RSA

Encryption

curl

curl -i -XPOST \
    -H 'authorization: bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwOjJlOmQ5OmUxOmI4OmEyOjM0OjM3Ojk5OjNhOjI0OmZjOmFhOmQxOmM4OjU5IiwidHlwIjoiSldUIn0.eyJhdWQiOiJodHRwczovL3Byb3ZpZGUuc2VydmljZXMvYXBpL3YxIiwiZXhwIjoxNTk5ODM1ODEzLCJpYXQiOjE1OTk3NDk0MTMsImlzcyI6Imh0dHBzOi8vaWRlbnQucHJvdmlkZS5zZXJ2aWNlcyIsImp0aSI6IjUzMDFhZjAwLTEyNjMtNGMxNC04Mjc0LTI2NWYzOTNlZDJiNSIsIm5hdHMiOnsicGVybWlzc2lvbnMiOnsic3Vic2NyaWJlIjp7ImFsbG93IjpbInVzZXIuNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIiwibmV0d29yay4qLmNvbm5lY3Rvci4qIiwibmV0d29yay4qLnN0YXR1cyIsInBsYXRmb3JtLlx1MDAzZSJdfX19LCJwcnZkIjp7InBlcm1pc3Npb25zIjo3NTUzLCJ1c2VyX2lkIjoiNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0sInN1YiI6InVzZXI6NGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0.fJL7wi5IfZdIZBoTXX0hFDBJuMtfU2Ub03oc0x7lD75MY9JSJ4DRdLCjiBK0DdYAv2D-V3erq9BtuooTkhUEsTAqciBhoxBygFAwvhnlxbdG_L_Fl9IyLQDow7LV7WY5odS4p1h8OAH_mpwfABDsc50uRLeJKtsWsOWzgahciIZgXGJrx-ogX-vEOrLHonytVcNZmWIeRDswO_SoZyc9Msx_Ywt6bMxVSC1ZS8t-5Spq-_xZqbGTDiM6MS0fAEsUidPZRPuZiXn473jj_dqkPbXt8pYHt4H9tdsMRGrFZbMRVxB-ebXeRhgIuTXrxrAmq6oLpw_WZ7pTrODVCeLqkRflkFculO3U1f8izsizXIX41goejOHECuE-VNXKGTr-dtOaDIlXzeejzuO-k4OjP7S2UFl98sNtj_eRjKLh4QTjd4HrPIpwjPUubA-tog76g1edeCHFkKUQzg3HGu1Lh-11tUXJeabdliRCeTrHTCAToAGUrLnihuTZRk7c9-ONeAbeKGALsciZIKMgDM-_wCQLdLbjokw_FlGiWhedp9xqFJJDpkenxElPfOesnmFaHqzAa_eFQuiC7wgdaeb06LdFOV3YmfQkmCHLdxGkRmz1mvjQZnmyoqwmKOBc8vVF9LScH6IsHn0gHn7vWUPnf2HGj3KUWevuoFmi7_2VlsA' \
    -H 'Content-Type: application/json' \
    https://vault.provide.services/api/v1/vaults/730afe0f-a62d-48e0-9d67-1e07c118fbf8/keys/9975e23f-b445-4349-a09f-dbbb4e8850c2/encrypt \
    -d '{
      "data": "text to be encrypted"
    }'
HTTP/2 200

Response JSON:

{
  "data": "7e415ad7f603db114a40a1a2f9aa28f6db546c6888cc10bb14e116b5f87cc0ffbe8cb4377af2cb8973de18fd8195caec"
}

The data returned in the response is hex-encoded.

Decryption

curl

curl -i -XPOST \
    -H 'authorization: bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwOjJlOmQ5OmUxOmI4OmEyOjM0OjM3Ojk5OjNhOjI0OmZjOmFhOmQxOmM4OjU5IiwidHlwIjoiSldUIn0.eyJhdWQiOiJodHRwczovL3Byb3ZpZGUuc2VydmljZXMvYXBpL3YxIiwiZXhwIjoxNTk5ODM1ODEzLCJpYXQiOjE1OTk3NDk0MTMsImlzcyI6Imh0dHBzOi8vaWRlbnQucHJvdmlkZS5zZXJ2aWNlcyIsImp0aSI6IjUzMDFhZjAwLTEyNjMtNGMxNC04Mjc0LTI2NWYzOTNlZDJiNSIsIm5hdHMiOnsicGVybWlzc2lvbnMiOnsic3Vic2NyaWJlIjp7ImFsbG93IjpbInVzZXIuNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIiwibmV0d29yay4qLmNvbm5lY3Rvci4qIiwibmV0d29yay4qLnN0YXR1cyIsInBsYXRmb3JtLlx1MDAzZSJdfX19LCJwcnZkIjp7InBlcm1pc3Npb25zIjo3NTUzLCJ1c2VyX2lkIjoiNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0sInN1YiI6InVzZXI6NGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0.fJL7wi5IfZdIZBoTXX0hFDBJuMtfU2Ub03oc0x7lD75MY9JSJ4DRdLCjiBK0DdYAv2D-V3erq9BtuooTkhUEsTAqciBhoxBygFAwvhnlxbdG_L_Fl9IyLQDow7LV7WY5odS4p1h8OAH_mpwfABDsc50uRLeJKtsWsOWzgahciIZgXGJrx-ogX-vEOrLHonytVcNZmWIeRDswO_SoZyc9Msx_Ywt6bMxVSC1ZS8t-5Spq-_xZqbGTDiM6MS0fAEsUidPZRPuZiXn473jj_dqkPbXt8pYHt4H9tdsMRGrFZbMRVxB-ebXeRhgIuTXrxrAmq6oLpw_WZ7pTrODVCeLqkRflkFculO3U1f8izsizXIX41goejOHECuE-VNXKGTr-dtOaDIlXzeejzuO-k4OjP7S2UFl98sNtj_eRjKLh4QTjd4HrPIpwjPUubA-tog76g1edeCHFkKUQzg3HGu1Lh-11tUXJeabdliRCeTrHTCAToAGUrLnihuTZRk7c9-ONeAbeKGALsciZIKMgDM-_wCQLdLbjokw_FlGiWhedp9xqFJJDpkenxElPfOesnmFaHqzAa_eFQuiC7wgdaeb06LdFOV3YmfQkmCHLdxGkRmz1mvjQZnmyoqwmKOBc8vVF9LScH6IsHn0gHn7vWUPnf2HGj3KUWevuoFmi7_2VlsA' \
    -H 'Content-Type: application/json' \
    https://vault.provide.services/api/v1/vaults/730afe0f-a62d-48e0-9d67-1e07c118fbf8/keys/9975e23f-b445-4349-a09f-dbbb4e8850c2/decrypt \
    -d '{
      "data": "7e415ad7f603db114a40a1a2f9aa28f6db546c6888cc10bb14e116b5f87cc0ffbe8cb4377af2cb8973de18fd8195caec"
    }'
HTTP/2 200

Response JSON:

{
  "data": "text to be encrypted"
}

Optional Nonce Usage

For ChaCha20 and AES-256-GCM keys, a 12-byte nonce is auto-generated and returned as part of the encrypted data response. Never encrypt with the same key more than 2³² times to reduce the risk of a nonce-repeat which will expose the key.

If you prefer to provide a nonce to remove the risk of a nonce repeat, typically by providing a sequential nonce, then the additional nonce details should be added to the post data. As the nonce is prepended to the encrypted hex-encoded response data, the nonce is not required in the post data when decrypting.

curl

curl -i -XPOST \
    -H 'authorization: bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwOjJlOmQ5OmUxOmI4OmEyOjM0OjM3Ojk5OjNhOjI0OmZjOmFhOmQxOmM4OjU5IiwidHlwIjoiSldUIn0.eyJhdWQiOiJodHRwczovL3Byb3ZpZGUuc2VydmljZXMvYXBpL3YxIiwiZXhwIjoxNTk5ODM1ODEzLCJpYXQiOjE1OTk3NDk0MTMsImlzcyI6Imh0dHBzOi8vaWRlbnQucHJvdmlkZS5zZXJ2aWNlcyIsImp0aSI6IjUzMDFhZjAwLTEyNjMtNGMxNC04Mjc0LTI2NWYzOTNlZDJiNSIsIm5hdHMiOnsicGVybWlzc2lvbnMiOnsic3Vic2NyaWJlIjp7ImFsbG93IjpbInVzZXIuNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIiwibmV0d29yay4qLmNvbm5lY3Rvci4qIiwibmV0d29yay4qLnN0YXR1cyIsInBsYXRmb3JtLlx1MDAzZSJdfX19LCJwcnZkIjp7InBlcm1pc3Npb25zIjo3NTUzLCJ1c2VyX2lkIjoiNGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0sInN1YiI6InVzZXI6NGM1ZDI5NjktYTQwYy00ZjZkLWFhMDItMjEzNTVmM2M5MDkxIn0.fJL7wi5IfZdIZBoTXX0hFDBJuMtfU2Ub03oc0x7lD75MY9JSJ4DRdLCjiBK0DdYAv2D-V3erq9BtuooTkhUEsTAqciBhoxBygFAwvhnlxbdG_L_Fl9IyLQDow7LV7WY5odS4p1h8OAH_mpwfABDsc50uRLeJKtsWsOWzgahciIZgXGJrx-ogX-vEOrLHonytVcNZmWIeRDswO_SoZyc9Msx_Ywt6bMxVSC1ZS8t-5Spq-_xZqbGTDiM6MS0fAEsUidPZRPuZiXn473jj_dqkPbXt8pYHt4H9tdsMRGrFZbMRVxB-ebXeRhgIuTXrxrAmq6oLpw_WZ7pTrODVCeLqkRflkFculO3U1f8izsizXIX41goejOHECuE-VNXKGTr-dtOaDIlXzeejzuO-k4OjP7S2UFl98sNtj_eRjKLh4QTjd4HrPIpwjPUubA-tog76g1edeCHFkKUQzg3HGu1Lh-11tUXJeabdliRCeTrHTCAToAGUrLnihuTZRk7c9-ONeAbeKGALsciZIKMgDM-_wCQLdLbjokw_FlGiWhedp9xqFJJDpkenxElPfOesnmFaHqzAa_eFQuiC7wgdaeb06LdFOV3YmfQkmCHLdxGkRmz1mvjQZnmyoqwmKOBc8vVF9LScH6IsHn0gHn7vWUPnf2HGj3KUWevuoFmi7_2VlsA' \
    -H 'Content-Type: application/json' \
    https://vault.provide.services/api/v1/vaults/730afe0f-a62d-48e0-9d67-1e07c118fbf8/keys/9975e23f-b445-4349-a09f-dbbb4e8850c2/encrypt \
    -d '{
      "data": "text to be encrypted",
      "nonce": 1
    }'
HTTP/2 200

Encrypting with RSA

RSA keys are asymmetric keypairs which can also be used to encrypt and decrypt. RSA does not use a nonce for encryption, so any nonce data passed to an RSA key for encryption will be ignored.

The maximum length of data that can be encrypted by RSA (we currently only implement the RSAES_OAEP_SHA_256encryption algorithm which uses the SHA-256 hash function) is keylength(bytes) - 66. So an RSA-4096keypair cannot encrypt more than 446-bytes of data (4096/8 - 66).