aead

package
v2.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 14, 2025 License: Apache-2.0 Imports: 31 Imported by: 18

Documentation

Overview

Package aead provides implementations of the AEAD primitive.

AEAD encryption assures the confidentiality and authenticity of the data. This primitive is CPA secure.

Example 
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/tink-crypto/tink-go/v2/aead"
	"github.com/tink-crypto/tink-go/v2/insecurecleartextkeyset"
	"github.com/tink-crypto/tink-go/v2/keyset"
)

func main() {
	// A keyset created with "tinkey create-keyset --key-template=AES256_GCM". Note
	// that this keyset has the secret key information in cleartext.
	jsonKeyset := `{
			"key": [{
					"keyData": {
							"keyMaterialType":
									"SYMMETRIC",
							"typeUrl":
									"type.googleapis.com/google.crypto.tink.AesGcmKey",
							"value":
									"GiBWyUfGgYk3RTRhj/LIUzSudIWlyjCftCOypTr0jCNSLg=="
					},
					"keyId": 294406504,
					"outputPrefixType": "TINK",
					"status": "ENABLED"
			}],
			"primaryKeyId": 294406504
	}`

	// Create a keyset handle from the cleartext keyset in the previous
	// step. The keyset handle provides abstract access to the underlying keyset to
	// limit the exposure of accessing the raw key material. WARNING: In practice,
	// it is unlikely you will want to use a insecurecleartextkeyset, as it implies
	// that your key material is passed in cleartext, which is a security risk.
	// Consider encrypting it with a remote key in Cloud KMS, AWS KMS or HashiCorp Vault.
	// See https://github.com/google/tink/blob/master/docs/GOLANG-HOWTO.md#storing-and-loading-existing-keysets.
	keysetHandle, err := insecurecleartextkeyset.Read(
		keyset.NewJSONReader(bytes.NewBufferString(jsonKeyset)))
	if err != nil {
		log.Fatal(err)
	}

	// Retrieve the AEAD primitive we want to use from the keyset handle.
	primitive, err := aead.New(keysetHandle)
	if err != nil {
		log.Fatal(err)
	}

	// Use the primitive to encrypt a message. In this case the primary key of the
	// keyset will be used (which is also the only key in this example).
	plaintext := []byte("message")
	associatedData := []byte("associated data")
	ciphertext, err := primitive.Encrypt(plaintext, associatedData)
	if err != nil {
		log.Fatal(err)
	}

	// Use the primitive to decrypt the message. Decrypt finds the correct key in
	// the keyset and decrypts the ciphertext. If no key is found or decryption
	// fails, it returns an error.
	decrypted, err := primitive.Decrypt(ciphertext, associatedData)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(decrypted))
}

Output:

message
Example (KmsEnvelopeAEAD) 
package main

// [START kms-envelope-aead-example]

import (
	"fmt"
	"log"

	"github.com/tink-crypto/tink-go/v2/aead"
	"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)
	}

	// Get the KMS envelope AEAD primitive.
	primitive := aead.NewKMSEnvelopeAEAD2(aead.AES256GCMKeyTemplate(), kekAEAD)

	// Use the primitive.
	plaintext := []byte("message")
	associatedData := []byte("example KMS envelope AEAD 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 kms-envelope-aead-example]

Output:

message

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AES128CTRHMACSHA256KeyTemplate 

func AES128CTRHMACSHA256KeyTemplate() *tinkpb.KeyTemplate

AES128CTRHMACSHA256KeyTemplate is a KeyTemplate that generates an AES-CTR-HMAC-AEAD key with the following parameters:

  • AES key size: 16 bytes
  • AES CTR IV size: 16 bytes
  • HMAC key size: 32 bytes
  • HMAC tag size: 16 bytes
  • HMAC hash function: SHA256

func AES128GCMKeyTemplate 

func AES128GCMKeyTemplate() *tinkpb.KeyTemplate

AES128GCMKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:

  • Key size: 16 bytes
  • Output prefix type: TINK

func AES128GCMSIVKeyTemplate 

func AES128GCMSIVKeyTemplate() *tinkpb.KeyTemplate

AES128GCMSIVKeyTemplate is a KeyTemplate that generates an AES-GCM-SIV key with the following parameters:

  • Key size: 16 bytes
  • Output prefix type: TINK

func AES256CTRHMACSHA256KeyTemplate 

func AES256CTRHMACSHA256KeyTemplate() *tinkpb.KeyTemplate

AES256CTRHMACSHA256KeyTemplate is a KeyTemplate that generates an AES-CTR-HMAC-AEAD key with the following parameters:

  • AES key size: 32 bytes
  • AES CTR IV size: 16 bytes
  • HMAC key size: 32 bytes
  • HMAC tag size: 32 bytes
  • HMAC hash function: SHA256

func AES256GCMKeyTemplate 

func AES256GCMKeyTemplate() *tinkpb.KeyTemplate

AES256GCMKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:

  • Key size: 32 bytes
  • Output prefix type: TINK

func AES256GCMNoPrefixKeyTemplate 

func AES256GCMNoPrefixKeyTemplate() *tinkpb.KeyTemplate

AES256GCMNoPrefixKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:

  • Key size: 32 bytes
  • Output prefix type: RAW

func AES256GCMSIVKeyTemplate 

func AES256GCMSIVKeyTemplate() *tinkpb.KeyTemplate

AES256GCMSIVKeyTemplate is a KeyTemplate that generates an AES-GCM-SIV key with the following parameters:

  • Key size: 32 bytes
  • Output prefix type: TINK

func AES256GCMSIVNoPrefixKeyTemplate 

func AES256GCMSIVNoPrefixKeyTemplate() *tinkpb.KeyTemplate

AES256GCMSIVNoPrefixKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:

  • Key size: 32 bytes
  • Output prefix type: RAW

func ChaCha20Poly1305KeyTemplate 

func ChaCha20Poly1305KeyTemplate() *tinkpb.KeyTemplate

ChaCha20Poly1305KeyTemplate is a KeyTemplate that generates a CHACHA20_POLY1305 key.

func CreateKMSEnvelopeAEADKeyTemplate 

func CreateKMSEnvelopeAEADKeyTemplate(uri string, dekTemplate *tinkpb.KeyTemplate) (*tinkpb.KeyTemplate, error)

CreateKMSEnvelopeAEADKeyTemplate returns a key template that generates a KMSEnvelopeAEAD key for a given key encryption key (KEK) in a remote key management service (KMS).

When performing encrypt operations, a data encryption key (DEK) is generated for each ciphertext. The DEK is wrapped by the remote KMS using the KEK and stored alongside the ciphertext.

dekTemplate must be a KeyTemplate for any of these Tink AEAD key types (any other key template will be rejected):

  • AesCtrHmacAeadKey
  • AesGcmKey
  • ChaCha20Poly1305Key
  • XChaCha20Poly1305
  • AesGcmSivKey

DEKs generated by this key template use the RAW output prefix to make them compatible with remote KMS encrypt/decrypt operations.

Unlike other templates, when you generate new keys with this template, Tink does not generate new key material, but only creates a reference to the remote KEK.

If either uri or dekTemplate contain invalid input, an error is returned.

It is often not necessary to use this function. Instead, you can call kmsClient.GetAEAD to get a remote AEAD, and create an envelope AEAD using NewKMSEnvelopeAEAD2.

There is no need to call registry.RegisterKMSClient anymore.

func KMSEnvelopeAEADKeyTemplate deprecated 

func KMSEnvelopeAEADKeyTemplate(uri string, dekTemplate *tinkpb.KeyTemplate) *tinkpb.KeyTemplate

KMSEnvelopeAEADKeyTemplate returns a KeyTemplate that generates a KMSEnvelopeAEAD key for a given key encryption key (KEK) in a remote key management service (KMS).

If either uri or dekTemplate contain invalid input, program execution will be interrupted.

Deprecated: Use CreateKMSEnvelopeAEADKeyTemplate, which returns an error value instead of interrupting the program.

func New 

func New(handle *keyset.Handle) (tink.AEAD, error)

New returns an AEAD primitive from the given keyset handle.

func NewWithConfig added in v2.3.0 

func NewWithConfig(handle *keyset.Handle, config keyset.Config) (tink.AEAD, error)

NewWithConfig creates an AEAD primitive from the given keyset.Handle using the provided [Config].

func XAES256GCM160BitNonceKeyTemplate added in v2.3.0 

func XAES256GCM160BitNonceKeyTemplate() *tinkpb.KeyTemplate

XAES256GCM160BitNonceKeyTemplate is a KeyTemplate that generates an X-AES-GCM key with the following parameters:

  • Salt size: 8 bytes
  • Output prefix type: TINK

func XAES256GCM160BitNonceNoPrefixKeyTemplate added in v2.3.0 

func XAES256GCM160BitNonceNoPrefixKeyTemplate() *tinkpb.KeyTemplate

XAES256GCM160BitNonceNoPrefixKeyTemplate is a KeyTemplate that generates an X-AES-GCM key with the following parameters:

  • Salt size: 8 bytes
  • Output prefix type: RAW

func XAES256GCM192BitNonceKeyTemplate added in v2.3.0 

func XAES256GCM192BitNonceKeyTemplate() *tinkpb.KeyTemplate

XAES256GCM192BitNonceKeyTemplate is a KeyTemplate that generates an X-AES-GCM key with the following parameters:

  • Salt size: 12 bytes
  • Output prefix type: TINK

func XAES256GCM192BitNonceNoPrefixKeyTemplate added in v2.3.0 

func XAES256GCM192BitNonceNoPrefixKeyTemplate() *tinkpb.KeyTemplate

XAES256GCM192BitNonceNoPrefixKeyTemplate is a KeyTemplate that generates an X-AES-GCM key with the following parameters:

  • Salt size: 12 bytes
  • Output prefix type: RAW

func XChaCha20Poly1305KeyTemplate 

func XChaCha20Poly1305KeyTemplate() *tinkpb.KeyTemplate

XChaCha20Poly1305KeyTemplate is a KeyTemplate that generates a XCHACHA20_POLY1305 key.

Types

type KMSEnvelopeAEAD 

type KMSEnvelopeAEAD struct {
	// contains filtered or unexported fields
}

KMSEnvelopeAEAD represents an instance of KMS Envelope AEAD that implements the tink.AEAD interface.

func NewKMSEnvelopeAEAD2 

func NewKMSEnvelopeAEAD2(dekTemplate *tinkpb.KeyTemplate, keyEncryptionAEAD tink.AEAD) *KMSEnvelopeAEAD

NewKMSEnvelopeAEAD2 creates an new instance of KMSEnvelopeAEAD.

dekTemplate specifies the key template of the data encryption key (DEK). It must be a KeyTemplate for any of these Tink AEAD key types (any other key template will be rejected):

  • AesCtrHmacAeadKey
  • AesGcmKey
  • ChaCha20Poly1305Key
  • XChaCha20Poly1305
  • AesGcmSivKey

keyEncryptionAEAD is used to encrypt the DEK, and is usually a remote AEAD provided by a KMS. It is preferable to use NewKMSEnvelopeAEADWithContext instead.

func (*KMSEnvelopeAEAD) Decrypt 

func (a *KMSEnvelopeAEAD) Decrypt(ciphertext, associatedData []byte) ([]byte, error)

Decrypt implements the tink.AEAD interface for decryption.

func (*KMSEnvelopeAEAD) Encrypt 

func (a *KMSEnvelopeAEAD) Encrypt(plaintext, associatedData []byte) ([]byte, error)

Encrypt implements the tink.AEAD interface for encryption.

type KMSEnvelopeAEADWithContext added in v2.3.0 

type KMSEnvelopeAEADWithContext struct {
	// contains filtered or unexported fields
}

KMSEnvelopeAEADWithContext represents an instance of KMS Envelope AEAD that implements the tink.AEADWithContext interface.

func NewKMSEnvelopeAEADWithContext added in v2.3.0 

func NewKMSEnvelopeAEADWithContext(dekTemplate *tinkpb.KeyTemplate, keyEncryptionAEAD tink.AEADWithContext) (*KMSEnvelopeAEADWithContext, error)

NewKMSEnvelopeAEADWithContext creates an new instance of KMSEnvelopeAEADWithContext.

dekTemplate must be a KeyTemplate for any of these Tink AEAD key types (any other key template will be rejected):

  • AesCtrHmacAeadKey
  • AesGcmKey
  • ChaCha20Poly1305Key
  • XChaCha20Poly1305
  • AesGcmSivKey

keyEncryptionAEAD is used to encrypt the DEK, and is usually a remote AEAD provided by a KMS.

func (*KMSEnvelopeAEADWithContext) DecryptWithContext added in v2.3.0 

func (a *KMSEnvelopeAEADWithContext) DecryptWithContext(ctx context.Context, ciphertext, associatedData []byte) ([]byte, error)

DecryptWithContext implements the tink.AEADWithContext interface for decryption.

func (*KMSEnvelopeAEADWithContext) EncryptWithContext added in v2.3.0 

func (a *KMSEnvelopeAEADWithContext) EncryptWithContext(ctx context.Context, plaintext, associatedData []byte) ([]byte, error)

EncryptWithContext implements the tink.AEADWithContext interface for encryption.

Source Files

View all Source files

Directories

Path Synopsis
Package aesctrhmac provides a key manager for the AES-CTR-HMAC AEAD.
 Package aesctrhmac provides a key manager for the AES-CTR-HMAC AEAD.
Package aesgcm implements AES-GCM parameters and key, as well as key manager.
 Package aesgcm implements AES-GCM parameters and key, as well as key manager.
Package aesgcmsiv provides an implementation of AES-GCM-SIV.
 Package aesgcmsiv provides an implementation of AES-GCM-SIV.
Package chacha20poly1305 implements ChaCha20-Poly1305 parameters and key.
 Package chacha20poly1305 implements ChaCha20-Poly1305 parameters and key.
internal
testutil
Package testutil provides testing utilities for AEAD primitives.
 Package testutil provides testing utilities for AEAD primitives.
Package subtle provides subtle implementations of the AEAD primitive.
 Package subtle provides subtle implementations of the AEAD primitive.
Package xaesgcm provides a key and parameters definition for X-AES-GCM, which is specified in https://c2sp.org/XAES-256-GCM.
 Package xaesgcm provides a key and parameters definition for X-AES-GCM, which is specified in https://c2sp.org/XAES-256-GCM.
Package xchacha20poly1305 provides a Tink key manager for XChaCha20Poly1305 keys.
 Package xchacha20poly1305 provides a Tink key manager for XChaCha20Poly1305 keys.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.