Transit Engine

Details

Interact with vault's transit engine. This is useful for encrypting arbitrary data without storing it in the vault - like "cryptography as a service" or "encryption as a service". The transit secrets engine can also sign and verify data; generate hashes and HMACs of data; and act as a source of random bytes. See https://developer.hashicorp.com/vault/docs/secrets/transit for an introduction to the capabilities of the transit engine.

Super class

vaultr::vault_client_object -> vault_client_transit

Methods

Inherited methods

Method `new()`

Create a vault_client_transit object. Not typically called by users.

Usage

vault_client_transit$new(api_client, mount)

Arguments

api_client: A vault_api_client object
mount: Mount point for the backend

Method `custom_mount()`

Set up a vault_client_transit object at a custom mount. For example, suppose you mounted the transit secret backend at /transit2 you might use tr <- vault$secrets$transit$custom_mount("/transit2") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_transit$custom_mount(mount)

Arguments

mount: String, indicating the path that the engine is mounted at.

Method `key_create()`

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

Usage

vault_client_transit$key_create(
  name,
  key_type = NULL,
  convergent_encryption = NULL,
  derived = NULL,
  exportable = NULL,
  allow_plaintext_backup = NULL
)

Arguments

name

Name for the key. This will be used in all future interactions with the key - the key itself is not returned.

key_type

Specifies the type of key to create. The default is aes256-gcm96. The currently-supported types are:

aes256-gcm96: AES-256 wrapped with GCM using a 96-bit nonce size AEAD (symmetric, supports derivation and convergent encryption)
chacha20-poly1305: ChaCha20-Poly1305 AEAD (symmetric, supports derivation and convergent encryption)
ed25519: ED25519 (asymmetric, supports derivation). When using derivation, a sign operation with the same context will derive the same key and signature; this is a signing analogue to convergent_encryption
ecdsa-p256: ECDSA using the P-256 elliptic curve (asymmetric)
rsa-2048: RSA with bit size of 2048 (asymmetric)
rsa-4096: RSA with bit size of 4096 (asymmetric)

convergent_encryption

Logical with default of FALSE. If TRUE, then 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

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 (default is FALSE).

exportable

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 (default is FALSE).

allow_plaintext_backup

If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled (default is FALSE).

Method `key_read()`

Read information about a previously generated key. The returned object shows the creation time of each key version; the values are not the keys themselves. Depending on the type of key, different information may be returned, e.g. an asymmetric key will return its public key in a standard format for the type.

Usage

vault_client_transit$key_read(name)

Arguments

name: The name of the key to read

Method `key_list()`

List names of all keys

Usage

vault_client_transit$key_list()

Method `key_delete()`

Delete a key by name. It will no longer be possible to decrypt any data encrypted with the named key. Because this is a potentially catastrophic operation, the deletion_allowed tunable must be set using $key_update().

Usage

vault_client_transit$key_delete(name)

Arguments

name: The name of the key to delete.

Method `key_update()`

This method allows tuning configuration values for a given key. (These values are returned during a read operation on the named key.)

Usage

vault_client_transit$key_update(
  name,
  min_decryption_version = NULL,
  min_encryption_version = NULL,
  deletion_allowed = NULL,
  exportable = NULL,
  allow_plaintext_backup = NULL
)

Arguments

name: The name of the key to update
min_decryption_version: Specifies the minimum version of ciphertext allowed to be decrypted, as an integer (default is 0). Adjusting this as part of a key rotation policy can prevent old copies of ciphertext from being decrypted, should they fall into the wrong hands. For signatures, this value controls the minimum version of signature that can be verified against. For HMACs, this controls the minimum version of a key allowed to be used as the key for verification.
min_encryption_version: Specifies the minimum version of the key that can be used to encrypt plaintext, sign payloads, or generate HMACs, as an integer (default is 0). Must be 0 (which will use the latest version) or a value greater or equal to min_decryption_version.
deletion_allowed: Specifies if the key is allowed to be deleted, as a logical (default is FALSE).
exportable: 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: If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.

Method `key_rotate()`

Rotates the version of the named key. After rotation, new plaintext requests will be encrypted with the new version of the key. To upgrade ciphertext to be encrypted with the latest version of the key, use the rewrap endpoint. This is only supported with keys that support encryption and decryption operations.

Usage

vault_client_transit$key_rotate(name)

Arguments

name: The name of the key to rotate

Method `key_export()`

Export the named key. If version is specified, the specific version will be returned. If latest is provided as the version, the current key will be provided. Depending on the type of key, different information may be returned. The key must be exportable to support this operation and the version must still be valid.

For more details see https://github.com/hashicorp/vault/issues/2667 where HashiCorp says "Part of the "contract" of transit is that the key is never exposed outside of Vault. We added the ability to export keys because some enterprises have key escrow requirements, but it leaves a permanent mark in the key metadata. I suppose we could at some point allow importing a key and also leave such a mark."

Usage

vault_client_transit$key_export(name, key_type, version = NULL)

Arguments

name: Name of the key to export
key_type: Specifies the type of the key to export. Valid values are encryption-key, signing-key and hmac-key.
version: Specifies the version of the key to read. If omitted, all versions of the key will be returned. If the version is set to latest, the current key will be returned

Method `data_encrypt()`

This endpoint encrypts the provided plaintext using the named key.

Usage

vault_client_transit$data_encrypt(
  key_name,
  data,
  key_version = NULL,
  context = NULL
)

Arguments

key_name: Specifies the name of the encryption key to encrypt against.
data: Data to encrypt, as a raw vector
key_version: Key version to use, as an integer. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
context: Specifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.

Method `data_decrypt()`

Decrypts the provided ciphertext using the named key.

Usage

vault_client_transit$data_decrypt(key_name, data, context = NULL)

Arguments

key_name: Specifies the name of the encryption key to decrypt with.
data: The data to decrypt. Must be a string, as returned by $data_encrypt.
context: Specifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.

Method `data_rewrap()`

Rewraps the provided ciphertext using the latest version of the named key. Because this never returns plaintext, it is possible to delegate this functionality to untrusted users or scripts.

Usage

vault_client_transit$data_rewrap(
  key_name,
  data,
  key_version = NULL,
  context = NULL
)

Arguments

key_name: Specifies the name of the encryption key to re-encrypt against
data: The data to decrypt. Must be a string, as returned by $data_encrypt.
key_version: Specifies the version of the key to use for the operation. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
context: Specifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.

Method `datakey_create()`

This endpoint generates a new high-entropy key and the value encrypted with the named key. Optionally return the plaintext of the key as well.

Usage

vault_client_transit$datakey_create(
  name,
  plaintext = FALSE,
  bits = NULL,
  context = NULL
)

Arguments

name: Specifies the name of the encryption key to use to encrypt the datakey
plaintext: Logical, indicating if the plaintext key should be returned.
bits: Specifies the number of bits in the desired key. Can be 128, 256, or 512.
context: Specifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.

Method `random()`

Generates high-quality random bytes of the specified length. This is totally independent of R's random number stream and provides random numbers suitable for cryptographic purposes.

Usage

vault_client_transit$random(bytes = 32, format = "hex")

Arguments

bytes: Number of bytes to generate (as an integer)
format: The output format to produce; must be one of hex (a single hex string such as d1189e2f83b72ab6), base64 (a single base64 encoded string such as 8TDJekY0mYs=) or raw (a raw vector of length bytes).

Method `hash()`

Generates a cryptographic hash of given data using the specified algorithm.

Usage

vault_client_transit$hash(data, algorithm = NULL, format = "hex")

Arguments

data: A raw vector of data to hash. To generate a raw vector from an R object, one option is to use unserialize(x, NULL) but be aware that version information may be included. Alternatively, for a string, one might use charToRaw.
algorithm: A string indicating the hash algorithm to use. The exact set of supported algorithms may depend by vault server version, but as of version 1.0.0 vault supports sha2-224, sha2-256, sha2-384 and sha2-512. The default is sha2-256.
format: The format of the output - must be one of hex or base64.

Method `hmac()`

This endpoint returns the digest of given data using the specified hash algorithm and the named key. The key can be of any type supported by the transit engine; the raw key will be marshalled into bytes to be used for the HMAC function. If the key is of a type that supports rotation, the latest (current) version will be used.

Usage

vault_client_transit$hmac(name, data, key_version = NULL, algorithm = NULL)

Arguments

name: Specifies the name of the encryption key to generate hmac against
data: The input data, as a raw vector
key_version: Specifies the version of the key to use for the operation. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
algorithm: Specifies the hash algorithm to use. Currently-supported algorithms are sha2-224, sha2-256, sha2-384 and sha2-512. The default is sha2-256.

Method `sign()`

Returns the cryptographic signature of the given data using the named key and the specified hash algorithm. The key must be of a type that supports signing.

Usage

vault_client_transit$sign(
  name,
  data,
  key_version = NULL,
  hash_algorithm = NULL,
  prehashed = FALSE,
  signature_algorithm = NULL,
  context = NULL
)

Arguments

name: Specifies the name of the encryption key to use for signing
data: The input data, as a raw vector
key_version: 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: Specifies the hash algorithm to use. Currently-supported algorithms are sha2-224, sha2-256, sha2-384 and sha2-512. The default is sha2-256.
prehashed: Set to true when the input is already hashed. If the key type is rsa-2048 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter.
signature_algorithm: When using a RSA key, specifies the RSA signature algorithm to use for signing. Supported signature types are pss (the default) and pkcs1v15.
context: Specifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.

Method `verify_signature()`

Determine whether the provided signature is valid for the given data.

Usage

vault_client_transit$verify_signature(
  name,
  data,
  signature,
  hash_algorithm = NULL,
  signature_algorithm = NULL,
  context = NULL,
  prehashed = FALSE
)

Arguments

name: Name of the key
data: Data to verify, as a raw vector
signature: The signed data, as a string.
hash_algorithm: Specifies the hash algorithm to use. This can also be specified as part of the URL (see $sign and $hmac for details).
signature_algorithm: When using a RSA key, specifies the RSA signature algorithm to use for signature verification
context: Specifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.
prehashed: Set to TRUE when the input is already hashed

Method `verify_hmac()`

Determine whether the provided signature is valid for the given data.

Usage

vault_client_transit$verify_hmac(
  name,
  data,
  signature,
  hash_algorithm = NULL,
  signature_algorithm = NULL,
  context = NULL,
  prehashed = FALSE
)

Arguments

name: Name of the key
data: Data to verify, as a raw vector
signature: The signed data, as a string.
hash_algorithm: Specifies the hash algorithm to use. This can also be specified as part of the URL (see $sign and $hmac for details).
signature_algorithm: When using a RSA key, specifies the RSA signature algorithm to use for signature verification
context: Specifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.
prehashed: Set to TRUE when the input is already hashed

Method `key_backup()`

Returns a plaintext backup of a named key. The backup contains all the configuration data and keys of all the versions along with the HMAC key. The response from this endpoint can be used with $key_restore to restore the key.

Usage

vault_client_transit$key_backup(name)

Arguments

name: Name of the key to backup

Method `key_restore()`

Restores the backup as a named key. This will restore the key configurations and all the versions of the named key along with HMAC keys. The input to this method should be the output of $key_restore method.

Usage

vault_client_transit$key_restore(name, backup, force = FALSE)

Arguments

name: Name of the restored key.
backup: Backed up key data to be restored. This should be the output from the $key_backup endpoint.
force: Logical. If TRUE, then force the restore to proceed even if a key by this name already exists.

Method `key_trim()`

This endpoint trims older key versions setting a minimum version for the keyring. Once trimmed, previous versions of the key cannot be recovered.

Usage

vault_client_transit$key_trim(name, min_version)

Arguments

name: Key to trim
min_version: The minimum version for the key ring. All versions before this version will be permanently deleted. This value can at most be equal to the lesser of min_decryption_version and min_encryption_version. This is not allowed to be set when either min_encryption_version or min_decryption_version is set to zero.

Examples

server <- vaultr::vault_test_server(if_disabled = message)
#> ...waiting for Vault to start
#> ...waiting for Vault to start
if (!is.null(server)) {
  client <- server$client()

  client$secrets$enable("transit")
  transit <- client$secrets$transit

  # Before encrypting anything, create a key.  Note that it will
  # not be returned to you, and is accessed purely by name
  transit$key_create("test")

  # Some text to encrypt
  plaintext <- "hello world"

  # Encrypted:
  cyphertext <- transit$data_encrypt("test", charToRaw(plaintext))

  # Decrypt the data
  res <- transit$data_decrypt("test", cyphertext)
  rawToChar(res)

  # This approach works with R objects too, if used with serialise.
  # First, serialise an R object to a raw vector:
  data <- serialize(mtcars, NULL)

  # Then encrypt this data:
  enc <- transit$data_encrypt("test", data)

  # The resulting string can be safely passed around (e.g., over
  # email) or written to disk, and can later be decrypted by
  # anyone who has access to the "test" key in the vault:
  data2 <- transit$data_decrypt("test", enc)

  # Once decrypted, the data can be "unserialised" back into an R
  # object:
  unserialize(data2)

  # cleanup
  server$kill()
}

Transit Engine

Details

Super class

Methods

Public methods

Method new()

Usage

Arguments

Method custom_mount()

Usage

Arguments

Method key_create()

Usage

Arguments

Method key_read()

Usage

Arguments

Method key_list()

Usage

Method key_delete()

Usage

Arguments

Method key_update()

Usage

Arguments

Method key_rotate()

Usage

Arguments

Method key_export()

Usage

Arguments

Method data_encrypt()

Usage

Arguments

Method data_decrypt()

Usage

Arguments

Method data_rewrap()

Usage

Arguments

Method datakey_create()

Usage

Arguments

Method random()

Usage

Arguments

Method hash()

Usage

Arguments

Method hmac()

Usage

Arguments

Method sign()

Usage

Arguments

Method verify_signature()

Usage

Arguments

Method verify_hmac()

Usage

Arguments

Method key_backup()

Usage

Arguments

Method key_restore()

Usage

Arguments

Method key_trim()

Usage

Arguments

Examples

Method `new()`

Method `custom_mount()`

Method `key_create()`

Method `key_read()`

Method `key_list()`

Method `key_delete()`

Method `key_update()`

Method `key_rotate()`

Method `key_export()`

Method `data_encrypt()`

Method `data_decrypt()`

Method `data_rewrap()`

Method `datakey_create()`

Method `random()`

Method `hash()`

Method `hmac()`

Method `sign()`

Method `verify_signature()`

Method `verify_hmac()`

Method `key_backup()`

Method `key_restore()`

Method `key_trim()`