Expand description
POLYVAL is a GHASH-like universal hash over GF(2^128) useful for implementing AES-GCM-SIV or AES-GCM/GMAC.
From RFC 8452 Section 3 which defines POLYVAL for use in AES-GCM-SIV:
“POLYVAL, like GHASH (the authenticator in AES-GCM; …), operates in a binary field of size 2^128. The field is defined by the irreducible polynomial x^128 + x^127 + x^126 + x^121 + 1.”
By multiplying (in the finite field sense) a sequence of 128-bit blocks of
input data data by a field element H, POLYVAL can be used to authenticate
the message sequence as powers (in the finite field sense) of H.
§Minimum Supported Rust Version
Rust 1.56 or higher.
In the future the minimum supported Rust version may be changed, but it be will be accompanied with a minor version bump.
§Supported backends
This crate provides multiple backends including a portable pure Rust backend as well as ones based on CPU intrinsics.
§“soft” portable backend
As a baseline implementation, this crate provides a constant-time pure Rust implementation based on BearSSL, which is a straightforward and compact implementation which uses a clever but simple technique to avoid carry-spilling.
§ARMv8 intrinsics (PMULL, nightly-only)
On aarch64 targets including aarch64-apple-darwin (Apple M1) and Linux
targets such as aarch64-unknown-linux-gnu and aarch64-unknown-linux-musl,
support for using the PMULL instructions in ARMv8’s Cryptography Extensions
is available when using the nightly compiler, and can be enabled using the
armv8 crate feature.
On Linux and macOS, when the armv8 feature is enabled support for AES
intrinsics is autodetected at runtime. On other platforms the crypto
target feature must be enabled via RUSTFLAGS.
§x86/x86_64 intrinsics (CMLMUL)
By default this crate uses runtime detection on i686/x86_64 targets
in order to determine if CLMUL is available, and if it is not, it will
fallback to using a constant-time software implementation.
For optimal performance, set target-cpu in RUSTFLAGS to sandybridge
or newer:
Example:
$ RUSTFLAGS="-Ctarget-cpu=sandybridge" cargo bench
§Relationship to GHASH
POLYVAL can be thought of as the little endian equivalent of GHASH, which affords it a small performance advantage over GHASH when used on little endian architectures.
It has also been designed so it can also be used to compute GHASH and with it GMAC, the Message Authentication Code (MAC) used by AES-GCM.
From RFC 8452 Appendix A:
“GHASH and POLYVAL both operate in GF(2^128), although with different irreducible polynomials: POLYVAL works modulo x^128 + x^127 + x^126 + x^121 + 1 and GHASH works modulo x^128 + x^7 + x^2 + x + 1. Note that these irreducible polynomials are the ‘reverse’ of each other.”
Re-exports§
pub use universal_hash;
Structs§
- POLYVAL: GHASH-like universal hash over GF(2^128).
Constants§
- Size of a POLYVAL block in bytes
- Size of a POLYVAL key in bytes
Functions§
- The
mulX_POLYVAL()function as defined in RFC 8452 Appendix A.
Type Aliases§
- POLYVAL blocks (16-bytes)
- POLYVAL keys (16-bytes)
- POLYVAL tags (16-bytes)