com.google.crypto.tink

Class KeysetHandle

java.lang.Object

com.google.crypto.tink.KeysetHandle

public final class KeysetHandle
extends Object

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	KeysetHandle.Builder Used to create new KeysetHandle objects.
static class	KeysetHandle.Entry Represents a single entry in a keyset.

Method Summary

Modifier and Type	Method and Description
static KeysetHandle	createFromKey(KeyHandle keyHandle, KeyAccess access) Deprecated. Use KeysetHandle.Builder.addEntry instead.
boolean	equalsKeyset(KeysetHandle other) Returns true if this keyset is equal to other, ignoring monitoring annotations.
static KeysetHandle.Builder.Entry	generateEntryFromParameters(Parameters parameters) Creates a new entry with Status "ENABLED" and a new key created from the parameters.
static KeysetHandle.Builder.Entry	generateEntryFromParametersName(String parametersName) Creates a new entry with Status "ENABLED" and a new key created from the named parameters.
static KeysetHandle	generateNew(KeyTemplate keyTemplate) Deprecated. Use the overload taking a Parameters object instead.
static KeysetHandle	generateNew(KeyTemplate keyTemplate) Generates a new KeysetHandle that contains a single fresh key generated according to keyTemplate.
static KeysetHandle	generateNew(Parameters parameters) Generates a new KeysetHandle that contains a single fresh key generated key with the given Parameters object.
KeysetHandle.Entry	getAt(int i) Returns the entry at index i.
List<KeyHandle>	getKeys() Deprecated. Use "getAt" instead.
KeysetInfo	getKeysetInfo() Returns the KeysetInfo that doesn't contain actual key material.
KeysetHandle.Entry	getPrimary() Returns the unique entry where isPrimary() = true and getStatus() = ENABLED.
<P> P	getPrimitive(Class<P> targetClassObject) Returns a primitive from this keyset, using the global registry to create resources creating the primitive.
<P> P	getPrimitive(Configuration configuration, Class<P> targetClassObject) Returns a primitive from this keyset using the provided Configuration to create resources used in creating the primitive.
KeysetHandle	getPublicKeysetHandle() If the managed keyset contains private keys, returns a KeysetHandle of the public keys.
static KeysetHandle.Builder.Entry	importKey(Key key) Creates a new entry with a fixed key.
static KeysetHandle.Builder	newBuilder() Creates a new builder.
static KeysetHandle.Builder	newBuilder(KeysetHandle handle) Creates a new builder, initially containing all entries from handle.
KeyHandle	primaryKey() Deprecated. Use getPrimary() instead.
static KeysetHandle	read(KeysetReader reader, Aead masterKey) Tries to create a KeysetHandle from an encrypted keyset obtained via reader.
static KeysetHandle	readNoSecret(byte[] serialized) Deprecated. Call {TinkProtoKeysetFormat.parseKeysetWithoutSecret} instead.
static KeysetHandle	readNoSecret(KeysetReader reader) Tries to create a KeysetHandle from a keyset, obtained via reader, which contains no secret key material.
static KeysetHandle	readWithAssociatedData(KeysetReader reader, Aead masterKey, byte[] associatedData) Tries to create a KeysetHandle from an encrypted keyset obtained via reader, using the provided associated data.
int	size() Returns the size of this keyset.
String	toString() Extracts and returns the string representation of the KeysetInfo of the managed keyset.
void	write(KeysetWriter keysetWriter, Aead masterKey) Serializes, encrypts with masterKey and writes the keyset to outputStream.
void	writeNoSecret(KeysetWriter writer) Tries to write to writer this keyset which must not contain any secret key material.
void	writeWithAssociatedData(KeysetWriter keysetWriter, Aead masterKey, byte[] associatedData) Serializes, encrypts with masterKey and writes the keyset to outputStream using the provided associated data.

Methods inherited from class java.lang.Object

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

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(String parametersName)
                                                                  throws 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:

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.

newBuilder

public static KeysetHandle.Builder newBuilder()

Creates a new builder.

newBuilder

public static KeysetHandle.Builder newBuilder(KeysetHandle handle)

Creates a new builder, initially containing all entries from handle.

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.

size

public int size()

Returns the size of this keyset.

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).

Throws:

IndexOutOfBoundsException - if i < 0 or i >= size();

getKeys

@Deprecated
public 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

public KeysetInfo getKeysetInfo()

Returns the KeysetInfo that doesn't contain actual key material.

generateNew

public static final KeysetHandle generateNew(Parameters parameters)
                                      throws GeneralSecurityException

Generates a new KeysetHandle that contains a single fresh key generated key with the given Parameters object.

Throws:

GeneralSecurityException - if no generation method for the given parameters has been registered.

generateNew

@Deprecated
public static final KeysetHandle generateNew(KeyTemplate keyTemplate)
                                                  throws 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:

GeneralSecurityException - if the key template is invalid.

generateNew

public static final KeysetHandle generateNew(KeyTemplate keyTemplate)
                                      throws 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:

GeneralSecurityException - if the key template is invalid.

createFromKey

@Deprecated
public static final KeysetHandle createFromKey(KeyHandle keyHandle,
                                                           KeyAccess access)
                                                    throws GeneralSecurityException

Deprecated. Use KeysetHandle.Builder.addEntry instead.

Returns a KeysetHandle that contains the single KeyHandle passed as input.

Throws:

GeneralSecurityException

read

public static final KeysetHandle read(KeysetReader reader,
                                      Aead masterKey)
                               throws GeneralSecurityException,
                                      IOException

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:

GeneralSecurityException - if cannot decrypt the keyset or it doesn't contain encrypted key material

IOException

readWithAssociatedData

public static final KeysetHandle readWithAssociatedData(KeysetReader reader,
                                                        Aead masterKey,
                                                        byte[] associatedData)
                                                 throws GeneralSecurityException,
                                                        IOException

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:

GeneralSecurityException - if cannot decrypt the keyset or it doesn't contain encrypted key material

IOException

readNoSecret

public static final KeysetHandle readNoSecret(KeysetReader reader)
                                       throws GeneralSecurityException,
                                              IOException

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:

GeneralSecurityException - if the keyset is invalid

IOException

readNoSecret

@Deprecated
public static final KeysetHandle readNoSecret(byte[] serialized)
                                                   throws 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:

GeneralSecurityException - if the keyset is invalid

write

public void write(KeysetWriter keysetWriter,
                  Aead masterKey)
           throws GeneralSecurityException,
                  IOException

Serializes, encrypts with masterKey and writes the keyset to outputStream.

Throws:

GeneralSecurityException

IOException

writeWithAssociatedData

public void writeWithAssociatedData(KeysetWriter keysetWriter,
                                    Aead masterKey,
                                    byte[] associatedData)
                             throws GeneralSecurityException,
                                    IOException

Serializes, encrypts with masterKey and writes the keyset to outputStream using the provided associated data.

Throws:

GeneralSecurityException

IOException

writeNoSecret

public void writeNoSecret(KeysetWriter writer)
                   throws GeneralSecurityException,
                          IOException

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:

GeneralSecurityException - if the keyset contains any secret key material

IOException

getPublicKeysetHandle

public KeysetHandle getPublicKeysetHandle()
                                   throws GeneralSecurityException

If the managed keyset contains private keys, returns a KeysetHandle of the public keys.

Throws:

GeneralSecurityException - if the managed keyset is null or if it contains any non-private keys.

toString

public String toString()

Extracts and returns the string representation of the KeysetInfo of the managed keyset.

Overrides:

toString in class Object

getPrimitive

public <P> P getPrimitive(Configuration configuration,
                          Class<P> targetClassObject)
                   throws GeneralSecurityException

Returns a primitive from this keyset using the provided Configuration to create resources used in creating the primitive.

Throws:

GeneralSecurityException

getPrimitive

@InlineMe(replacement="this.getPrimitive(RegistryConfiguration.get(), targetClassObject)",
          imports="com.google.crypto.tink.RegistryConfiguration")
public <P> P getPrimitive(Class<P> targetClassObject)
                                                                                                                                                                                throws GeneralSecurityException

Returns a primitive from this keyset, using the global registry to create resources creating the primitive.

Throws:

GeneralSecurityException

primaryKey

@Deprecated
public KeyHandle primaryKey()
                                 throws 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:

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.