STORE: Add documentation on the expectations for returned names
authorRichard Levitte <levitte@openssl.org>
Wed, 5 Jul 2017 14:08:19 +0000 (16:08 +0200)
committerRichard Levitte <levitte@openssl.org>
Tue, 15 Aug 2017 19:37:04 +0000 (21:37 +0200)
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)

doc/man3/OSSL_STORE_INFO.pod

index cda1be9..20d41ac 100644 (file)
@@ -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.