Involved Source Filescast.gofield.gomlkem1024.go Package mlkem implements the quantum-resistant key encapsulation method
ML-KEM (formerly known as Kyber), as specified in [NIST FIPS 203].
[NIST FIPS 203]: https://doi.org/10.6028/NIST.FIPS.203
Package-Level Type Names (total 11, in which 4 are exported)
/* sort exporteds by: | */
A DecapsulationKey1024 is the secret key used to decapsulate a shared key from a
ciphertext. It includes various precomputed values. // decapsulation key seeddecryptionKey1024decryptionKey1024 // ByteDecode₁₂(dk[:decryptionKey1024Size])encryptionKey1024encryptionKey1024 // A[i*k+j] = sampleNTT(ρ, j, i) // ByteDecode₁₂(ek[:384k]) // H(ek), stored for ML-KEM.Decaps_internal // implicit rejection sampling seed // sampleNTT seed for A, stored for the encapsulation key Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
The decapsulation key must be kept secret. Decapsulate generates a shared key from a ciphertext and a decapsulation key.
If the ciphertext is not valid, Decapsulate returns an error.
The shared key must be kept secret. EncapsulationKey returns the public encapsulation key necessary to produce
ciphertexts.
func GenerateKey1024() (*DecapsulationKey1024, error)
func GenerateKeyInternal1024(d, z *[32]byte) *DecapsulationKey1024
func NewDecapsulationKey1024(seed []byte) (*DecapsulationKey1024, error)
func TestingOnlyNewDecapsulationKey1024(b []byte) (*DecapsulationKey1024, error)
func generateKey1024(dk *DecapsulationKey1024) (*DecapsulationKey1024, error)
func newKeyFromSeed1024(dk *DecapsulationKey1024, seed []byte) (*DecapsulationKey1024, error)
func TestingOnlyExpandedBytes1024(dk *DecapsulationKey1024) []byte
func generateKey1024(dk *DecapsulationKey1024) (*DecapsulationKey1024, error)
func kemDecaps1024(dk *DecapsulationKey1024, c *[1568]byte) (K []byte)
func kemKeyGen1024(dk *DecapsulationKey1024, d, z *[32]byte)
func kemPCT1024(dk *DecapsulationKey1024) error
func newKeyFromSeed1024(dk *DecapsulationKey1024, seed []byte) (*DecapsulationKey1024, error)
A DecapsulationKey768 is the secret key used to decapsulate a shared key from a
ciphertext. It includes various precomputed values. // decapsulation key seeddecryptionKeydecryptionKey // ByteDecode₁₂(dk[:decryptionKeySize])encryptionKeyencryptionKey // A[i*k+j] = sampleNTT(ρ, j, i) // ByteDecode₁₂(ek[:384k]) // H(ek), stored for ML-KEM.Decaps_internal // implicit rejection sampling seed // sampleNTT seed for A, stored for the encapsulation key Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
The decapsulation key must be kept secret. Decapsulate generates a shared key from a ciphertext and a decapsulation key.
If the ciphertext is not valid, Decapsulate returns an error.
The shared key must be kept secret. EncapsulationKey returns the public encapsulation key necessary to produce
ciphertexts.
func GenerateKey768() (*DecapsulationKey768, error)
func GenerateKeyInternal768(d, z *[32]byte) *DecapsulationKey768
func NewDecapsulationKey768(seed []byte) (*DecapsulationKey768, error)
func TestingOnlyNewDecapsulationKey768(b []byte) (*DecapsulationKey768, error)
func generateKey(dk *DecapsulationKey768) (*DecapsulationKey768, error)
func newKeyFromSeed(dk *DecapsulationKey768, seed []byte) (*DecapsulationKey768, error)
func TestingOnlyExpandedBytes768(dk *DecapsulationKey768) []byte
func generateKey(dk *DecapsulationKey768) (*DecapsulationKey768, error)
func kemDecaps(dk *DecapsulationKey768, c *[1088]byte) (K []byte)
func kemKeyGen(dk *DecapsulationKey768, d, z *[32]byte)
func kemPCT(dk *DecapsulationKey768) error
func newKeyFromSeed(dk *DecapsulationKey768, seed []byte) (*DecapsulationKey768, error)
An EncapsulationKey1024 is the public key used to produce ciphertexts to be
decapsulated by the corresponding [DecapsulationKey1024].encryptionKey1024encryptionKey1024 // A[i*k+j] = sampleNTT(ρ, j, i) // ByteDecode₁₂(ek[:384k]) // H(ek) // sampleNTT seed for A Bytes returns the encapsulation key as a byte slice. Encapsulate generates a shared key and an associated ciphertext from an
encapsulation key, drawing random bytes from a DRBG.
The shared key must be kept secret. EncapsulateInternal is a derandomized version of Encapsulate, exclusively for
use in tests.(*EncapsulationKey1024) bytes(b []byte) []byte(*EncapsulationKey1024) encapsulate(cc *[1568]byte) (sharedKey, ciphertext []byte)
func NewEncapsulationKey1024(encapsulationKey []byte) (*EncapsulationKey1024, error)
func (*DecapsulationKey1024).EncapsulationKey() *EncapsulationKey1024
func parseEK1024(ek *EncapsulationKey1024, ekPKE []byte) (*EncapsulationKey1024, error)
func kemEncaps1024(cc *[1568]byte, ek *EncapsulationKey1024, m *[32]byte) (K, c []byte)
func parseEK1024(ek *EncapsulationKey1024, ekPKE []byte) (*EncapsulationKey1024, error)
An EncapsulationKey768 is the public key used to produce ciphertexts to be
decapsulated by the corresponding [DecapsulationKey768].encryptionKeyencryptionKey // A[i*k+j] = sampleNTT(ρ, j, i) // ByteDecode₁₂(ek[:384k]) // H(ek) // sampleNTT seed for A Bytes returns the encapsulation key as a byte slice. Encapsulate generates a shared key and an associated ciphertext from an
encapsulation key, drawing random bytes from a DRBG.
The shared key must be kept secret. EncapsulateInternal is a derandomized version of Encapsulate, exclusively for
use in tests.(*EncapsulationKey768) bytes(b []byte) []byte(*EncapsulationKey768) encapsulate(cc *[1088]byte) (sharedKey, ciphertext []byte)
func NewEncapsulationKey768(encapsulationKey []byte) (*EncapsulationKey768, error)
func (*DecapsulationKey768).EncapsulationKey() *EncapsulationKey768
func parseEK(ek *EncapsulationKey768, ekPKE []byte) (*EncapsulationKey768, error)
func kemEncaps(cc *[1088]byte, ek *EncapsulationKey768, m *[32]byte) (K, c []byte)
func parseEK(ek *EncapsulationKey768, ekPKE []byte) (*EncapsulationKey768, error)
decryptionKey is the parsed and expanded form of a PKE decryption key. // ByteDecode₁₂(dk[:decryptionKeySize])
func pkeDecrypt(dx *decryptionKey, c *[1088]byte) []byte
decryptionKey1024 is the parsed and expanded form of a PKE decryption key. // ByteDecode₁₂(dk[:decryptionKey1024Size])
func pkeDecrypt1024(dx *decryptionKey1024, c *[1568]byte) []byte
encryptionKey is the parsed and expanded form of a PKE encryption key. // A[i*k+j] = sampleNTT(ρ, j, i) // ByteDecode₁₂(ek[:384k])
func pkeEncrypt(cc *[1088]byte, ex *encryptionKey, m *[32]byte, rnd []byte) []byte
encryptionKey1024 is the parsed and expanded form of a PKE encryption key. // A[i*k+j] = sampleNTT(ρ, j, i) // ByteDecode₁₂(ek[:384k])
func pkeEncrypt1024(cc *[1568]byte, ex *encryptionKey1024, m *[32]byte, rnd []byte) []byte
fieldElement is an integer modulo q, an element of ℤ_q. It is always reduced.
func decompress(y uint16, d uint8) fieldElement
func fieldAdd(a, b fieldElement) fieldElement
func fieldAddMul(a, b, c, d fieldElement) fieldElement
func fieldCheckReduced(a uint16) (fieldElement, error)
func fieldMul(a, b fieldElement) fieldElement
func fieldMulSub(a, b, c fieldElement) fieldElement
func fieldReduce(a uint32) fieldElement
func fieldReduceOnce(a uint16) fieldElement
func fieldSub(a, b fieldElement) fieldElement
func compress(x fieldElement, d uint8) uint16
func fieldAdd(a, b fieldElement) fieldElement
func fieldAddMul(a, b, c, d fieldElement) fieldElement
func fieldMul(a, b fieldElement) fieldElement
func fieldMulSub(a, b, c fieldElement) fieldElement
func fieldSub(a, b fieldElement) fieldElement
nttElement is an NTT representation, an element of T_q, represented as an
array according to FIPS 203, Section 2.4.4.
func ntt(f ringElement) nttElement
func nttMul(f, g nttElement) nttElement
func sampleNTT(rho []byte, ii, jj byte) nttElement
func inverseNTT(f nttElement) ringElement
func nttMul(f, g nttElement) nttElement
Package-Level Functions (total 63, in which 12 are exported)
GenerateKey1024 generates a new decapsulation key, drawing random bytes from
a DRBG. The decapsulation key must be kept secret.
GenerateKey768 generates a new decapsulation key, drawing random bytes from
a DRBG. The decapsulation key must be kept secret.
GenerateKeyInternal1024 is a derandomized version of GenerateKey1024,
exclusively for use in tests.
GenerateKeyInternal768 is a derandomized version of GenerateKey768,
exclusively for use in tests.
NewDecapsulationKey1024 parses a decapsulation key from a 64-byte
seed in the "d || z" form. The seed must be uniformly random.
NewDecapsulationKey768 parses a decapsulation key from a 64-byte
seed in the "d || z" form. The seed must be uniformly random.
NewEncapsulationKey1024 parses an encapsulation key from its encoded form.
If the encapsulation key is not valid, NewEncapsulationKey1024 returns an error.
NewEncapsulationKey768 parses an encapsulation key from its encoded form.
If the encapsulation key is not valid, NewEncapsulationKey768 returns an error.
TestingOnlyExpandedBytes1024 returns the decapsulation key as a byte slice
using the full expanded NIST encoding.
This should only be used for ACVP testing. For all other purposes prefer
the Bytes method that returns the (much smaller) seed.
TestingOnlyExpandedBytes768 returns the decapsulation key as a byte slice
using the full expanded NIST encoding.
This should only be used for ACVP testing. For all other purposes prefer
the Bytes method that returns the (much smaller) seed.
TestingOnlyNewDecapsulationKey1024 parses a decapsulation key from its expanded NIST format.
Bytes() must not be called on the returned key, as it will not produce the
original seed.
This function should only be used for ACVP testing. Prefer NewDecapsulationKey1024 for all
other purposes.
TestingOnlyNewDecapsulationKey768 parses a decapsulation key from its expanded NIST format.
Bytes() must not be called on the returned key, as it will not produce the
original seed.
This function should only be used for ACVP testing. Prefer NewDecapsulationKey768 for all
other purposes.
compress maps a field element uniformly to the range 0 to 2ᵈ-1, according to
FIPS 203, Definition 4.7.
decompress maps a number x between 0 and 2ᵈ-1 uniformly to the full range of
field elements, according to FIPS 203, Definition 4.8.
inverseNTT maps a nttElement back to the ringElement it represents.
It implements NTT⁻¹, according to FIPS 203, Algorithm 10.
kemDecaps produces a shared key from a ciphertext.
It implements ML-KEM.Decaps_internal according to FIPS 203, Algorithm 18.
kemDecaps1024 produces a shared key from a ciphertext.
It implements ML-KEM.Decaps_internal according to FIPS 203, Algorithm 18.
kemEncaps generates a shared key and an associated ciphertext.
It implements ML-KEM.Encaps_internal according to FIPS 203, Algorithm 17.
kemEncaps1024 generates a shared key and an associated ciphertext.
It implements ML-KEM.Encaps_internal according to FIPS 203, Algorithm 17.
kemKeyGen generates a decapsulation key.
It implements ML-KEM.KeyGen_internal according to FIPS 203, Algorithm 16, and
K-PKE.KeyGen according to FIPS 203, Algorithm 13. The two are merged to save
copies and allocations.
kemKeyGen1024 generates a decapsulation key.
It implements ML-KEM.KeyGen_internal according to FIPS 203, Algorithm 16, and
K-PKE.KeyGen according to FIPS 203, Algorithm 13. The two are merged to save
copies and allocations.
kemPCT performs a Pairwise Consistency Test per FIPS 140-3 IG 10.3.A
Additional Comment 1: "For key pairs generated for use with approved KEMs in
FIPS 203, the PCT shall consist of applying the encapsulation key ek to
encapsulate a shared secret K leading to ciphertext c, and then applying
decapsulation key dk to retrieve the same shared secret K. The PCT passes if
the two shared secret K values are equal. The PCT shall be performed either
when keys are generated/imported, prior to the first exportation, or prior to
the first operational use (if not exported before the first use)."
kemPCT1024 performs a Pairwise Consistency Test per FIPS 140-3 IG 10.3.A
Additional Comment 1: "For key pairs generated for use with approved KEMs in
FIPS 203, the PCT shall consist of applying the encapsulation key ek to
encapsulate a shared secret K leading to ciphertext c, and then applying
decapsulation key dk to retrieve the same shared secret K. The PCT passes if
the two shared secret K values are equal. The PCT shall be performed either
when keys are generated/imported, prior to the first exportation, or prior to
the first operational use (if not exported before the first use)."
ntt maps a ringElement to its nttElement representation.
It implements NTT, according to FIPS 203, Algorithm 9.
nttMul multiplies two nttElements.
It implements MultiplyNTTs, according to FIPS 203, Algorithm 11.
parseEK parses an encryption key from its encoded form.
It implements the initial stages of K-PKE.Encrypt according to FIPS 203,
Algorithm 14.
parseEK1024 parses an encryption key from its encoded form.
It implements the initial stages of K-PKE.Encrypt according to FIPS 203,
Algorithm 14.
pkeDecrypt decrypts a ciphertext.
It implements K-PKE.Decrypt according to FIPS 203, Algorithm 15,
although s is retained from kemKeyGen.
pkeDecrypt1024 decrypts a ciphertext.
It implements K-PKE.Decrypt according to FIPS 203, Algorithm 15,
although s is retained from kemKeyGen1024.
pkeEncrypt encrypt a plaintext message.
It implements K-PKE.Encrypt according to FIPS 203, Algorithm 14, although the
computation of t and AT is done in parseEK.
pkeEncrypt1024 encrypt a plaintext message.
It implements K-PKE.Encrypt according to FIPS 203, Algorithm 14, although the
computation of t and AT is done in parseEK1024.
Type Parameters:
T: ~[256]fieldElement polyAdd adds two ringElements or nttElements.
Type Parameters:
T: ~[256]fieldElement polyByteDecode decodes the 384-byte encoding of a polynomial, checking that
all the coefficients are properly reduced. This fulfills the "Modulus check"
step of ML-KEM Encapsulation.
It implements ByteDecode₁₂, according to FIPS 203, Algorithm 6.
Type Parameters:
T: ~[256]fieldElement polyByteEncode appends the 384-byte encoding of f to b.
It implements ByteEncode₁₂, according to FIPS 203, Algorithm 5.
Type Parameters:
T: ~[256]fieldElement polySub subtracts two ringElements or nttElements.
ringCompressAndEncode appends an encoding of a ring element to s,
compressing each coefficient to d bits.
It implements Compress, according to FIPS 203, Definition 4.7,
followed by ByteEncode, according to FIPS 203, Algorithm 5.
ringCompressAndEncode1 appends a 32-byte encoding of a ring element to s,
compressing one coefficients per bit.
It implements Compress₁, according to FIPS 203, Definition 4.7,
followed by ByteEncode₁, according to FIPS 203, Algorithm 5.
ringCompressAndEncode10 appends a 320-byte encoding of a ring element to s,
compressing four coefficients per five bytes.
It implements Compress₁₀, according to FIPS 203, Definition 4.7,
followed by ByteEncode₁₀, according to FIPS 203, Algorithm 5.
ringCompressAndEncode11 appends a 352-byte encoding of a ring element to s,
compressing eight coefficients per eleven bytes.
It implements Compress₁₁, according to FIPS 203, Definition 4.7,
followed by ByteEncode₁₁, according to FIPS 203, Algorithm 5.
ringCompressAndEncode4 appends a 128-byte encoding of a ring element to s,
compressing two coefficients per byte.
It implements Compress₄, according to FIPS 203, Definition 4.7,
followed by ByteEncode₄, according to FIPS 203, Algorithm 5.
ringCompressAndEncode5 appends a 160-byte encoding of a ring element to s,
compressing eight coefficients per five bytes.
It implements Compress₅, according to FIPS 203, Definition 4.7,
followed by ByteEncode₅, according to FIPS 203, Algorithm 5.
ringDecodeAndDecompress decodes an encoding of a ring element where
each d bits are mapped to an equidistant distribution.
It implements ByteDecode, according to FIPS 203, Algorithm 6,
followed by Decompress, according to FIPS 203, Definition 4.8.
ringDecodeAndDecompress1 decodes a 32-byte slice to a ring element where each
bit is mapped to 0 or ⌈q/2⌋.
It implements ByteDecode₁, according to FIPS 203, Algorithm 6,
followed by Decompress₁, according to FIPS 203, Definition 4.8.
ringDecodeAndDecompress10 decodes a 320-byte encoding of a ring element where
each ten bits are mapped to an equidistant distribution.
It implements ByteDecode₁₀, according to FIPS 203, Algorithm 6,
followed by Decompress₁₀, according to FIPS 203, Definition 4.8.
ringDecodeAndDecompress11 decodes a 352-byte encoding of a ring element where
each eleven bits are mapped to an equidistant distribution.
It implements ByteDecode₁₁, according to FIPS 203, Algorithm 6,
followed by Decompress₁₁, according to FIPS 203, Definition 4.8.
ringDecodeAndDecompress4 decodes a 128-byte encoding of a ring element where
each four bits are mapped to an equidistant distribution.
It implements ByteDecode₄, according to FIPS 203, Algorithm 6,
followed by Decompress₄, according to FIPS 203, Definition 4.8.
ringDecodeAndDecompress5 decodes a 160-byte encoding of a ring element where
each five bits are mapped to an equidistant distribution.
It implements ByteDecode₅, according to FIPS 203, Algorithm 6,
followed by Decompress₅, according to FIPS 203, Definition 4.8.
sampleNTT draws a uniformly random nttElement from a stream of uniformly
random bytes generated by the XOF function, according to FIPS 203,
Algorithm 7.
samplePolyCBD draws a ringElement from the special Dη distribution given a
stream of random bytes generated by the PRF function, according to FIPS 203,
Algorithm 8 and Definition 4.3.
sliceForAppend takes a slice and a requested number of bytes. It returns a
slice with the contents of the given slice followed by that many bytes and a
second slice that aliases into it and contains only the extra bytes. If the
original slice has sufficient capacity then no allocation is performed.
Package-Level Variables (total 2, neither is exported)
gammas are the values ζ^2BitRev7(i)+1 mod q for each index i, according to
FIPS 203, Appendix A (with negative values reduced to positive).
zetas are the values ζ^BitRev7(k) mod q for each index k, according to FIPS
203, Appendix A.
Package-Level Constants (total 21, in which 6 are exported)