registry

Documentation

Overview

Package registry provides a container that for each supported key type holds a corresponding KeyManager object, which can generate new keys or instantiate the primitive corresponding to given key.

Registry is initialized at startup, and is later used to instantiate primitives for given keys or keysets. 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.

Note that regular users will usually not work directly with Registry, but rather via primitive factories, which in the background query the Registry for specific KeyManagers. Registry is public though, to enable configurations with custom primitives and KeyManagers.

Index

• func ClearKMSClients()
• func NewKey(template *tinkpb.KeyTemplate) (proto.Message, error)
• func NewKeyData(template *tinkpb.KeyTemplate) (*tinkpb.KeyData, error)
• func Primitive(typeURL string, serializedKey []byte) (any, error)
• func PrimitiveFromKeyData(keyData *tinkpb.KeyData) (any, error)
• func RegisterKMSClient(kmsClient KMSClient)
• func RegisterKeyManager(keyManager KeyManager) error
• type KMSClient
  • func GetKMSClient(keyURI string) (KMSClient, error)
• type KeyManager
  • func GetKeyManager(typeURL string) (KeyManager, error)
• type PrivateKeyManager

Functions

func ClearKMSClients

func ClearKMSClients()

ClearKMSClients removes all registered KMS clients.

Should only be used in tests.

func NewKey

func NewKey(template *tinkpb.KeyTemplate) (proto.Message, error)

NewKey generates a new key for the given key template.

Deprecated: use NewKeyData instead.

func NewKeyData

func NewKeyData(template *tinkpb.KeyTemplate) (*tinkpb.KeyData, error)

NewKeyData generates a new KeyData for the given key template.

func Primitive

func Primitive(typeURL string, serializedKey []byte) (any, error)

Primitive creates a new primitive for the given serialized key using the KeyManager identified by the given typeURL. Note that the returned primitive does not add/remove the output prefix. It is the caller's responsibility to handle this correctly, based on the key's output_prefix_type.

func PrimitiveFromKeyData

func PrimitiveFromKeyData(keyData *tinkpb.KeyData) (any, error)

PrimitiveFromKeyData creates a new primitive for the key given in the given KeyData. Note that the returned primitive does not add/remove the output prefix. It is the caller's responsibility to handle this correctly, based on the key's output_prefix_type.

func RegisterKMSClient

func RegisterKMSClient(kmsClient KMSClient)

RegisterKMSClient is used to register a new KMS client.

This function adds an object to a global list. It should only be called on startup.

In many cases, registering a KMS client is not needed. Instead, call kmsClient.GetAEAD to get a remote AEAD, and then use it to encrypt a keyset with keyset.Write, or to create an envelope AEAD using aead.NewKMSEnvelopeAEAD2.

func RegisterKeyManager

func RegisterKeyManager(keyManager KeyManager) error

RegisterKeyManager registers the given key manager. Does not allow to overwrite existing key managers.

Types

type KMSClient

type KMSClient interface {
	// Supported true if this client does support keyURI
	Supported(keyURI string) bool

	// GetAEAD  gets an AEAD backend by keyURI.
	GetAEAD(keyURI string) (tink.AEAD, error)
}

KMSClient knows how to produce primitives backed by keys stored in remote KMS services.

func GetKMSClient

func GetKMSClient(keyURI string) (KMSClient, error)

GetKMSClient fetches a KMSClient by a given URI.

type KeyManager

type KeyManager interface {
	// Primitive constructs a primitive instance for the key given in serializedKey, which must be a
	// serialized key protocol buffer handled by this manager.
	Primitive(serializedKey []byte) (any, error)

	// NewKey generates a new key according to specification in serializedKeyFormat, which must be
	// supported by this manager.
	//
	// Deprecated: Tink always used [NewKeyData] to create new keys. This function is
	// unused (except in the unused and deprecated function [registry.NewKey]). It doesn't need to be
	// implemented.
	NewKey(serializedKeyFormat []byte) (proto.Message, error)

	// DoesSupport returns true iff this KeyManager supports key type identified by typeURL.
	DoesSupport(typeURL string) bool

	// TypeURL returns the type URL that identifies the key type of keys managed by this key manager.
	TypeURL() string

	// NewKeyData generates a new KeyData according to specification in serializedkeyFormat.
	// This should be used solely by the key management API.
	NewKeyData(serializedKeyFormat []byte) (*tinkpb.KeyData, error)
}

KeyManager "understands" keys of a specific key types: it can generate keys of a supported type and create primitives for supported keys. A key type is identified by the global name of the protocol buffer that holds the corresponding key material, and is given by type_url-field of KeyData-protocol buffer.

func GetKeyManager

func GetKeyManager(typeURL string) (KeyManager, error)

GetKeyManager returns the key manager for the given typeURL if existed.

type PrivateKeyManager

type PrivateKeyManager interface {
	KeyManager

	// PublicKeyData extracts the public key data from the private key.
	PublicKeyData(serializedKey []byte) (*tinkpb.KeyData, error)
}

PrivateKeyManager is a special type of KeyManager that understands private key types.