Add PKCS#11 provider support for ML-KEM

.gitignore

@@ -70,6 +70,7 @@ examples/x25519keygen
 examples/x448keygen
 examples/falcon512keygen
 examples/mldsa87keygen
+examples/mlkem768keygen
 examples/slhdsa256skeygen
 examples/storecert
 
@@ -98,6 +99,7 @@ tests/ed448-keygen
 tests/ed25519-keygen-prov
 tests/ed448-keygen-prov
 tests/mldsa87-keygen-prov
+tests/mlkem768-keygen-prov
 tests/check-all-prov
 
 tests/*.log

NEWS

@@ -1,6 +1,9 @@
 NEWS for Libp11 -- History of user visible changes
 
 New in 0.4.20; unreleased
+* Updated the bundled PKCS#11 header to version 3.2. (Małgorzata Olszówka)
+* Added PKCS#11 provider support for ML-KEM key generation,
+  encapsulation and decapsulation (Małgorzata Olszówka)
 
 New in 0.4.19; 2026-07-21; Michał Trojnara
 * Define LIBP11_VERSION_NUMBER (Michał Trojnara)

examples/Makefile.am

@@ -7,7 +7,8 @@ EXTRA_DIST = README
 noinst_PROGRAMS = auth decrypt getrandom listkeys listkeys_ext \
 	ed25519keygen ed448keygen eckeygen rsakeygen \
 	x25519keygen x448keygen \
-	mldsa87keygen slhdsa256skeygen falcon512keygen \
+	mldsa87keygen mlkem768keygen \
+	slhdsa256skeygen falcon512keygen \
 	storecert
 
 LDADD = ../src/libp11.la $(OPENSSL_LIBS)

examples/mlkem768keygen.c

@@ -0,0 +1,193 @@
+/*
+ * Copyright © 2026 Mobi - Com Polska Sp. z o.o.
+ * Author: Małgorzata Olszówka <Malgorzata.Olszowka@stunnel.org>
+ * All rights reserved.
+ *
+ * Module-Lattice-based KEM ML-KEM-768 key pair generation
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+#include <libp11.h>
+#include <string.h>
+
+#if !defined(OPENSSL_NO_ML_KEM) && (OPENSSL_VERSION_NUMBER >= 0x30500000L)
+
+#define EVP_PKEY_ML_KEM_768 NID_ML_KEM_768
+
+#define CHECK_ERR(cond, txt, code) \
+	do { \
+		if (cond) { \
+			fprintf(stderr, "%s\n", (txt)); \
+			rc=(code); \
+			goto end; \
+		} \
+	} while (0)
+
+static void error_queue(const char *name)
+{
+	if (ERR_peek_last_error()) {
+		fprintf(stderr, "%s generated errors:\n", name);
+		ERR_print_errors_fp(stderr);
+	}
+}
+
+static int hex_to_bytes(const char *hex, unsigned char *out, size_t out_len)
+{
+	size_t i;
+
+	for (i = 0; i < out_len; i++) {
+		if (sscanf(hex + (i * 2), "%2hhx", &out[i]) != 1) {
+			return -1;
+		}
+	}
+	return 0;
+}
+
+static void list_keys(const char *title, const PKCS11_KEY *keys,
+		const unsigned int nkeys) {
+	unsigned int i;
+
+	printf("\n%s:\n", title);
+	for (i = 0; i < nkeys; i++) {
+		printf(" #%d id=", i);
+		for (size_t j = 0; j < keys[i].id_len; j++) {
+			printf("%02x", keys[i].id[j]);
+		}
+		printf(";object=%s\n", keys[i].label);
+	}
+}
+
+int main(int argc, char *argv[])
+{
+	PKCS11_CTX *ctx = NULL;
+	PKCS11_SLOT *slots = NULL, *slot;
+	PKCS11_KEY *keys;
+	unsigned int nslots, nkeys;
+	unsigned char *key_id = NULL;
+	size_t len, key_id_len;
+	const char *key_id_str;
+	int rc = 0;
+	PKCS11_params params = {.sensitive = 1, .extractable = 0};
+	PKCS11_EDDSA_KGEN mlkem = {.nid = NID_ML_KEM_768};
+	PKCS11_KGEN_ATTRS eckg = {0};
+
+	if (argc < 6) {
+		fprintf(stderr, "usage: %s [module] [TOKEN] [KEY-LABEL] [KEY-ID] [PIN]\n", argv[0]);
+		return 1;
+	}
+	key_id_str = argv[4];
+	len = strlen(key_id_str);
+	CHECK_ERR(len % 2 != 0, "Invalid key ID format: odd length", 1);
+
+	/* key_id_str is a null-terminated string, but key_id is not */
+	key_id_len = len / 2;
+	key_id = OPENSSL_malloc(key_id_len);
+	CHECK_ERR(!key_id, "Memory allocation failed for key ID", 2);
+
+	rc = hex_to_bytes(key_id_str, key_id, key_id_len);
+	CHECK_ERR(rc != 0, "Invalid hex digit in key ID", 3);
+
+	ctx = PKCS11_CTX_new();
+	error_queue("PKCS11_CTX_new");
+
+	/* load PKCS#11 module */
+	rc = PKCS11_CTX_load(ctx, argv[1]);
+	error_queue("PKCS11_CTX_load");
+	CHECK_ERR(rc < 0, "loading PKCS#11 module failed", 4);
+
+	/* get information on all slots */
+	rc = PKCS11_enumerate_slots(ctx, &slots, &nslots);
+	error_queue("PKCS11_enumerate_slots");
+	CHECK_ERR(rc < 0, "no slots available", 5);
+
+	slot = PKCS11_find_token(ctx, slots, nslots);
+	error_queue("PKCS11_find_token");
+	while (slot) {
+		if (slot->token && slot->token->initialized && slot->token->label
+			&& strcmp(argv[2], slot->token->label) == 0)
+			break;
+		slot = PKCS11_find_next_token(ctx, slots, nslots, slot);
+	};
+	CHECK_ERR(!slot || !slot->token, "no token available", 6);
+
+	printf("Found token:\n");
+	printf("Slot manufacturer......: %s\n", slot->manufacturer);
+	printf("Slot description.......: %s\n", slot->description);
+	printf("Slot token label.......: %s\n", slot->token->label);
+	printf("Slot token serialnr....: %s\n", slot->token->serialnr);
+
+	rc = PKCS11_login(slot, 0, argv[5]);
+	error_queue("PKCS11_login");
+	CHECK_ERR(rc < 0, "PKCS11_login failed", 7);
+
+	eckg.type = EVP_PKEY_ML_KEM_768;
+	eckg.kgen.eddsa = &mlkem;
+	eckg.token_label = argv[2];
+	eckg.key_label = argv[3];
+	/* key_id is a raw binary buffer of length key_id_len */
+	eckg.key_id = (const unsigned char *)key_id;
+	eckg.id_len = key_id_len;
+	eckg.key_params = &params;
+
+	rc = PKCS11_keygen(slot->token, &eckg);
+	error_queue("PKCS11_keygen");
+	CHECK_ERR(rc < 0, "Failed to generate a key pair on the token", 8);
+
+	printf("\nML-KEM-768 keys generated\n");
+
+	/* get private keys */
+	rc = PKCS11_enumerate_keys(slot->token, &keys, &nkeys);
+	error_queue("PKCS11_enumerate_keys");
+	CHECK_ERR(rc < 0, "PKCS11_enumerate_keys failed", 9);
+	CHECK_ERR(nkeys == 0, "No private keys found", 10);
+	list_keys("Private keys", keys, nkeys);
+
+end:
+	if (slots)
+		PKCS11_release_all_slots(ctx, slots, nslots);
+	if (ctx) {
+		PKCS11_CTX_unload(ctx);
+		PKCS11_CTX_free(ctx);
+	}
+	OPENSSL_free(key_id);
+
+	if (rc)
+		printf("Failed (error code %d).\n", rc);
+	else
+		printf("Success.\n");
+	return rc;
+}
+
+#else /* !OPENSSL_NO_ML_KEM && OpenSSL 3.5 */
+
+#include <stdio.h>
+
+int main(void)
+{
+	fprintf(stderr, "Skipped: requires OpenSSL 3.5 built with ML-KEM support\n");
+	return 77;
+}
+
+#endif /* !OPENSSL_NO_ML_KEM && OpenSSL 3.5 */
+
+/* vim: set noexpandtab: */

src/libp11-int.h

@@ -52,6 +52,12 @@ extern int NID_FALCON_512;
 extern int NID_FALCON_1024;
 #endif /* OPENSSL_VERSION_NUMBER >= 0x30000000L */
 
+#if !defined(OPENSSL_NO_ML_KEM) && OPENSSL_VERSION_NUMBER >= 0x30500000L
+#define EVP_PKEY_ML_KEM_512 NID_ML_KEM_512
+#define EVP_PKEY_ML_KEM_768 NID_ML_KEM_768
+#define EVP_PKEY_ML_KEM_1024 NID_ML_KEM_1024
+#endif /* !defined(OPENSSL_NO_ML_KEM) && OPENSSL_VERSION_NUMBER >= 0x30500000L */
+
 /* forward type declarations */
 typedef struct pkcs11_keys PKCS11_keys;
 typedef struct pkcs11_object_ops PKCS11_OBJECT_ops;
@@ -65,6 +71,7 @@ typedef struct pkcs11_template_st PKCS11_TEMPLATE;
 struct pkcs11_ctx_private {
 	int flags;
 	CK_FUNCTION_LIST_PTR method;
+	CK_FUNCTION_LIST_3_2_PTR method_3_2;
 	void *handle;
 	char *init_args;
 	CK_VERSION cryptoki_version;
@@ -143,6 +150,11 @@ extern PKCS11_OBJECT_ops pkcs11_mldsa44_ops;
 extern PKCS11_OBJECT_ops pkcs11_mldsa65_ops;
 extern PKCS11_OBJECT_ops pkcs11_mldsa87_ops;
 #endif /* OPENSSL_NO_ML_DSA */
+#ifndef OPENSSL_NO_ML_KEM
+extern PKCS11_OBJECT_ops pkcs11_mlkem512_ops;
+extern PKCS11_OBJECT_ops pkcs11_mlkem768_ops;
+extern PKCS11_OBJECT_ops pkcs11_mlkem1024_ops;
+#endif /* OPENSSL_NO_ML_KEM */
 #ifndef OPENSSL_NO_SLH_DSA
 extern PKCS11_OBJECT_ops pkcs11_slhdsa_sha2_128s_ops;
 extern PKCS11_OBJECT_ops pkcs11_slhdsa_sha2_128f_ops;
@@ -177,6 +189,10 @@ extern PKCS11_OBJECT_ops pkcs11_falcon1024_ops;
 	} while (0)
 #define CRYPTOKI_call(ctx, func_and_args) \
 	ctx->method->func_and_args
+
+#define CRYPTOKI_call_3_2(ctx, func_and_args) \
+	(ctx)->method_3_2->func_and_args
+
 extern int ERR_load_CKR_strings(void);
 
 /* Memory allocation */
@@ -203,7 +219,8 @@ extern int check_slot_fork(PKCS11_SLOT_private *slot);
 extern int check_object_fork(PKCS11_OBJECT_private *key);
 
 /* Other internal functions */
-extern void *C_LoadModule(const char *name, CK_FUNCTION_LIST_PTR_PTR);
+extern void *C_LoadModule(const char *name, CK_FUNCTION_LIST_PTR_PTR,
+	CK_FUNCTION_LIST_3_2_PTR_PTR);
 extern CK_RV C_UnloadModule(void *module);
 extern void pkcs11_destroy_keys(PKCS11_SLOT_private *, unsigned int);
 extern void pkcs11_destroy_certs(PKCS11_SLOT_private *);
@@ -411,6 +428,12 @@ extern int pkcs11_mldsa_keygen(PKCS11_SLOT_private *tpriv,
 	size_t id_len, const PKCS11_params *params);
 #endif /* OPENSSL_NO_ML_DSA */
 
+#ifndef OPENSSL_NO_ML_KEM
+extern int pkcs11_mlkem_keygen(PKCS11_SLOT_private *tpriv,
+	int nid, const char *label, const unsigned char *id,
+	size_t id_len, const PKCS11_params *params);
+#endif /* OPENSSL_NO_ML_KEM */
+
 #ifndef OPENSSL_NO_SLH_DSA
 extern int pkcs11_slhdsa_keygen(PKCS11_SLOT_private *tpriv,
 	int nid, const char *label, const unsigned char *id,
@@ -510,6 +533,18 @@ extern int pkcs11_evp_pkey_xdh_derive(PKCS11_OBJECT_private *key,
 	unsigned char *secret, size_t *secretlen);
 #endif /* !defined(OPENSSL_NO_ECX) && OPENSSL_VERSION_NUMBER >= 0x30000000L */
 
+#if OPENSSL_VERSION_NUMBER >= 0x30000000L
+extern int pkcs11_evp_pkey_rsa_decapsulate(PKCS11_OBJECT_private *key,
+	unsigned char *out, size_t *outlen,
+	const unsigned char *in, size_t inlen);
+#endif /* OPENSSL_VERSION_NUMBER >= 0x30000000L */
+
+#if !defined(OPENSSL_NO_ML_KEM) && OPENSSL_VERSION_NUMBER >= 0x30500000L
+extern int pkcs11_evp_pkey_ml_kem_decapsulate(PKCS11_OBJECT_private *key,
+	unsigned char *out, size_t *outlen,
+	const unsigned char *in, size_t inlen);
+#endif /* !defined(OPENSSL_NO_ML_KEM) && OPENSSL_VERSION_NUMBER >= 0x30500000L */
+
 /* This function has never been implemented */
 extern int pkcs11_verify(int type,
 	const unsigned char *m, unsigned int m_len,

src/libp11.exports

@@ -42,6 +42,7 @@ PKCS11_evp_pkey_sign
 PKCS11_evp_pkey_verify
 PKCS11_evp_pkey_decrypt
 PKCS11_evp_pkey_derive
+PKCS11_evp_pkey_decapsulate
 PKCS11_private_encrypt
 PKCS11_private_decrypt
 PKCS11_verify

src/libp11.h

@@ -581,6 +581,11 @@ extern int PKCS11_evp_pkey_derive(EVP_PKEY *pk, int type,
 	const unsigned char *peer_pub, size_t peer_pub_len,
 	int cofactor_mode, unsigned char *secret, size_t *secretlen);
 
+/* Perform a private-key decapsulate operation using a PKCS#11-backed EVP_PKEY */
+extern int PKCS11_evp_pkey_decapsulate(EVP_PKEY *pk, int type,
+	unsigned char *out, size_t *outlen,
+	const unsigned char *in, size_t inlen);
+
 #endif /* OPENSSL_VERSION_NUMBER >= 0x30000000L */
 
 /* Encrypts data using the private key */