Transit¶
Encryption as a service on a transit mount (client.transit(mount = "transit")). Plaintext,
input and context values are bytes (text is UTF-8 encoded; the SDK base64-encodes them on the
wire). Ciphertexts, signatures and HMACs are strings of the form vault:v<keyVersion>:<base64>.
| Function | What it does |
|---|---|
createKey(name, type = "aes256-gcm96", options?) |
creates a key (idempotent); options exportable, derived, autoRotatePeriod, allowPlaintextBackup, keySize |
readKey(name) / listKeys() |
key properties (latestVersion, minDecryptionVersion, keys, supportsSigning, …) / key names |
rotateKey(name) |
adds a key version |
updateKeyConfig(name, config) |
deletionAllowed, minDecryptionVersion, minEncryptionVersion, exportable, autoRotatePeriod |
deleteKey(name) |
needs deletionAllowed: true first (VALIDATION otherwise) |
encrypt(name, plaintext, {context, keyVersion}) → {ciphertext, keyVersion} |
|
decrypt(name, ciphertext, {context}) → bytes |
VALIDATION for an invalid or too old ciphertext |
rewrap(name, ciphertext) |
re-encrypts with the latest key version without revealing the plaintext |
encryptBatch(name, items) / decryptBatch(name, items) |
one request; results in order with per-item error (a failed item does not throw) |
generateDataKey(name, {plaintext = true, bits = 256}) |
data key for envelope encryption (ciphertext, plaintext when requested) |
hmac(name, input, {algorithm}) |
vault:vN: HMAC |
sign(name, input, {hashAlgorithm, signatureAlgorithm, prehashed}) |
signature with an asymmetric key (VALIDATION for a symmetric key) |
verify(name, input, signature or hmac) → boolean |
false for an invalid signature (not an error) |
hash(input, {algorithm = "sha2-256", format = "hex"}) |
digest |
randomBytes(n, {format = "base64"}) |
random bytes from the server |
How verify takes an HMAC instead of a signature: TypeScript { hmac } target, Python hmac=,
Java verifyHmac(...), Rust/Go a hmac field in the options.
Encrypt and decrypt¶
const transit = client.transit();
await transit.createKey("orders", "aes256-gcm96");
const { ciphertext } = await transit.encrypt("orders", "card 4111");
const plain = new TextDecoder().decode(await transit.decrypt("orders", ciphertext));
await transit.rotateKey("orders");
const rewrapped = await transit.rewrap("orders", ciphertext);
let transit = client.transit();
transit.create_key("orders", "aes256-gcm96", None).await?;
let ct = transit.encrypt("orders", b"card 4111", None).await?;
let plain = transit.decrypt("orders", &ct.ciphertext, None).await?;
transit.rotate_key("orders").await?;
let rewrapped = transit.rewrap("orders", &ct.ciphertext, None).await?;
transit := client.Transit("transit")
if _, err := transit.CreateKey(ctx, "orders", "aes256-gcm96", nil); err != nil {
return err
}
ct, err := transit.Encrypt(ctx, "orders", []byte("card 4111"), nil)
plain, err := transit.Decrypt(ctx, "orders", ct.Ciphertext, nil)
_, err = transit.RotateKey(ctx, "orders")
rewrapped, err := transit.Rewrap(ctx, "orders", ct.Ciphertext, nil)