Package org.apache.iceberg.encryption

Interface KmsClient

  • All Superinterfaces:
    java.io.Serializable
    public interface KmsClient
extends java.io.Serializable
    A minimum client interface to connect to a key management service (KMS).

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  KmsClient.KeyGenerationResult
      For KMS systems that support key generation, this class keeps the key generation result - the raw secret key, and its wrap.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default KmsClient.KeyGenerationResult generateKey​(java.lang.String wrappingKeyId)
      Generate a new secret key in the KMS server, and wrap it using a wrapping/master key which is stored in KMS and referenced by an ID.
      void initialize​(java.util.Map<java.lang.String,​java.lang.String> properties)
      Initialize the KMS client with given properties
      default boolean supportsKeyGeneration()
      Some KMS systems support generation of secret keys inside the KMS server.
      java.nio.ByteBuffer unwrapKey​(java.lang.String wrappedKey, java.lang.String wrappingKeyId)
      Unwrap a secret key, using a wrapping/master key which is stored in KMS and referenced by an ID.
      java.lang.String wrapKey​(java.nio.ByteBuffer key, java.lang.String wrappingKeyId)
      Wrap a secret key, using a wrapping/master key which is stored in KMS and referenced by an ID.

    • Method Detail

      • wrapKey

        java.lang.String wrapKey​(java.nio.ByteBuffer key,
                         java.lang.String wrappingKeyId)
        Wrap a secret key, using a wrapping/master key which is stored in KMS and referenced by an ID. Wrapping means encryption of the secret key with the master key, and adding optional KMS-specific metadata that allows the KMS to decrypt the secret key in an unwrapping call.
        Parameters:
        key - a secret key being wrapped
        wrappingKeyId - a key ID that represents a wrapping key stored in KMS
        Returns:
        wrapped key material

      • supportsKeyGeneration

        default boolean supportsKeyGeneration()
        Some KMS systems support generation of secret keys inside the KMS server.
        Returns:
        true if KMS server supports key generation and KmsClient implementation is interested to leverage this capability. Otherwise, return false - Iceberg will then generate secret keys locally (using the SecureRandom mechanism) and call wrapKey(ByteBuffer, String) to wrap them in KMS.

      • generateKey

        default KmsClient.KeyGenerationResult generateKey​(java.lang.String wrappingKeyId)
        Generate a new secret key in the KMS server, and wrap it using a wrapping/master key which is stored in KMS and referenced by an ID. This method will be called only if supportsKeyGeneration returns true.
        Parameters:
        wrappingKeyId - a key ID that represents a wrapping key stored in KMS
        Returns:
        key in two forms: raw, and wrapped with the given wrappingKeyId

      • unwrapKey

        java.nio.ByteBuffer unwrapKey​(java.lang.String wrappedKey,
                              java.lang.String wrappingKeyId)
        Unwrap a secret key, using a wrapping/master key which is stored in KMS and referenced by an ID.
        Parameters:
        wrappedKey - wrapped key material (encrypted key and optional KMS metadata, returned by the wrapKey method)
        wrappingKeyId - a key ID that represents a wrapping key stored in KMS
        Returns:
        raw key bytes

      • initialize

        void initialize​(java.util.Map<java.lang.String,​java.lang.String> properties)
        Initialize the KMS client with given properties
        Parameters:
        properties - kms client properties