From 477622e7a1fee6b05bda43c3c2895d4f0b633da6 Mon Sep 17 00:00:00 2001 From: Ameer Ghani Date: Tue, 10 Nov 2026 21:51:27 -0600 Subject: [PATCH 1/2] ML-DSA support --- acme/api/internal/secure/signer.go | 2 + acme/api/internal/secure/signer_mldsa.go | 28 +++++ acme/api/internal/secure/signer_mldsa_test.go | 22 ++++ acme/api/internal/secure/signer_no_mldsa.go | 14 +++ certcrypto/crypto.go | 19 ++- certcrypto/keytypes.go | 11 +- certcrypto/mldsa.go | 68 +++++++++++ certcrypto/mldsa_test.go | 108 ++++++++++++++++++ certcrypto/no_mldsa.go | 24 ++++ docs/data/zz_cli_help.toml | 10 +- 10 files changed, 295 insertions(+), 11 deletions(-) create mode 100644 acme/api/internal/secure/signer_mldsa.go create mode 100644 acme/api/internal/secure/signer_mldsa_test.go create mode 100644 acme/api/internal/secure/signer_no_mldsa.go create mode 100644 certcrypto/mldsa.go create mode 100644 certcrypto/mldsa_test.go create mode 100644 certcrypto/no_mldsa.go diff --git a/acme/api/internal/secure/signer.go b/acme/api/internal/secure/signer.go index 6aa75cbc5bf..7f7a222aee1 100644 --- a/acme/api/internal/secure/signer.go +++ b/acme/api/internal/secure/signer.go @@ -160,6 +160,8 @@ func signatureAlgorithm(privKey crypto.Signer) jose.SignatureAlgorithm { } else if k.Curve == elliptic.P384() { alg = jose.ES384 } + default: + alg = mldsaSignatureAlgorithm(k) } return alg diff --git a/acme/api/internal/secure/signer_mldsa.go b/acme/api/internal/secure/signer_mldsa.go new file mode 100644 index 00000000000..00868718ac1 --- /dev/null +++ b/acme/api/internal/secure/signer_mldsa.go @@ -0,0 +1,28 @@ +//go:build go1.27 + +package secure + +import ( + "crypto" + "crypto/mldsa" + + "github.com/go-jose/go-jose/v4" +) + +func mldsaSignatureAlgorithm(pubKey crypto.PublicKey) jose.SignatureAlgorithm { + k, ok := pubKey.(*mldsa.PublicKey) + if !ok { + return "" + } + + switch k.Parameters() { + case mldsa.MLDSA44(): + return jose.MLDSA44 + case mldsa.MLDSA65(): + return jose.MLDSA65 + case mldsa.MLDSA87(): + return jose.MLDSA87 + } + + return "" +} diff --git a/acme/api/internal/secure/signer_mldsa_test.go b/acme/api/internal/secure/signer_mldsa_test.go new file mode 100644 index 00000000000..7c09fea4494 --- /dev/null +++ b/acme/api/internal/secure/signer_mldsa_test.go @@ -0,0 +1,22 @@ +//go:build go1.27 + +package secure + +import ( + "crypto/mldsa" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestSigner_SignContent_mldsa(t *testing.T) { + privKey, err := mldsa.GenerateKey(mldsa.MLDSA44()) + require.NoError(t, err) + + signer := NewSigner(privKey, "https://foo.example/kid") + + content, err := signer.SignContent(&MockNonceSource{}, "https://foo.example", []byte("{}")) + require.NoError(t, err) + + check(t, content) +} diff --git a/acme/api/internal/secure/signer_no_mldsa.go b/acme/api/internal/secure/signer_no_mldsa.go new file mode 100644 index 00000000000..208074c4ca1 --- /dev/null +++ b/acme/api/internal/secure/signer_no_mldsa.go @@ -0,0 +1,14 @@ +//go:build !go1.27 + +package secure + +import ( + "crypto" + + "github.com/go-jose/go-jose/v4" +) + +// ML-DSA requires Go 1.27 or later. +func mldsaSignatureAlgorithm(_ crypto.PublicKey) jose.SignatureAlgorithm { + return "" +} diff --git a/certcrypto/crypto.go b/certcrypto/crypto.go index 96c99aefbac..4f64fdfd572 100644 --- a/certcrypto/crypto.go +++ b/certcrypto/crypto.go @@ -99,6 +99,10 @@ func ParsePEMPrivateKey(key []byte) (crypto.Signer, error) { case ed25519.PrivateKey: return key, nil default: + if signer, ok := key.(crypto.Signer); ok && isMLDSAPrivateKey(key) { + return signer, nil + } + return nil, fmt.Errorf("found unknown private key type in PKCS#8 wrapping: %T", key) } } @@ -126,7 +130,7 @@ func GeneratePrivateKey(keyType KeyType) (crypto.Signer, error) { return rsa.GenerateKey(rand.Reader, 8192) } - return nil, fmt.Errorf("invalid KeyType: %s", keyType) + return generateMLDSAKey(keyType) } type CSROptions struct { @@ -176,17 +180,26 @@ func PEMBlock(data any) *pem.Block { switch key := data.(type) { case *ecdsa.PrivateKey, *rsa.PrivateKey: - keyBytes, _ := x509.MarshalPKCS8PrivateKey(key) - pemBlock = &pem.Block{Type: "PRIVATE KEY", Bytes: keyBytes} + pemBlock = pkcs8PEMBlock(key) case *x509.CertificateRequest: pemBlock = &pem.Block{Type: "CERTIFICATE REQUEST", Bytes: key.Raw} case DERCertificateBytes: pemBlock = &pem.Block{Type: "CERTIFICATE", Bytes: []byte(data.(DERCertificateBytes))} + default: + if isMLDSAPrivateKey(key) { + pemBlock = pkcs8PEMBlock(key) + } } return pemBlock } +func pkcs8PEMBlock(key any) *pem.Block { + keyBytes, _ := x509.MarshalPKCS8PrivateKey(key) + + return &pem.Block{Type: "PRIVATE KEY", Bytes: keyBytes} +} + func pemDecode(data []byte) (*pem.Block, error) { pemBlock, _ := pem.Decode(data) if pemBlock == nil { diff --git a/certcrypto/keytypes.go b/certcrypto/keytypes.go index e5b4331a225..bcb2d387053 100644 --- a/certcrypto/keytypes.go +++ b/certcrypto/keytypes.go @@ -46,14 +46,19 @@ func ToKeyType(keyType string) (KeyType, error) { return EC384, nil } + kt := KeyType(strings.ToUpper(keyType)) + if slices.Contains(mldsaKeyTypes(), kt) { + return kt, nil + } + return "", fmt.Errorf("unsupported key type: %s", keyType) } func AllKeyTypes() []KeyType { - return []KeyType{ + return append([]KeyType{ EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192, - } + }, mldsaKeyTypes()...) } // IsSupported checks if the key type is supported. @@ -92,7 +97,7 @@ func GetKeyType(key any) (KeyType, error) { return getECDSAKeyType(k.Curve) default: - return "", fmt.Errorf("unsupported key type: %T", k) + return getMLDSAKeyType(k) } } diff --git a/certcrypto/mldsa.go b/certcrypto/mldsa.go new file mode 100644 index 00000000000..38ff2014e07 --- /dev/null +++ b/certcrypto/mldsa.go @@ -0,0 +1,68 @@ +//go:build go1.27 + +package certcrypto + +import ( + "crypto" + "crypto/mldsa" + "fmt" +) + +const ( + MLDSA44 = KeyType("MLDSA44") + MLDSA65 = KeyType("MLDSA65") + MLDSA87 = KeyType("MLDSA87") +) + +// mldsaKeyTypes returns the ML-DSA key types supported by this build. +func mldsaKeyTypes() []KeyType { + return []KeyType{MLDSA44, MLDSA65, MLDSA87} +} + +// generateMLDSAKey generates an ML-DSA private key. It returns an error if +// keyType is not an ML-DSA key type. +func generateMLDSAKey(keyType KeyType) (crypto.Signer, error) { + switch keyType { + case MLDSA44: + return mldsa.GenerateKey(mldsa.MLDSA44()) + case MLDSA65: + return mldsa.GenerateKey(mldsa.MLDSA65()) + case MLDSA87: + return mldsa.GenerateKey(mldsa.MLDSA87()) + } + + return nil, fmt.Errorf("invalid KeyType: %s", keyType) +} + +// isMLDSAPrivateKey reports whether key is an ML-DSA private key. +func isMLDSAPrivateKey(key any) bool { + _, ok := key.(*mldsa.PrivateKey) + + return ok +} + +// getMLDSAKeyType gets the key type of an ML-DSA key. +// It returns an error if key is not an ML-DSA key. +func getMLDSAKeyType(key any) (KeyType, error) { + var params mldsa.Parameters + + switch k := key.(type) { + case *mldsa.PublicKey: + params = k.Parameters() + case *mldsa.PrivateKey: + params = k.PublicKey().Parameters() + default: + return "", fmt.Errorf("unsupported key type: %T", key) + } + + switch params { + case mldsa.MLDSA44(): + return MLDSA44, nil + case mldsa.MLDSA65(): + return MLDSA65, nil + case mldsa.MLDSA87(): + return MLDSA87, nil + default: + return "", fmt.Errorf("unsupported ML-DSA parameters: %s", params) + } +} diff --git a/certcrypto/mldsa_test.go b/certcrypto/mldsa_test.go new file mode 100644 index 00000000000..1bb1ca480b2 --- /dev/null +++ b/certcrypto/mldsa_test.go @@ -0,0 +1,108 @@ +//go:build go1.27 + +package certcrypto + +import ( + "crypto/mldsa" + "crypto/x509" + "encoding/pem" + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestGeneratePrivateKey_mldsa(t *testing.T) { + testCases := []struct { + keyType KeyType + expected mldsa.Parameters + }{ + {keyType: MLDSA44, expected: mldsa.MLDSA44()}, + {keyType: MLDSA65, expected: mldsa.MLDSA65()}, + {keyType: MLDSA87, expected: mldsa.MLDSA87()}, + } + + for _, test := range testCases { + t.Run(test.keyType.String(), func(t *testing.T) { + t.Parallel() + + key, err := GeneratePrivateKey(test.keyType) + require.NoError(t, err) + + require.IsType(t, &mldsa.PrivateKey{}, key) + assert.Equal(t, test.expected, key.(*mldsa.PrivateKey).PublicKey().Parameters()) + + keyType, err := GetPrivateKeyType(key) + require.NoError(t, err) + + assert.Equal(t, test.keyType, keyType) + + keyType, err = GetKeyType(key) + require.NoError(t, err) + + assert.Equal(t, test.keyType, keyType) + }) + } +} + +func TestPEMEncode_mldsa(t *testing.T) { + for _, keyType := range []KeyType{MLDSA44, MLDSA65, MLDSA87} { + t.Run(keyType.String(), func(t *testing.T) { + t.Parallel() + + privateKey, err := GeneratePrivateKey(keyType) + require.NoError(t, err) + + data := PEMEncode(privateKey) + require.NotNil(t, data) + + p, rest := pem.Decode(data) + + assert.Equal(t, "PRIVATE KEY", p.Type) + assert.Empty(t, rest) + assert.Empty(t, p.Headers) + + decoded, err := ParsePEMPrivateKey(data) + require.NoError(t, err) + + require.IsType(t, &mldsa.PrivateKey{}, decoded) + assert.True(t, decoded.(*mldsa.PrivateKey).Equal(privateKey)) + }) + } +} + +func TestCreateCSR_mldsa(t *testing.T) { + privateKey, err := GeneratePrivateKey(MLDSA44) + require.NoError(t, err) + + der, err := CreateCSR(privateKey, CSROptions{SAN: []string{testDomain1}}) + require.NoError(t, err) + + csr, err := x509.ParseCertificateRequest(der) + require.NoError(t, err) + + require.NoError(t, csr.CheckSignature()) + + assert.Equal(t, []string{testDomain1}, csr.DNSNames) + + keyType, err := GetCSRKeyType(csr) + require.NoError(t, err) + + assert.Equal(t, MLDSA44, keyType) +} + +func TestToKeyType_mldsa(t *testing.T) { + for _, expected := range []KeyType{MLDSA44, MLDSA65, MLDSA87} { + t.Run(expected.String(), func(t *testing.T) { + t.Parallel() + + keyType, err := ToKeyType(strings.ToLower(expected.String())) + require.NoError(t, err) + + assert.Equal(t, expected, keyType) + assert.True(t, IsSupported(keyType)) + assert.Contains(t, AllKeyTypes(), keyType) + }) + } +} diff --git a/certcrypto/no_mldsa.go b/certcrypto/no_mldsa.go new file mode 100644 index 00000000000..c38c7711189 --- /dev/null +++ b/certcrypto/no_mldsa.go @@ -0,0 +1,24 @@ +//go:build !go1.27 + +package certcrypto + +import ( + "crypto" + "fmt" +) + +func mldsaKeyTypes() []KeyType { + return nil +} + +func generateMLDSAKey(keyType KeyType) (crypto.Signer, error) { + return nil, fmt.Errorf("invalid KeyType: %s", keyType) +} + +func isMLDSAPrivateKey(_ any) bool { + return false +} + +func getMLDSAKeyType(key any) (KeyType, error) { + return "", fmt.Errorf("unsupported key type: %T", key) +} diff --git a/docs/data/zz_cli_help.toml b/docs/data/zz_cli_help.toml index 189cdca7211..17ffe5863d0 100644 --- a/docs/data/zz_cli_help.toml +++ b/docs/data/zz_cli_help.toml @@ -55,7 +55,7 @@ lego run [options] | `--domains string`, `-d string` | `LEGO_DOMAINS` | Add a domain. For multiple values either repeat the flag or provide a comma-separated list. | | `--email string`, `-m string` | `LEGO_EMAIL` | Email used for registration and recovery contact. | | `--help`, `-h` | | show help | -| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for private keys. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192.
(Default: "EC256") | +| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for private keys. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192, MLDSA44, MLDSA65, MLDSA87.
(Default: "EC256") | | `--server string`, `-s string` | `LEGO_SERVER` | CA (ACME server). It can be either a URL or a shortcode.
(available shortcodes: actalis, digicert, freessl, globalsign, googletrust, googletrust-staging, letsencrypt, letsencrypt-staging, litessl, peeringhub, sslcomecc, sslcomrsa, sectigo, sectigoev, sectigoov, zerossl)
(Default: "https://acme-v02.api.letsencrypt.org/directory") | #### Flags related to External Account Binding: @@ -202,7 +202,7 @@ lego accounts register [options] | `--accept-tos`, `-a` | `LEGO_ACCEPT_TOS` | By setting this flag to true, you indicate that you accept the current CA terms of service. | | `--email string`, `-m string` | `LEGO_EMAIL` | Email used for registration and recovery contact. | | `--help`, `-h` | | show help | -| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for the private key of the account. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192.
(Default: "EC256") | +| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for the private key of the account. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192, MLDSA44, MLDSA65, MLDSA87.
(Default: "EC256") | | `--server string`, `-s string` | `LEGO_SERVER` | CA (ACME server). It can be either a URL or a shortcode.
(available shortcodes: actalis, digicert, freessl, globalsign, googletrust, googletrust-staging, letsencrypt, letsencrypt-staging, litessl, peeringhub, sslcomecc, sslcomrsa, sectigo, sectigoev, sectigoov, zerossl)
(Default: "https://acme-v02.api.letsencrypt.org/directory") | #### Flags related to External Account Binding: @@ -264,7 +264,7 @@ lego accounts recover [options] |------|-------|-------| | `--email string`, `-m string` | `LEGO_EMAIL` | Email used for registration and recovery contact. | | `--help`, `-h` | | show help | -| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for the private key of the account. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192.
(Default: "EC256") | +| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for the private key of the account. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192, MLDSA44, MLDSA65, MLDSA87.
(Default: "EC256") | | `--private-key string` | `LEGO_PRIVATE_KEY` | Path to the account private key (PEM encoded). | | `--server string`, `-s string` | `LEGO_SERVER` | CA (ACME server). It can be either a URL or a shortcode.
(available shortcodes: actalis, digicert, freessl, globalsign, googletrust, googletrust-staging, letsencrypt, letsencrypt-staging, litessl, peeringhub, sslcomecc, sslcomrsa, sectigo, sectigoev, sectigoov, zerossl)
(Default: "https://acme-v02.api.letsencrypt.org/directory") | @@ -327,7 +327,7 @@ lego accounts keyrollover [options] |------|-------|-------| | `--email string`, `-m string` | `LEGO_EMAIL` | Email used for registration and recovery contact. | | `--help`, `-h` | | show help | -| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for the new private key of the account. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192.
(Default: "EC256") | +| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for the new private key of the account. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192, MLDSA44, MLDSA65, MLDSA87.
(Default: "EC256") | | `--private-key string` | `LEGO_PRIVATE_KEY` | Path to the new account private key (PEM encoded). If not specified, the private key will be generated. | | `--server string`, `-s string` | `LEGO_SERVER` | CA (ACME server). It can be either a URL or a shortcode.
(available shortcodes: actalis, digicert, freessl, globalsign, googletrust, googletrust-staging, letsencrypt, letsencrypt-staging, litessl, peeringhub, sslcomecc, sslcomrsa, sectigo, sectigoev, sectigoov, zerossl)
(Default: "https://acme-v02.api.letsencrypt.org/directory") | @@ -433,7 +433,7 @@ lego certificates revoke [options] | `--email string`, `-m string` | `LEGO_EMAIL` | Email used for registration and recovery contact. | | `--help`, `-h` | | show help | | `--keep` | `LEGO_KEEP` | Keep the certificates after the revocation instead of archiving them. | -| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for the private key of the account. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192.
(Default: "EC256") | +| `--key-type string`, `-k string` | `LEGO_KEY_TYPE` | Key type to use for the private key of the account. Supported: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192, MLDSA44, MLDSA65, MLDSA87.
(Default: "EC256") | | `--reason uint` | `LEGO_REASON` | Identifies the reason for the certificate revocation. See https://www.rfc-editor.org/rfc/rfc5280.html#section-5.3.1.
Valid values are: 0 (unspecified), 1 (keyCompromise), 2 (cACompromise), 3 (affiliationChanged), 4 (superseded), 5 (cessationOfOperation), 6 (certificateHold), 8 (removeFromCRL), 9 (privilegeWithdrawn), or 10 (aACompromise).
(Default: 0) | | `--server string`, `-s string` | `LEGO_SERVER` | CA (ACME server). It can be either a URL or a shortcode.
(available shortcodes: actalis, digicert, freessl, globalsign, googletrust, googletrust-staging, letsencrypt, letsencrypt-staging, litessl, peeringhub, sslcomecc, sslcomrsa, sectigo, sectigoev, sectigoov, zerossl)
(Default: "https://acme-v02.api.letsencrypt.org/directory") | From 62bffee7d9e366d29296928743323f674e2afdb3 Mon Sep 17 00:00:00 2001 From: Ameer Ghani Date: Tue, 10 Nov 2026 21:55:42 -0600 Subject: [PATCH 2/2] Add ML-DSA E2E test --- e2e/mldsa_test.go | 51 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 e2e/mldsa_test.go diff --git a/e2e/mldsa_test.go b/e2e/mldsa_test.go new file mode 100644 index 00000000000..d88ee61f5d4 --- /dev/null +++ b/e2e/mldsa_test.go @@ -0,0 +1,51 @@ +//go:build go1.27 + +package e2e + +import ( + "os" + "path/filepath" + "testing" + + "github.com/go-acme/lego/v5/certcrypto" + "github.com/go-acme/lego/v5/e2e/loader" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestMLDSA_Run(t *testing.T) { + testCases := []certcrypto.KeyType{ + certcrypto.MLDSA44, + certcrypto.MLDSA65, + certcrypto.MLDSA87, + } + + for _, keyType := range testCases { + t.Run(keyType.String(), func(t *testing.T) { + loader.CleanLegoFiles(t.Context()) + + err := load.RunLego(t.Context(), + "run", + "-m", testEmail1, + "--accept-tos", + "-s", caDirectory, + "-d", testDomain1, + "--key-type", keyType.String(), + "--http", + "--http.address", ":5002", + ) + require.NoError(t, err) + + data, err := os.ReadFile(filepath.FromSlash(".lego/certificates/" + testDomain1 + ".crt")) + require.NoError(t, err) + + cert, err := certcrypto.ParsePEMCertificate(data) + require.NoError(t, err) + + certKeyType, err := certcrypto.GetCertificateKeyType(cert) + require.NoError(t, err) + + assert.Equal(t, keyType, certKeyType) + }) + } +}