From 1fcb6a3daa3da1f6baa4cc5b4092642c6bf5103c Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Wed, 5 Jul 2017 16:08:19 +0200 Subject: [PATCH] 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) --- doc/man3/OSSL_STORE_INFO.pod | 8 ++++++++ 1 file changed, 8 insertions(+) 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. -- 2.25.1