1 // Copyright 2020 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 /////////////////////////////////////////////////////////////////////////////// 16 17 #ifndef TINK_PRF_PRF_SET_H_ 18 #define TINK_PRF_PRF_SET_H_ 19 20 #include <map> 21 #include <string> 22 23 #include "absl/strings/string_view.h" 24 #include "tink/util/statusor.h" 25 26 namespace crypto { 27 namespace tink { 28 29 // The PRF interface is an abstraction for an element of a pseudo random 30 // function family, selected by a key. It has the following property: 31 // * It is deterministic. PRF.compute(input, length) will always return the 32 // same output if the same key is used. PRF.compute(input, length1) will be 33 // a prefix of PRF.compute(input, length2) if length1 < length2 and the same 34 // key is used. 35 // * It is indistinguishable from a random function: 36 // Given the evaluation of n different inputs, an attacker cannot 37 // distinguish between the PRF and random bytes on an input different from 38 // the n that are known. 39 // Use cases for PRF are deterministic redaction of PII, keyed hash functions, 40 // creating sub IDs that do not allow joining with the original dataset without 41 // knowing the key. 42 // While PRFs can be used in order to prove authenticity of a message, using the 43 // MAC interface is recommended for that use case, as it has support for 44 // verification, avoiding the security problems that often happen during 45 // verification, and having automatic support for key rotation. It also allows 46 // for non-deterministic MAC algorithms. 47 class Prf { 48 public: 49 virtual ~Prf() = default; 50 // Computes the PRF selected by the underlying key on input and 51 // returns the first outputLength bytes. 52 // When choosing this parameter keep the birthday paradox in mind. 53 // If you have 2^n different inputs that your system has to handle 54 // set the output length (in bytes) to at least 55 // ceil(n/4 + 4) 56 // This corresponds to 2*n + 32 bits, meaning a collision will occur with 57 // a probability less than 1:2^32. When in doubt, request a security review. 58 // Returns a non ok status if the algorithm fails or if the output of 59 // algorithm is less than outputLength. 60 virtual util::StatusOr<std::string> Compute(absl::string_view input, 61 size_t output_length) const = 0; 62 }; 63 64 // A Tink Keyset can be converted into a set of PRFs using this primitive. Every 65 // key in the keyset corresponds to a PRF in the PRFSet. 66 // Every PRF in the set is given an ID, which is the same ID as the key id in 67 // the Keyset. 68 class PrfSet { 69 public: 70 virtual ~PrfSet() = default; 71 // The primary ID of the keyset. 72 virtual uint32_t GetPrimaryId() const = 0; 73 // A map of the PRFs represented by the keys in this keyset. 74 // The map is guaranteed to contain getPrimaryId() as a key. 75 virtual const std::map<uint32_t, Prf*>& GetPrfs() const = 0; 76 // Convenience method to compute the primary PRF on a given input. 77 // See PRF.compute for details of the parameters. 78 util::StatusOr<std::string> ComputePrimary(absl::string_view input, 79 size_t output_length) const; 80 }; 81 82 } // namespace tink 83 } // namespace crypto 84 85 #endif // TINK_PRF_PRF_SET_H_ 86