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

Method Summary

Modifier and Type	Method and Description
static void	assertEnoughEncryptedKeyMaterial(com.google.crypto.tink.proto.EncryptedKeyset keyset) Validates that an encrypted keyset contains enough key material to build a keyset on.
static void	assertEnoughKeyMaterial(com.google.crypto.tink.proto.Keyset keyset) Validates that a keyset handle contains enough key material to build a keyset on.
static KeysetHandle	generateNew(com.google.crypto.tink.proto.KeyTemplate keyTemplate) Deprecated. This method takes a KeyTemplate proto, which is an internal implementation detail. Please use the generateNew method that takes a KeyTemplate POJO.
static KeysetHandle	generateNew(KeyTemplate keyTemplate) Generates a new KeysetHandle that contains a single fresh key generated according to keyTemplate.
com.google.crypto.tink.proto.KeysetInfo	getKeysetInfo()
<P> P	getPrimitive(Class<P> classObject) Returns a primitive from this keyset, using the global registry to create resources creating the primitive.
<P> P	getPrimitive(KeyManager<P> customKeyManager, Class<P> classObject) Returns a primitive from this keyset, using the given customKeyManager and the global registry to get resources creating the primitive.
KeysetHandle	getPublicKeysetHandle() If the managed keyset contains private keys, returns a KeysetHandle of the public keys.
static KeysetHandle	read(KeysetReader reader, Aead masterKey) Tries to create a KeysetHandle from an encrypted keyset obtained via reader.
static KeysetHandle	readNoSecret(byte[] serialized) Tries to create a KeysetHandle from a serialized keyset which contains no secret key material.
static KeysetHandle	readNoSecret(KeysetReader reader) Tries to create a KeysetHandle from a keyset, obtained via reader, which contains no secret key material.
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.

Methods inherited from class java.lang.Object

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

Method Detail

getKeysetInfo

public com.google.crypto.tink.proto.KeysetInfo getKeysetInfo()

Returns:

the KeysetInfo that doesn't contain actual key material.

generateNew

@Deprecated
public static final KeysetHandle generateNew(com.google.crypto.tink.proto.KeyTemplate keyTemplate)
                                                  throws GeneralSecurityException

Deprecated. This method takes a KeyTemplate proto, which is an internal implementation detail. Please use the generateNew method that takes a KeyTemplate POJO.

Generates a new KeysetHandle that contains a single fresh key generated according to keyTemplate.

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.

Throws:

GeneralSecurityException - if the key template is invalid.

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

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

IOException

readNoSecret

public static final KeysetHandle readNoSecret(byte[] serialized)
                                       throws GeneralSecurityException

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.

Returns:

a new KeysetHandle from serialized that is a serialized Keyset

Throws:

GeneralSecurityException

write

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

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

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:

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

GeneralSecurityException

toString

public String toString()

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

Overrides:

toString in class Object

assertEnoughKeyMaterial

public static void assertEnoughKeyMaterial(com.google.crypto.tink.proto.Keyset keyset)
                                    throws GeneralSecurityException

Validates that a keyset handle contains enough key material to build a keyset on.

Throws:

GeneralSecurityException

assertEnoughEncryptedKeyMaterial

public static void assertEnoughEncryptedKeyMaterial(com.google.crypto.tink.proto.EncryptedKeyset keyset)
                                             throws GeneralSecurityException

Validates that an encrypted keyset contains enough key material to build a keyset on.

Throws:

GeneralSecurityException

getPrimitive

public <P> P getPrimitive(Class<P> classObject)
                   throws GeneralSecurityException

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

Throws:

GeneralSecurityException

getPrimitive

public <P> P getPrimitive(KeyManager<P> customKeyManager,
                          Class<P> classObject)
                   throws GeneralSecurityException

Returns a primitive from this keyset, using the given customKeyManager and the global registry to get resources creating the primitive. The given keyManager will take precedence when creating primitives over the globally registered keyManagers.

Throws:

GeneralSecurityException