Package com.google.crypto.tink.aead

Class KmsEnvelopeAead

  • All Implemented Interfaces:
    Aead
    public final class KmsEnvelopeAead
extends java.lang.Object
implements Aead
    This primitive implements envelope encryption.

    In envelope encryption, a user generates a data encryption key (DEK) locally, encrypts data with the DEK, sends the DEK to a KMS to be encrypted (with a key managed by KMS), and then stores the encrypted DEK with the encrypted data. At a later point, a user can retrieve the encrypted data and the encyrpted DEK, use the KMS to decrypt the DEK, and use the decrypted DEK to decrypt the data.

    The ciphertext structure is as follows:

    • Length of the encrypted DEK: 4 bytes.
    • Encrypted DEK: variable length that is equal to the value specified in the last 4 bytes.
    • AEAD payload: variable length.

    • Constructor Summary

      Constructors 
      Constructor Description
      KmsEnvelopeAead​(com.google.crypto.tink.proto.KeyTemplate dekTemplate, Aead remote)
      Deprecated.
      Instead, call KmsEnvelopeAead.create as explained above.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static Aead create​(AeadParameters dekParameters, Aead remote)
      Creates a new instance of Tink's KMS Envelope AEAD.
      byte[] decrypt​(byte[] ciphertext, byte[] associatedData)
      Decrypts ciphertext with associatedData as associated authenticated data.
      byte[] encrypt​(byte[] plaintext, byte[] associatedData)
      Encrypts plaintext with associatedData as associated authenticated data.
      static boolean isSupportedDekKeyType​(java.lang.String dekKeyTypeUrl)  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • KmsEnvelopeAead

        @Deprecated
public KmsEnvelopeAead​(com.google.crypto.tink.proto.KeyTemplate dekTemplate,
                       Aead remote)
                throws java.security.GeneralSecurityException
        Deprecated.
        Instead, call KmsEnvelopeAead.create as explained above.
        Creates a new KmsEnvelopeAead.

        This function should be avoided. Instead, if you use this with one of the predefined key templates, call create with the corresponding parameters object.

        For example, if you use:

        Aead aead = new KmsEnvelopeAead(AeadKeyTemplates.AES128_GCM, remote) you should replace this with:

        Aead aead = KmsEnvelopeAead.create(PredefinedAeadParameters.AES128_GCM, remote)

        Throws:
        java.security.GeneralSecurityException

    • Method Detail

      • isSupportedDekKeyType

        public static boolean isSupportedDekKeyType​(java.lang.String dekKeyTypeUrl)

      • encrypt

        public byte[] encrypt​(byte[] plaintext,
                      byte[] associatedData)
               throws java.security.GeneralSecurityException
        Description copied from interface: Aead
        Encrypts plaintext with associatedData as associated authenticated data. The resulting ciphertext allows for checking authenticity and integrity of associated data (associatedData), but does not guarantee its secrecy.
        Specified by:
        encrypt in interface Aead
        Parameters:
        plaintext - the plaintext to be encrypted. It must be non-null, but can also be an empty (zero-length) byte array
        associatedData - associated data to be authenticated, but not encrypted. Associated data is optional, so this parameter can be null. In this case the null value is equivalent to an empty (zero-length) byte array. For successful decryption the same associatedData must be provided along with the ciphertext.
        Returns:
        resulting ciphertext
        Throws:
        java.security.GeneralSecurityException

      • decrypt

        public byte[] decrypt​(byte[] ciphertext,
                      byte[] associatedData)
               throws java.security.GeneralSecurityException
        Description copied from interface: Aead
        Decrypts ciphertext with associatedData as associated authenticated data. The decryption verifies the authenticity and integrity of the associated data, but there are no guarantees wrt. secrecy of that data.
        Specified by:
        decrypt in interface Aead
        Parameters:
        ciphertext - the plaintext to be decrypted. It must be non-null.
        associatedData - associated data to be authenticated. For successful decryption it must be the same as associatedData used during encryption. Can be null, which is equivalent to an empty (zero-length) byte array.
        Returns:
        resulting plaintext
        Throws:
        java.security.GeneralSecurityException - if decryption fails. Decryption must fail if ciphertext is not correctly authenticated for the given associatedData.