aead

package
v0.0.0-...-d6de17e Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2023 License: Apache-2.0 Imports: 29 Imported by: 1

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

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.

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 [CreateKMSEnvelopAEADKeyTemplate], 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 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 Envelope AEAD.

func NewKMSEnvelopeAEAD2 

func NewKMSEnvelopeAEAD2(kt *tinkpb.KeyTemplate, remote tink.AEAD) *KMSEnvelopeAEAD

NewKMSEnvelopeAEAD2 creates an new instance of KMSEnvelopeAEAD.

func (*KMSEnvelopeAEAD) Decrypt 

func (a *KMSEnvelopeAEAD) Decrypt(ct, aad []byte) ([]byte, error)

Decrypt implements the tink.AEAD interface for decryption.

func (*KMSEnvelopeAEAD) Encrypt 

func (a *KMSEnvelopeAEAD) Encrypt(pt, aad []byte) ([]byte, error)

Encrypt implements the tink.AEAD interface for encryption.

Source Files

View all Source files

Directories

Path Synopsis
internal
testing/kmsaead
Package kmsaead provides a keymanager for KmsAeadKey that may only be used in tests.
 Package kmsaead provides a keymanager for KmsAeadKey that may only be used in tests.
Package subtle provides subtle implementations of the AEAD primitive.
 Package subtle provides subtle implementations of the AEAD primitive.

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.