Package org.apache.iceberg.encryption

Interface KeyManagementClient

All Superinterfaces:
AutoCloseable, Closeable, Serializable
All Known Implementing Classes:
AwsKeyManagementClient, GcpKeyManagementClient
public interface KeyManagementClient extends Serializable, Closeable
A minimum client interface to connect to a key management service (KMS).

  • Nested Class Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Close KMS Client to release underlying resources, this could be triggered in different threads when KmsClient is shared by multiple encryption managers.
    default KeyManagementClient.KeyGenerationResult
    generateKey(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(Map<String,String> properties)
    Initialize the KMS client with given properties.
    default boolean
    supportsKeyGeneration()
    Some KMS systems support generation of secret keys inside the KMS server.
    ByteBuffer
    unwrapKey(ByteBuffer wrappedKey, String wrappingKeyId)
    Unwrap a secret key, using a wrapping/master key which is stored in KMS and referenced by an ID.
    ByteBuffer
    wrapKey(ByteBuffer key, String wrappingKeyId)
    Wrap a secret key, using a wrapping/master key which is stored in KMS and referenced by an ID.

  • Method Details

    • wrapKey

      ByteBuffer wrapKey(ByteBuffer key, 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 KeyManagementClient 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 KeyManagementClient.KeyGenerationResult generateKey(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

      ByteBuffer unwrapKey(ByteBuffer wrappedKey, 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(Map<String,String> properties)
      Initialize the KMS client with given properties.
      Parameters:
      properties - kms client properties

    • close

      default void close()
      Close KMS Client to release underlying resources, this could be triggered in different threads when KmsClient is shared by multiple encryption managers.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable