mlkem.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 implements the quantum-resistant key encapsulation method
     6  // ML-KEM (formerly known as Kyber), as specified in [NIST FIPS 203].
     7  //
     8  // Most applications should use the ML-KEM-768 parameter set, as implemented by
     9  // [DecapsulationKey768] and [EncapsulationKey768].
    10  //
    11  // [NIST FIPS 203]: https://doi.org/10.6028/NIST.FIPS.203
    12  package mlkem
    13  
    14  import "crypto/internal/fips140/mlkem"
    15  
    16  const (
    17  	// SharedKeySize is the size of a shared key produced by ML-KEM.
    18  	SharedKeySize = 32
    19  
    20  	// SeedSize is the size of a seed used to generate a decapsulation key.
    21  	SeedSize = 64
    22  
    23  	// CiphertextSize768 is the size of a ciphertext produced by ML-KEM-768.
    24  	CiphertextSize768 = 1088
    25  
    26  	// EncapsulationKeySize768 is the size of an ML-KEM-768 encapsulation key.
    27  	EncapsulationKeySize768 = 1184
    28  
    29  	// CiphertextSize1024 is the size of a ciphertext produced by ML-KEM-1024.
    30  	CiphertextSize1024 = 1568
    31  
    32  	// EncapsulationKeySize1024 is the size of an ML-KEM-1024 encapsulation key.
    33  	EncapsulationKeySize1024 = 1568
    34  )
    35  
    36  // DecapsulationKey768 is the secret key used to decapsulate a shared key
    37  // from a ciphertext. It includes various precomputed values.
    38  type DecapsulationKey768 struct {
    39  	key *mlkem.DecapsulationKey768
    40  }
    41  
    42  // GenerateKey768 generates a new decapsulation key, drawing random bytes from
    43  // the default crypto/rand source. The decapsulation key must be kept secret.
    44  func GenerateKey768() (*DecapsulationKey768, error) {
    45  	key, err := mlkem.GenerateKey768()
    46  	if err != nil {
    47  		return nil, err
    48  	}
    49  
    50  	return &DecapsulationKey768{key}, nil
    51  }
    52  
    53  // NewDecapsulationKey768 expands a decapsulation key from a 64-byte seed in the
    54  // "d || z" form. The seed must be uniformly random.
    55  func NewDecapsulationKey768(seed []byte) (*DecapsulationKey768, error) {
    56  	key, err := mlkem.NewDecapsulationKey768(seed)
    57  	if err != nil {
    58  		return nil, err
    59  	}
    60  
    61  	return &DecapsulationKey768{key}, nil
    62  }
    63  
    64  // Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
    65  //
    66  // The decapsulation key must be kept secret.
    67  func (dk *DecapsulationKey768) Bytes() []byte {
    68  	return dk.key.Bytes()
    69  }
    70  
    71  // Decapsulate generates a shared key from a ciphertext and a decapsulation
    72  // key. If the ciphertext is not valid, Decapsulate returns an error.
    73  //
    74  // The shared key must be kept secret.
    75  func (dk *DecapsulationKey768) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) {
    76  	return dk.key.Decapsulate(ciphertext)
    77  }
    78  
    79  // EncapsulationKey returns the public encapsulation key necessary to produce
    80  // ciphertexts.
    81  func (dk *DecapsulationKey768) EncapsulationKey() *EncapsulationKey768 {
    82  	return &EncapsulationKey768{dk.key.EncapsulationKey()}
    83  }
    84  
    85  // An EncapsulationKey768 is the public key used to produce ciphertexts to be
    86  // decapsulated by the corresponding DecapsulationKey768.
    87  type EncapsulationKey768 struct {
    88  	key *mlkem.EncapsulationKey768
    89  }
    90  
    91  // NewEncapsulationKey768 parses an encapsulation key from its encoded form. If
    92  // the encapsulation key is not valid, NewEncapsulationKey768 returns an error.
    93  func NewEncapsulationKey768(encapsulationKey []byte) (*EncapsulationKey768, error) {
    94  	key, err := mlkem.NewEncapsulationKey768(encapsulationKey)
    95  	if err != nil {
    96  		return nil, err
    97  	}
    98  
    99  	return &EncapsulationKey768{key}, nil
   100  }
   101  
   102  // Bytes returns the encapsulation key as a byte slice.
   103  func (ek *EncapsulationKey768) Bytes() []byte {
   104  	return ek.key.Bytes()
   105  }
   106  
   107  // Encapsulate generates a shared key and an associated ciphertext from an
   108  // encapsulation key, drawing random bytes from the default crypto/rand source.
   109  //
   110  // The shared key must be kept secret.
   111  func (ek *EncapsulationKey768) Encapsulate() (sharedKey, ciphertext []byte) {
   112  	return ek.key.Encapsulate()
   113  }
   114  
   115  // DecapsulationKey1024 is the secret key used to decapsulate a shared key
   116  // from a ciphertext. It includes various precomputed values.
   117  type DecapsulationKey1024 struct {
   118  	key *mlkem.DecapsulationKey1024
   119  }
   120  
   121  // GenerateKey1024 generates a new decapsulation key, drawing random bytes from
   122  // the default crypto/rand source. The decapsulation key must be kept secret.
   123  func GenerateKey1024() (*DecapsulationKey1024, error) {
   124  	key, err := mlkem.GenerateKey1024()
   125  	if err != nil {
   126  		return nil, err
   127  	}
   128  
   129  	return &DecapsulationKey1024{key}, nil
   130  }
   131  
   132  // NewDecapsulationKey1024 expands a decapsulation key from a 64-byte seed in the
   133  // "d || z" form. The seed must be uniformly random.
   134  func NewDecapsulationKey1024(seed []byte) (*DecapsulationKey1024, error) {
   135  	key, err := mlkem.NewDecapsulationKey1024(seed)
   136  	if err != nil {
   137  		return nil, err
   138  	}
   139  
   140  	return &DecapsulationKey1024{key}, nil
   141  }
   142  
   143  // Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
   144  //
   145  // The decapsulation key must be kept secret.
   146  func (dk *DecapsulationKey1024) Bytes() []byte {
   147  	return dk.key.Bytes()
   148  }
   149  
   150  // Decapsulate generates a shared key from a ciphertext and a decapsulation
   151  // key. If the ciphertext is not valid, Decapsulate returns an error.
   152  //
   153  // The shared key must be kept secret.
   154  func (dk *DecapsulationKey1024) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) {
   155  	return dk.key.Decapsulate(ciphertext)
   156  }
   157  
   158  // EncapsulationKey returns the public encapsulation key necessary to produce
   159  // ciphertexts.
   160  func (dk *DecapsulationKey1024) EncapsulationKey() *EncapsulationKey1024 {
   161  	return &EncapsulationKey1024{dk.key.EncapsulationKey()}
   162  }
   163  
   164  // An EncapsulationKey1024 is the public key used to produce ciphertexts to be
   165  // decapsulated by the corresponding DecapsulationKey1024.
   166  type EncapsulationKey1024 struct {
   167  	key *mlkem.EncapsulationKey1024
   168  }
   169  
   170  // NewEncapsulationKey1024 parses an encapsulation key from its encoded form. If
   171  // the encapsulation key is not valid, NewEncapsulationKey1024 returns an error.
   172  func NewEncapsulationKey1024(encapsulationKey []byte) (*EncapsulationKey1024, error) {
   173  	key, err := mlkem.NewEncapsulationKey1024(encapsulationKey)
   174  	if err != nil {
   175  		return nil, err
   176  	}
   177  
   178  	return &EncapsulationKey1024{key}, nil
   179  }
   180  
   181  // Bytes returns the encapsulation key as a byte slice.
   182  func (ek *EncapsulationKey1024) Bytes() []byte {
   183  	return ek.key.Bytes()
   184  }
   185  
   186  // Encapsulate generates a shared key and an associated ciphertext from an
   187  // encapsulation key, drawing random bytes from the default crypto/rand source.
   188  //
   189  // The shared key must be kept secret.
   190  func (ek *EncapsulationKey1024) Encapsulate() (sharedKey, ciphertext []byte) {
   191  	return ek.key.Encapsulate()
   192  }
   193
View as plain text