[openssl-commits] [openssl] master update

[Richard Levitte]

The branch master has been updated
       via  1fcb6a3daa3da1f6baa4cc5b4092642c6bf5103c (commit)
       via  330242959d5efdffd2aed378ea96cc7aa5cb9bde (commit)
      from  645c8790a7fa3a5d7efd2e88bb80c0cea82882e2 (commit)


- Log -----------------------------------------------------------------
commit 1fcb6a3daa3da1f6baa4cc5b4092642c6bf5103c
Author: Richard Levitte <levitte at openssl.org>
Date:   Wed Jul 5 16:08:19 2017 +0200

    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 at mit.edu>
    (Merged from https://github.com/openssl/openssl/pull/3856)

commit 330242959d5efdffd2aed378ea96cc7aa5cb9bde
Author: Richard Levitte <levitte at openssl.org>
Date:   Wed Jul 5 16:00:30 2017 +0200

    STORE: Add info on the expected post_process callback behavior
    
    Reviewed-by: Ben Kaduk <kaduk at mit.edu>
    (Merged from https://github.com/openssl/openssl/pull/3856)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/OSSL_STORE_INFO.pod | 8 ++++++++
 doc/man3/OSSL_STORE_open.pod | 4 ++++
 2 files changed, 12 insertions(+)

diff --git a/doc/man3/OSSL_STORE_INFO.pod b/doc/man3/OSSL_STORE_INFO.pod
index cda1be9..20d41ac 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</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.
 
diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod
index 0bc6d5c..3a05a88 100644
--- a/doc/man3/OSSL_STORE_open.pod
+++ b/doc/man3/OSSL_STORE_open.pod
@@ -55,6 +55,10 @@ The given B<ui_method> and B<ui_data_data> will be reused by all
 functions that use B<OSSL_STORE_CTX> when interaction is needed.
 The given B<post_process> and B<post_process_data> will be reused by
 OSSL_STORE_load() to manipulate or drop the value to be returned.
+The B<post_process> function drops values by returning B<NULL>, which
+will cause OSSL_STORE_load() to start its process over with loading
+the next object, until B<post_process> returns something other than
+B<NULL>, or the end of data is reached as indicated by OSSL_STORE_eof().
 
 OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> and
 more arguments not specified here.