vault_client_transit: Transit Engine

In vimc/vaultr: Vault Client for Secrets and Sensitive Data

Transit Engine

Description

Transit Engine

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

Public methods

• vault_client_transit$new()

• vault_client_transit$custom_mount()

• vault_client_transit$key_create()

• vault_client_transit$key_read()

• vault_client_transit$key_list()

• vault_client_transit$key_delete()

• vault_client_transit$key_update()

• vault_client_transit$key_rotate()

• vault_client_transit$key_export()

• vault_client_transit$data_encrypt()

• vault_client_transit$data_decrypt()

• vault_client_transit$data_rewrap()

• vault_client_transit$datakey_create()

• vault_client_transit$random()

• vault_client_transit$hash()

• vault_client_transit$hmac()

• vault_client_transit$sign()

• vault_client_transit$verify_signature()

• vault_client_transit$verify_hmac()

• vault_client_transit$key_backup()

• vault_client_transit$key_restore()

• vault_client_transit$key_trim()

Inherited methods

• vaultr::vault_client_object$format()
• vaultr::vault_client_object$help()

---

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)
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()
}

vimc/vaultr documentation built on Nov. 11, 2023, 8:21 a.m.