From: Filippo Valsorda Date: Wed, 8 Jan 2025 09:40:39 +0000 (+0100) Subject: crypto/mlkem: merge mlkem768.go and mlkem1024.go to improve godoc X-Git-Tag: go1.24rc3~2^2~60 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=c87a6f932efd3643c73f6b972da5500755048f85;p=gostls13.git crypto/mlkem: merge mlkem768.go and mlkem1024.go to improve godoc The constants appeared badly ordered and grouped in the godoc before const ( CiphertextSize1024 = 1568 EncapsulationKeySize1024 = 1568 ) const ( SharedKeySize = 32 SeedSize = 64 CiphertextSize768 = 1088 EncapsulationKeySize768 = 1184 ) while now they are a single group with the good size first const ( SharedKeySize = 32 SeedSize = 64 CiphertextSize768 = 1088 EncapsulationKeySize768 = 1184 CiphertextSize1024 = 1568 EncapsulationKeySize1024 = 1568 ) No code changes. Change-Id: I6a6a4656961b1e8c8bca3992aafa33e0575af8a2 Reviewed-on: https://go-review.googlesource.com/c/go/+/640997 Auto-Submit: Filippo Valsorda Reviewed-by: Dmitri Shuralyov LUCI-TryBot-Result: Go LUCI Reviewed-by: Russ Cox Reviewed-by: Daniel McCarney --- diff --git a/src/crypto/mlkem/mlkem768.go b/src/crypto/mlkem/mlkem.go similarity index 55% rename from src/crypto/mlkem/mlkem768.go rename to src/crypto/mlkem/mlkem.go index a165eb1c9f..69c0bc571f 100644 --- a/src/crypto/mlkem/mlkem768.go +++ b/src/crypto/mlkem/mlkem.go @@ -25,6 +25,12 @@ const ( // EncapsulationKeySize768 is the size of an ML-KEM-768 encapsulation key. EncapsulationKeySize768 = 1184 + + // CiphertextSize1024 is the size of a ciphertext produced by ML-KEM-1024. + CiphertextSize1024 = 1568 + + // EncapsulationKeySize1024 is the size of an ML-KEM-1024 encapsulation key. + EncapsulationKeySize1024 = 1568 ) // DecapsulationKey768 is the secret key used to decapsulate a shared key @@ -105,3 +111,82 @@ func (ek *EncapsulationKey768) Bytes() []byte { func (ek *EncapsulationKey768) Encapsulate() (sharedKey, ciphertext []byte) { return ek.key.Encapsulate() } + +// DecapsulationKey1024 is the secret key used to decapsulate a shared key +// from a ciphertext. It includes various precomputed values. +type DecapsulationKey1024 struct { + key *mlkem.DecapsulationKey1024 +} + +// GenerateKey1024 generates a new decapsulation key, drawing random bytes from +// the default crypto/rand source. The decapsulation key must be kept secret. +func GenerateKey1024() (*DecapsulationKey1024, error) { + key, err := mlkem.GenerateKey1024() + if err != nil { + return nil, err + } + + return &DecapsulationKey1024{key}, nil +} + +// NewDecapsulationKey1024 expands a decapsulation key from a 64-byte seed in the +// "d || z" form. The seed must be uniformly random. +func NewDecapsulationKey1024(seed []byte) (*DecapsulationKey1024, error) { + key, err := mlkem.NewDecapsulationKey1024(seed) + if err != nil { + return nil, err + } + + return &DecapsulationKey1024{key}, nil +} + +// Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form. +// +// The decapsulation key must be kept secret. +func (dk *DecapsulationKey1024) Bytes() []byte { + return dk.key.Bytes() +} + +// 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 (dk *DecapsulationKey1024) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) { + return dk.key.Decapsulate(ciphertext) +} + +// EncapsulationKey returns the public encapsulation key necessary to produce +// ciphertexts. +func (dk *DecapsulationKey1024) EncapsulationKey() *EncapsulationKey1024 { + return &EncapsulationKey1024{dk.key.EncapsulationKey()} +} + +// An EncapsulationKey1024 is the public key used to produce ciphertexts to be +// decapsulated by the corresponding DecapsulationKey1024. +type EncapsulationKey1024 struct { + key *mlkem.EncapsulationKey1024 +} + +// NewEncapsulationKey1024 parses an encapsulation key from its encoded form. If +// the encapsulation key is not valid, NewEncapsulationKey1024 returns an error. +func NewEncapsulationKey1024(encapsulationKey []byte) (*EncapsulationKey1024, error) { + key, err := mlkem.NewEncapsulationKey1024(encapsulationKey) + if err != nil { + return nil, err + } + + return &EncapsulationKey1024{key}, nil +} + +// Bytes returns the encapsulation key as a byte slice. +func (ek *EncapsulationKey1024) Bytes() []byte { + return ek.key.Bytes() +} + +// Encapsulate generates a shared key and an associated ciphertext from an +// encapsulation key, drawing random bytes from the default crypto/rand source. +// +// The shared key must be kept secret. +func (ek *EncapsulationKey1024) Encapsulate() (sharedKey, ciphertext []byte) { + return ek.key.Encapsulate() +} diff --git a/src/crypto/mlkem/mlkem1024.go b/src/crypto/mlkem/mlkem1024.go deleted file mode 100644 index 014cfce1e4..0000000000 --- a/src/crypto/mlkem/mlkem1024.go +++ /dev/null @@ -1,94 +0,0 @@ -// Copyright 2023 The Go Authors. All rights reserved. -// Use of this source code is governed by a BSD-style -// license that can be found in the LICENSE file. - -package mlkem - -import "crypto/internal/fips140/mlkem" - -const ( - // CiphertextSize1024 is the size of a ciphertext produced by ML-KEM-1024. - CiphertextSize1024 = 1568 - - // EncapsulationKeySize1024 is the size of an ML-KEM-1024 encapsulation key. - EncapsulationKeySize1024 = 1568 -) - -// DecapsulationKey1024 is the secret key used to decapsulate a shared key -// from a ciphertext. It includes various precomputed values. -type DecapsulationKey1024 struct { - key *mlkem.DecapsulationKey1024 -} - -// GenerateKey1024 generates a new decapsulation key, drawing random bytes from -// the default crypto/rand source. The decapsulation key must be kept secret. -func GenerateKey1024() (*DecapsulationKey1024, error) { - key, err := mlkem.GenerateKey1024() - if err != nil { - return nil, err - } - - return &DecapsulationKey1024{key}, nil -} - -// NewDecapsulationKey1024 expands a decapsulation key from a 64-byte seed in the -// "d || z" form. The seed must be uniformly random. -func NewDecapsulationKey1024(seed []byte) (*DecapsulationKey1024, error) { - key, err := mlkem.NewDecapsulationKey1024(seed) - if err != nil { - return nil, err - } - - return &DecapsulationKey1024{key}, nil -} - -// Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form. -// -// The decapsulation key must be kept secret. -func (dk *DecapsulationKey1024) Bytes() []byte { - return dk.key.Bytes() -} - -// 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 (dk *DecapsulationKey1024) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) { - return dk.key.Decapsulate(ciphertext) -} - -// EncapsulationKey returns the public encapsulation key necessary to produce -// ciphertexts. -func (dk *DecapsulationKey1024) EncapsulationKey() *EncapsulationKey1024 { - return &EncapsulationKey1024{dk.key.EncapsulationKey()} -} - -// An EncapsulationKey1024 is the public key used to produce ciphertexts to be -// decapsulated by the corresponding DecapsulationKey1024. -type EncapsulationKey1024 struct { - key *mlkem.EncapsulationKey1024 -} - -// NewEncapsulationKey1024 parses an encapsulation key from its encoded form. If -// the encapsulation key is not valid, NewEncapsulationKey1024 returns an error. -func NewEncapsulationKey1024(encapsulationKey []byte) (*EncapsulationKey1024, error) { - key, err := mlkem.NewEncapsulationKey1024(encapsulationKey) - if err != nil { - return nil, err - } - - return &EncapsulationKey1024{key}, nil -} - -// Bytes returns the encapsulation key as a byte slice. -func (ek *EncapsulationKey1024) Bytes() []byte { - return ek.key.Bytes() -} - -// Encapsulate generates a shared key and an associated ciphertext from an -// encapsulation key, drawing random bytes from the default crypto/rand source. -// -// The shared key must be kept secret. -func (ek *EncapsulationKey1024) Encapsulate() (sharedKey, ciphertext []byte) { - return ek.key.Encapsulate() -}