Crate guff

Grand Unified Finite Field library*

Implements GF(2^x) for various “natural” sizes such as 2⁸, 2¹⁶ and 2³².

Basic Use: doing maths on elements of a particular field

The general outline for using this library is:

• decide what “class” of field you want to use (GF(2⁸), GF(2¹⁶), …);

• decide if you want to use one of the optimised adaptations or are happy with the default, generic code;

• create a new field object (we can call f) of that class with your chosen field polynomial (aka “irreducible polynomial”) by calling the appropriate constructor;

• use that object to do maths in that field: eg, result = f.mul(a,b)

Example of using the default generic code:

use guff::{GaloisField, F4, new_gf4};
 
// Create a GF(2<sup>4</sup>) field from a struct
// * `19` is the field's irreducible polynomial
// * `3` is the same value with bit 0x10 removed
let f = guff::F4 { full : 19, compact : 3 };
 
assert_eq!(f.pow(5,3), f.mul(5,f.mul(5,5)) );
 
// The same, but using a constructor as syntactic sugar
let f2 = guff::new_gf4(19, 3);

assert_eq!(f2.pow(5,3), f2.mul(5,f2.mul(5,5)) );
assert_eq!(f.pow(5,3), f2.pow(5,3));
 

The guff::good module provides a set of reasonably good implementations that in most cases should be better than the generic implementation. Example of use:

use guff::GaloisField;
use guff::good::{F4_0x13, new_gf4_0x13};
 
let f = guff::good::new_gf4_0x13();

assert_eq!(f.pow(5,3), f.mul(5,f.mul(5,5)) );
 

Vector Operations

Many applications involving Galois Fields involve working with vectors of field elements instead of single elements. Various primitive methods are implemented:

• sum of vector elements
• sum of two equal-length vectors
• cross product (pairwise multiplication of elements)
• dot product (sum of cross-product values)
• scaling a vector by a constant
• fused multiply add (scale and sum by a pair of constants across vector)

These are all implemented using slices of the appropriate ElementStore type. Where necessary, if a vector (slice) type is to be returned, it must be handled by the user by passing in a mutable reference. Also note that some operations (such as scaling a vector) are done in-place, so if the previous values need to be saved, they should be copied first.

See the GaloisField documentation for a full list of method signatures (prefixed with vec_).

Crate Name

* The crate name is deliberately hyperbolic:

Noun guff - unacceptable behavior (especially ludicrously false statements)

Modules

good

A set of “good” optimised routines in native Rust

Structs

F4

A type implementing (default) maths in GF(2⁴)

F8

A type implementing (default) maths in GF(2⁸)

F16

A type implementing (default) maths in GF(2¹⁶)

F32

A type implementing (default) maths in GF(2³²)

Traits

ElementStore

A typing trait meant to map to a primitive unsigned integer type such as u8, u16 or u32.

GaloisField

Collection of methods needed to implement maths in GF(2^x). Provides (slow) default implementations that can be overriden by optimised versions.

Functions

new_gf4

Create a new GF(2⁴) field with a supplied field polynomial (using the default implementation)

new_gf8

Create a new GF(2⁸) field with a supplied field polynomial (using the default implementation)

new_gf16

Create a new GF(2¹⁶) field with a supplied field polynomial (using the default implementation)

new_gf32

Create a new GF(2³²) field with a supplied field polynomial (using the default implementation)