prf

Documentation

Overview

Package prf contains utilities to calculate pseudo random function families.

Example

package main

import (
	"encoding/base64"
	"fmt"
	"log"

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

func main() {
	kh, err := keyset.NewHandle(prf.HMACSHA256PRFKeyTemplate())
	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.

	ps, err := prf.NewPRFSet(kh)
	if err != nil {
		log.Fatal(err)
	}

	msg := []byte("This is an ID needs to be redacted")
	output, err := ps.ComputePrimaryPRF(msg, 16)

	fmt.Printf("Message: %s\n", msg)
	fmt.Printf("Redacted: %s\n", base64.StdEncoding.EncodeToString(output))
}

Index

• func AESCMACPRFKeyTemplate() *tinkpb.KeyTemplate
• func HKDFSHA256PRFKeyTemplate() *tinkpb.KeyTemplate
• func HMACSHA256PRFKeyTemplate() *tinkpb.KeyTemplate
• func HMACSHA512PRFKeyTemplate() *tinkpb.KeyTemplate
• type PRF
• type Set
  • func NewPRFSet(handle *keyset.Handle) (*Set, error)
  • func (s Set) ComputePrimaryPRF(input []byte, outputLength uint32) ([]byte, error)

Examples

• Package

Functions

func AESCMACPRFKeyTemplate

func AESCMACPRFKeyTemplate() *tinkpb.KeyTemplate

AESCMACPRFKeyTemplate is a KeyTemplate that generates a AES-CMAC key with the following parameters:

• Key size: 32 bytes

func HKDFSHA256PRFKeyTemplate

func HKDFSHA256PRFKeyTemplate() *tinkpb.KeyTemplate

HKDFSHA256PRFKeyTemplate is a KeyTemplate that generates an HKDF key with the following parameters:

• Key size: 32 bytes
• Salt: empty
• Hash function: SHA256

func HMACSHA256PRFKeyTemplate

func HMACSHA256PRFKeyTemplate() *tinkpb.KeyTemplate

HMACSHA256PRFKeyTemplate is a KeyTemplate that generates an HMAC key with the following parameters:

• Key size: 32 bytes
• Hash function: SHA256

func HMACSHA512PRFKeyTemplate

func HMACSHA512PRFKeyTemplate() *tinkpb.KeyTemplate

HMACSHA512PRFKeyTemplate is a KeyTemplate that generates an HMAC key with the following parameters:

• Key size: 64 bytes
• Hash function: SHA512

Types

type PRF

type PRF interface {
	// Computes the PRF selected by the underlying key on input and
	// returns the first outputLength bytes.
	//
	// When choosing this parameter keep the birthday paradox in mind.
	// If you have 2^n different inputs that your system has to handle
	// set the output length (in bytes) to at least
	// ceil(n/4 + 4)
	//
	// This corresponds to 2*n + 32 bits, meaning a collision will occur
	// with a probability less than 1:2^32. When in doubt, request a
	// security review.
	//
	// Returns a non-nil error if the algorithm fails or if the output of
	// the underlying algorithm is less than outputLength.
	ComputePRF(input []byte, outputLength uint32) ([]byte, error)
}

The PRF interface is an abstraction for an element of a pseudo-random function family, selected by a key.

It has the following properties:

• It is deterministic. ComputePRF(input, length) will always return the same output if the same key is used. ComputePRF(input, length1) will be a prefix of ComputePRF(input, length2) if length1 < length2 and the same key is used.
• It is indistinguishable from a random function. Given the evaluation of n different inputs, an attacker cannot distinguish between the PRF and random bytes on an input different from the n that are known.

Use cases for PRF are deterministic redaction of PII, keyed hash functions, creating sub IDs that do not allow joining with the original dataset without knowing the key.

While PRFs can be used in order to prove authenticity of a message, using the MAC interface is recommended for that use case, as it has support for verification, avoiding the security problems that often happen during verification, and having automatic support for key rotation. It also allows for non-deterministic MAC algorithms.

type Set

type Set struct {
	// PrimaryID is the key ID marked as primary in the corresponding Keyset.
	PrimaryID uint32
	// PRFs maps key IDs to their corresponding PRF.
	PRFs map[uint32]PRF
}

Set is a set of PRFs.

A Tink Keyset can be converted into a set of PRFs using this primitive. Every key in the keyset corresponds to a PRF in the prf.Set. Every PRF in the set is given an ID, which is the same ID as the key id in the Keyset.

func NewPRFSet

func NewPRFSet(handle *keyset.Handle) (*Set, error)

NewPRFSet creates a prf.Set primitive from the given keyset handle.

func (Set) ComputePrimaryPRF

func (s Set) ComputePrimaryPRF(input []byte, outputLength uint32) ([]byte, error)

ComputePrimaryPRF is equivalent to set.PRFs[set.PrimaryID].ComputePRF().