tink_core/
prf.rs

1// Copyright 2020 The Tink-Rust Authors
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//! Pseudo-random function.
18
19/// The `Prf` trait is an abstraction for an element of a pseudo random
20/// function family, selected by a key. It has the following property:
21///   * It is deterministic. `compute_prf(input, length)` will always return the same output if the
22///     same key is used. `compute_prf(input, length1)` will be a prefix of `compute_prf(input,
23///     length2)` if `length1` < `length2` and the same key is used.
24///   * It is indistinguishable from a random function: Given the evaluation of n different inputs,
25///     an attacker cannot distinguish between the PRF and random bytes on an input different from
26///     the n that are known.
27///
28/// Use cases for PRF are deterministic redaction of PII, keyed hash functions,
29/// creating sub IDs that do not allow joining with the original dataset without
30/// knowing the key.
31///
32/// While PRFs can be used in order to prove authenticity of a message, using the
33/// [`Mac`](crate::Mac) interface is recommended for that use case, as it has support for
34/// verification, avoiding the security problems that often happen during
35/// verification, and having automatic support for key rotation. It also allows
36/// for non-deterministic MAC algorithms.
37pub trait Prf: PrfBoxClone {
38    /// Compute the PRF selected by the underlying key on input and
39    /// returns the first `output_length` bytes.
40    /// When choosing this parameter keep the birthday paradox in mind.
41    /// If you have 2^n different inputs that your system has to handle
42    /// set the output length (in bytes) to at least
43    /// ceil(n/4 + 4)
44    /// This corresponds to 2*n + 32 bits, meaning a collision will occur with
45    /// a probability less than 1:2^32. When in doubt, request a security review.
46    /// Returns a non ok status if the algorithm fails or if the output of
47    /// algorithm is less than outputLength.
48    fn compute_prf(&self, input: &[u8], output_length: usize) -> Result<Vec<u8>, crate::TinkError>;
49}
50
51/// Trait bound to indicate that primitive trait objects should support cloning
52/// themselves as trait objects.
53pub trait PrfBoxClone {
54    fn box_clone(&self) -> Box<dyn Prf>;
55}
56
57/// Default implementation of the box-clone trait bound for any underlying
58/// concrete type that implements [`Clone`].
59impl<T> PrfBoxClone for T
60where
61    T: 'static + Prf + Clone,
62{
63    fn box_clone(&self) -> Box<dyn Prf> {
64        Box::new(self.clone())
65    }
66}
tink_core/prf.rs

tink_core/
prf.rs
