STORE: Add documentation on the expectations for returned names

Returned OSSL_STORE_INFO_NAME typed infos are supposed to be a
canonical URI for the corresponding object.  For example, when using
the 'file' scheme loader, the file name is returned, possibly prefixed
with 'file://'

Reviewed-by: Ben Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/3856)

diff --git a/doc/man3/OSSL_STORE_INFO.pod b/doc/man3/OSSL_STORE_INFO.pod
index cda1be921f01e61fcc6c37736c30af2e11ea4142..20d41ac534e7b5c186b979029e2bac7207de027f 100644 (file)
--- a/doc/man3/OSSL_STORE_INFO.pod
+++ b/doc/man3/OSSL_STORE_INFO.pod
@@ -122,6 +122,14 @@ returned name will be the path of each object, so if C</foo/bar> was
 given and that path has the file C<cookie.pem>, the name
 C</foo/bar/cookie.pem> will be returned.
 
+The returned URI is considered canonical and must be unique and permanent
+for the storage where the object (or collection of objects) resides.
+Each loader is responsible for ensuring that it only returns canonical
+URIs.
+However, it's possible that certain schemes allow an object (or collection
+thereof) to be reached with alternative URIs; just because one URI is
+canonical doesn't mean that other variants can't be used.
+
 At the discretion of the loader that was used to get these names, an
 extra description may be attached as well.