From: Richard Levitte Date: Wed, 5 Jul 2017 14:08:19 +0000 (+0200) Subject: STORE: Add documentation on the expectations for returned names X-Git-Tag: OpenSSL_1_1_1-pre1~841 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=1fcb6a3daa3da1f6baa4cc5b4092642c6bf5103c;p=oweals%2Fopenssl.git 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 (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 cda1be921f..20d41ac534 100644 --- 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 was given and that path has the file C, the name C 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.