Add documentation for URIs in PEM files

Fixes latchset#361

Signed-off-by: Simo Sorce <[email protected]>

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:

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
 ========