From 28a5a56a51a3ace3628968dacbede372756e89d0 Mon Sep 17 00:00:00 2001
From: Charles Lee <ckl@google.com>
Date: Wed, 10 Apr 2024 10:25:05 -0700
Subject: [PATCH] Update godoc for the prf package.

PiperOrigin-RevId: 623535827
Change-Id: I40b14ee3230995b8ab1485343d4cfb795e1b5b75
---
 prf/prf_set.go | 47 +++++++++++++++++++++++++++--------------------
 1 file changed, 27 insertions(+), 20 deletions(-)

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 {