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 catalogue names to instances of Catalogue and 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). 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 Config and primitive factories which in the background register and query the Registry for specific KeyManagers. Registry is public though, to enable configurations with custom catalogues, primitives or KeyManagers.

To initialize the Registry with all key managers in Tink 1.0.0, one can do as follows:

 TinkConfig.register();
 

Here's how to register only Aead key managers:

 AeadConfig.register();
 

After the Registry has been initialized, one can use AeadFactory, MacFactory, etc., to obtain corresponding primitive instances. For example, here's how to obtain an Aead primitive:

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

Since:

1.0.0

Constructor Summary

Constructors

Constructor and Description
Registry()

Method Summary

Modifier and Type	Method and Description
static <P> void	addCatalogue(String catalogueName, Catalogue<P> catalogue) Tries to add a catalogue, to enable custom configuration of key types and key managers.
static <P> Catalogue<P>	getCatalogue(String catalogueName) Tries to get a catalogue associated with catalogueName.
static <P> KeyManager<P>	getKeyManager(String typeUrl)
static <P> P	getPrimitive(KeyData keyData) Convenience method for creating a new primitive for the key given in proto.
static <P> P	getPrimitive(String typeUrl, byte[] serialized) Convenience method for creating a new primitive for the key given in proto.
static <P> P	getPrimitive(String typeUrl, com.google.protobuf.ByteString serialized) Convenience method for creating a new primitive for the key given in proto.
static <P> P	getPrimitive(String typeUrl, com.google.protobuf.MessageLite key) Convenience method for creating a new primitive for the key given in proto.
static <P> PrimitiveSet<P>	getPrimitives(KeysetHandle keysetHandle) Creates a set of primitives corresponding to the keys with status=ENABLED in the keyset given in keysetHandle, assuming all the corresponding key managers are present (keys with status!=ENABLED are skipped).
static <P> PrimitiveSet<P>	getPrimitives(KeysetHandle keysetHandle, KeyManager<P> customManager) Creates a set of primitives corresponding to the keys with status=ENABLED in the keyset given in keysetHandle, using customManager (instead of registered key managers) for keys supported by it.
static <P> 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 <P> com.google.protobuf.MessageLite	newKey(KeyTemplate keyTemplate) Convenience method for generating a new key for the specified keyTemplate.
static <P> com.google.protobuf.MessageLite	newKey(String typeUrl, com.google.protobuf.MessageLite format) Convenience method for generating a new key for the specified format.
static <P> KeyData	newKeyData(KeyTemplate keyTemplate) Convenience method for generating a new KeyData for the specified template.
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 <P> void	registerKeyManager(String typeUrl, KeyManager<P> manager) Deprecated. use #registerKeyManager(KeyManager )
static <P> void	registerKeyManager(String typeUrl, KeyManager<P> manager, boolean newKeyAllowed) Deprecated. use #registerKeyManager(KeyManager , boolean)

Methods inherited from class java.lang.Object

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

Constructor Detail

Registry

public Registry()

Method Detail

addCatalogue

public static <P> void addCatalogue(String catalogueName,
                                    Catalogue<P> catalogue)
                             throws GeneralSecurityException

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 is not an instance of the same class as catalogue

getCatalogue

public static <P> Catalogue<P> getCatalogue(String catalogueName)
                                     throws GeneralSecurityException

Tries to get a catalogue associated with catalogueName.

Throws:

GeneralSecurityException - if cannot find any catalogue

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

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

Deprecated. use #registerKeyManager(KeyManager

)

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.

If there is an existing key manager, throw exception if manager and the existing key manager aren't instances of the same class, and do nothing if they are.

Throws:

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

registerKeyManager

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

Deprecated. use #registerKeyManager(KeyManager

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

If there is an existing key manager, throw exception if manager and the existing key manager aren't instances of the same class, and do nothing if they are.

Throws:

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

getKeyManager

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

Returns:

a KeyManager for the given typeUrl (if found).

TODO(przydatek): find a way for verifying the primitive type.

Throws:

GeneralSecurityException

newKeyData

public static <P> 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 <P> 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 <P> 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 <P> 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

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

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.ByteString serialized)
                          throws GeneralSecurityException

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 serialized as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

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

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 serialized as the parameter.

Returns:

a new primitive

Throws:

GeneralSecurityException

getPrimitive

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

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

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

getPrimitives

public static <P> PrimitiveSet<P> getPrimitives(KeysetHandle keysetHandle)
                                         throws GeneralSecurityException

Creates a set of primitives corresponding to the keys with status=ENABLED in the keyset given in keysetHandle, assuming all the corresponding key managers are present (keys with status!=ENABLED are skipped).

The returned set is usually later "wrapped" into a class that implements the corresponding Primitive-interface.

Returns:

a PrimitiveSet with all instantiated primitives

Throws:

GeneralSecurityException

getPrimitives

public static <P> PrimitiveSet<P> getPrimitives(KeysetHandle keysetHandle,
                                                KeyManager<P> customManager)
                                         throws GeneralSecurityException

Creates a set of primitives corresponding to the keys with status=ENABLED in the keyset given in keysetHandle, using customManager (instead of registered key managers) for keys supported by it. Keys not supported by customManager are handled by matching registered key managers (if present), and keys with status!=ENABLED are skipped.

This enables custom treatment of keys, for example providing extra context (e.g., credentials for accessing keys managed by a KMS), or gathering custom monitoring/profiling information.

The returned set is usually later "wrapped" into a class that implements the corresponding Primitive-interface.

Returns:

a PrimitiveSet with all instantiated primitives

Throws:

GeneralSecurityException