Skip to content

Latest commit

 

History

History
227 lines (207 loc) · 14.1 KB

secret-transit.md

File metadata and controls

227 lines (207 loc) · 14.1 KB

Transit Secret Configuration Options

This benchmark tests the performance of the transit operations.

Test Parameters

General Transit Config

  • payload_len (int: 128): Specifies the payload length to use for encryption/decryption operations.
  • context_len (int: 32): Specifies the context length to use for encryption/decryption operations.

Key Config keys

  • name (string: "test") – Specifies the name of the encryption key to create. This is specified as part of the URL.
  • convergent_encryption (bool: false): If enabled, the key will support convergent encryption, where the same plaintext creates the same ciphertext. This requires derived to be set to true. When enabled, each encryption(/decryption/rewrap/datakey) operation will derive a nonce value rather than randomly generate it.
  • derived (bool: false): Specifies if key derivation is to be used. If enabled, all encrypt/decrypt requests to this named key must provide a context which is used for key derivation.
  • exportable (bool: false) - Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled.
  • allow_plaintext_backup (bool: false) - If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.
  • type (string: "rsa-2048"): Specifies the type of key to create. See API docs for supported values.
  • key_size (int: "0") - The key size in bytes for algorithms that allow variable key sizes. Currently only applicable to HMAC, where it must be between 32 and 512 bytes.
  • auto_rotate_period (duration: "0") – The period at which this key should be rotated automatically. Setting this to "0" (the default) will disable automatic key rotation. This value cannot be shorter than one hour. Uses duration format strings.
  • managed_key_name (string: "") - The name of the managed key to use for this transit key.
  • managed_key_id (string: "") - The UUID of the managed key to use for this transit key.

Sign Config sign

  • name (string: "test") – Specifies the name of the encryption key to use for signing. This is specified as part of the URL.
  • key_version (int: 0) – Specifies the version of the key to use for signing. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
  • hash_algorithm (string: "sha2-256"): Specifies the hash algorithm to use for supporting key types (notably, not including ed25519 which specifies its own hash algorithm). See API docs for supported values.
  • input (string: "") – Specifies the base64 encoded input data. One of input or batch_input must be supplied.
  • reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
  • batch_input ([]interface{}: nil) – Specifies a list of items for processing. When this parameter is set, any supplied 'input' or 'context' parameters will be ignored. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input. If the input data value of an item is invalid, the corresponding item in the 'batch_results' will have the key 'error' with a value describing the error.
  • context (string: "") - Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
  • prehashed (bool: false) - Set to true when the input is already hashed. If the key type is rsa-2048, rsa-3072 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter. Just as the value to sign should be the base64-encoded representation of the exact binary data you want signed, when set, input is expected to be base64-encoded binary hashed data, not hex-formatted. (As an example, on the command line, you could generate a suitable input via openssl dgst -sha256 -binary | base64.)
  • signature_algorithm (string: "pss"): When using a RSA key, specifies the RSA signature algorithm to use for signing. See API docs for supported values.
  • marshaling_algorithm (string: "asn1"): Specifies the way in which the signature should be marshaled. This currently only applies to ECDSA keys. See API docs for supported values.
  • salt_length (string: "auto") – The salt length used to sign. This currently only applies to the RSA PSS signature scheme. See API docs for supported values.

Verify Config verify

  • name (string: test) – Specifies the name of the encryption key that was used to generate the signature or HMAC.
  • hash_algorithm (string: "sha2-256") – Specifies the hash algorithm to use. This can also be specified as part of the URL.
  • input (string: "") – Specifies the base64 encoded input data. One of input or batch_input must be supplied.
  • signature (string: "") – Specifies the signature output from the /transit/sign function. Either this must be supplied or hmac must be supplied.
  • hmac (string: "") – Specifies the signature output from the /transit/hmac function. Either this must be supplied or signature must be supplied.
  • reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
  • batch_input ([]interface{}: nil) – Specifies a list of items for processing. When this parameter is set, any supplied 'input', 'hmac' or 'signature' parameters will be ignored. 'batch_input' items should contain an 'input' parameter and either an 'hmac' or 'signature' parameter. All items in the batch must consistently supply either 'hmac' or 'signature' parameters. It is an error for some items to supply 'hmac' while others supply 'signature'. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input. If the input data value of an item is invalid, the corresponding item in the 'batch_results' will have the key 'error' with a value describing the error.
  • context (string: "") - Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
  • prehashed (bool: false) - Set to true when the input is already hashed. If the key type is rsa-2048, rsa-3072 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter. Just as the value to sign should be the base64-encoded representation of the exact binary data you want signed, when set, input is expected to be base64-encoded binary hashed data, not hex-formatted. (As an example, on the command line, you could generate a suitable input via openssl dgst -sha256 -binary | base64.)
  • signature_algorithm (string: "pss"): When using a RSA key, specifies the RSA signature algorithm to use for signing. See API docs for supported values.
  • marshaling_algorithm (string: "asn1"): Specifies the way in which the signature should be marshaled. This currently only applies to ECDSA keys. See API docs for supported values.
  • salt_length (string: "auto") – The salt length used to sign. This currently only applies to the RSA PSS signature scheme. See API docs for supported values.

Encrypt Config encrypt

  • name (string: test) – Specifies the name of the encryption key to encrypt against. This is specified as part of the URL.
  • plaintext (string: "") – Specifies base64 encoded plaintext to be encoded.
  • associated_data (string: "") - Specifies base64 encoded associated data (also known as additional data or AAD) to also be authenticated with AEAD cphers (aes128-gcm96, aes256-gcm, and chacha20-poly1305).
  • context (string: "") – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled for this key.
  • key_version (int: 0) – Specifies the version of the key to use for encryption. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
  • nonce (string: "") – Specifies the base64 encoded nonce value. This must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The value must be exactly 96 bits (12 bytes) long and the user must ensure that for any given context (and thus, any given encryption key) this nonce value is never reused.
  • reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
  • batch_input ([]interface{}: nil) – Specifies a list of items to be encrypted in a single batch. When this parameter is set, if the parameters 'plaintext', 'context' and 'nonce' are also set, they will be ignored. Any batch output will preserve the order of the batch input.
  • type (string: "aes256-gcm96") –This parameter is required when encryption key is expected to be created. When performing an upsert operation, the type of key to create.
  • convergent_encryption (string: "") – This parameter will only be used when a key is expected to be created. Whether to support convergent encryption. This is only supported when using a key with key derivation enabled and will require all requests to carry both a context and 96-bit (12-byte) nonce. The given nonce will be used in place of a randomly generated nonce. As a result, when the same context and nonce are supplied, the same ciphertext is generated. It is very important when using this mode that you ensure that all nonces are unique for a given context. Failing to do so will severely impact the ciphertext's security.
  • partial_failure_response_code (int: 400) Ordinarily, if a batch item fails to encrypt due to a bad input, but other batch items succeed, the HTTP response code is 400 (Bad Request). Some applications may want to treat partial failures differently. Providing the parameter returns the given response code integer instead of a failed status code in this case. If all values fail an error code is still returned. Be warned that some failures (such as failure to decrypt) could be indicative of a security breach and should not be ignored.

Decrypt Config decrypt

  • name (string: test) – Specifies the name of the encryption key to decrypt against. This is specified as part of the URL.
  • ciphertext (string: "") – Specifies the ciphertext to decrypt.
  • associated_data (string: "") - Specifies base64 encoded associated data (also known as additional data or AAD) to also be authenticated with AEAD ciphers (aes128-gcm96, aes256-gcm, and chacha20-poly1305).
  • context (string: "") – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled.
  • nonce (string: "") – Specifies a base64 encoded nonce value used during encryption. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+.
  • reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
  • batch_input ([]interface{}: nil) – Specifies a list of items to be decrypted in a single batch. When this parameter is set, if the parameters 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. Any batch output will preserve the order of the batch input.
  • partial_failure_response_code (int: 400) Ordinarily, if a batch item fails to encrypt due to a bad input, but other batch items succeed, the HTTP response code is 400 (Bad Request). Some applications may want to treat partial failures differently. Providing the parameter returns the given response code integer instead of a failed status code in this case. If all values fail an error code is still returned. Be warned that some failures (such as failure to decrypt) could be indicative of a security breach and should not be ignored.

Example Configuration

test "transit_sign" "transit_sign_test_1" {
    weight = 25
}

test "transit_verify" "transit_verify_test_1" {
    weight = 25
    config {
        verify {
            signature_algorithm = "pkcs1v15"
        }
    }
}

test "transit_encrypt" "transit_encrypt_test_1" {
    weight = 25
    config {
      payload_len = 128
      context_len = 32
      keys {
        convergent_encryption = true
        derived = true
        type = "aes128-gcm96"
      }
    }
}

test "transit_decrypt" "transit_decrypt_test_1" {
    weight = 25
    config {
        payload_len = 64
    }
}