Package com.google.crypto.tink

Class Registry

  • public final class Registry
extends java.lang.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(RegistryConfiguration.get(), Aead.class);
    Since:
    1.0.0

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static void addCatalogue​(java.lang.String catalogueName, Catalogue<?> catalogue)
      Deprecated.
      Catalogues are no longer supported.
      static Catalogue<?> getCatalogue​(java.lang.String catalogueName)
      Deprecated.
      Catalogues are no longer supported.
      static <P> KeyManager<P> getKeyManager​(java.lang.String typeUrl, java.lang.Class<P> primitiveClass)
      Deprecated.
      KeyManagers should not be used directly.
      static <P> P getPrimitive​(com.google.crypto.tink.proto.KeyData keyData, java.lang.Class<P> primitiveClass)
      Deprecated.
      Use the standard API instead or file an issue on https://github.com/tink-crypto/tink-java, explaining your use case.
      static <P> P getPrimitive​(java.lang.String typeUrl, byte[] serializedKey, java.lang.Class<P> primitiveClass)
      Deprecated.
      Use the standard API instead or file an issue on https://github.com/tink-crypto/tink-java, explaining your use case.
      static <P> P getPrimitive​(java.lang.String typeUrl, com.google.protobuf.ByteString serializedKey, java.lang.Class<P> primitiveClass)
      Deprecated.
      Use the standard API instead or file an issue on https://github.com/tink-crypto/tink-java, explaining your use case.
      static <P> P getPrimitive​(java.lang.String typeUrl, com.google.protobuf.MessageLite key, java.lang.Class<P> primitiveClass)
      Deprecated.
      Use getPrimitive(typeUrl, serializedKey, Primitive.class instead.
      static com.google.crypto.tink.proto.KeyData getPublicKeyData​(java.lang.String typeUrl, com.google.protobuf.ByteString serializedPrivateKey)
      Deprecated.
      Instead, users should have their keys in a KeysetHandle and call keysetHandle.getPublicKeysetHandle.
      static KeyManager<?> getUntypedKeyManager​(java.lang.String typeUrl)
      Deprecated.
      KeyManagers should not be used directly.
      static java.util.List<java.lang.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​(com.google.crypto.tink.proto.KeyTemplate keyTemplate)
      Deprecated.
      Use newKeyData instead.
      static com.google.protobuf.MessageLite newKey​(java.lang.String typeUrl, com.google.protobuf.MessageLite format)
      Deprecated.
      Use newKeyData instead.
      static com.google.crypto.tink.proto.KeyData newKeyData​(KeyTemplate keyTemplate)
      Deprecated.
      Use KeysetHandle.generateNew(keyTemplate.toParameters()) instead and use the Keyset Handle API.
      static com.google.crypto.tink.proto.KeyData newKeyData​(com.google.crypto.tink.proto.KeyTemplate keyTemplate)
      Deprecated.
      Use KeysetHandle.generateNew with a Parameters object instead.
      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​(java.lang.String typeUrl, KeyManager<P> manager)
      Deprecated.
      use registerKeyManager(KeyManager<P>)
      static <P> void registerKeyManager​(java.lang.String typeUrl, KeyManager<P> manager, boolean newKeyAllowed)
      Deprecated.
      use registerKeyManager(KeyManager<P>, boolean)
      static void restrictToFipsIfEmpty()
      Tries to enable the FIPS restrictions if the Registry is empty.

      • 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​(java.lang.String catalogueName,
                                Catalogue<?> catalogue)
                         throws java.security.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:
        java.security.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​(java.lang.String catalogueName)
                                 throws java.security.GeneralSecurityException
        Deprecated.
        Catalogues are no longer supported.
        Tries to get a catalogue associated with catalogueName.
        Throws:
        java.security.GeneralSecurityException - if no catalogue is found

      • registerKeyManager

        public static <P> void registerKeyManager​(KeyManager<P> manager)
                                   throws java.security.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:
        java.security.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 java.security.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:
        java.security.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​(java.lang.String typeUrl,
                                          KeyManager<P> manager)
                                   throws java.security.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:
        java.security.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​(java.lang.String typeUrl,
                                          KeyManager<P> manager,
                                          boolean newKeyAllowed)
                                   throws java.security.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:
        java.security.GeneralSecurityException - if there's an existing key manager and it is not an instance of the same class as manager

      • getKeyManager

        @Deprecated
public static <P> KeyManager<P> getKeyManager​(java.lang.String typeUrl,
                                              java.lang.Class<P> primitiveClass)
                                       throws java.security.GeneralSecurityException
        Deprecated.
        KeyManagers should not be used directly. Use newKeyData or getPrimitive instead.
        Returns a KeyManager for the given typeUrl (if found).
        Throws:
        java.security.GeneralSecurityException

      • getUntypedKeyManager

        @Deprecated
public static KeyManager<?> getUntypedKeyManager​(java.lang.String typeUrl)
                                          throws java.security.GeneralSecurityException
        Deprecated.
        KeyManagers should not be used directly. Use newKeyData or getPrimitive instead.
        Returns a KeyManager for the given typeUrl (if found).
        Throws:
        java.security.GeneralSecurityException

      • newKeyData

        @Deprecated
public static com.google.crypto.tink.proto.KeyData newKeyData​(com.google.crypto.tink.proto.KeyTemplate keyTemplate)
                                                       throws java.security.GeneralSecurityException
        Deprecated.
        Use KeysetHandle.generateNew with a Parameters object instead. To convert a proto KeyTemplate to a parameters one can use TinkProtoParametersFormat.parse(t.toByteArray());
        Generates 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:
        java.security.GeneralSecurityException

      • newKeyData

        @Deprecated
public static com.google.crypto.tink.proto.KeyData newKeyData​(KeyTemplate keyTemplate)
                                                       throws java.security.GeneralSecurityException
        Deprecated.
        Use KeysetHandle.generateNew(keyTemplate.toParameters()) instead and use the Keyset Handle API.
        Generates 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:
        java.security.GeneralSecurityException

      • newKey

        @Deprecated
public static com.google.protobuf.MessageLite newKey​(com.google.crypto.tink.proto.KeyTemplate keyTemplate)
                                              throws java.security.GeneralSecurityException
        Deprecated.
        Use newKeyData instead.
        Generates 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:
        java.security.GeneralSecurityException

      • newKey

        @Deprecated
public static com.google.protobuf.MessageLite newKey​(java.lang.String typeUrl,
                                                     com.google.protobuf.MessageLite format)
                                              throws java.security.GeneralSecurityException
        Deprecated.
        Use newKeyData instead.
        Generates 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:
        java.security.GeneralSecurityException

      • getPublicKeyData

        @Deprecated
public static com.google.crypto.tink.proto.KeyData getPublicKeyData​(java.lang.String typeUrl,
                                                                    com.google.protobuf.ByteString serializedPrivateKey)
                                                             throws java.security.GeneralSecurityException
        Deprecated.
        Instead, users should have their keys in a KeysetHandle and call keysetHandle.getPublicKeysetHandle.
        Extracts 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:
        the public key of the corresponding private key
        Throws:
        java.security.GeneralSecurityException

      • getPrimitive

        @Deprecated
public static <P> P getPrimitive​(java.lang.String typeUrl,
                                 com.google.protobuf.MessageLite key,
                                 java.lang.Class<P> primitiveClass)
                          throws java.security.GeneralSecurityException
        Deprecated.
        Use getPrimitive(typeUrl, serializedKey, Primitive.class instead.
        Creates 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:
        java.security.GeneralSecurityException

      • getPrimitive

        @Deprecated
public static <P> P getPrimitive​(java.lang.String typeUrl,
                                 com.google.protobuf.ByteString serializedKey,
                                 java.lang.Class<P> primitiveClass)
                          throws java.security.GeneralSecurityException
        Deprecated.
        Use the standard API instead or file an issue on https://github.com/tink-crypto/tink-java, explaining your use case.
        Creates 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:
        java.security.GeneralSecurityException

      • getPrimitive

        @Deprecated
public static <P> P getPrimitive​(java.lang.String typeUrl,
                                 byte[] serializedKey,
                                 java.lang.Class<P> primitiveClass)
                          throws java.security.GeneralSecurityException
        Deprecated.
        Use the standard API instead or file an issue on https://github.com/tink-crypto/tink-java, explaining your use case.
        Creates 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:
        java.security.GeneralSecurityException

      • getPrimitive

        @Deprecated
public static <P> P getPrimitive​(com.google.crypto.tink.proto.KeyData keyData,
                                 java.lang.Class<P> primitiveClass)
                          throws java.security.GeneralSecurityException
        Deprecated.
        Use the standard API instead or file an issue on https://github.com/tink-crypto/tink-java, explaining your use case.
        Creates 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:
        java.security.GeneralSecurityException

      • keyTemplates

        public static java.util.List<java.lang.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

      • restrictToFipsIfEmpty

        public static void restrictToFipsIfEmpty()
                                  throws java.security.GeneralSecurityException
        Tries to enable the FIPS restrictions if the Registry is empty.
        Throws:
        java.security.GeneralSecurityException - if any key manager has already been registered.