blob: 556c220d82f5f5f59aede47feae20ebc2251b8cb [file] [log] [blame]
// Copyright 2020 Google LLC
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
#include <map>
#include "absl/strings/string_view.h"
#include "tink/util/statusor.h"
namespace crypto {
namespace tink {
// 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
// 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.
class Prf {
virtual ~Prf() {}
// 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.
virtual util::StatusOr<std::string> Compute(absl::string_view input,
size_t output_length) const = 0;
// 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 PRFSet.
// Every PRF in the set is given an ID, which is the same ID as the key id in
// the Keyset.
class PrfSet {
virtual ~PrfSet() {}
// The primary ID of the keyset.
virtual uint32_t GetPrimaryId() const = 0;
// A map of the PRFs represented by the keys in this keyset.
// The map is guaranteed to contain getPrimaryId() as a key.
virtual const std::map<uint32_t, Prf*>& GetPrfs() const = 0;
// Convenience method to compute the primary PRF on a given input.
// See PRF.compute for details of the parameters.
util::StatusOr<std::string> ComputePrimary(absl::string_view input,
size_t output_length) const;
} // namespace tink
} // namespace crypto
#endif // TINK_PRF_PRF_SET_H_