From 4e99adb321f4672bca3004874058b11ed70f679c Mon Sep 17 00:00:00 2001
From: Simo Sorce <simo@redhat.com>
Date: Thu, 24 Oct 2024 10:58:14 -0400
Subject: [PATCH] Add documentation for URIs in PEM files

Fixes #361

Signed-off-by: Simo Sorce <simo@redhat.com>
---
 docs/provider-pkcs11.7    | 30 ++++++++++++++++++++++++++++++
 docs/provider-pkcs11.7.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/docs/provider-pkcs11.7 b/docs/provider-pkcs11.7
index 7740fba3..e733c09c 100644
--- a/docs/provider-pkcs11.7
+++ b/docs/provider-pkcs11.7
@@ -265,6 +265,36 @@ Examples:
 \f[V]PKCS11_PROVIDER_DEBUG=file:/tmp/debug.log\f[R]
 .PP
 \f[V]PKCS11_PROVIDER_DEBUG=file:/dev/stderr,level:2\f[R]
+.SH USE IN OLDER APPLICATIONS (URIs in PEM files)
+.PP
+It is strongly suggested to update applications to use the new
+OSSL_STORE API provided by OpenSSL 3.0 which accepts URIs to
+transparenly load keys from either files or any other supported
+mechanism including pkcs11 URIs.
+.PP
+However, for those applications that cannot yet be changed there is
+support for generating a \[lq]wrapper\[rq] PEM file that contains the
+pkcs11 URI needed to identify a key on the a token.
+.PP
+This PEM file can be loaded via the clasic methods used to parse PEM/DER
+representations of keys and will trigger the use of the pkcs11-provider
+decoders when the provider is loaded.
+An error will be returned if the provided is not pre-loaded or an older
+version of OpenSSL is used.
+.PP
+In tools/uri2pem.py there is a sample python script that can take a key
+URI and produce a PEM file that references it.
+Note that storing PINs within these PEM files is not secure.
+These files are not encrypted.
+.PP
+The follwing command can be used to list all keys on a token and print
+their identifying URI:
+.IP
+.nf
+\f[C]
+openssl storeutl -keys -text pkcs11:
+\f[R]
+.fi
 .SH EXAMPLES
 .PP
 openssl.cnf:
diff --git a/docs/provider-pkcs11.7.md b/docs/provider-pkcs11.7.md
index 8585f4fc..9a92de2b 100644
--- a/docs/provider-pkcs11.7.md
+++ b/docs/provider-pkcs11.7.md
@@ -258,6 +258,34 @@ Examples:
 ```PKCS11_PROVIDER_DEBUG=file:/dev/stderr,level:2```
 
 
+USE IN OLDER APPLICATIONS (URIs in PEM files)
+=============================================
+
+It is strongly suggested to update applications to use the new
+OSSL_STORE API provided by OpenSSL 3.0 which accepts URIs to
+transparenly load keys from either files or any other supported
+mechanism including pkcs11 URIs.
+
+However, for those applications that cannot yet be changed there is
+support for generating a "wrapper" PEM file that contains the pkcs11
+URI needed to identify a key on the a token.
+
+This PEM file can be loaded via the clasic methods used to parse
+PEM/DER representations of keys and will trigger the use of the
+pkcs11-provider decoders when the provider is loaded. An error will be
+returned if the provided is not pre-loaded or an older version of
+OpenSSL is used.
+
+In tools/uri2pem.py there is a sample python script that can take a key
+URI and produce a PEM file that references it. Note that storing PINs
+within these PEM files is not secure. These files are not encrypted.
+
+The follwing command can be used to list all keys on a token and print
+their identifying URI:
+
+    openssl storeutl -keys -text pkcs11:
+
+
 EXAMPLES
 ========