support for mldsa - csrs, ca signing and verifying

Author: Emma Stensland

Makefile.am

@@ -73,6 +73,7 @@ man_MANS+= manpages/wolfssl-sign_verify.1
 man_MANS+= manpages/wolfssl-ecc.1
 man_MANS+= manpages/wolfssl-ed25519.1
 man_MANS+= manpages/wolfssl-dilithium.1
+man_MANS+= manpages/wolfssl-ml-dsa.1
 man_MANS+= manpages/wolfssl-xmss.1
 man_MANS+= manpages/wolfssl-xmssmt.1
 man_MANS+= manpages/wolfssl-rand.1

README.md

@@ -154,10 +154,7 @@ uqGDApXWYuBdjheL4Ysoq6YXtt6dnm8DkBVrnt+gAMCBFbBNPXxy2MODBDqya907
 iky6IRTUzkBy1fssv3Gr/jOsyN8J565NST3RpQ==
 -----END CERTIFICATE-----
 ```
-A self-signed certificate can also be generated with a pure post-quantum
-ML-DSA (FIPS 204) key. `ml-dsa` and `dilithium` are interchangeable, and the
-level (`2`/`3`/`5`) selects ML-DSA-44/65/87. This needs wolfSSL built with
-`--enable-dilithium --enable-experimental`.
+A self-signed certificate can also be generated with post-quantum ML-DSA (FIPS 204) key. `ml-dsa` and `dilithium` are interchangeable command aliases, and the level (`2`/`3`/`5`) selects ML-DSA-44/65/87. This needs wolfSSL built with `--enable-dilithium --enable-experimental`.
 ```
 wolfssl req -x509 -newkey ml-dsa:2 -keyout ml-dsa-key -days 3650 \
     -subj /CN=wolfSSL -out ml-dsa.cert
@@ -175,7 +172,7 @@ wolfssl dgst -sha256 -verify mykey.pub -signature readme.sig ./README.md
 
 The following demonstrates how to create a root CA and use it to sign other certificates. This example uses ECC, but steps are similar for RSA.
 
-In this scenario there are three entities A, B, and C, where A is meant to function as a root CA. 
+In this scenario there are three entities A, B, and C, where A is meant to function as a root CA.
 
 The following steps demonstrate how to generate keys and certificates for A, B, and C, where A is self-signed and B and C are signed by A
 

configure.ac

@@ -135,6 +135,9 @@ AC_CHECK_FUNC([wolfSSL_X509_REQ_print],
 AC_CHECK_FUNC([wc_EncodeObjectId],
     [],
     [AM_CFLAGS="$AM_CFLAGS -DNO_WC_ENCODE_OBJECT_ID"])
+AC_CHECK_FUNC([wc_MlDsaKey_Init],
+    [AM_CFLAGS="$AM_CFLAGS -DWOLFCLU_HAVE_MLDSA -DWOLFCLU_MLDSA_CHECKED"],
+    [AM_CFLAGS="$AM_CFLAGS -DWOLFCLU_MLDSA_CHECKED"])
 
 
 ###############################################

ide/winvs/user_settings.h

@@ -56,4 +56,6 @@
 #define HAVE_OCSP
 #define HAVE_OCSP_RESPONDER
 
+#define WOLFSSL_HAVE_ERROR_QUEUE
+
 #endif /* _WIN_USER_SETTINGS_H_ */

manpages/wolfssl-ca.1

@@ -20,7 +20,15 @@ the configuration file (see -config).
 -out file             output file for the signed certificate.
 .br
 .LP
--keyfile file         private key used to sign the certificate.
+-keyfile file         private key used to sign the certificate (RSA, ECDSA, or
+.br
+                      ML-DSA). For ML-DSA, the companion public key must
+.br
+                      co-exist and is loaded automatically (e.g. <name>.pub
+.br
+                      for <name>.priv, or <stem>Pub.pem for <stem>.pem).
+.br
+                      The key may also be set via [CA_default] private_key.
 .br
 .LP
 -cert file            CA certificate to issue from.
@@ -78,6 +86,11 @@ Sign a CSR as a CA with your CA certificate and key:
 wolfssl ca -in csr.pem -out cert.pem -keyfile ca-key.pem -cert ca-cert.pem -days 365 -md sha256
 .RE
 .LP
+Sign a CSR with an ML-DSA CA key:
+.RS
+wolfssl ca -in csr.pem -out cert.pem -keyfile ca-key.priv -cert ca-cert.pem -days 365
+.RE
+.LP
 View the certificate details after signing:
 .RS
 wolfssl x509 -in cert.pem -text -noout

manpages/wolfssl-genkey.1

@@ -84,6 +84,11 @@ Generate a Dilithium key pair:
 wolfssl genkey dilithium -level 3 -out mykey -outform der -output KEYPAIR
 .br
 .LP
+Generate an ML-DSA-65 key pair (ML-DSA OIDs, not interchangeable with dilithium keys):
+.br
+wolfssl genkey ml-dsa -level 3 -out mykey -outform der -output KEYPAIR
+.br
+.LP
 Generate an XMSS key pair:
 .br
 wolfssl genkey xmss -height 10 -out mykey -outform raw -output KEYPAIR

manpages/wolfssl-ml-dsa.1

@@ -0,0 +1,5 @@
+.\" Alias page: ml-dsa sign/verify is documented in wolfssl-sign_verify(1).
+.TH wolfSSL SSL1  "June 2026" "0.2.0" "wolfssl ml-dsa man page"
+.SH NAME
+wolfssl-ml-dsa, ml-dsa \- ML-DSA raw signing and verification
+.so man1/wolfssl-sign_verify.1

manpages/wolfssl-req.1

@@ -26,9 +26,9 @@ key is written to stdout.
 .LP
 -newkey type:bits     generate the private key to use with the request.
 .br
-                      RSA: rsa:2048. Dilithium (with -x509 and certgen):
+                      RSA: rsa:2048. ML-DSA: ml-dsa:N (or dilithium:N),
 .br
-                      dilithium:2, dilithium:3, dilithium:5, or ml-dsa:N.
+                      where N is 2, 3, or 5 (requires HAVE_DILITHIUM).
 .br
                       For ECC keys, generate with ecparam first.
 .br
@@ -98,11 +98,24 @@ View a CSR in human-readable format:
 .RS
 wolfssl req -in mycsr.pem -text -noout
 .RE
+.LP
+Generate an ML-DSA-65 CSR with a new key:
+.RS
+wolfssl req -new -newkey ml-dsa:3 -keyout ml-dsa -out my.csr.pem -subj "/CN=example.com"
+.RE
+.LP
+Create a self-signed ML-DSA-44 CA certificate:
+.RS
+wolfssl req -x509 -newkey ml-dsa:2 -keyout ca-ml-dsa -out ca-ml-dsa.pem -days 3650 -subj "/CN=ML-DSA Root CA"
+.RE
 .SH SEE ALSO
 .BR wolfssl-genkey(1) ", " wolfssl-ca(1) ", " wolfssl-x509(1)
 .SH NOTES
 Available only when wolfSSL is built with certificate request support
 (WOLFSSL_CERT_REQ) and filesystem support.
+.LP
+For ML-DSA keys, -config and -extensions are ignored (only the subject DN is
+carried), and -text and -verify are not supported.
 .SH BUGS
 No known bugs at this time.
 .SH AUTHOR

manpages/wolfssl-sign_verify.1

@@ -19,7 +19,9 @@ command.
 .br
 -ed25519   Ed25519 signing and verification (requires HAVE_ED25519).
 .br
--dilithium Dilithium (ML-DSA) signing and verification (requires HAVE_DILITHIUM).
+-ml-dsa    ML-DSA (Dilithium) signing and verification (requires HAVE_DILITHIUM).
+.br
+           -dilithium is accepted as an alias for -ml-dsa.
 .br
 -xmss      XMSS signing and verification (requires WOLFSSL_HAVE_XMSS).
 .br
@@ -73,6 +75,16 @@ wolfssl -rsa -verify -inkey pub.pem -inform pem -sigfile message.sig -out verify
 Verify with an ECC public key:
 .br
 wolfssl -ecc -verify -inkey pub.pem -inform pem -sigfile message.sig -in message.txt -pubin
+.br
+.LP
+Sign a file with an ML-DSA private key:
+.br
+wolfssl -ml-dsa -sign -inkey mykey.priv -inform der -in message.bin -out message.sig
+.br
+.LP
+Verify with an ML-DSA public key:
+.br
+wolfssl -ml-dsa -verify -inkey mykey.pub -inform der -sigfile message.sig -in message.bin -pubin
 .SH NOTES
 Available only when wolfSSL is built with filesystem support. The set of
 usable key types depends on the wolfSSL configure options.

manpages/wolfssl-x509.1

@@ -98,6 +98,10 @@ Unless both -req and -signkey are used, -extfile and -extensions are
 silently ignored on output: the (re-encoded) certificate is written from
 the original input DER, not from any in-memory changes made while parsing
 extensions.
+.LP
+When -text is used on a certificate containing an ML-DSA SubjectPublicKey,
+the output shows the algorithm OID but does not decode key bytes due to
+library limitations.
 .SH EXAMPLES
 View certificate details in human-readable format:
 .RS