com.google.crypto.tink

Class Registry

java.lang.Object

com.google.crypto.tink.Registry

public final class Registry
extends Object

A global container of key managers and catalogues.

Registry maps each supported key type to a corresponding KeyManager object, which "understands" the key type (i.e., the KeyManager can instantiate the primitive corresponding to given key, or can generate new keys of the supported key type). It holds also a PrimitiveWrapper for each supported primitive, so that it can wrap a set of primitives (corresponding to a keyset) into a single primitive.

Keeping KeyManagers for all primitives in a single Registry (rather than having a separate KeyManager per primitive) enables modular construction of compound primitives from "simple" ones, e.g., AES-CTR-HMAC AEAD encryption uses IND-CPA encryption and a MAC.

Registry is initialized at startup, and is later used to instantiate primitives for given keys or keysets. Note that regular users will usually not work directly with Registry, but rather via TinkConfig and KeysetHandle.getPrimitive(Class)-methods, which in the background register and query the Registry for specific KeyManagers and PrimitiveWrappers. Registry is public though, to enable configurations with custom catalogues, primitives or KeyManagers.

To initialize the Registry with all key managers:

 TinkConfig.register();
 

Here's how to register only Aead key managers:

 AeadConfig.register();
 

After the Registry has been initialized, one can use get a primitive as follows:

 KeysetHandle keysetHandle = ...;
 Aead aead = keysetHandle.getPrimitive(Aead.class);
 

Since:

1.0.0

Method Summary

Modifier and Type	Method and Description
static void	addCatalogue(String catalogueName, Catalogue<?> catalogue) Deprecated. Catalogues are no longer supported.
static Catalogue<?>	getCatalogue(String catalogueName) Deprecated. Catalogues are no longer supported.
static Class<?>	getInputPrimitive(Class<?> wrappedPrimitive) Returns the input primitive required when creating a wrappedPrimitive.
static <P> KeyManager<P>	getKeyManager(String typeUrl) Deprecated. Use getKeyManager(typeUrl, Primitive.class) or getUntypedKeyManager typeUrl instead.
static <P> KeyManager<P>	getKeyManager(String typeUrl, Class<P> primitiveClass)
static <P> P	getPrimitive(KeyData keyData) Deprecated. Use getPrimitive(keyData, Primitive.class) instead.
static <P> P	getPrimitive(KeyData keyData, Class<P> primitiveClass) Convenience method for creating a new primitive for the key given in keyData.
static <P> P	getPrimitive(String typeUrl, byte[] serializedKey) Deprecated. Use getPrimitive(typeUrl, serializedKey, Primitive.class) instead.
static <P> P	getPrimitive(String typeUrl, byte[] serializedKey, Class<P> primitiveClass) Convenience method for creating a new primitive for the key given in serializedKey.
static <P> P	getPrimitive(String typeUrl, com.google.protobuf.ByteString serializedKey) Deprecated. Use getPrimitive(typeUrl, serializedKey, Primitive.class instead.
static <P> P	getPrimitive(String typeUrl, com.google.protobuf.ByteString serializedKey, Class<P> primitiveClass) Convenience method for creating a new primitive for the key given in serializedKey.
static <P> P	getPrimitive(String typeUrl, com.google.protobuf.MessageLite key) Deprecated. Use getPrimitive(typeUrl, key, P.class) instead.
static <P> P	getPrimitive(String typeUrl, com.google.protobuf.MessageLite key, Class<P> primitiveClass) Convenience method for creating a new primitive for the key given in key.
static KeyData	getPublicKeyData(String typeUrl, com.google.protobuf.ByteString serializedPrivateKey) Convenience method for extracting the public key data from the private key given in serializedPrivateKey.
static KeyManager<?>	getUntypedKeyManager(String typeUrl)
static List<String>	keyTemplates() Returns an immutable list of key template names supported by registered key managers that are allowed to generate new keys.
static com.google.protobuf.MessageLite	newKey(KeyTemplate keyTemplate) Convenience method for generating a new key for the specified keyTemplate.
static com.google.protobuf.MessageLite	newKey(String typeUrl, com.google.protobuf.MessageLite format) Convenience method for generating a new key for the specified format.
static KeyData	newKeyData(KeyTemplate keyTemplate) Convenience method for generating a new KeyData for the specified template.
static KeyData	newKeyData(KeyTemplate keyTemplate) Convenience method for generating a new KeyData for the specified template.
static <KeyProtoT extends com.google.protobuf.MessageLite,PublicKeyProtoT extends com.google.protobuf.MessageLite> void	registerAsymmetricKeyManagers(PrivateKeyTypeManager<KeyProtoT,PublicKeyProtoT> privateKeyTypeManager, KeyTypeManager<PublicKeyProtoT> publicKeyTypeManager, boolean newKeyAllowed) Tries to register manager for manager.getKeyType().
static <P> void	registerKeyManager(KeyManager<P> manager) Tries to register manager for manager.getKeyType().
static <P> void	registerKeyManager(KeyManager<P> manager, boolean newKeyAllowed) Tries to register manager for manager.getKeyType().
static <KeyProtoT extends com.google.protobuf.MessageLite> void	registerKeyManager(KeyTypeManager<KeyProtoT> manager, boolean newKeyAllowed) Tries to register manager for manager.getKeyType().
static <P> void	registerKeyManager(String typeUrl, KeyManager<P> manager) Deprecated. use registerKeyManager(KeyManager<P>)
static <P> void	registerKeyManager(String typeUrl, KeyManager<P> manager, boolean newKeyAllowed) Deprecated. use registerKeyManager(KeyManager<P>, boolean)
static <B,P> void	registerPrimitiveWrapper(PrimitiveWrapper<B,P> wrapper) Tries to register wrapper as a new SetWrapper for primitive P.
static void	restrictToFipsIfEmpty() Tries to enable the FIPS restrictions if the Registry is empty.
static <B,P> P	wrap(PrimitiveSet<B> primitiveSet, Class<P> clazz) Looks up the globally registered PrimitiveWrapper for this primitive and wraps the given PrimitiveSet with it.
static <P> P	wrap(PrimitiveSet<P> primitiveSet)

Methods inherited from class java.lang.Object

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

Method Detail

addCatalogue

@Deprecated
public static void addCatalogue(String catalogueName,
                                            Catalogue<?> catalogue)
                                     throws GeneralSecurityException

Deprecated. Catalogues are no longer supported.

Tries to add a catalogue, to enable custom configuration of key types and key managers.

Adding a custom catalogue should be a one-time operaton. There is an existing catalogue, throw exception if catalogue and the existing catalogue aren't instances of the same class, and do nothing if they are.

Throws:

GeneralSecurityException - if there's an existing catalogue and it is not an instance of the same class as catalogue

getCatalogue

@Deprecated
public static Catalogue<?> getCatalogue(String catalogueName)
                                             throws GeneralSecurityException

Deprecated. Catalogues are no longer supported.

Tries to get a catalogue associated with catalogueName.

Throws:

GeneralSecurityException - if no catalogue is found

registerKeyManager

public static <P> void registerKeyManager(KeyManager<P> manager)
                                   throws GeneralSecurityException

Tries to register manager for manager.getKeyType(). Users can generate new keys with this manager using the newKey(com.google.crypto.tink.proto.KeyTemplate) methods.

If there is an existing key manager, throws an exception if manager and the existing key manager aren't instances of the same class, or the existing key manager could not create new keys. Otherwise registration succeeds.

Throws:

GeneralSecurityException - if there's an existing key manager is not an instance of the class of manager, or the registration tries to re-enable the generation of new keys.

registerKeyManager

public static <P> void registerKeyManager(KeyManager<P> manager,
                                          boolean newKeyAllowed)
                                   throws GeneralSecurityException

Tries to register manager for manager.getKeyType(). If newKeyAllowed is true, users can generate new keys with this manager using the newKey(com.google.crypto.tink.proto.KeyTemplate) methods.

If there is an existing key manager, throws an exception if manager and the existing key manager aren't instances of the same class, or if newKeyAllowed is true while the existing key manager could not create new keys. Otherwise registration succeeds.

Throws:

GeneralSecurityException - if there's an existing key manager is not an instance of the class of manager, or the registration tries to re-enable the generation of new keys.

registerKeyManager

public static <KeyProtoT extends com.google.protobuf.MessageLite> void registerKeyManager(KeyTypeManager<KeyProtoT> manager,
                                                                                          boolean newKeyAllowed)
                                                                                   throws GeneralSecurityException

Tries to register manager for manager.getKeyType(). If newKeyAllowed is true, users can generate new keys with this manager using the newKey(com.google.crypto.tink.proto.KeyTemplate) methods.

If there is an existing key manager, throws an exception if manager and the existing key manager aren't instances of the same class, or if newKeyAllowed is true while the existing key manager could not create new keys. Otherwise registration succeeds.

If newKeyAllowed is true, also tries to register the key templates supported by manager.

Throws:

GeneralSecurityException - if there's an existing key manager is not an instance of the class of manager, or the registration tries to re-enable the generation of new keys.

GeneralSecurityException - if there's an existing key template.

GeneralSecurityException - if the key manager is not compatible with the restrictions in FIPS-mode.

registerKeyManager

@Deprecated
public static <P> void registerKeyManager(String typeUrl,
                                                      KeyManager<P> manager)
                                               throws GeneralSecurityException

Deprecated. use registerKeyManager(KeyManager<P>)

Tries to register manager for the given typeUrl. Users can generate new keys with this manager using the newKey(com.google.crypto.tink.proto.KeyTemplate) methods.

Does nothing if there's an existing key manager and it's an instance of the same class as manager.

Throws:

GeneralSecurityException - if there's an existing key manager and it is not an instance of the same class as manager

registerKeyManager

@Deprecated
public static <P> void registerKeyManager(String typeUrl,
                                                      KeyManager<P> manager,
                                                      boolean newKeyAllowed)
                                               throws GeneralSecurityException

Deprecated. use registerKeyManager(KeyManager<P>, boolean)

Tries to register manager for the given typeUrl. If newKeyAllowed is true, users can generate new keys with this manager using the newKey(com.google.crypto.tink.proto.KeyTemplate) methods.

Does nothing if there's an existing key manager and it's an instance of the same class as manager.

Throws:

GeneralSecurityException - if there's an existing key manager and it is not an instance of the same class as manager

registerAsymmetricKeyManagers

public static <KeyProtoT extends com.google.protobuf.MessageLite,PublicKeyProtoT extends com.google.protobuf.MessageLite> void registerAsymmetricKeyManagers(PrivateKeyTypeManager<KeyProtoT,PublicKeyProtoT> privateKeyTypeManager,
                                                                                                                                                             KeyTypeManager<PublicKeyProtoT> publicKeyTypeManager,
                                                                                                                                                             boolean newKeyAllowed)
                                                                                                                                                      throws GeneralSecurityException

Tries to register manager for manager.getKeyType(). If newKeyAllowed is true, users can generate new keys with this manager using the newKey(com.google.crypto.tink.proto.KeyTemplate) methods.

If newKeyAllowed is true, also tries to register the key templates supported by manager.

If there is an existing key manager, throws an exception if manager and the existing key manager aren't instances of the same class, or if newKeyAllowed is true while the existing key manager could not create new keys. Otherwise registration succeeds.

Throws:

GeneralSecurityException - if there's an existing key manager is not an instance of the class of manager, or the registration tries to re-enable the generation of new keys.

GeneralSecurityException - if there's an existing key template.

registerPrimitiveWrapper

public static <B,P> void registerPrimitiveWrapper(PrimitiveWrapper<B,P> wrapper)
                                           throws GeneralSecurityException

Tries to register wrapper as a new SetWrapper for primitive P.

If no SetWrapper is registered for P, registers the given one. If there already is a SetWrapper registered which is of the same class ass the passed in set wrapper, the call is silently ignored. If the new set wrapper is of a different type, the call fails with a GeneralSecurityException.

Throws:

GeneralSecurityException - if there's an existing key manager and it is not an instance of the class of manager, or the registration tries to re-enable the generation of new keys.

getKeyManager

@Deprecated
public static <P> KeyManager<P> getKeyManager(String typeUrl)
                                                   throws GeneralSecurityException

Deprecated. Use getKeyManager(typeUrl, Primitive.class) or getUntypedKeyManager typeUrl instead.

Returns:

a KeyManager for the given typeUrl (if found).

Throws:

GeneralSecurityException

getKeyManager

public static <P> KeyManager<P> getKeyManager(String typeUrl,
                                              Class<P> primitiveClass)
                                       throws GeneralSecurityException

Returns:

a KeyManager for the given typeUrl (if found).

Throws:

GeneralSecurityException

getUntypedKeyManager

public static KeyManager<?> getUntypedKeyManager(String typeUrl)
                                          throws GeneralSecurityException

Returns:

a KeyManager for the given typeUrl (if found).

Throws:

GeneralSecurityException

newKeyData

public static KeyData newKeyData(KeyTemplate keyTemplate)
                          throws GeneralSecurityException

Convenience method for generating a new KeyData for the specified template.

It looks up a KeyManager identified by keyTemplate.type_url, and calls KeyManager.newKeyData(com.google.protobuf.ByteString).

This method should be used solely for key management.

Returns:

a new KeyData

Throws:

GeneralSecurityException

newKeyData

public static KeyData newKeyData(KeyTemplate keyTemplate)
                          throws GeneralSecurityException

Convenience method for generating a new KeyData for the specified template.

It looks up a KeyManager identified by keyTemplate.type_url, and calls KeyManager.newKeyData(com.google.protobuf.ByteString).

This method should be used solely for key management.

Returns:

a new KeyData

Throws:

GeneralSecurityException

newKey

public static com.google.protobuf.MessageLite newKey(KeyTemplate keyTemplate)
                                              throws GeneralSecurityException

Convenience method for generating a new key for the specified keyTemplate.

It looks up a KeyManager identified by keyTemplate.type_url, and calls KeyManager.newKey(com.google.protobuf.ByteString) with keyTemplate as the parameter.

Returns:

a new key

Throws:

GeneralSecurityException

newKey

public static com.google.protobuf.MessageLite newKey(String typeUrl,
                                                     com.google.protobuf.MessageLite format)
                                              throws GeneralSecurityException

Convenience method for generating a new key for the specified format.

It looks up a KeyManager identified by keyTemplate.type_url, and calls KeyManager.newKey(com.google.protobuf.ByteString) with format as the parameter.

Returns:

a new key

Throws:

GeneralSecurityException

getPublicKeyData

public static KeyData getPublicKeyData(String typeUrl,
                                       com.google.protobuf.ByteString serializedPrivateKey)
                                throws GeneralSecurityException

Convenience method for extracting the public key data from the private key given in serializedPrivateKey.

It looks up a PrivateKeyManager identified by typeUrl, and calls PrivateKeyManager.getPublicKeyData(com.google.protobuf.ByteString) with serializedPrivateKey as the parameter.

Returns:

a new key

Throws:

GeneralSecurityException

getPrimitive

@Deprecated
public static <P> P getPrimitive(String typeUrl,
                                             com.google.protobuf.MessageLite key)
                                      throws GeneralSecurityException

Deprecated. Use getPrimitive(typeUrl, key, P.class) instead.

Convenience method for creating a new primitive for the key given in proto.

It looks up a KeyManager identified by type_url, and calls KeyManager.getPrimitive(com.google.protobuf.ByteString) with key as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

public static <P> P getPrimitive(String typeUrl,
                                 com.google.protobuf.MessageLite key,
                                 Class<P> primitiveClass)
                          throws GeneralSecurityException

Convenience method for creating a new primitive for the key given in key.

It looks up a KeyManager identified by type_url, and calls KeyManager.getPrimitive(com.google.protobuf.ByteString) with key as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

@Deprecated
public static <P> P getPrimitive(String typeUrl,
                                             com.google.protobuf.ByteString serializedKey)
                                      throws GeneralSecurityException

Deprecated. Use getPrimitive(typeUrl, serializedKey, Primitive.class instead.

Convenience method for creating a new primitive for the key given in proto.

It looks up a KeyManager identified by type_url, and calls KeyManager.getPrimitive(com.google.protobuf.ByteString) with serializedKey as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

public static <P> P getPrimitive(String typeUrl,
                                 com.google.protobuf.ByteString serializedKey,
                                 Class<P> primitiveClass)
                          throws GeneralSecurityException

Convenience method for creating a new primitive for the key given in serializedKey.

It looks up a KeyManager identified by type_url, and calls KeyManager.getPrimitive(com.google.protobuf.ByteString) with serialized as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

@Deprecated
public static <P> P getPrimitive(String typeUrl,
                                             byte[] serializedKey)
                                      throws GeneralSecurityException

Deprecated. Use getPrimitive(typeUrl, serializedKey, Primitive.class) instead.

Convenience method for creating a new primitive for the key given in serializedKey.

It looks up a KeyManager identified by type_url, and calls KeyManager.getPrimitive(com.google.protobuf.ByteString) with serialized as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

public static <P> P getPrimitive(String typeUrl,
                                 byte[] serializedKey,
                                 Class<P> primitiveClass)
                          throws GeneralSecurityException

Convenience method for creating a new primitive for the key given in serializedKey.

It looks up a KeyManager identified by type_url, and calls KeyManager.getPrimitive(com.google.protobuf.ByteString) with serialized as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

@Deprecated
public static <P> P getPrimitive(KeyData keyData)
                                      throws GeneralSecurityException

Deprecated. Use getPrimitive(keyData, Primitive.class) instead.

Convenience method for creating a new primitive for the key given in keyData.

It looks up a KeyManager identified by keyData.type_url, and calls KeyManager.getPrimitive(com.google.protobuf.ByteString) with keyData.value as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

public static <P> P getPrimitive(KeyData keyData,
                                 Class<P> primitiveClass)
                          throws GeneralSecurityException

Convenience method for creating a new primitive for the key given in keyData.

It looks up a KeyManager identified by keyData.type_url, and calls KeyManager.getPrimitive(com.google.protobuf.ByteString) with keyData.value as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

wrap

public static <B,P> P wrap(PrimitiveSet<B> primitiveSet,
                           Class<P> clazz)
                    throws GeneralSecurityException

Looks up the globally registered PrimitiveWrapper for this primitive and wraps the given PrimitiveSet with it.

Throws:

GeneralSecurityException

wrap

public static <P> P wrap(PrimitiveSet<P> primitiveSet)
                  throws GeneralSecurityException

Throws:

GeneralSecurityException

keyTemplates

public static List<String> keyTemplates()

Returns an immutable list of key template names supported by registered key managers that are allowed to generate new keys.

Since:

1.6.0

getInputPrimitive

@Nullable
public static Class<?> getInputPrimitive(Class<?> wrappedPrimitive)

Returns the input primitive required when creating a wrappedPrimitive.

This returns the primitive class of the objects required when we want to create a wrapped primitive of type wrappedPrimitive. Returns null if no wrapper for this primitive has been registered.

restrictToFipsIfEmpty

public static void restrictToFipsIfEmpty()
                                  throws GeneralSecurityException

Tries to enable the FIPS restrictions if the Registry is empty.

Throws:

GeneralSecurityException - if any key manager has already been registered.