Documentation
¶
Overview ¶
Package keyset provides methods to generate, read, write or validate keysets.
Example (EncryptedKeyset) ¶
package main
// [START encrypted-keyset-example]
import (
"bytes"
"fmt"
"log"
"github.com/tink-crypto/tink-go/v2/aead"
"github.com/tink-crypto/tink-go/v2/keyset"
"github.com/tink-crypto/tink-go/v2/testing/fakekms"
)
// The fake KMS should only be used in tests. It is not secure.
const keyURI = "fake-kms://CM2b3_MDElQKSAowdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUuY3J5cHRvLnRpbmsuQWVzR2NtS2V5EhIaEIK75t5L-adlUwVhWvRuWUwYARABGM2b3_MDIAE"
func main() {
// Get a KEK (key encryption key) AEAD. This is usually a remote AEAD to a KMS. In this example,
// we use a fake KMS to avoid making RPCs.
client, err := fakekms.NewClient(keyURI)
if err != nil {
log.Fatal(err)
}
kekAEAD, err := client.GetAEAD(keyURI)
if err != nil {
log.Fatal(err)
}
// Generate a new keyset handle for the primitive we want to use.
newHandle, err := keyset.NewHandle(aead.AES256GCMKeyTemplate())
if err != nil {
log.Fatal(err)
}
// Choose some associated data. This is the context in which the keyset will be used.
keysetAssociatedData := []byte("keyset encryption example")
// Encrypt the keyset with the KEK AEAD and the associated data.
buf := new(bytes.Buffer)
writer := keyset.NewBinaryWriter(buf)
err = newHandle.WriteWithAssociatedData(writer, kekAEAD, keysetAssociatedData)
if err != nil {
log.Fatal(err)
}
encryptedKeyset := buf.Bytes()
// The encrypted keyset can now be stored.
// To use the primitive, we first need to decrypt the keyset. We use the same
// KEK AEAD and the same associated data that we used to encrypt it.
reader := keyset.NewBinaryReader(bytes.NewReader(encryptedKeyset))
handle, err := keyset.ReadWithAssociatedData(reader, kekAEAD, keysetAssociatedData)
if err != nil {
log.Fatal(err)
}
// Get the primitive.
primitive, err := aead.New(handle)
if err != nil {
log.Fatal(err)
}
// Use the primitive.
plaintext := []byte("message")
associatedData := []byte("example encryption")
ciphertext, err := primitive.Encrypt(plaintext, associatedData)
if err != nil {
log.Fatal(err)
}
decrypted, err := primitive.Decrypt(ciphertext, associatedData)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(decrypted))
}
// [END encrypted-keyset-example]
Output: message
Index ¶
- func Validate(keyset *tinkpb.Keyset) error
- func ValidateKeyVersion(version, maxExpected uint32) error
- type BinaryReader
- type BinaryWriter
- type Handle
- func NewHandle(kt *tinkpb.KeyTemplate) (*Handle, error)
- func NewHandleWithNoSecrets(ks *tinkpb.Keyset) (*Handle, error)
- func Read(reader Reader, masterKey tink.AEAD) (*Handle, error)
- func ReadWithAssociatedData(reader Reader, masterKey tink.AEAD, associatedData []byte) (*Handle, error)
- func ReadWithNoSecrets(reader Reader) (*Handle, error)
- func (h *Handle) KeysetInfo() *tinkpb.KeysetInfo
- func (h *Handle) Primitives() (*primitiveset.PrimitiveSet, error)
- func (h *Handle) PrimitivesWithKeyManager(km registry.KeyManager) (*primitiveset.PrimitiveSet, error)
- func (h *Handle) Public() (*Handle, error)
- func (h *Handle) String() string
- func (h *Handle) Write(writer Writer, masterKey tink.AEAD) error
- func (h *Handle) WriteWithAssociatedData(writer Writer, masterKey tink.AEAD, associatedData []byte) error
- func (h *Handle) WriteWithNoSecrets(w Writer) error
- type JSONReader
- type JSONWriter
- type Manager
- type MemReaderWriterdeprecated
- type Option
- type Reader
- type Writer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Validate ¶
Validate validates the given key set. Returns nil if it is valid; an error otherwise.
func ValidateKeyVersion ¶
ValidateKeyVersion checks whether the given version is valid. The version is valid only if it is the range [0..maxExpected]
Types ¶
type BinaryReader ¶
type BinaryReader struct {
// contains filtered or unexported fields
}
BinaryReader deserializes a keyset from binary proto format.
func NewBinaryReader ¶
func NewBinaryReader(r io.Reader) *BinaryReader
NewBinaryReader returns new BinaryReader that will read from r.
func (*BinaryReader) Read ¶
func (bkr *BinaryReader) Read() (*tinkpb.Keyset, error)
Read parses a (cleartext) keyset from the underlying io.Reader.
func (*BinaryReader) ReadEncrypted ¶
func (bkr *BinaryReader) ReadEncrypted() (*tinkpb.EncryptedKeyset, error)
ReadEncrypted parses an EncryptedKeyset from the underlying io.Reader.
type BinaryWriter ¶
type BinaryWriter struct {
// contains filtered or unexported fields
}
BinaryWriter serializes a keyset into binary proto format.
func NewBinaryWriter ¶
func NewBinaryWriter(w io.Writer) *BinaryWriter
NewBinaryWriter returns a new BinaryWriter that will write to w.
func (*BinaryWriter) Write ¶
func (bkw *BinaryWriter) Write(keyset *tinkpb.Keyset) error
Write writes the keyset to the underlying io.Writer.
func (*BinaryWriter) WriteEncrypted ¶
func (bkw *BinaryWriter) WriteEncrypted(keyset *tinkpb.EncryptedKeyset) error
WriteEncrypted writes the encrypted keyset to the underlying io.Writer.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle provides access to a Keyset protobuf, to limit the exposure of actual protocol buffers that hold sensitive key material.
func NewHandle ¶
func NewHandle(kt *tinkpb.KeyTemplate) (*Handle, error)
NewHandle creates a keyset handle that contains a single fresh key generated according to the given KeyTemplate.
func NewHandleWithNoSecrets ¶
NewHandleWithNoSecrets creates a new instance of KeysetHandle using the given keyset which does not contain any secret key material.
func ReadWithAssociatedData ¶
func ReadWithAssociatedData(reader Reader, masterKey tink.AEAD, associatedData []byte) (*Handle, error)
ReadWithAssociatedData tries to create a Handle from an encrypted keyset obtained via reader using the provided associated data.
func ReadWithNoSecrets ¶
ReadWithNoSecrets tries to create a keyset.Handle from a keyset obtained via reader.
func (*Handle) KeysetInfo ¶
func (h *Handle) KeysetInfo() *tinkpb.KeysetInfo
KeysetInfo returns KeysetInfo representation of the managed keyset. The result does not contain any sensitive key material.
func (*Handle) Primitives ¶
func (h *Handle) Primitives() (*primitiveset.PrimitiveSet, error)
Primitives creates a set of primitives corresponding to the keys with status=ENABLED in the keyset of the given keyset handle, 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.
func (*Handle) PrimitivesWithKeyManager ¶
func (h *Handle) PrimitivesWithKeyManager(km registry.KeyManager) (*primitiveset.PrimitiveSet, error)
PrimitivesWithKeyManager creates a set of primitives corresponding to the keys with status=ENABLED in the keyset of the given keysetHandle, using the given key manager (instead of registered key managers) for keys supported by it. Keys not supported by the key manager 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.
func (*Handle) Public ¶
Public returns a Handle of the public keys if the managed keyset contains private keys.
func (*Handle) String ¶
String returns a string representation of the managed keyset. The result does not contain any sensitive key material.
func (*Handle) WriteWithAssociatedData ¶
func (h *Handle) WriteWithAssociatedData(writer Writer, masterKey tink.AEAD, associatedData []byte) error
WriteWithAssociatedData encrypts and writes the enclosing keyset using the provided associated data.
func (*Handle) WriteWithNoSecrets ¶
WriteWithNoSecrets exports the keyset in h to the given Writer w returning an error if the keyset contains secret key material.
type JSONReader ¶
type JSONReader struct {
// contains filtered or unexported fields
}
JSONReader deserializes a keyset from json format.
func NewJSONReader ¶
func NewJSONReader(r io.Reader) *JSONReader
NewJSONReader returns new JSONReader that will read from r.
func (*JSONReader) Read ¶
func (bkr *JSONReader) Read() (*tinkpb.Keyset, error)
Read parses a (cleartext) keyset from the underlying io.Reader.
func (*JSONReader) ReadEncrypted ¶
func (bkr *JSONReader) ReadEncrypted() (*tinkpb.EncryptedKeyset, error)
ReadEncrypted parses an EncryptedKeyset from the underlying io.Reader.
type JSONWriter ¶
type JSONWriter struct {
// contains filtered or unexported fields
}
JSONWriter serializes a keyset into json format.
func NewJSONWriter ¶
func NewJSONWriter(w io.Writer) *JSONWriter
NewJSONWriter returns a new JSONWriter that will write to w.
func (*JSONWriter) Write ¶
func (bkw *JSONWriter) Write(keyset *tinkpb.Keyset) error
Write writes the keyset to the underlying io.Writer.
func (*JSONWriter) WriteEncrypted ¶
func (bkw *JSONWriter) WriteEncrypted(keyset *tinkpb.EncryptedKeyset) error
WriteEncrypted writes the encrypted keyset to the underlying io.Writer.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager manages a Keyset-proto, with convenience methods that rotate, disable, enable or destroy keys. Note: It is not thread-safe.
func NewManager ¶
func NewManager() *Manager
NewManager creates a new instance with an empty Keyset.
func NewManagerFromHandle ¶
NewManagerFromHandle creates a new instance from the given Handle.
func (*Manager) Add ¶
func (km *Manager) Add(kt *tinkpb.KeyTemplate) (uint32, error)
Add generates and adds a fresh key using the given key template. the key is enabled on creation, but not set to primary. It returns the ID of the new key
func (*Manager) Delete ¶
Delete will delete the key with given keyID, removing the key from the keyset entirely. Returns an error if the key is not found or it is the primary key.
func (*Manager) Disable ¶
Disable will disable the key with given keyID. Returns an error if the key is not found or it is the primary key.
func (*Manager) Enable ¶
Enable will enable the key with given keyID. Returns an error if the key is not found or is not enabled or disabled already.
func (*Manager) SetPrimary ¶
SetPrimary sets the key with given keyID as primary. Returns an error if the key is not found or not enabled.
type MemReaderWriter
deprecated
type MemReaderWriter struct {
Keyset *tinkpb.Keyset
EncryptedKeyset *tinkpb.EncryptedKeyset
}
MemReaderWriter implements keyset.Reader and keyset.Writer for *tinkpb.Keyset and *tinkpb.EncryptedKeyset.
Deprecated: Use keyset.NewBinaryReader or keyset.NewBinaryWriter instead. See tests in mem_io_test.go for examples on how to use them instead.
func (*MemReaderWriter) Read ¶
func (m *MemReaderWriter) Read() (*tinkpb.Keyset, error)
Read returns *tinkpb.Keyset from memory.
func (*MemReaderWriter) ReadEncrypted ¶
func (m *MemReaderWriter) ReadEncrypted() (*tinkpb.EncryptedKeyset, error)
ReadEncrypted returns *tinkpb.EncryptedKeyset from memory.
func (*MemReaderWriter) Write ¶
func (m *MemReaderWriter) Write(keyset *tinkpb.Keyset) error
Write keyset to memory.
func (*MemReaderWriter) WriteEncrypted ¶
func (m *MemReaderWriter) WriteEncrypted(keyset *tinkpb.EncryptedKeyset) error
WriteEncrypted keyset to memory.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option is used to pass options for a keyset handle.
func WithAnnotations ¶
WithAnnotations adds monitoring annotations to a keyset handle.
type Reader ¶
type Reader interface {
// Read returns a (cleartext) Keyset object from the underlying source.
Read() (*tinkpb.Keyset, error)
// ReadEncrypted returns an EncryptedKeyset object from the underlying source.
ReadEncrypted() (*tinkpb.EncryptedKeyset, error)
}
Reader knows how to read a Keyset or an EncryptedKeyset from some source. In order to turn a Reader into a KeysetHandle for use, callers must use insecure.KeysetHandle or by keyset.Read (with encryption).
Source Files