mldsa.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  // Package mldsa implements the post-quantum ML-DSA signature scheme specified
     6  // in [FIPS 204].
     7  //
     8  // This package is unavailable if using the [FIPS 140-3 Go Cryptographic Module]
     9  // v1.0.0, in which case [GenerateKey], [NewPrivateKey], [NewPublicKey], and
    10  // [Verify] will return an error. It is available if using v1.26.0 or later.
    11  //
    12  // [FIPS 204]: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.204.pdf
    13  // [FIPS 140-3 Go Cryptographic Module]: https://go.dev/doc/security/fips140
    14  package mldsa
    15  
    16  import "crypto"
    17  
    18  const (
    19  	PrivateKeySize = 32
    20  
    21  	MLDSA44PublicKeySize = 1312
    22  	MLDSA65PublicKeySize = 1952
    23  	MLDSA87PublicKeySize = 2592
    24  
    25  	MLDSA44SignatureSize = 2420
    26  	MLDSA65SignatureSize = 3309
    27  	MLDSA87SignatureSize = 4627
    28  )
    29  
    30  // Parameters represents one of the fixed parameter sets defined in FIPS 204.
    31  //
    32  // Most applications should use [MLDSA44].
    33  //
    34  // Multiple invocations of [MLDSA44], [MLDSA65], or [MLDSA87] will return the
    35  // same respective value, which can be used for equality checks and switch
    36  // statements. The returned value is safe for concurrent use.
    37  type Parameters struct {
    38  	name          string
    39  	publicKeySize int
    40  	signatureSize int
    41  }
    42  
    43  // MLDSA44 returns the ML-DSA-44 parameter set defined in FIPS 204.
    44  func MLDSA44() Parameters {
    45  	return Parameters{
    46  		name:          "ML-DSA-44",
    47  		publicKeySize: MLDSA44PublicKeySize,
    48  		signatureSize: MLDSA44SignatureSize,
    49  	}
    50  }
    51  
    52  // MLDSA65 returns the ML-DSA-65 parameter set defined in FIPS 204.
    53  func MLDSA65() Parameters {
    54  	return Parameters{
    55  		name:          "ML-DSA-65",
    56  		publicKeySize: MLDSA65PublicKeySize,
    57  		signatureSize: MLDSA65SignatureSize,
    58  	}
    59  }
    60  
    61  // MLDSA87 returns the ML-DSA-87 parameter set defined in FIPS 204.
    62  func MLDSA87() Parameters {
    63  	return Parameters{
    64  		name:          "ML-DSA-87",
    65  		publicKeySize: MLDSA87PublicKeySize,
    66  		signatureSize: MLDSA87SignatureSize,
    67  	}
    68  }
    69  
    70  // PublicKeySize returns the size of public keys for this parameter set, in bytes.
    71  func (params Parameters) PublicKeySize() int {
    72  	return params.publicKeySize
    73  }
    74  
    75  // SignatureSize returns the size of signatures for this parameter set, in bytes.
    76  func (params Parameters) SignatureSize() int {
    77  	return params.signatureSize
    78  }
    79  
    80  // String returns the name of the parameter set, e.g. "ML-DSA-44".
    81  func (params Parameters) String() string {
    82  	return params.name
    83  }
    84  
    85  // Options contains additional options for signing and verifying ML-DSA signatures.
    86  type Options struct {
    87  	// Context can be used to distinguish signatures created for different
    88  	// purposes. It must be at most 255 bytes long, and it is empty by default.
    89  	//
    90  	// The same context must be used when signing and verifying a signature.
    91  	Context string
    92  }
    93  
    94  // HashFunc returns zero, to implement the [crypto.SignerOpts] interface.
    95  func (opts *Options) HashFunc() crypto.Hash {
    96  	return 0
    97  }
    98
View as plain text