vault_client_transit: Transit Engine

Description

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://www.vaultproject.io/docs/secrets/transit/index.html for an introduction to the capabilities of the transit engine.

Arguments

Methods

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:

custom_mount(mount)

Arguments:

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

key_create

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

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).

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:

key_read(name)

Arguments:

name: The name of the key to read

key_list

List names of all keys Usage:

key_list()

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:

key_delete(name)

Arguments:

name: The name of the key to delete.

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:

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.

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:

key_rotate(name)

Arguments:

name: The name of the key to rotate

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. Usage:

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

Details: 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."

data_encrypt

This endpoint encrypts the provided plaintext using the named key. Usage:

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.

data_decrypt

Decrypts the provided ciphertext using the named key. Usage:

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.

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:

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.

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:

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.

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:

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).

hash

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

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.

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:

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.

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:

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.

verify_signature

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

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

verify_hmac

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

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

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:

key_backup(name)

Arguments:

name: Name of the key to backup

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:

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.

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:

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

Run this code

# NOT RUN {
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()
}
# }

Run the code above in your browser using DataLab