diff --git a/prf/prf_set.go b/prf/prf_set.go index d1d4b0b..5c7aa93 100644 --- a/prf/prf_set.go +++ b/prf/prf_set.go @@ -23,36 +23,42 @@ import ( "github.com/tink-crypto/tink-go/v2/monitoring" ) -// The PRF interface is an abstraction for an element of a pseudo random -// function family, selected by a key. It has the following property: -// - It is deterministic. PRF.compute(input, length) will always return the -// same output if the same key is used. PRF.compute(input, length1) will be -// a prefix of PRF.compute(input, length2) if length1 < length2 and the same +// 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. +// - 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 +// +// 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 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 ok status if the algorithm fails or if the output of - // algorithm is less than outputLength. + // + // 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) } @@ -74,10 +80,11 @@ func (w *monitoredPRF) ComputePRF(input []byte, outputLength uint32) ([]byte, er return p, nil } -// 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. +// 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. type Set struct { // PrimaryID is the key ID marked as primary in the corresponding Keyset. PrimaryID uint32 @@ -85,7 +92,7 @@ type Set struct { PRFs map[uint32]PRF } -// ComputePrimaryPRF is equivalent to set.PRFs[set.PrimaryID].ComputePRF(input, outputLength). +// ComputePrimaryPRF is equivalent to set.PRFs[set.PrimaryID].ComputePRF(). func (s Set) ComputePrimaryPRF(input []byte, outputLength uint32) ([]byte, error) { prf, ok := s.PRFs[s.PrimaryID] if !ok {