Transit Engine
Transit Engine
vaultr::vault_client_object -> vault_client_transit
Inherited methods
new()Create a vault_client_transit object. Not typically
called by users.
vault_client_transit$new(api_client, mount)api_clientA vault_api_client object
mountMount point for the backend
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.
vault_client_transit$custom_mount(mount)mountString, 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.
vault_client_transit$key_create(
name,
key_type = NULL,
convergent_encryption = NULL,
derived = NULL,
exportable = NULL,
allow_plaintext_backup = NULL
)nameName for the key. This will be used in all future interactions with the key - the key itself is not returned.
key_typeSpecifies 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_encryptionLogical 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.
derivedSpecifies 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).
exportableEnables 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_backupIf 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.
vault_client_transit$key_read(name)nameThe name of the key to read
key_list()List names of all keys
vault_client_transit$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().
vault_client_transit$key_delete(name)nameThe 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.)
vault_client_transit$key_update(
name,
min_decryption_version = NULL,
min_encryption_version = NULL,
deletion_allowed = NULL,
exportable = NULL,
allow_plaintext_backup = NULL
)nameThe name of the key to update
min_decryption_versionSpecifies 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_versionSpecifies 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_allowedSpecifies if the key is allowed to be
deleted, as a logical (default is FALSE).
exportableEnables 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_backupIf 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.
vault_client_transit$key_rotate(name)nameThe 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.
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."
vault_client_transit$key_export(name, key_type, version = NULL)nameName of the key to export
key_typeSpecifies the type of the key to export. Valid
values are encryption-key, signing-key and hmac-key.
versionSpecifies 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
data_encrypt()This endpoint encrypts the provided plaintext using the named key.
vault_client_transit$data_encrypt(
key_name,
data,
key_version = NULL,
context = NULL
)key_nameSpecifies the name of the encryption key to encrypt against.
dataData to encrypt, as a raw vector
key_versionKey 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.
contextSpecifies 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.
vault_client_transit$data_decrypt(key_name, data, context = NULL)key_nameSpecifies the name of the encryption key to decrypt with.
dataThe data to decrypt. Must be a string, as returned
by $data_encrypt.
contextSpecifies 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.
vault_client_transit$data_rewrap(
key_name,
data,
key_version = NULL,
context = NULL
)key_nameSpecifies the name of the encryption key to re-encrypt against
dataThe data to decrypt. Must be a string, as returned
by $data_encrypt.
key_versionSpecifies 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.
contextSpecifies 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.
vault_client_transit$datakey_create(
name,
plaintext = FALSE,
bits = NULL,
context = NULL
)nameSpecifies the name of the encryption key to use to encrypt the datakey
plaintextLogical, indicating if the plaintext key should be returned.
bitsSpecifies the number of bits in the desired key. Can be 128, 256, or 512.
contextSpecifies 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.
vault_client_transit$random(bytes = 32, format = "hex")bytesNumber of bytes to generate (as an integer)
formatThe 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.
vault_client_transit$hash(data, algorithm = NULL, format = "hex")dataA 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.
algorithmA 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.
formatThe 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.
vault_client_transit$hmac(name, data, key_version = NULL, algorithm = NULL)nameSpecifies the name of the encryption key to generate hmac against
dataThe input data, as a raw vector
key_versionSpecifies 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.
algorithmSpecifies 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.
vault_client_transit$sign(
name,
data,
key_version = NULL,
hash_algorithm = NULL,
prehashed = FALSE,
signature_algorithm = NULL,
context = NULL
)nameSpecifies the name of the encryption key to use for signing
dataThe input data, as a raw vector
key_versionSpecifies 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_algorithmSpecifies the hash algorithm to
use. Currently-supported algorithms are sha2-224,
sha2-256, sha2-384 and sha2-512. The default is
sha2-256.
prehashedSet 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_algorithmWhen using a RSA key, specifies the
RSA signature algorithm to use for signing. Supported
signature types are pss (the default) and pkcs1v15.
contextSpecifies 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.
vault_client_transit$verify_signature(
name,
data,
signature,
hash_algorithm = NULL,
signature_algorithm = NULL,
context = NULL,
prehashed = FALSE
)nameName of the key
dataData to verify, as a raw vector
signatureThe signed data, as a string.
hash_algorithmSpecifies the hash algorithm to use. This
can also be specified as part of the URL (see $sign and
$hmac for details).
signature_algorithmWhen using a RSA key, specifies the RSA signature algorithm to use for signature verification
contextSpecifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.
prehashedSet to TRUE when the input is already hashed
verify_hmac()Determine whether the provided signature is valid for the given data.
vault_client_transit$verify_hmac(
name,
data,
signature,
hash_algorithm = NULL,
signature_algorithm = NULL,
context = NULL,
prehashed = FALSE
)nameName of the key
dataData to verify, as a raw vector
signatureThe signed data, as a string.
hash_algorithmSpecifies the hash algorithm to use. This
can also be specified as part of the URL (see $sign and
$hmac for details).
signature_algorithmWhen using a RSA key, specifies the RSA signature algorithm to use for signature verification
contextSpecifies the context for key derivation. This is required if key derivation is enabled for this key. Must be a raw vector.
prehashedSet 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.
vault_client_transit$key_backup(name)nameName 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.
vault_client_transit$key_restore(name, backup, force = FALSE)nameName of the restored key.
backupBacked up key data to be restored. This should be
the output from the $key_backup endpoint.
forceLogical. 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.
vault_client_transit$key_trim(name, min_version)nameKey to trim
min_versionThe 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.
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.
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