streamingaead

Documentation

Overview

Package streamingaead provides implementations of the streaming AEAD primitive.

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

Example

package main

import (
	"fmt"
	"io"
	"io/ioutil"
	"log"
	"os"
	"path/filepath"

	"github.com/google/tink/go/keyset"
	"github.com/google/tink/go/streamingaead"
)

func main() {
	dir, err := ioutil.TempDir("", "streamingaead")
	if err != nil {
		log.Fatal(err)
	}
	defer os.RemoveAll(dir)

	var (
		srcFilename = filepath.Join(dir, "plaintext.src")
		ctFilename  = filepath.Join(dir, "ciphertext.bin")
		dstFilename = filepath.Join(dir, "plaintext.dst")
	)

	if err := ioutil.WriteFile(srcFilename, []byte("this data needs to be encrypted"), 0666); err != nil {
		log.Fatal(err)
	}

	kh, err := keyset.NewHandle(streamingaead.AES256GCMHKDF4KBKeyTemplate())
	if err != nil {
		log.Fatal(err)
	}

	// TODO: save the keyset to a safe location. DO NOT hardcode it in source code.
	// 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.

	// Encrypt file.

	a, err := streamingaead.New(kh)
	if err != nil {
		log.Fatal(err)
	}

	srcFile, err := os.Open(srcFilename)
	if err != nil {
		log.Fatal(err)
	}

	ctFile, err := os.Create(ctFilename)
	if err != nil {
		log.Fatal(err)
	}

	aad := []byte("this data needs to be authenticated, but not encrypted")
	w, err := a.NewEncryptingWriter(ctFile, aad)
	if err != nil {
		log.Fatal(err)
	}

	if _, err := io.Copy(w, srcFile); err != nil {
		log.Fatal(err)
	}

	if err := w.Close(); err != nil {
		log.Fatal(err)
	}

	if err := ctFile.Close(); err != nil {
		log.Fatal(err)
	}
	if err := srcFile.Close(); err != nil {
		log.Fatal(err)
	}

	// Decrypt file.

	ctFile, err = os.Open(ctFilename)
	if err != nil {
		log.Fatal(err)
	}

	dstFile, err := os.Create(dstFilename)
	if err != nil {
		log.Fatal(err)
	}

	r, err := a.NewDecryptingReader(ctFile, aad)
	if err != nil {
		log.Fatal(err)
	}

	if _, err := io.Copy(dstFile, r); err != nil {
		log.Fatal(err)
	}

	if err := dstFile.Close(); err != nil {
		log.Fatal(err)
	}
	if err := ctFile.Close(); err != nil {
		log.Fatal(err)
	}

	b, err := ioutil.ReadFile(dstFilename)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(b))
}

Output:

this data needs to be encrypted

Index

• func AES128CTRHMACSHA256Segment1MBKeyTemplate() *tinkpb.KeyTemplate
• func AES128CTRHMACSHA256Segment4KBKeyTemplate() *tinkpb.KeyTemplate
• func AES128GCMHKDF1MBKeyTemplate() *tinkpb.KeyTemplate
• func AES128GCMHKDF4KBKeyTemplate() *tinkpb.KeyTemplate
• func AES256CTRHMACSHA256Segment1MBKeyTemplate() *tinkpb.KeyTemplate
• func AES256CTRHMACSHA256Segment4KBKeyTemplate() *tinkpb.KeyTemplate
• func AES256GCMHKDF1MBKeyTemplate() *tinkpb.KeyTemplate
• func AES256GCMHKDF4KBKeyTemplate() *tinkpb.KeyTemplate
• func New(h *keyset.Handle) (tink.StreamingAEAD, error)
• func NewWithKeyManager(h *keyset.Handle, km registry.KeyManager) (tink.StreamingAEAD, error)

Examples

• Package

Functions

func AES128CTRHMACSHA256Segment1MBKeyTemplate

func AES128CTRHMACSHA256Segment1MBKeyTemplate() *tinkpb.KeyTemplate

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

• Main key size: 16 bytes
• HKDF algorthim: HMAC-SHA256
• AES-CTR derived key size: 16 bytes
• Tag algorithm: HMAC-SHA256
• Tag size: 32 bytes
• Ciphertext segment size: 1048576 bytes (1 MB)

func AES128CTRHMACSHA256Segment4KBKeyTemplate

func AES128CTRHMACSHA256Segment4KBKeyTemplate() *tinkpb.KeyTemplate

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

• Main key size: 16 bytes
• HKDF algorthim: HMAC-SHA256
• AES-CTR derived key size: 16 bytes
• Tag algorithm: HMAC-SHA256
• Tag size: 32 bytes
• Ciphertext segment size: 4096 bytes (4 KB)

func AES128GCMHKDF1MBKeyTemplate

func AES128GCMHKDF1MBKeyTemplate() *tinkpb.KeyTemplate

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

• Main key size: 16 bytes
• HKDF algo: HMAC-SHA256
• Size of AES-GCM derived keys: 16 bytes
• Ciphertext segment size: 1048576 bytes (1 MB)

func AES128GCMHKDF4KBKeyTemplate

func AES128GCMHKDF4KBKeyTemplate() *tinkpb.KeyTemplate

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

• Main key size: 16 bytes
• HKDF algo: HMAC-SHA256
• Size of AES-GCM derived keys: 16 bytes
• Ciphertext segment size: 4096 bytes

func AES256CTRHMACSHA256Segment1MBKeyTemplate

func AES256CTRHMACSHA256Segment1MBKeyTemplate() *tinkpb.KeyTemplate

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

• Main key size: 32 bytes
• HKDF algorthim: HMAC-SHA256
• AES-CTR derived key size: 32 bytes
• Tag algorithm: HMAC-SHA256
• Tag size: 32 bytes
• Ciphertext segment size: 1048576 bytes (1 MB)

func AES256CTRHMACSHA256Segment4KBKeyTemplate

func AES256CTRHMACSHA256Segment4KBKeyTemplate() *tinkpb.KeyTemplate

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

• Main key size: 32 bytes
• HKDF algorthim: HMAC-SHA256
• AES-CTR derived key size: 32 bytes
• Tag algorithm: HMAC-SHA256
• Tag size: 32 bytes
• Ciphertext segment size: 4096 bytes (4 KB)

func AES256GCMHKDF1MBKeyTemplate

func AES256GCMHKDF1MBKeyTemplate() *tinkpb.KeyTemplate

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

• Main key size: 32 bytes
• HKDF algo: HMAC-SHA256
• Size of AES-GCM derived keys: 32 bytes
• Ciphertext segment size: 1048576 bytes (1 MB)

func AES256GCMHKDF4KBKeyTemplate

func AES256GCMHKDF4KBKeyTemplate() *tinkpb.KeyTemplate

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

• Main key size: 32 bytes
• HKDF algo: HMAC-SHA256
• Size of AES-GCM derived keys: 32 bytes
• Ciphertext segment size: 4096 bytes

func New

func New(h *keyset.Handle) (tink.StreamingAEAD, error)

New returns a StreamingAEAD primitive from the given keyset handle.

func NewWithKeyManager

func NewWithKeyManager(h *keyset.Handle, km registry.KeyManager) (tink.StreamingAEAD, error)

NewWithKeyManager returns a StreamingAEAD primitive from the given keyset handle and custom key manager.

Deprecated: Use New.