Class Transit

java.lang.Object
codes.grow.packages.vault.Transit

public final class Transit extends Object
Transit engine on one mount: client.transit() (mount transit). Plaintexts are bytes (text is UTF-8 encoded); ciphertexts, signatures and HMACs are vault:v<n>:... strings.

 Transit transit = client.transit();
 Ciphertext ct = transit.encrypt("app-key", "hello");
 byte[] plain = transit.decrypt("app-key", ct.ciphertext());
 
  • Method Details

    • mount

      public String mount()
      Returns the mount.
      Returns:
      the mount path
    • createKey

      public TransitKey createKey(String name)
      Creates an aes256-gcm96 key (idempotent: an existing key is returned unchanged).
      Parameters:
      name - key name
      Returns:
      the key
    • createKey

      public TransitKey createKey(String name, String type)
      Creates a key of a type.
      Parameters:
      name - key name
      type - key type, e.g. ed25519
      Returns:
      the key
    • createKey

      public TransitKey createKey(String name, CreateKeyOptions options)
      Creates a key with options.
      Parameters:
      name - key name
      options - key options
      Returns:
      the key
    • createKeyAsync

      public CompletableFuture<TransitKey> createKeyAsync(String name, CreateKeyOptions o)
      Parameters:
      name - key name
      o - key options
      Returns:
      a future with the key
    • readKey

      public TransitKey readKey(String name)
      Reads a key; NotFoundException when missing.
      Parameters:
      name - key name
      Returns:
      the key
    • readKeyAsync

      public CompletableFuture<TransitKey> readKeyAsync(String name)
      Asynchronous readKey(String).
      Parameters:
      name - key name
      Returns:
      a future with the key
    • listKeys

      public List<String> listKeys()
      Key names (sorted); empty when there is none.
      Returns:
      the names
    • listKeysAsync

      public CompletableFuture<List<String>> listKeysAsync()
      Asynchronous listKeys().
      Returns:
      a future with the names
    • rotateKey

      public TransitKey rotateKey(String name)
      Adds a new key version.
      Parameters:
      name - key name
      Returns:
      the updated key
    • rotateKeyAsync

      public CompletableFuture<TransitKey> rotateKeyAsync(String name)
      Asynchronous rotateKey(String).
      Parameters:
      name - key name
      Returns:
      a future with the updated key
    • updateKeyConfig

      public TransitKey updateKeyConfig(String name, KeyConfig config)
      Updates key settings.
      Parameters:
      name - key name
      config - settings
      Returns:
      the updated key
    • updateKeyConfigAsync

      public CompletableFuture<TransitKey> updateKeyConfigAsync(String name, KeyConfig c)
      Parameters:
      name - key name
      c - settings
      Returns:
      a future with the updated key
    • deleteKey

      public void deleteKey(String name)
      Deletes a key (needs deletionAllowed, else ValidationException).
      Parameters:
      name - key name
    • deleteKeyAsync

      public CompletableFuture<Void> deleteKeyAsync(String name)
      Asynchronous deleteKey(String).
      Parameters:
      name - key name
      Returns:
      a future completed when done
    • encrypt

      public Ciphertext encrypt(String name, String plaintext)
      Encrypts UTF-8 text.
      Parameters:
      name - key name
      plaintext - text
      Returns:
      the ciphertext
    • encrypt

      public Ciphertext encrypt(String name, byte[] plaintext, TransitOptions options)
      Encrypts bytes.
      Parameters:
      name - key name
      plaintext - bytes
      options - context, key version, associated data
      Returns:
      the ciphertext
    • encryptAsync

      public CompletableFuture<Ciphertext> encryptAsync(String name, byte[] plaintext, TransitOptions o)
      Parameters:
      name - key name
      plaintext - bytes
      o - options
      Returns:
      a future with the ciphertext
    • decrypt

      public byte[] decrypt(String name, String ciphertext)
      Decrypts a ciphertext.
      Parameters:
      name - key name
      ciphertext - vault:v<n>: ciphertext
      Returns:
      the plaintext bytes
    • decrypt

      public byte[] decrypt(String name, String ciphertext, TransitOptions options)
      Decrypts a ciphertext with options.
      Parameters:
      name - key name
      ciphertext - ciphertext
      options - context, associated data
      Returns:
      the plaintext bytes
    • decryptAsync

      public CompletableFuture<byte[]> decryptAsync(String name, String ciphertext, TransitOptions o)
      Parameters:
      name - key name
      ciphertext - ciphertext
      o - options
      Returns:
      a future with the plaintext bytes
    • rewrap

      public Ciphertext rewrap(String name, String ciphertext)
      Re-encrypts a ciphertext with the latest key version without revealing the plaintext.
      Parameters:
      name - key name
      ciphertext - ciphertext
      Returns:
      the new ciphertext
    • rewrap

      public Ciphertext rewrap(String name, String ciphertext, TransitOptions options)
      Re-encrypts with options (key version, context).
      Parameters:
      name - key name
      ciphertext - ciphertext
      options - options
      Returns:
      the new ciphertext
    • rewrapAsync

      public CompletableFuture<Ciphertext> rewrapAsync(String name, String ciphertext, TransitOptions o)
      Parameters:
      name - key name
      ciphertext - ciphertext
      o - options
      Returns:
      a future with the new ciphertext
    • encryptBatch

      public List<EncryptBatchResult> encryptBatch(String name, List<EncryptBatchItem> items)
      Encrypts many items in one request. Results are in input order; a failed item has error set (the call itself fails only when the whole request fails).
      Parameters:
      name - key name
      items - items
      Returns:
      the results
    • encryptBatchAsync

      public CompletableFuture<List<EncryptBatchResult>> encryptBatchAsync(String name, List<EncryptBatchItem> items)
      Parameters:
      name - key name
      items - items
      Returns:
      a future with the results
    • decryptBatch

      public List<DecryptBatchResult> decryptBatch(String name, List<DecryptBatchItem> items)
      Decrypts many items in one request; see encryptBatch(java.lang.String, java.util.List<codes.grow.packages.vault.EncryptBatchItem>) for error handling.
      Parameters:
      name - key name
      items - items
      Returns:
      the results
    • decryptBatchAsync

      public CompletableFuture<List<DecryptBatchResult>> decryptBatchAsync(String name, List<DecryptBatchItem> items)
      Parameters:
      name - key name
      items - items
      Returns:
      a future with the results
    • generateDataKey

      public DataKey generateDataKey(String name)
      Generates a 256-bit data key encrypted with the transit key, plus its plaintext.
      Parameters:
      name - key name
      Returns:
      the data key
    • generateDataKey

      public DataKey generateDataKey(String name, boolean plaintext, int bits)
      Generates a data key.
      Parameters:
      name - key name
      plaintext - also return the plaintext (plaintext variant) instead of only the ciphertext (wrapped variant)
      bits - 128, 256 or 512
      Returns:
      the data key
    • generateDataKeyAsync

      public CompletableFuture<DataKey> generateDataKeyAsync(String name, boolean plaintext, int bits, TransitOptions o)
      Asynchronous generateDataKey(String, boolean, int) (options: context).
      Parameters:
      name - key name
      plaintext - also return the plaintext
      bits - key size
      o - options
      Returns:
      a future with the data key
    • hmac

      public String hmac(String name, byte[] input)
      HMAC of the input with the key (vault:v<n>:<base64>).
      Parameters:
      name - key name
      input - bytes
      Returns:
      the HMAC
    • hmac

      public String hmac(String name, byte[] input, TransitOptions options)
      HMAC with options (hash algorithm, key version).
      Parameters:
      name - key name
      input - bytes
      options - options
      Returns:
      the HMAC
    • hmacAsync

      public CompletableFuture<String> hmacAsync(String name, byte[] input, TransitOptions o)
      Parameters:
      name - key name
      input - bytes
      o - options
      Returns:
      a future with the HMAC
    • sign

      public Signature sign(String name, byte[] input)
      Signs the input with an asymmetric key.
      Parameters:
      name - key name
      input - bytes
      Returns:
      the signature
    • sign

      public Signature sign(String name, byte[] input, TransitOptions options)
      Signs with options (hash algorithm, signature algorithm, prehashed, key version, context).
      Parameters:
      name - key name
      input - bytes
      options - options
      Returns:
      the signature
    • signAsync

      public CompletableFuture<Signature> signAsync(String name, byte[] input, TransitOptions o)
      Parameters:
      name - key name
      input - bytes
      o - options
      Returns:
      a future with the signature
    • verify

      public boolean verify(String name, byte[] input, String signature)
      Verifies a signature; false for an invalid signature (not an error).
      Parameters:
      name - key name
      input - signed bytes
      signature - vault:v<n>: signature
      Returns:
      whether the signature is valid
    • verify

      public boolean verify(String name, byte[] input, String signature, TransitOptions options)
      Verifies a signature with options.
      Parameters:
      name - key name
      input - signed bytes
      signature - signature
      options - options
      Returns:
      whether the signature is valid
    • verifyHmac

      public boolean verifyHmac(String name, byte[] input, String hmac)
      Verifies an HMAC produced by hmac(java.lang.String, byte[]).
      Parameters:
      name - key name
      input - bytes
      hmac - vault:v<n>: HMAC
      Returns:
      whether the HMAC is valid
    • verifyAsync

      public CompletableFuture<Boolean> verifyAsync(String name, byte[] input, String signature, String hmac, TransitOptions o)
      Asynchronous verification of a signature or an HMAC (exactly one must be given).
      Parameters:
      name - key name
      input - bytes
      signature - signature, or null
      hmac - HMAC, or null
      o - options
      Returns:
      a future with the result
    • hash

      public String hash(byte[] input)
      SHA2-256 hash of the input, hex encoded.
      Parameters:
      input - bytes
      Returns:
      the hash
    • hash

      public String hash(byte[] input, String algorithm, String format)
      Hash of the input.
      Parameters:
      input - bytes
      algorithm - e.g. sha2-256 (default), sha2-512, sha3-256; may be null
      format - hex (default) or base64; may be null
      Returns:
      the hash
    • hashAsync

      public CompletableFuture<String> hashAsync(byte[] input, String algorithm, String format)
      Parameters:
      input - bytes
      algorithm - algorithm, may be null
      format - format, may be null
      Returns:
      a future with the hash
    • randomBytes

      public String randomBytes(int bytes)
      Random bytes from the server, base64 encoded.
      Parameters:
      bytes - number of bytes
      Returns:
      the base64 text
    • randomBytes

      public String randomBytes(int bytes, String format)
      Random bytes from the server.
      Parameters:
      bytes - number of bytes (positive)
      format - base64 or hex
      Returns:
      the encoded bytes
    • randomBytesAsync

      public CompletableFuture<String> randomBytesAsync(int bytes, String format)
      Parameters:
      bytes - number of bytes
      format - format, may be null for base64
      Returns:
      a future with the encoded bytes
    • toString

      public String toString()
      Overrides:
      toString in class Object