package mlkem768

Import Path
	crypto/internal/mlkem768 (on go.dev)

Dependency Relation
	imports 5 packages, and imported by one package

Involved Source Files

	  d mlkem768.go
		Package mlkem768 implements the quantum-resistant key encapsulation method
		ML-KEM (formerly known as Kyber).
		
		Only the recommended ML-KEM-768 parameter set is provided.
		
		The version currently implemented is the one specified by [NIST FIPS 203 ipd],
		with the unintentional transposition of the matrix A reverted to match the
		behavior of [Kyber version 3.0]. Future versions of this package might
		introduce backwards incompatible changes to implement changes to FIPS 203.
		
		[Kyber version 3.0]: https://pq-crystals.org/kyber/data/kyber-specification-round3-20210804.pdf
		[NIST FIPS 203 ipd]: https://doi.org/10.6028/NIST.FIPS.203.ipd
Package-Level Type Names (total 6, in which 1 is exported)

	/* sort exporteds by: alphabet | popularity */
	 type DecapsulationKey (struct)
		A DecapsulationKey is the secret key used to decapsulate a shared key from a
		ciphertext. It includes various precomputed values.

		Fields (total 6, in which 1 is exported)
			encryptionKey.A [9]nttElement
				// A[i*k+j] = sampleNTT(ρ, j, i)

			/* 5 unexporteds ... *//* 5 unexporteds: */
			decryptionKey decryptionKey
			decryptionKey.s [3]nttElement
				// ByteDecode₁₂(dk[:decryptionKeySize])

			dk [2400]byte
			encryptionKey encryptionKey
			encryptionKey.t [3]nttElement
				// ByteDecode₁₂(ek[:384k])

		Methods (total 2, both are exported)
			(*DecapsulationKey) Bytes() []byte
				Bytes returns the extended encoding of the decapsulation key, according to
				FIPS 203 (DRAFT).

			(*DecapsulationKey) EncapsulationKey() []byte
				EncapsulationKey returns the public encapsulation key necessary to produce
				ciphertexts.

		As Outputs Of (at least 7, in which 3 are exported)
			func GenerateKey() (*DecapsulationKey, error)
			func NewKeyFromExtendedEncoding(decapsulationKey []byte) (*DecapsulationKey, error)
			func NewKeyFromSeed(seed []byte) (*DecapsulationKey, error)
			/* 4+ unexporteds ... *//* 4+ unexporteds: */
			func generateKey(dk *DecapsulationKey) (*DecapsulationKey, error)
			func kemKeyGen(dk *DecapsulationKey, d, z *[32]byte) *DecapsulationKey
			func newKeyFromExtendedEncoding(dk *DecapsulationKey, dkBytes []byte) (*DecapsulationKey, error)
			func newKeyFromSeed(dk *DecapsulationKey, seed []byte) (*DecapsulationKey, error)
		As Inputs Of (at least 7, in which 1 is exported)
			func Decapsulate(dk *DecapsulationKey, ciphertext []byte) (sharedKey []byte, err error)
			/* 6+ unexporteds ... *//* 6+ unexporteds: */
			func generateKey(dk *DecapsulationKey) (*DecapsulationKey, error)
			func kemDecaps(dk *DecapsulationKey, c *[1088]byte) (K []byte)
			func kemKeyGen(dk *DecapsulationKey, d, z *[32]byte) *DecapsulationKey
			func newKeyFromExtendedEncoding(dk *DecapsulationKey, dkBytes []byte) (*DecapsulationKey, error)
			func newKeyFromSeed(dk *DecapsulationKey, seed []byte) (*DecapsulationKey, error)
			func crypto/tls.kyberDecapsulate(dk *DecapsulationKey, c []byte) ([]byte, error)

	/* 5 unexporteds ... *//* 5 unexporteds: */
	 type decryptionKey (struct)
		decryptionKey is the parsed and expanded form of a PKE decryption key.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			s [3]nttElement
				// ByteDecode₁₂(dk[:decryptionKeySize])

		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func parseDK(dx *decryptionKey, dkPKE []byte) error
			func pkeDecrypt(dx *decryptionKey, c *[1088]byte) []byte

	 type encryptionKey (struct)
		encryptionKey is the parsed and expanded form of a PKE encryption key.

		Fields (total 2, in which 1 is exported)
			A [9]nttElement
				// A[i*k+j] = sampleNTT(ρ, j, i)

			/* one unexported ... *//* one unexported: */
			t [3]nttElement
				// ByteDecode₁₂(ek[:384k])

		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func parseEK(ex *encryptionKey, ekPKE []byte) error
			func pkeEncrypt(cc *[1088]byte, ex *encryptionKey, m *[32]byte, rnd []byte) []byte

	 type fieldElement uint16 (basic type)
		fieldElement is an integer modulo q, an element of ℤ_q. It is always reduced.

		As Outputs Of (at least 9, none are exported)
			/* 9+ unexporteds ... *//* 9+ unexporteds: */
			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
		As Inputs Of (at least 6, none are exported)
			/* 6+ unexporteds ... *//* 6+ unexporteds: */
			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

	 type nttElement ([...])
		nttElement is an NTT representation, an element of T_q, represented as an
		array according to FIPS 203 (DRAFT), Section 2.4.

		As Outputs Of (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func ntt(f ringElement) nttElement
			func nttMul(f, g nttElement) nttElement
			func sampleNTT(rho []byte, ii, jj byte) nttElement
		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func inverseNTT(f nttElement) ringElement
			func nttMul(f, g nttElement) nttElement

	 type ringElement ([...])
		ringElement is a polynomial, an element of R_q, represented as an array
		according to FIPS 203 (DRAFT), Section 2.4.

		As Outputs Of (at least 5, none are exported)
			/* 5+ unexporteds ... *//* 5+ unexporteds: */
			func inverseNTT(f nttElement) ringElement
			func ringDecodeAndDecompress1(b *[32]byte) ringElement
			func ringDecodeAndDecompress10(bb *[320]byte) ringElement
			func ringDecodeAndDecompress4(b *[128]byte) ringElement
			func samplePolyCBD(s []byte, b byte) ringElement
		As Inputs Of (at least 4, none are exported)
			/* 4+ unexporteds ... *//* 4+ unexporteds: */
			func ntt(f ringElement) nttElement
			func ringCompressAndEncode1(s []byte, f ringElement) []byte
			func ringCompressAndEncode10(s []byte, f ringElement) []byte
			func ringCompressAndEncode4(s []byte, f ringElement) []byte


Package-Level Functions (total 42, in which 5 are exported)

	 func Decapsulate(dk *DecapsulationKey, ciphertext []byte) (sharedKey []byte, err error)
		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.

	 func Encapsulate(encapsulationKey []byte) (ciphertext, sharedKey []byte, err error)
		Encapsulate generates a shared key and an associated ciphertext from an
		encapsulation key, drawing random bytes from crypto/rand.
		If the encapsulation key is not valid, Encapsulate returns an error.
		
		The shared key must be kept secret.

	 func GenerateKey() (*DecapsulationKey, error)
		GenerateKey generates a new decapsulation key, drawing random bytes from
		crypto/rand. The decapsulation key must be kept secret.

	 func NewKeyFromExtendedEncoding(decapsulationKey []byte) (*DecapsulationKey, error)
		NewKeyFromExtendedEncoding parses a decapsulation key from its FIPS 203
		(DRAFT) extended encoding.

	 func NewKeyFromSeed(seed []byte) (*DecapsulationKey, error)
		NewKeyFromSeed deterministically generates a decapsulation key from a 64-byte
		seed in the "d || z" form. The seed must be uniformly random.

	/* 37 unexporteds ... *//* 37 unexporteds: */
	 func compress(x fieldElement, d uint8) uint16
		compress maps a field element uniformly to the range 0 to 2ᵈ-1, according to
		FIPS 203 (DRAFT), Definition 4.5.

	 func decompress(y uint16, d uint8) fieldElement
		decompress maps a number x between 0 and 2ᵈ-1 uniformly to the full range of
		field elements, according to FIPS 203 (DRAFT), Definition 4.6.

	 func encapsulate(cc *[1088]byte, encapsulationKey []byte) (ciphertext, sharedKey []byte, err error)
	 func fieldAdd(a, b fieldElement) fieldElement
	 func fieldAddMul(a, b, c, d fieldElement) fieldElement
		fieldAddMul returns a * b + c * d. This operation is fused to save a
		fieldReduceOnce and a fieldReduce.

	 func fieldCheckReduced(a uint16) (fieldElement, error)
		fieldCheckReduced checks that a value a is < q.

	 func fieldMul(a, b fieldElement) fieldElement
	 func fieldMulSub(a, b, c fieldElement) fieldElement
		fieldMulSub returns a * (b - c). This operation is fused to save a
		fieldReduceOnce after the subtraction.

	 func fieldReduce(a uint32) fieldElement
		fieldReduce reduces a value a < 2q² using Barrett reduction, to avoid
		potentially variable-time division.

	 func fieldReduceOnce(a uint16) fieldElement
		fieldReduceOnce reduces a value a < 2q.

	 func fieldSub(a, b fieldElement) fieldElement
	 func generateKey(dk *DecapsulationKey) (*DecapsulationKey, error)
	 func inverseNTT(f nttElement) ringElement
		inverseNTT maps a nttElement back to the ringElement it represents.
		
		It implements NTT⁻¹, according to FIPS 203 (DRAFT), Algorithm 9.

	 func kemDecaps(dk *DecapsulationKey, c *[1088]byte) (K []byte)
		kemDecaps produces a shared key from a ciphertext.
		
		It implements ML-KEM.Decaps according to FIPS 203 (DRAFT), Algorithm 17.

	 func kemEncaps(cc *[1088]byte, ek []byte, m *[32]byte) (c, K []byte, err error)
		kemEncaps generates a shared key and an associated ciphertext.
		
		It implements ML-KEM.Encaps according to FIPS 203 (DRAFT), Algorithm 16.

	 func kemKeyGen(dk *DecapsulationKey, d, z *[32]byte) *DecapsulationKey
		kemKeyGen generates a decapsulation key.
		
		It implements ML-KEM.KeyGen according to FIPS 203 (DRAFT), Algorithm 15, and
		K-PKE.KeyGen according to FIPS 203 (DRAFT), Algorithm 12. The two are merged
		to save copies and allocations.

	 func newKeyFromExtendedEncoding(dk *DecapsulationKey, dkBytes []byte) (*DecapsulationKey, error)
	 func newKeyFromSeed(dk *DecapsulationKey, seed []byte) (*DecapsulationKey, error)
	 func ntt(f ringElement) nttElement
		ntt maps a ringElement to its nttElement representation.
		
		It implements NTT, according to FIPS 203 (DRAFT), Algorithm 8.

	 func nttMul(f, g nttElement) nttElement
		nttMul multiplies two nttElements.
		
		It implements MultiplyNTTs, according to FIPS 203 (DRAFT), Algorithm 10.

	 func parseDK(dx *decryptionKey, dkPKE []byte) error
		parseDK parses a decryption key from its encoded form.
		
		It implements the computation of s from K-PKE.Decrypt according to FIPS 203
		(DRAFT), Algorithm 14.

	 func parseEK(ex *encryptionKey, ekPKE []byte) error
		parseEK parses an encryption key from its encoded form.
		
		It implements the initial stages of K-PKE.Encrypt according to FIPS 203
		(DRAFT), Algorithm 13.

	 func pkeDecrypt(dx *decryptionKey, c *[1088]byte) []byte
		pkeDecrypt decrypts a ciphertext.
		
		It implements K-PKE.Decrypt according to FIPS 203 (DRAFT), Algorithm 14,
		although the computation of s is done in parseDK.

	 func pkeEncrypt(cc *[1088]byte, ex *encryptionKey, m *[32]byte, rnd []byte) []byte
		pkeEncrypt encrypt a plaintext message.
		
		It implements K-PKE.Encrypt according to FIPS 203 (DRAFT), Algorithm 13,
		although the computation of t and AT is done in parseEK.

	 func polyAdd[T](a, b T) (s T)

		Type Parameters:
			T: ~[256]fieldElement

		polyAdd adds two ringElements or nttElements.

	 func polyByteDecode[T](b []byte) (T, error)

		Type Parameters:
			T: ~[256]fieldElement

		polyByteDecode decodes the 384-byte encoding of a polynomial, checking that
		all the coefficients are properly reduced. This achieves the "Modulus check"
		step of ML-KEM Encapsulation Input Validation.
		
		polyByteDecode is also used in ML-KEM Decapsulation, where the input
		validation is not required, but implicitly allowed by the specification.
		
		It implements ByteDecode₁₂, according to FIPS 203 (DRAFT), Algorithm 5.

	 func polyByteEncode[T](b []byte, f T) []byte

		Type Parameters:
			T: ~[256]fieldElement

		polyByteEncode appends the 384-byte encoding of f to b.
		
		It implements ByteEncode₁₂, according to FIPS 203 (DRAFT), Algorithm 4.

	 func polySub[T](a, b T) (s T)

		Type Parameters:
			T: ~[256]fieldElement

		polySub subtracts two ringElements or nttElements.

	 func ringCompressAndEncode1(s []byte, f ringElement) []byte
		ringCompressAndEncode1 appends a 32-byte encoding of a ring element to s,
		compressing one coefficients per bit.
		
		It implements Compress₁, according to FIPS 203 (DRAFT), Definition 4.5,
		followed by ByteEncode₁, according to FIPS 203 (DRAFT), Algorithm 4.

	 func ringCompressAndEncode10(s []byte, f ringElement) []byte
		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 (DRAFT), Definition 4.5,
		followed by ByteEncode₁₀, according to FIPS 203 (DRAFT), Algorithm 4.

	 func ringCompressAndEncode4(s []byte, f ringElement) []byte
		ringCompressAndEncode4 appends a 128-byte encoding of a ring element to s,
		compressing two coefficients per byte.
		
		It implements Compress₄, according to FIPS 203 (DRAFT), Definition 4.5,
		followed by ByteEncode₄, according to FIPS 203 (DRAFT), Algorithm 4.

	 func ringDecodeAndDecompress1(b *[32]byte) ringElement
		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 (DRAFT), Algorithm 5,
		followed by Decompress₁, according to FIPS 203 (DRAFT), Definition 4.6.

	 func ringDecodeAndDecompress10(bb *[320]byte) ringElement
		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 (DRAFT), Algorithm 5,
		followed by Decompress₁₀, according to FIPS 203 (DRAFT), Definition 4.6.

	 func ringDecodeAndDecompress4(b *[128]byte) ringElement
		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 (DRAFT), Algorithm 5,
		followed by Decompress₄, according to FIPS 203 (DRAFT), Definition 4.6.

	 func sampleNTT(rho []byte, ii, jj byte) nttElement
		sampleNTT draws a uniformly random nttElement from a stream of uniformly
		random bytes generated by the XOF function, according to FIPS 203 (DRAFT),
		Algorithm 6 and Definition 4.2.

	 func samplePolyCBD(s []byte, b byte) ringElement
		samplePolyCBD draws a ringElement from the special Dη distribution given a
		stream of random bytes generated by the PRF function, according to FIPS 203
		(DRAFT), Algorithm 7 and Definition 4.1.

	 func sliceForAppend(in []byte, n int) (head, tail []byte)
		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)

	/* 2 unexporteds ... *//* 2 unexporteds: */
	  var gammas [128]fieldElement
		gammas are the values ζ^2BitRev7(i)+1 mod q for each index i.

	  var zetas [128]fieldElement
		zetas are the values ζ^BitRev7(k) mod q for each index k.


Package-Level Constants (total 21, in which 5 are exported)

	const CiphertextSize = 1088
	const DecapsulationKeySize = 2400
	const EncapsulationKeySize = 1184
	const SeedSize = 64
	const SharedKeySize = 32
	/* 16 unexporteds ... *//* 16 unexporteds: */
	const barrettMultiplier = 5039 // 2¹² * 2¹² / q
	const barrettShift = 24 // log₂(2¹² * 2¹²)
	const decryptionKeySize = 1152
	const du = 10
	const dv = 4
	const encodingSize1 = 32
	const encodingSize10 = 320
	const encodingSize12 = 384
		encodingSizeX is the byte size of a ringElement or nttElement encoded
		by ByteEncode_X (FIPS 203 (DRAFT), Algorithm 4).

	const encodingSize4 = 128
	const encryptionKeySize = 1184
	const k = 3
		ML-KEM-768 parameters. The code makes assumptions based on these values,
		they can't be changed blindly.

	const log2q = 12
	const messageSize = 32
	const n = 256
		ML-KEM global constants.

	const q = 3329
	const η = 2

The pages are generated with Golds v0.7.6. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.