Struct permutation_iterator::FeistelNetwork

pub struct FeistelNetwork {
    pub half_width: u64,
    pub right_mask: u64,
    pub left_mask: u64,
    // some fields omitted
}

Implements a Feistel network, which can take a non-invertible pseudo-random function (PRF) and turn it into an invertible pseudo-random permutation (PRP).

If you use this struct directly note that its intended purpose is to be a PRP and map from an n-bit input to an n-bit output, where n is an even positive integer. For example, if constructed with a max of 10, internally it creates a 4-bit Feistel network, and for all integers in the 4-bit domain [0, 16) (0 inclusive to 16 exclusive) it will map an input to one and only one output, and vice-versa (a given output maps to one and only one input). Even though you specified a max value of 10, the output range may be larger than expected. Clients like RandomPermutor handle this by excluding output values outside of the desired range.

This is useful in fields like cryptography, where a block cipher is a PRP.

Another great use of a Feistel network is when you want some input to always map to one and only one output (and vice versa). For example, given a 32-bit IP address, we could use some secret key and map each IP address to some other 32-bit IP address. We could log this new 32-bit IP address and people who do not know what the secret key is would find it difficult to determine what the input IP address was. This is Format Preserving Encryption (FPE).

Fields

half_width: u64

TODO visible just for testing, fix

right_mask: u64

Mask used to keep within the width for the right. TODO visible just for testing, fix

left_mask: u64

Mask used to keep within the width for the left. TODO visible just for testing, fix

Methods

impl FeistelNetwork

pub fn new(max: u64) -> FeistelNetwork

Create a new FeistelNetwork instance that can give you a random permutation of integers.

Note that the value of max is rounded up to the nearest even power of 2. If clients are trying to get a permutation of [0, max) they need to iterate over the input range and discard values from FeistelNetwork >= max.

The key used for the permutation is made up of securely gathered 32 bytes.

pub fn new_with_slice_key(max_value: u64, key: [u8; 32]) -> FeistelNetwork

Create a new FeistelNetwork instance that can give you a random permutation of integers.

Note that the value of max is rounded up to the nearest even power of 2. If clients are trying to get a permutation of [0, max) they need to iterate over the input range and discard values from FeistelNetwork >= max.

pub fn permute(&self, input: u64) -> u64