Merge pull request #466 from philljj/ml_dsa_example

pq: ML-DSA example, and reorganize examples.

Author: dgarske

.gitignore

@@ -265,6 +265,11 @@ pq/stateful_hash_sig/xmss_example.key
 pq/stateful_hash_sig/lms_example
 pq/stateful_hash_sig/lms_example.key
 
+# PQ ML-DSA
+pq/ml_dsa/ml_dsa_test
+pq/ml_dsa/*.bin
+pq/ml_dsa/*.key
+
 embedded/tls-client-server
 embedded/tls-server-size
 embedded/tls-sock-client

pq/ml_dsa/Makefile

@@ -0,0 +1,18 @@
+CC = gcc
+
+WOLFSSL_INSTALL_DIR = /usr/local
+
+WOLFSSL_CFLAGS = -Wextra -Werror -Wall -I$(WOLFSSL_INSTALL_DIR)/include
+WOLFSSL_LIBS   = -L$(WOLFSSL_INSTALL_DIR)/lib -lm -lwolfssl
+
+DEBUG_FLAGS    = -g -DDEBUG
+
+all: ml_dsa_test
+
+ml_dsa_test: ml_dsa.c
+	$(CC) -o $@ $^ $(WOLFSSL_CFLAGS) $(WOLFSSL_LIBS) $(DEBUG_FLAGS)
+
+.PHONY: clean all
+
+clean:
+	rm -f *.o wolfssl_acert ml_dsa_test

pq/ml_dsa/README.md

@@ -0,0 +1,65 @@
+# Description
+
+Simple example of wolfCrypt ML-DSA keygen, signing, and verifying.
+
+Requires wolfSSL is built with:
+
+```sh
+./configure --enable-dilithium
+make
+make install
+```
+
+Build the ML-DSA example with:
+
+```sh
+make ml_dsa_test
+```
+
+# Usage
+
+```
+./ml_dsa_test -?
+usage:
+  ./ml_dsa_test [-pvw] -c <security category> [-m <message>]
+
+parms:
+  -m <message>               the message to sign
+  -c <security category>     set the security category {2,3,5}
+  -p                         print FIPS 204 parameters and exit
+  -v                         verbose
+  -w                         write keys, msg, and sig to file
+  -?                         show this help
+```
+
+## Keygen, sign, and verify
+
+This will generate a keypair with security category 5, then
+sign and verify a test message, and write the keys, message,
+and signature to `*.key` and `*.bin` files:
+```
+./ml_dsa_test -c 5 -m "my test message" -w
+info: making key
+info: using ML-DSA-87, Security Category 5: priv_len 4896, pub_len 2592, sig_len 4627
+info: signed message
+info: verify message good
+info: done
+```
+
+## Print Supported ML-DSA Parameters
+
+To see the supported parameters:
+
+```
+./ml_dsa_test -p
+ML-DSA parameters and key/sig sizes*
+
+                Private Key   Public Key   Signature Size   Security Strength
+    ML-DSA-44      2560          1312         2420            Category 2
+    ML-DSA-65      4032          1952         3309            Category 3
+    ML-DSA-87      4896          2592         4627            Category 5
+
+
+* from Tables 1 & 2 of FIPS 204:
+    https://csrc.nist.gov/pubs/fips/204/final
+```