Add documentation for STORE functions

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3542)

1 files changed, 103 insertions, 0 deletions

diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod
new file mode 100644
index 0000000000..b4b76dd503
--- /dev/null
+++ b/doc/man7/ossl_store.pod
@@ -0,0 +1,103 @@
+=pod
+
+=head1 NAME
+
+ossl_store - Store retrieval functions
+
+=head1 SYNOPSIS
+
+=for comment generic
+
+#include <openssl/store.h>
+
+=head1 DESCRIPTION
+
+=head2 General
+
+A STORE is a layer of functionality to retrieve a number of supported
+objects from a repository of any kind, addressable as a file name or
+as a URI.
+
+The functionality supports the pattern "open a channel to the
+repository", "loop and retrieve one object at a time", and "finish up
+by closing the channel".
+
+The retrieved objects are returned as a wrapper type B<OSSL_STORE_INFO>,
+from which an OpenSSL type can be retrieved.
+
+=head2 URI schemes and loaders
+
+Support for a URI scheme is called a STORE "loader", and can be added
+dynamically from the calling application or from a loadable engine.
+
+=head2 The 'file' scheme
+
+Support for the 'file' scheme is already built into C<libcrypto>.
+Since files come in all kinds of formats and content types, the 'file'
+scheme has its own layer of functionality called "file handlers",
+which are used to try to decode diverse types of file contents.
+
+In case a file is formatted as PEM, each called file handler receives
+the PEM name (everything following any 'C<-----BEGIN >') as well as
+possible PEM headers, together with the decoded PEM body.  Since PEM
+formatted files can contain more than one object, the file handlers
+are called upon for each such object.
+
+If the file isn't determined to be formatted as PEM, the content is
+loaded in raw form in its entirety and passed to the available file
+handlers as is, with no PEM name or headers.
+
+Each file handler is expected to handle PEM and non-PEM content as
+appropriate.  Some may refuse non-PEM content for the sake of
+determinism (for example, there are keys out in the wild that are
+represented as an ASN.1 OCTET STRING.  In raw form, it's not easily
+possible to distinguish those from any other data coming as an ASN.1
+OCTET STRING, so such keys would naturally be accepted as PEM files
+only).
+
+=head1 EXAMPLES
+
+=head2 A generic call
+
+ /*
+  * There is also a OSSL_STORE_open_file() that can be used for file paths
+  * that can't be represented as URIs, such as Windows backslashes
+  */
+ OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem");
+
+ /*
+  * OSSL_STORE_eof() simulates file semantics for any repository to signal
+  * that no more data can be expected
+  */ 
+ while (!OSSL_STORE_eof(ctx)) {
+     OSSL_STORE_INFO *info = OSSL_STORE_load(ctx);
+
+     /*
+      * Do whatever is necessary with the OSSL_STORE_INFO,
+      * here just one example
+      */
+     switch (OSSL_STORE_INFO_get_type(info)) {
+     case OSSL_STORE_INFO_X509:
+         /* Print the X.509 certificate text */
+         X509_print_fp(stdout, OSSL_STORE_INFO_get0_CERT(info));
+         /* Print the X.509 certificate PEM output */
+         PEM_write_X509(stdout, OSSL_STORE_INFO_get0_CERT(info));
+         break;
+     }
+ }
+
+ OSSL_STORE_close(ctx);
+
+=head1 SEE ALSO
+L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut