From ecb34311e38b1c9741f374abe7d98cd206b1e84c Mon Sep 17 00:00:00 2001 From: Cliff Jansen Date: Thu, 14 Nov 2024 13:39:19 -0800 Subject: [PATCH] PROTON-2594: update documentation for PKCS#11 --- c/include/proton/ssl.h | 10 +++++----- c/src/ssl/PLATFORM_NOTES.md | 7 ++++++- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/c/include/proton/ssl.h b/c/include/proton/ssl.h index a84a9b524a..22becf4894 100644 --- a/c/include/proton/ssl.h +++ b/c/include/proton/ssl.h @@ -143,12 +143,12 @@ PN_EXTERN void pn_ssl_domain_free(pn_ssl_domain_t *domain); * * @param[in] domain the ssl domain that will use this certificate. * @param[in] credential_1 specifier for the file/database containing the identifying - * certificate. For Openssl users, this is a PEM file. For Windows SChannel users, this is - * the PKCS#12 file or system store. + * certificate. For OpenSSL users, this is a PEM file or PKCS#11 URI. For Windows SChannel + * users, this is the PKCS#12 file or system store. * @param[in] credential_2 an optional key to access the identifying certificate. For - * Openssl users, this is an optional PEM file containing the private key used to sign the - * certificate. For Windows SChannel users, this is the friendly name of the - * self-identifying certificate if there are multiple certificates in the store. + * OpenSSL users, this is an optional PEM file or PKCS#11 URI containing the private key + * used to sign the certificate. For Windows SChannel users, this is the friendly name of + * the self-identifying certificate if there are multiple certificates in the store. * @param[in] password the password used to sign the key, else NULL if key is not * protected. * @return 0 on success diff --git a/c/src/ssl/PLATFORM_NOTES.md b/c/src/ssl/PLATFORM_NOTES.md index fa5664afc0..d4bc49dea3 100644 --- a/c/src/ssl/PLATFORM_NOTES.md +++ b/c/src/ssl/PLATFORM_NOTES.md @@ -8,7 +8,7 @@ On OpenSSL (POSIX) based systems, certificates and their private keys are specified separately in two files: the public X509 certificate in PEM format and the password protected PKCS#8 encoded private key. - `pn_ssl_domain_set_credentials(path_to_public_x509.pem, + `pn_ssl_domain_set_credentials(domain, path_to_public_x509.pem, path_to_private_pkcs8.pem, password_for_pkcs8)` @@ -25,6 +25,11 @@ Proton uses the OpenSSL X509_V_FLAG_PARTIAL_CHAIN flag during peer verification. All certificates included in a CA database, including those for intermediate Certificate Authorities, will be treated as potential trust anchors by OpenSSL. +PKCS#11 support for Hardware Security Module provider extensions is available on +systems with OpenSSL version >= 3.0.0. Credentials specified in PKCS#11 URI +format are retrieved by the provider extension. The OpenSSL config file must +contain a valid "providers" initialization section for a provider named "pkcs11" +that loads and activates the HSM. SChannel ========