Data Encryption

Creates a new named encryption key of the specified type. The values set here cannot be changed after key creation.

• type (required)
  Specifies the type of key to create. You can create the following types of keys:

  • aes256-gcm96

    This is a AES-256 key wrapped with GCM using a 12-byte nonce size (symmetric). This is the default type.

  • ecdsa-p256

    This is a ECDSA key using the P-256 elliptic curve (asymmetric).

• derived (optional)

  Set it to true to indicate that the key derivation must be used for encryption or decryption. If you use this parameter, you must provide a context that is used for key derivation in all encrypt or decrypt requests to this named key. By default, it is set to false.

• convergent_encryption (optional)

  Set it to true for the key to support convergent encryption. In convergent encryption, the plain text creates the same cipher text. This parameter requires the derived parameter to be set to true. When enabled, each encryption, decryption, rewrap, or datakey operation derives a nonce value instead of a random value. The key space for the nonce value is 96 bit. The default value is false.

  Note: For complete security, you must generate unique nonce values with a given context
• exportable (optional)

  Set it to true to indicate that the key is exportable. This option is required only when you need to export out the value of the key. For more information, see vault-service-data-encryption.html#reference_36decd1d-6189-41a6-81d6-31b68f01f4a5__retrieving_specific_type_of_key. The default value is false.

{
    "data":{
        "type":"aes256-gcm96",
        "deletion_allowed":false,
        "derived":false,
        "exportable":false,
        "keys":{
            "1":1442851412
        },
        "min_decryption_version":0,
        "name":"foo",
        "supports_encryption":true,
        "supports_decryption":true,
        "supports_derivation":true,
        "supports_signing":false
    }
}

{
"data":{
    "keys":["foo","bar"]
},
"lease_duration":0,
"lease_id":"",
"renewable":false
}

• min_decryption_version (optional)
  Specify the minimum version of ciphertext allowed to be decrypted. This value can be used for the following:

  • As part of a key rotation policy to prevent decryption of the old copies of ciphertext.
  • For key signatures to control the minimum version of signature used for key verification.
  • For keyed-hash message authentication code (HMAC) to control the minimum version of a key allowed to be used as the key for the HMAC function.

  The default value is 0.
• deletion_allowed (optional)

  Set to true to allow the key to be deleted. The default value is false.

/encryption/export/signing-key/<name>(/<version>)

/encryption/export/hmac-key/<name>(/<version>)

{
    "data":{
        "name":"foo",
        "keys":{
        "1":"eyXYGHbTmugUJn6EtYD/yVEoF6pCxm4R/cMEutUm3MY=",
        "2":"Euzymqx6iXjS3/NuGKDCiM2Ev6wdhnU+rBiKnJ7YpHE="
        }
    }
}

• plaintext (required)

  Specify the base64-encoded plain-text value that you need to encrypt.

• context (optional)

  Specify the base64-encoded context for deriving the key. This parameter is required if you set the convergent_encryption parameter to true while generating a new key.

• nonce (optional)

  Specify the base64-encoded nonce value. The value must be exactly 96 bits (12 bytes) long.

  Note: You must never reuse a nonce value or the generated encryption key for any given context.
• batch_input (optional)

  Specify a list of items to be encrypted in a single batch. If this parameter is set, the parameters plaintext, context and nonce are ignored.

  Use the following format for the input:

  [
  {
  "context":"c2FtcGxlY29udGV4dA==",
  "plaintext":"dGhlIHF1aWNrIGJyb3duIGZveA=="
  },
  {
  "context":"YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
  "plaintext":"dGhlIHF1aWNrIGJyb3duIGZveA=="
  },
  ...
  ]

• convergent_encryption (optional)

  Set it to true for the generated key to support convergent encryption. In convergent encryption, the plain text creates the same cipher text. This parameter is used only when the specified key does not exist and a new key is created. If a new key is generated, it is created with key derivation enabled and will require all requests to carry both a context and 96-bit (12-byte) nonce. When enabled, each encryption operation derives a nonce value instead of a random value. Therefore when the same context and nonce are supplied, the same ciphertext is generated.

  Note: For complete security, you must generate unique nonce values with a given context

{
    "data":{
        "ciphertext":"vault:v1:abcdefgh"
    }
}

• ciphertext (required)

  Specify the encrypted ciphertext that you need to decrypt.

• context (optional)

  Specify the base64-encoded context for deriving the key. This parameter is required if you set the convergent_encryption parameter to true while generating a new key.

• nonce (optional)

  Specify the base64-encoded nonce value that you specified during encryption.

• batch_input (optional)

  Specify a list of items to be decrypted in a single batch. If this parameter is set, the parameters ciphertext, context and nonce are ignored.

  Use the following format for the input:

  [
  {
  "context":"c2FtcGxlY29udGV4dA==",
  "ciphertext":"vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7d
  VI="
  },
  {
  "context":"YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
  "ciphertext":"vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4ls
  FA="
  },
  ...
  ]

{
    "data":{
        "plaintext":"dGhlIHF1aWNrIGJyb3duIGZveAo="
    }
}

• ciphertext (required)

  Specify the encrypted ciphertext that you need to rewrap.

• context (optional)

  Specify the base64-encoded context for deriving the key. This parameter is required if you set the convergent_encryption parameter to true while generating a new key.

• nonce (optional)

  Specify the base64-encoded nonce value that you specified during encryption.

• batch_input (optional)

  Specify a list of items to be rewrapped in a single batch. If this parameter is set, the parameters ciphertext, context and nonce are ignored.

  Use the following format for the input:

  [
  {
  "context":"c2FtcGxlY29udGV4dA==",
  "ciphertext":"vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7d
  VI="
  },
  {
  "context":"YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
  "ciphertext":"vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4ls
  FA="
  },
  ...
  ]

{
    "data":{
        "ciphertext":"vault:v2:abcdefgh"
    }
}

• plaintext|wrapped (path parameter) (required)

  If you specify plaintext, the plain-text key is returned along with the ciphertext. If you specify wrapped, only the ciphertext value is returned.

• context (optional)

  Specify the base64-encoded context for deriving the key. This parameter is required if you set the convergent_encryption parameter to true while generating a new key.

• nonce (optional)

  Specify the base64-encoded nonce value. The value must be exactly 96 bits (12 bytes) long.

  Note: You must never reuse a nonce value or the generated encryption key for any given context.
• bits (optional)

  Specify the number of bits in the requested key. You can specify 128, 256, or 512. The default value is 256.

{
    "data":{
        "plaintext":"dGhlIHF1aWNrIGJyb3duIGZveAo=",
        "ciphertext":"vault:v1:abcdefgh"
    }
}

• bytes (optional)

  Specify the number of bytes to return. The default value is 32 (256 bits). You can specify this value either in the request body, or as a part of the URL. The URL format is as follows:

  /encryption/random/48

• format (optional)

  Specify the encoding for the output value. You can specify either hex or base64. The default value is base64.

{
    "data":{
        "random_bytes":"dGhlIHF1aWNrIGJyb3duIGZveAo="
    }
}

• input (required)

  Specify the base64-encoded input data.

• algorithm (optional)
  Specify the hash algorithm to use. You can specify this value either in the request body, or as a part of the URL. The URL value takes precedence if both are set. You can specify the following algorithms:

  • sha2-224
  • sha2-256
  • sha2-384
  • sha2-512

  The default value is sha2-256.
• format (optional)

  Specify the encoding of the output value. You can specify either hex or base64. The default value is hex.

{
    "data":{
        "sum":"dGhlIHF1aWNrIGJyb3duIGZveAo="
    }
}

• input (required)

  Specify the base64-encoded input data.

• algorithm (optional)
  Specify the hash algorithm to use. You can specify this value either in the request body, or as a part of the URL. The URL value takes precedence if both are set. You can specify the following algorithms:

  • sha2-224
  • sha2-256
  • sha2-384
  • sha2-512

  The default value is sha2-256.
• format (optional)

  Specify the encoding of the output value. You can specify either hex or base64. The default value is hex.

{
    "data":{
        "hmac":"dGhlIHF1aWNrIGJyb3duIGZveAo="
    }
}

• input (required)

  Specify the base64-encoded input data.

• algorithm (optional)
  Specify the hash algorithm to use. You can specify this value either in the request body, or as a part of the URL. The URL value takes precedence if both are set. You can specify the following algorithms:

  • sha2-224
  • sha2-256
  • sha2-384
  • sha2-512

  The default value is sha2-256.

{
    "data":{
        "signature":"vault:v1:MEUCIQCyb869d7KWuA0hBM9b5NJrmWzMW3/
pT+0XYCM9VmGR+QIgWWF6ufi4OS2xo1eS2V5IeJQfsi59qeMWtgX0LipxEHI="
    }
}

• input (required)

  Specify the base64-encoded input data.

• signature (required)

  Specify the signature output from the /transit/sign. You must specify either this parameter or the hmac parameter.

• hmac (required)

  Specify the signature output from the /encryption/hmac function. Either this must be supplied or signature must be supplied.

• algorithm (optional)
  Specify the hash algorithm to use. You can specify this value either in the request body, or as a part of the URL. The URL value takes precedence if both are set. You can specify the following algorithms:

  • sha2-224
  • sha2-256
  • sha2-384
  • sha2-512

  The default value is sha2-256.

{
    "data":{
        "valid":true
    }
}