Documentation
¶
Overview ¶
Package mldsa implements the quantum-resistant digital signature algorithm ML-DSA (Module-Lattice-Based Digital Signature Standard) as specified in NIST FIPS 204.
This implementations referenced OpenSSL's implementation of ML-DSA and part of Golang ML-KEM [OpenSSL ML-DSA]: https://github.com/openssl/openssl/blob/master/crypto/ml_dsa [Golang ML-KEM]: https://github.com/golang/go/blob/master/src/crypto/internal/fips140/mlkem
Index ¶
Constants ¶
const ( PublicKeySize44 = 32 + 32*k44*10 PrivateKeySize44 = 32 + 32 + 64 + 32*((k44+l44)*bitLenOfETA2+d*k44) )
ML-DSA-44 parameters.
const ( PublicKeySize65 = 32 + 32*k65*10 PrivateKeySize65 = 32 + 32 + 64 + 32*((k65+l65)*bitLenOfETA4+d*k65) )
ML-DSA-65 parameters.
const ( PublicKeySize87 = 32 + 32*k87*10 PrivateKeySize87 = 32 + 32 + 64 + 32*((k87+l87)*bitLenOfETA2+d*k87) )
ML-DSA-87 parameters.
const (
SeedSize = 32
)
Variables ¶
var ( // Digest Algorithms OIDDigestAlgorithmSHA256 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 1} OIDDigestAlgorithmSHA512 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 3} OIDDigestAlgorithmSHA3_256 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 8} OIDDigestAlgorithmSHA3_384 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 9} OIDDigestAlgorithmSHA3_512 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 10} OIDDigestAlgorithmSHAKE128 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 11} OIDDigestAlgorithmSHAKE256 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 12} OIDDigestAlgorithmSM3 = asn1.ObjectIdentifier{1, 2, 156, 10197, 1, 401} )
var ErrUnsupportedDigestAlgorithm = errors.New("mldsa: unsupported digest algorithm")
Functions ¶
This section is empty.
Types ¶
type Key44 ¶
type Key44 struct {
PrivateKey44
// contains filtered or unexported fields
}
A Key44 is the key pair for the ML-DSA-44 signature scheme.
func GenerateKey44 ¶
GenerateKey44 generates a new Key44 (ML-DSA-44) using the provided random source.
func (*Key44) Bytes ¶
Bytes returns the byte representation of the PrivateKey44. It copies the internal seed (xi) into a fixed-size byte array and returns it as a slice.
func (*Key44) PublicKey ¶
func (sk *Key44) PublicKey() *PublicKey44
PublicKey generates and returns the corresponding public key for the given Key44 instance.
type Key65 ¶
type Key65 struct {
PrivateKey65
// contains filtered or unexported fields
}
A Key65 is the key pair for the ML-DSA-65 signature scheme.
func GenerateKey65 ¶
GenerateKey65 generates a new Key65 (ML-DSA-65) using the provided random source.
func (*Key65) Bytes ¶
Bytes returns the byte representation of the PrivateKey65. It copies the internal seed (xi) into a fixed-size byte array and returns it as a slice.
func (*Key65) PublicKey ¶
func (sk *Key65) PublicKey() *PublicKey65
PublicKey generates and returns the corresponding public key for the given Key65 instance.
type Key87 ¶
type Key87 struct {
PrivateKey87
// contains filtered or unexported fields
}
A Key87 is the key pair for the ML-DSA-87 signature scheme.
func GenerateKey87 ¶
GenerateKey87 generates a new Key87 (ML-DSA-87) using the provided random source.
func (*Key87) Bytes ¶
Bytes returns the byte representation of the PrivateKey87. It copies the internal seed (xi) into a fixed-size byte array and returns it as a slice.
func (*Key87) PublicKey ¶
func (sk *Key87) PublicKey() *PublicKey87
PublicKey generates and returns the corresponding public key for the given Key87 instance.
type PrivateKey44 ¶
type PrivateKey44 struct {
// contains filtered or unexported fields
}
A PrivateKey44 is the private key for the ML-DSA-44 signature scheme.
func NewPrivateKey44 ¶
func NewPrivateKey44(b []byte) (*PrivateKey44, error)
NewPrivateKey44 decode an private key from its encoded form. See FIPS 204, Algorithm 25 skDecode()
func (*PrivateKey44) Bytes ¶
func (sk *PrivateKey44) Bytes() []byte
Bytes converts the PrivateKey44 instance into a byte slice. See FIPS 204, Algorithm 24, skEncode()
func (*PrivateKey44) Equal ¶
func (sk *PrivateKey44) Equal(x any) bool
func (*PrivateKey44) Sign ¶
Sign generates a digital signature for the given message and context using the private key. It uses a random seed generated from the provided random source.
Parameters:
- rand: An io.Reader used to generate a random seed for signing.
- message: The message to be signed. Must not be empty.
- context: An optional context for domain separation. Must not exceed 255 bytes.
Returns:
- A byte slice containing the generated signature.
- An error if the message is empty, the context is too long, or if there is an issue reading from the random source.
Note:
- The function uses SHAKE256 from the SHA-3 family for hashing.
- The signing process involves generating a unique seed and a hash-based message digest (mu) before delegating to the internal signing function.
func (*PrivateKey44) SignWithPreHash ¶
func (sk *PrivateKey44) SignWithPreHash(rand io.Reader, message, context []byte, oid asn1.ObjectIdentifier) ([]byte, error)
SignWithPreHash generates a digital signature for the given message using the private key and additional context. It uses a given hashing algorithm from the OID to pre-hash the message before signing. It is similar to Sign but allows for pre-hashing the message.
type PrivateKey65 ¶
type PrivateKey65 struct {
// contains filtered or unexported fields
}
A PrivateKey65 is the private key for the ML-DSA-65 signature scheme.
func NewPrivateKey65 ¶
func NewPrivateKey65(b []byte) (*PrivateKey65, error)
NewPrivateKey65 decode an private key from its encoded form. See FIPS 204, Algorithm 25 skDecode()
func (*PrivateKey65) Bytes ¶
func (sk *PrivateKey65) Bytes() []byte
Bytes converts the PrivateKey65 instance into a byte slice. See FIPS 204, Algorithm 24, skEncode()
func (*PrivateKey65) Equal ¶
func (sk *PrivateKey65) Equal(x any) bool
func (*PrivateKey65) Sign ¶
Sign generates a digital signature for the given message and context using the private key. It uses a random seed generated from the provided random source.
Parameters:
- rand: An io.Reader used to generate a random seed for signing.
- message: The message to be signed. Must not be empty.
- context: An optional context for domain separation. Must not exceed 255 bytes.
Returns:
- A byte slice containing the generated signature.
- An error if the message is empty, the context is too long, or if there is an issue reading from the random source.
Note:
- The function uses SHAKE256 from the SHA-3 family for hashing.
- The signing process involves generating a unique seed and a hash-based message digest (mu) before delegating to the internal signing function.
func (*PrivateKey65) SignWithPreHash ¶
func (sk *PrivateKey65) SignWithPreHash(rand io.Reader, message, context []byte, oid asn1.ObjectIdentifier) ([]byte, error)
SignWithPreHash generates a digital signature for the given message using the private key and additional context. It uses a given hashing algorithm from the OID to pre-hash the message before signing. It is similar to Sign but allows for pre-hashing the message.
type PrivateKey87 ¶
type PrivateKey87 struct {
// contains filtered or unexported fields
}
A PrivateKey87 is the private key for the ML-DSA-87 signature scheme.
func NewPrivateKey87 ¶
func NewPrivateKey87(b []byte) (*PrivateKey87, error)
NewPrivateKey87 decode an private key from its encoded form. See FIPS 204, Algorithm 25 skDecode()
func (*PrivateKey87) Bytes ¶
func (sk *PrivateKey87) Bytes() []byte
Bytes converts the PrivateKey87 instance into a byte slice. See FIPS 204, Algorithm 24, skEncode()
func (*PrivateKey87) Equal ¶
func (sk *PrivateKey87) Equal(x any) bool
func (*PrivateKey87) Sign ¶
Sign generates a digital signature for the given message and context using the private key. It uses a random seed generated from the provided random source.
Parameters:
- rand: An io.Reader used to generate a random seed for signing.
- message: The message to be signed. Must not be empty.
- context: An optional context for domain separation. Must not exceed 255 bytes.
Returns:
- A byte slice containing the generated signature.
- An error if the message is empty, the context is too long, or if there is an issue reading from the random source.
Note:
- The function uses SHAKE256 from the SHA-3 family for hashing.
- The signing process involves generating a unique seed and a hash-based message digest (mu) before delegating to the internal signing function.
func (*PrivateKey87) SignWithPreHash ¶
func (sk *PrivateKey87) SignWithPreHash(rand io.Reader, message, context []byte, oid asn1.ObjectIdentifier) ([]byte, error)
SignWithPreHash generates a digital signature for the given message using the private key and additional context. It uses a given hashing algorithm from the OID to pre-hash the message before signing. It is similar to Sign but allows for pre-hashing the message.
type PublicKey44 ¶
type PublicKey44 struct {
// contains filtered or unexported fields
}
A PublicKey44 is the public key for the ML-DSA-44 signature scheme.
func NewPublicKey44 ¶
func NewPublicKey44(b []byte) (*PublicKey44, error)
NewPublicKey44 decode an public key from its encoded form. See FIPS 204, Algorithm 23 pkDecode()
func (*PublicKey44) Bytes ¶
func (pk *PublicKey44) Bytes() []byte
Bytes converts the PublicKey44 instance into a byte slice. See FIPS 204, Algorithm 22, pkEncode()
func (*PublicKey44) Verify ¶
func (pk *PublicKey44) Verify(sig []byte, message, context []byte) bool
Verify checks the validity of a given signature for a message and context using the public key.
func (*PublicKey44) VerifyWithPreHash ¶
func (pk *PublicKey44) VerifyWithPreHash(sig []byte, message, context []byte, oid asn1.ObjectIdentifier) bool
VerifyWithPreHash verifies a signature using a message and additional context. It uses a given hashing algorithm from the OID to pre-hash the message before verifying.
type PublicKey65 ¶
type PublicKey65 struct {
// contains filtered or unexported fields
}
A PublicKey65 is the public key for the ML-DSA-65 signature scheme.
func NewPublicKey65 ¶
func NewPublicKey65(b []byte) (*PublicKey65, error)
NewPublicKey65 decode an public key from its encoded form. See FIPS 204, Algorithm 23 pkDecode()
func (*PublicKey65) Bytes ¶
func (pk *PublicKey65) Bytes() []byte
Bytes converts the PublicKey65 instance into a byte slice. See FIPS 204, Algorithm 22, pkEncode()
func (*PublicKey65) Verify ¶
func (pk *PublicKey65) Verify(sig []byte, message, context []byte) bool
Verify checks the validity of a given signature for a message and context using the public key.
func (*PublicKey65) VerifyWithPreHash ¶
func (pk *PublicKey65) VerifyWithPreHash(sig []byte, message, context []byte, oid asn1.ObjectIdentifier) bool
VerifyWithPreHash verifies a signature using a message and additional context. It uses a given hashing algorithm from the OID to pre-hash the message before verifying.
type PublicKey87 ¶
type PublicKey87 struct {
// contains filtered or unexported fields
}
A PublicKey87 is the public key for the ML-DSA-87 signature scheme.
func NewPublicKey87 ¶
func NewPublicKey87(b []byte) (*PublicKey87, error)
NewPublicKey87 decode an public key from its encoded form. See FIPS 204, Algorithm 23 pkDecode()
func (*PublicKey87) Bytes ¶
func (pk *PublicKey87) Bytes() []byte
Bytes converts the PublicKey87 instance into a byte slice. See FIPS 204, Algorithm 22, pkEncode()
func (*PublicKey87) Verify ¶
func (pk *PublicKey87) Verify(sig []byte, message, context []byte) bool
Verify checks the validity of a given signature for a message and context using the public key.
func (*PublicKey87) VerifyWithPreHash ¶
func (pk *PublicKey87) VerifyWithPreHash(sig []byte, message, context []byte, oid asn1.ObjectIdentifier) bool
VerifyWithPreHash verifies a signature using a message and additional context. It uses a given hashing algorithm from the OID to pre-hash the message before verifying.
Source Files