mldsa_fips140v1.26.go

     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  	"crypto/internal/fips140/mldsa"
    12  	"errors"
    13  	"io"
    14  )
    15  
    16  // PrivateKey is an in-memory ML-DSA private key. It implements [crypto.Signer]
    17  // and the informal extended [crypto.PrivateKey] interface.
    18  //
    19  // A PrivateKey is safe for concurrent use.
    20  type PrivateKey struct {
    21  	k mldsa.PrivateKey
    22  }
    23  
    24  var errInvalidParameters = errors.New("mldsa: invalid parameters")
    25  
    26  // GenerateKey generates a new random ML-DSA private key.
    27  func GenerateKey(params Parameters) (*PrivateKey, error) {
    28  	switch params {
    29  	case MLDSA44():
    30  		return &PrivateKey{k: *mldsa.GenerateKey44()}, nil
    31  	case MLDSA65():
    32  		return &PrivateKey{k: *mldsa.GenerateKey65()}, nil
    33  	case MLDSA87():
    34  		return &PrivateKey{k: *mldsa.GenerateKey87()}, nil
    35  	default:
    36  		return nil, errInvalidParameters
    37  	}
    38  }
    39  
    40  // NewPrivateKey decodes an ML-DSA private key from the given seed.
    41  //
    42  // The seed must be exactly [PrivateKeySize] bytes long.
    43  func NewPrivateKey(params Parameters, seed []byte) (*PrivateKey, error) {
    44  	var err error
    45  	var k *mldsa.PrivateKey
    46  	switch params {
    47  	case MLDSA44():
    48  		k, err = mldsa.NewPrivateKey44(seed)
    49  	case MLDSA65():
    50  		k, err = mldsa.NewPrivateKey65(seed)
    51  	case MLDSA87():
    52  		k, err = mldsa.NewPrivateKey87(seed)
    53  	default:
    54  		return nil, errInvalidParameters
    55  	}
    56  	if err != nil {
    57  		return nil, err
    58  	}
    59  	return &PrivateKey{k: *k}, nil
    60  }
    61  
    62  // Public returns the corresponding [PublicKey] for this private key.
    63  //
    64  // It implements the [crypto.Signer] interface.
    65  func (sk *PrivateKey) Public() crypto.PublicKey {
    66  	return sk.PublicKey()
    67  }
    68  
    69  // Equal reports whether sk and x are the same key (i.e. they are derived from
    70  // the same seed).
    71  //
    72  // If x is not a *PrivateKey, Equal returns false.
    73  func (sk *PrivateKey) Equal(x crypto.PrivateKey) bool {
    74  	other, ok := x.(*PrivateKey)
    75  	if !ok || other == nil {
    76  		return false
    77  	}
    78  	return sk.k.Equal(&other.k)
    79  }
    80  
    81  // PublicKey returns the corresponding [PublicKey] for this private key.
    82  func (sk *PrivateKey) PublicKey() *PublicKey {
    83  	// Making a copy severs the pointer relationship between the private and
    84  	// public keys, so that keeping the public key around doesn't keep the
    85  	// private key alive. This costs a copy and an allocation.
    86  	return &PublicKey{p: *sk.k.PublicKey()}
    87  }
    88  
    89  // Bytes returns the private key seed.
    90  func (sk *PrivateKey) Bytes() []byte {
    91  	return sk.k.Bytes()
    92  }
    93  
    94  var errInvalidSignerOpts = errors.New("mldsa: invalid SignerOpts")
    95  
    96  // Sign returns a signature of the given message using this private key.
    97  //
    98  // If opts is nil or opts.HashFunc returns zero, the message is signed directly.
    99  // If opts.HashFunc returns [crypto.MLDSAMu], the provided message must be a
   100  // [pre-hashed μ message representative]. opts can be of type *[Options] if a
   101  // context string is desired along with a directly-signed message. The io.Reader
   102  // argument is ignored.
   103  //
   104  // [pre-hashed μ message representative]: https://www.rfc-editor.org/rfc/rfc9881.html#externalmu
   105  func (sk *PrivateKey) Sign(_ io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error) {
   106  	if opts == nil {
   107  		opts = &Options{}
   108  	}
   109  	switch opts.HashFunc() {
   110  	case 0:
   111  		var context string
   112  		if opts, ok := opts.(*Options); ok {
   113  			context = opts.Context
   114  		}
   115  		return mldsa.Sign(&sk.k, message, context)
   116  	case crypto.MLDSAMu:
   117  		return mldsa.SignExternalMu(&sk.k, message)
   118  	default:
   119  		return nil, errInvalidSignerOpts
   120  	}
   121  }
   122  
   123  // SignDeterministic works like [PrivateKey.Sign], but the signature is
   124  // deterministic.
   125  func (sk *PrivateKey) SignDeterministic(message []byte, opts crypto.SignerOpts) (signature []byte, err error) {
   126  	if opts == nil {
   127  		opts = &Options{}
   128  	}
   129  	switch opts.HashFunc() {
   130  	case 0:
   131  		var context string
   132  		if opts, ok := opts.(*Options); ok {
   133  			context = opts.Context
   134  		}
   135  		return mldsa.SignDeterministic(&sk.k, message, context)
   136  	case crypto.MLDSAMu:
   137  		return mldsa.SignExternalMuDeterministic(&sk.k, message)
   138  	default:
   139  		return nil, errInvalidSignerOpts
   140  	}
   141  }
   142  
   143  // PublicKey is an ML-DSA public key. It implements the informal extended
   144  // [crypto.PublicKey] interface.
   145  //
   146  // A PublicKey is safe for concurrent use.
   147  type PublicKey struct {
   148  	p mldsa.PublicKey
   149  }
   150  
   151  // NewPublicKey creates a new ML-DSA public key from the given encoding.
   152  func NewPublicKey(params Parameters, encoding []byte) (*PublicKey, error) {
   153  	return newPublicKey(&PublicKey{}, params, encoding)
   154  }
   155  
   156  func newPublicKey(pub *PublicKey, params Parameters, encoding []byte) (*PublicKey, error) {
   157  	var err error
   158  	var pk *mldsa.PublicKey
   159  	switch params {
   160  	case MLDSA44():
   161  		pk, err = mldsa.NewPublicKey44(encoding)
   162  	case MLDSA65():
   163  		pk, err = mldsa.NewPublicKey65(encoding)
   164  	case MLDSA87():
   165  		pk, err = mldsa.NewPublicKey87(encoding)
   166  	default:
   167  		return nil, errInvalidParameters
   168  	}
   169  	if err != nil {
   170  		return nil, err
   171  	}
   172  	pub.p = *pk
   173  	return pub, nil
   174  }
   175  
   176  // Bytes returns the public key encoding.
   177  func (pk *PublicKey) Bytes() []byte {
   178  	return pk.p.Bytes()
   179  }
   180  
   181  // Equal reports whether pk and x are the same key (i.e. they have the same
   182  // encoding).
   183  //
   184  // If x is not a *PublicKey, Equal returns false.
   185  func (pk *PublicKey) Equal(x crypto.PublicKey) bool {
   186  	other, ok := x.(*PublicKey)
   187  	if !ok || other == nil {
   188  		return false
   189  	}
   190  	return pk.p.Equal(&other.p)
   191  }
   192  
   193  // Parameters returns the parameters associated with this public key.
   194  func (pk *PublicKey) Parameters() Parameters {
   195  	switch pk.p.Parameters() {
   196  	case "ML-DSA-44":
   197  		return MLDSA44()
   198  	case "ML-DSA-65":
   199  		return MLDSA65()
   200  	case "ML-DSA-87":
   201  		return MLDSA87()
   202  	default:
   203  		panic("mldsa: invalid parameters in public key")
   204  	}
   205  }
   206  
   207  // Verify reports whether signature is a valid signature of message by pk.
   208  // If opts is nil, it's equivalent to the zero value of Options.
   209  func Verify(pk *PublicKey, message []byte, signature []byte, opts *Options) error {
   210  	if pk == nil {
   211  		return errors.New("mldsa: nil public key")
   212  	}
   213  	if opts == nil {
   214  		opts = &Options{}
   215  	}
   216  	return mldsa.Verify(&pk.p, message, signature, opts.Context)
   217  }
   218
View as plain text