mldsa_fips140v1.0.go

Documentation: crypto/mldsa

     1  // Copyright 2026 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  //go:build fips140v1.0
     6  
     7  package mldsa
     8  
     9  import (
    10  	"crypto"
    11  	"errors"
    12  	"io"
    13  )
    14  
    15  // This file provides stub implementations of the ML-DSA API for building
    16  // against the FIPS 140-3 Go Cryptographic Module v1.0.0, which does not include
    17  // ML-DSA. Top-level functions return an error, and methods are unreachable
    18  // since there is no way to construct a valid PublicKey or PrivateKey.
    19  
    20  var errUnavailable = errors.New("mldsa: unavailable in FIPS 140-3 Go Cryptographic Module v1.0.0")
    21  
    22  // PrivateKey is an in-memory ML-DSA private key. It implements [crypto.Signer]
    23  // and the informal extended [crypto.PrivateKey] interface.
    24  //
    25  // A PrivateKey is safe for concurrent use.
    26  type PrivateKey struct{}
    27  
    28  // GenerateKey generates a new random ML-DSA private key.
    29  func GenerateKey(params Parameters) (*PrivateKey, error) {
    30  	return nil, errUnavailable
    31  }
    32  
    33  // NewPrivateKey decodes an ML-DSA private key from the given seed.
    34  //
    35  // The seed must be exactly [PrivateKeySize] bytes long.
    36  func NewPrivateKey(params Parameters, seed []byte) (*PrivateKey, error) {
    37  	return nil, errUnavailable
    38  }
    39  
    40  // Public returns the corresponding [PublicKey] for this private key.
    41  //
    42  // It implements the [crypto.Signer] interface.
    43  func (sk *PrivateKey) Public() crypto.PublicKey {
    44  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
    45  }
    46  
    47  // Equal reports whether sk and x are the same key (i.e. they are derived from
    48  // the same seed).
    49  //
    50  // If x is not a *PrivateKey, Equal returns false.
    51  func (sk *PrivateKey) Equal(x crypto.PrivateKey) bool {
    52  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
    53  }
    54  
    55  // PublicKey returns the corresponding [PublicKey] for this private key.
    56  func (sk *PrivateKey) PublicKey() *PublicKey {
    57  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
    58  }
    59  
    60  // Bytes returns the private key seed.
    61  func (sk *PrivateKey) Bytes() []byte {
    62  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
    63  }
    64  
    65  // Sign returns a signature of the given message using this private key.
    66  //
    67  // If opts is nil or opts.HashFunc returns zero, the message is signed directly.
    68  // If opts.HashFunc returns [crypto.MLDSAMu], the provided message must be a
    69  // [pre-hashed μ message representative]. opts can be of type *[Options].
    70  // The io.Reader argument is ignored.
    71  //
    72  // [pre-hashed μ message representative]: https://www.rfc-editor.org/rfc/rfc9881.html#externalmu
    73  func (sk *PrivateKey) Sign(_ io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error) {
    74  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
    75  }
    76  
    77  // SignDeterministic works like [PrivateKey.Sign], but the signature is
    78  // deterministic.
    79  func (sk *PrivateKey) SignDeterministic(message []byte, opts crypto.SignerOpts) (signature []byte, err error) {
    80  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
    81  }
    82  
    83  // PublicKey is an ML-DSA public key. It implements the informal extended
    84  // [crypto.PublicKey] interface.
    85  //
    86  // A PublicKey is safe for concurrent use.
    87  type PublicKey struct{}
    88  
    89  // NewPublicKey creates a new ML-DSA public key from the given encoding.
    90  func NewPublicKey(params Parameters, encoding []byte) (*PublicKey, error) {
    91  	return nil, errUnavailable
    92  }
    93  
    94  // Bytes returns the public key encoding.
    95  func (pk *PublicKey) Bytes() []byte {
    96  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
    97  }
    98  
    99  // Equal reports whether pk and x are the same key (i.e. they have the same
   100  // encoding).
   101  //
   102  // If x is not a *PublicKey, Equal returns false.
   103  func (pk *PublicKey) Equal(x crypto.PublicKey) bool {
   104  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
   105  }
   106  
   107  // Parameters returns the parameters associated with this public key.
   108  func (pk *PublicKey) Parameters() Parameters {
   109  	panic("mldsa: methods are unreachable in FIPS 140-3 Go Cryptographic Module v1.0.0")
   110  }
   111  
   112  // Verify reports whether signature is a valid signature of message by pk.
   113  // If opts is nil, it's equivalent to the zero value of Options.
   114  func Verify(pk *PublicKey, message []byte, signature []byte, opts *Options) error {
   115  	return errUnavailable
   116  }
   117
View as plain text