mlkem1024.go

     1  // Copyright 2023 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package mlkem
     6  
     7  import "crypto/internal/fips140/mlkem"
     8  
     9  const (
    10  	// CiphertextSize1024 is the size of a ciphertext produced by the 1024-bit
    11  	// variant of ML-KEM.
    12  	CiphertextSize1024 = 1568
    13  
    14  	// EncapsulationKeySize1024 is the size of an encapsulation key for the
    15  	// 1024-bit variant of ML-KEM.
    16  	EncapsulationKeySize1024 = 1568
    17  )
    18  
    19  // DecapsulationKey1024 is the secret key used to decapsulate a shared key
    20  // from a ciphertext. It includes various precomputed values.
    21  type DecapsulationKey1024 struct {
    22  	key *mlkem.DecapsulationKey1024
    23  }
    24  
    25  // GenerateKey1024 generates a new decapsulation key, drawing random bytes from
    26  // crypto/rand. The decapsulation key must be kept secret.
    27  func GenerateKey1024() (*DecapsulationKey1024, error) {
    28  	key, err := mlkem.GenerateKey1024()
    29  	if err != nil {
    30  		return nil, err
    31  	}
    32  
    33  	return &DecapsulationKey1024{key}, nil
    34  }
    35  
    36  // NewDecapsulationKey1024 parses a decapsulation key from a 64-byte seed in the
    37  // "d || z" form. The seed must be uniformly random.
    38  func NewDecapsulationKey1024(seed []byte) (*DecapsulationKey1024, error) {
    39  	key, err := mlkem.NewDecapsulationKey1024(seed)
    40  	if err != nil {
    41  		return nil, err
    42  	}
    43  
    44  	return &DecapsulationKey1024{key}, nil
    45  }
    46  
    47  // Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
    48  //
    49  // The decapsulation key must be kept secret.
    50  func (dk *DecapsulationKey1024) Bytes() []byte {
    51  	return dk.key.Bytes()
    52  }
    53  
    54  // Decapsulate generates a shared key from a ciphertext and a decapsulation
    55  // key. If the ciphertext is not valid, Decapsulate returns an error.
    56  //
    57  // The shared key must be kept secret.
    58  func (dk *DecapsulationKey1024) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) {
    59  	return dk.key.Decapsulate(ciphertext)
    60  }
    61  
    62  // EncapsulationKey returns the public encapsulation key necessary to produce
    63  // ciphertexts.
    64  func (dk *DecapsulationKey1024) EncapsulationKey() *EncapsulationKey1024 {
    65  	return &EncapsulationKey1024{dk.key.EncapsulationKey()}
    66  }
    67  
    68  // An EncapsulationKey1024 is the public key used to produce ciphertexts to be
    69  // decapsulated by the corresponding DecapsulationKey1024.
    70  type EncapsulationKey1024 struct {
    71  	key *mlkem.EncapsulationKey1024
    72  }
    73  
    74  // NewEncapsulationKey1024 parses an encapsulation key from its encoded form. If
    75  // the encapsulation key is not valid, NewEncapsulationKey1024 returns an error.
    76  func NewEncapsulationKey1024(encapsulationKey []byte) (*EncapsulationKey1024, error) {
    77  	key, err := mlkem.NewEncapsulationKey1024(encapsulationKey)
    78  	if err != nil {
    79  		return nil, err
    80  	}
    81  
    82  	return &EncapsulationKey1024{key}, nil
    83  }
    84  
    85  // Bytes returns the encapsulation key as a byte slice.
    86  func (ek *EncapsulationKey1024) Bytes() []byte {
    87  	return ek.key.Bytes()
    88  }
    89  
    90  // Encapsulate generates a shared key and an associated ciphertext from an
    91  // encapsulation key, drawing random bytes from crypto/rand.
    92  //
    93  // The shared key must be kept secret.
    94  func (ek *EncapsulationKey1024) Encapsulate() (ciphertext, sharedKey []byte) {
    95  	return ek.key.Encapsulate()
    96  }
    97
View as plain text