Package com.google.crypto.tink

Class KeysetHandle

  • All Implemented Interfaces:
    KeysetHandleInterface
    public final class KeysetHandle
extends java.lang.Object
implements KeysetHandleInterface
    A KeysetHandle provides abstracted access to Keyset, to limit the exposure of actual protocol buffers that hold sensitive key material.

    This class allows reading and writing encrypted keysets. Users that want to read or write can use the restricted API CleartextKeysetHandle. Users can also load keysets that don't contain any secret key material with NoSecretKeysetHandle.

    Since:
    1.0.0

    • Method Detail

      • importKey

        public static KeysetHandle.Builder.Entry importKey​(Key key)
        Creates a new entry with a fixed key.

        If the Key has an IdRequirement, the default will be fixed to this ID. Otherwise, the user has to specify the ID to be used and call one of withFixedId(i) or withRandomId() on the returned entry.

      • generateEntryFromParametersName

        public static KeysetHandle.Builder.Entry generateEntryFromParametersName​(java.lang.String parametersName)
                                                                  throws java.security.GeneralSecurityException
        Creates a new entry with Status "ENABLED" and a new key created from the named parameters. No ID is set.

        namedParameters is the key template name that fully specifies the parameters, e.g. "DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM".

        Throws:
        java.security.GeneralSecurityException

      • generateEntryFromParameters

        public static KeysetHandle.Builder.Entry generateEntryFromParameters​(Parameters parameters)
        Creates a new entry with Status "ENABLED" and a new key created from the parameters. No ID is set.

      • getPrimary

        public KeysetHandle.Entry getPrimary()
        Returns the unique entry where isPrimary() = true and getStatus() = ENABLED.

        Note: currently this may throw IllegalStateException, since it is possible that keysets are parsed without a primary. In the future, such keysets will be rejected when the keyset is parsed.

        Specified by:
        getPrimary in interface KeysetHandleInterface

      • getAt

        public KeysetHandle.Entry getAt​(int i)
        Returns the entry at index i. The order is preserved and depends on the order at which the entries were inserted when the KeysetHandle was built.

        Currently, this may throw "IllegalStateException" in case the status entry of the Key in the keyset was wrongly set. In this case, we call this KeysetHandle invalid. In the future, Tink will throw at parsing time in this case, and we will not have invalid KeysetHandles.

        If you want to ensure that this does not throw an IllegalStateException, please first re-parse the KeysetHandle: KeysetHandle guaranteedValid = KeysetHandle.newBuilder(maybeInvalidHandle).build(); (This would throw a GeneralSecurityException if the maybeInvalidHandle handle is invalid).

        Specified by:
        getAt in interface KeysetHandleInterface
        Throws:
        java.lang.IndexOutOfBoundsException - if i < 0 or i >= size();

      • getKeys

        @Deprecated
public java.util.List<KeyHandle> getKeys()
        Deprecated.
        Use "getAt" instead.
        Returns the keyset data as a list of KeyHandles.

        Please do not use this function in new code. Instead, use getAt(int).

      • getKeysetInfo

        @Deprecated
public com.google.crypto.tink.proto.KeysetInfo getKeysetInfo()
        Deprecated.
        Most information can be obtained by calling getPrimary() or getAt(int) and inspecting the result. For legacy code, LegacyKeysetSerialization.getKeysetInfo gives the exact same output.
        Returns the KeysetInfo that doesn't contain actual key material.

      • generateNew

        public static final KeysetHandle generateNew​(Parameters parameters)
                                      throws java.security.GeneralSecurityException
        Generates a new KeysetHandle that contains a single fresh key generated key with the given Parameters object.
        Throws:
        java.security.GeneralSecurityException - if no generation method for the given parameters has been registered.

      • generateNew

        @Deprecated
public static final KeysetHandle generateNew​(com.google.crypto.tink.proto.KeyTemplate keyTemplate)
                                      throws java.security.GeneralSecurityException
        Deprecated.
        Use the overload taking a Parameters object instead.
        Generates a new KeysetHandle that contains a single fresh key generated according to keyTemplate.

        Please do not use this function. Instead, use generateNew(Parameters).

        For existing usage, try to use refaster https://github.com/tink-crypto/tink-java/tree/main/tools/refaster to replace usage automatically. This will replaces calls KeysetHandle.generateNew(XYZKeyTemplates.ABC); with KeysetHandle.generateNew(PredefinedXYZParameters.ABC); which is a NO-OP.

        If this is not possible, please inline the function in your code.

        Throws:
        java.security.GeneralSecurityException - if the key template is invalid.

      • generateNew

        public static final KeysetHandle generateNew​(KeyTemplate keyTemplate)
                                      throws java.security.GeneralSecurityException
        Generates a new KeysetHandle that contains a single fresh key generated according to keyTemplate.

        Please do not use this function. Instead, inline it: replace calls with generateNew(t) with generateNew(t.toParameters()).

        Throws:
        java.security.GeneralSecurityException - if the key template is invalid.

      • createFromKey

        @Deprecated
public static final KeysetHandle createFromKey​(KeyHandle keyHandle,
                                               KeyAccess access)
                                        throws java.security.GeneralSecurityException
        Deprecated.
        Use KeysetHandle.Builder.addEntry instead.
        Returns a KeysetHandle that contains the single KeyHandle passed as input.
        Throws:
        java.security.GeneralSecurityException

      • read

        @Deprecated
public static final KeysetHandle read​(KeysetReader reader,
                                      Aead masterKey)
                               throws java.security.GeneralSecurityException,
                                      java.io.IOException
        Deprecated.
        New users should prefer TinkProtoKeysetFormat. Existing users can use LegacyKeysetSerialization for exactly the same behavior.
        Tries to create a KeysetHandle from an encrypted keyset obtained via reader.

        Users that need to load cleartext keysets can use CleartextKeysetHandle.

        Returns:
        a new KeysetHandle from encryptedKeysetProto that was encrypted with masterKey
        Throws:
        java.security.GeneralSecurityException - if cannot decrypt the keyset or it doesn't contain encrypted key material
        java.io.IOException

      • readWithAssociatedData

        @Deprecated
public static final KeysetHandle readWithAssociatedData​(KeysetReader reader,
                                                        Aead masterKey,
                                                        byte[] associatedData)
                                                 throws java.security.GeneralSecurityException,
                                                        java.io.IOException
        Deprecated.
        New users should prefer TinkProtoKeysetFormat. Existing users can use LegacyKeysetSerialization for exactly the same behavior.
        Tries to create a KeysetHandle from an encrypted keyset obtained via reader, using the provided associated data.

        Users that need to load cleartext keysets can use CleartextKeysetHandle.

        Returns:
        a new KeysetHandle from encryptedKeysetProto that was encrypted with masterKey
        Throws:
        java.security.GeneralSecurityException - if cannot decrypt the keyset or it doesn't contain encrypted key material
        java.io.IOException

      • readNoSecret

        @Deprecated
public static final KeysetHandle readNoSecret​(KeysetReader reader)
                                       throws java.security.GeneralSecurityException,
                                              java.io.IOException
        Deprecated.
        New users should prefer TinkProtoKeysetFormat. Existing users can use LegacyKeysetSerialization for exactly the same behavior.
        Tries to create a KeysetHandle from a keyset, obtained via reader, which contains no secret key material.

        This can be used to load public keysets or envelope encryption keysets. Users that need to load cleartext keysets can use CleartextKeysetHandle.

        Returns:
        a new KeysetHandle from serialized that is a serialized Keyset
        Throws:
        java.security.GeneralSecurityException - if the keyset is invalid
        java.io.IOException

      • readNoSecret

        @Deprecated
public static final KeysetHandle readNoSecret​(byte[] serialized)
                                       throws java.security.GeneralSecurityException
        Deprecated.
        Call {TinkProtoKeysetFormat.parseKeysetWithoutSecret} instead.
        Tries to create a KeysetHandle from a serialized keyset which contains no secret key material.

        This can be used to load public keysets or envelope encryption keysets. Users that need to load cleartext keysets can use CleartextKeysetHandle.

        Note: new code should call TinkProtoKeysetFormat(serialized) instead.

        Returns:
        a new KeysetHandle from serialized that is a serialized Keyset
        Throws:
        java.security.GeneralSecurityException - if the keyset is invalid

      • write

        @Deprecated
public void write​(KeysetWriter keysetWriter,
                  Aead masterKey)
           throws java.security.GeneralSecurityException,
                  java.io.IOException
        Deprecated.
        New users should prefer TinkProtoKeysetFormat. Existing users can use LegacyKeysetSerialization for exactly the same behavior.
        Serializes, encrypts with masterKey and writes the keyset to outputStream.
        Throws:
        java.security.GeneralSecurityException
        java.io.IOException

      • writeWithAssociatedData

        @Deprecated
public void writeWithAssociatedData​(KeysetWriter keysetWriter,
                                    Aead masterKey,
                                    byte[] associatedData)
                             throws java.security.GeneralSecurityException,
                                    java.io.IOException
        Deprecated.
        New users should prefer TinkProtoKeysetFormat. Existing users can use LegacyKeysetSerialization for exactly the same behavior.
        Serializes, encrypts with masterKey and writes the keyset to outputStream using the provided associated data.
        Throws:
        java.security.GeneralSecurityException
        java.io.IOException

      • writeNoSecret

        @Deprecated
public void writeNoSecret​(KeysetWriter writer)
                   throws java.security.GeneralSecurityException,
                          java.io.IOException
        Deprecated.
        New users should prefer TinkProtoKeysetFormat. Existing users can use LegacyKeysetSerialization for exactly the same behavior.
        Tries to write to writer this keyset which must not contain any secret key material.

        This can be used to persist public keysets or envelope encryption keysets. Users that need to persist cleartext keysets can use CleartextKeysetHandle.

        Throws:
        java.security.GeneralSecurityException - if the keyset contains any secret key material
        java.io.IOException

      • getPublicKeysetHandle

        public KeysetHandle getPublicKeysetHandle()
                                   throws java.security.GeneralSecurityException
        If the managed keyset contains private keys, returns a KeysetHandle of the public keys.
        Throws:
        java.security.GeneralSecurityException - if the managed keyset is null or if it contains any non-private keys.

      • toString

        public java.lang.String toString()
        Extracts and returns the string representation of the KeysetInfo of the managed keyset.
        Overrides:
        toString in class java.lang.Object

      • getPrimitive

        public <P> P getPrimitive​(Configuration configuration,
                          java.lang.Class<P> targetClassObject)
                   throws java.security.GeneralSecurityException
        Returns a primitive from this keyset using the provided Configuration to create resources used in creating the primitive.
        Throws:
        java.security.GeneralSecurityException

      • getPrimitive

        @Deprecated
@InlineMe(replacement="this.getPrimitive(RegistryConfiguration.get(), targetClassObject)",
          imports="com.google.crypto.tink.RegistryConfiguration")
public <P> P getPrimitive​(java.lang.Class<P> targetClassObject)
                   throws java.security.GeneralSecurityException
        Deprecated.
        New users should use KeysetHandle.getPrimitive with a suitable Configuration. Existing users can use KeysetHandle.getPrimitive(RegistryConfiguration.get(), targetClassObject) for exactly the same behavior.
        Returns a primitive from this keyset, using the global registry to create resources creating the primitive.
        Throws:
        java.security.GeneralSecurityException

      • primaryKey

        @Deprecated
public KeyHandle primaryKey()
                     throws java.security.GeneralSecurityException
        Deprecated.
        Use getPrimary() instead.
        Searches the keyset to find the primary key of this KeysetHandle, and returns the key wrapped in a KeyHandle.

        Please do not use this function in new code. Instead, use getPrimary().

        Throws:
        java.security.GeneralSecurityException

      • equalsKeyset

        public boolean equalsKeyset​(KeysetHandle other)
        Returns true if this keyset is equal to other, ignoring monitoring annotations.

        Note: this may return false even if the keysets represent the same set of functions. For example, this can happen if the keys store zero-byte padding of a BigInteger, which are irrelevant to the function computed. Currently, keysets can also be invalid in which case this will return false.