From e2e603fe7c5b35d8dadb1eec4696307d16665731 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 13 Dec 2016 13:46:53 +0100 Subject: [PATCH] Add documentation for STORE functions Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/3542) --- doc/man3/OSSL_STORE_INFO.pod | 196 ++++++++++++++++++++++++++++ doc/man3/OSSL_STORE_LOADER.pod | 229 +++++++++++++++++++++++++++++++++ doc/man3/OSSL_STORE_open.pod | 138 ++++++++++++++++++++ doc/man7/ossl_store.pod | 103 +++++++++++++++ 4 files changed, 666 insertions(+) create mode 100644 doc/man3/OSSL_STORE_INFO.pod create mode 100644 doc/man3/OSSL_STORE_LOADER.pod create mode 100644 doc/man3/OSSL_STORE_open.pod create mode 100644 doc/man7/ossl_store.pod diff --git a/doc/man3/OSSL_STORE_INFO.pod b/doc/man3/OSSL_STORE_INFO.pod new file mode 100644 index 0000000000..22ab666572 --- /dev/null +++ b/doc/man3/OSSL_STORE_INFO.pod @@ -0,0 +1,196 @@ +=pod + +=head1 NAME + +OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME, +OSSL_STORE_INFO_get0_NAME_description, OSSL_STORE_INFO_get0_PARAMS, +OSSL_STORE_INFO_get0_PKEY, OSSL_STORE_INFO_get0_CERT, OSSL_STORE_INFO_get0_CRL, +OSSL_STORE_INFO_get1_NAME, OSSL_STORE_INFO_get1_NAME_description, +OSSL_STORE_INFO_get1_PARAMS, OSSL_STORE_INFO_get1_PKEY, +OSSL_STORE_INFO_get1_CERT, +OSSL_STORE_INFO_get1_CRL, OSSL_STORE_INFO_type_string, OSSL_STORE_INFO_free, +OSSL_STORE_INFO_new_NAME, OSSL_STORE_INFO_set0_NAME_description, +OSSL_STORE_INFO_new_PARAMS, OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, +OSSL_STORE_INFO_new_CRL - Functions to manipulate OSSL_STORE_INFO objects + +=head1 SYNOPSIS + + #include + + typedef struct ossl_store_info_st OSSL_STORE_INFO; + + int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info); + const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info); + char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info); + const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO + *store_info); + char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info); + EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info); + EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info); + EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info); + EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info); + X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info); + X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info); + X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info); + X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info); + + const char *OSSL_STORE_INFO_type_string(int type); + + void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info); + + OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name); + int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc); + OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params); + OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey); + OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509); + OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl); + +=head1 DESCRIPTION + +These functions are primarly useful for applications to retrieve +supported objects from B objects and for scheme specific +loaders to create B holders. + +=head2 Types + +B is an opaque type that's just an intermediary holder for +the objects that have been retrieved by OSSL_STORE_load() and similar +functions. +Supported OpenSSL type object can be extracted using one of +STORE_INFO_get0_TYPE(). +The life time of this extracted object is as long as the life time of +the B it was extracted from, so care should be taken not +to free the latter too early. +As an alternative, STORE_INFO_get1_TYPE() extracts a duplicate (or the +same object with its reference count increased), which can be used +after the containing B has been freed. +The object returned by STORE_INFO_get1_TYPE() must be freed separately +by the caller. +See L for more information on the types that are +supported. + +=head2 Functions + +OSSL_STORE_INFO_get_type() takes a B and returns the STORE +type number for the object inside. +STORE_INFO_get_type_string() takes a STORE type number and returns a +short string describing it. + +OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(), +OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(), +OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all take a +B and return the held object of the appropriate OpenSSL +type provided that's what's held. + +OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(), +OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(), +OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all take a +B and return a duplicate of the held object of the +appropriate OpenSSL type provided that's what's held. + +OSSL_STORE_INFO_free() frees a B and its contained type. + +OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(), +OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and +OSSL_STORE_INFO_new_CRL() create a B +object to hold the given input object. +Additionally, for B` objects, +OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra +description. +This description is meant to be human readable and should be used for +information printout. + +=head1 SUPPORTED OBJECTS + +Currently supported object types are: + +=over 4 + +=item OSSL_STORE_INFO_NAME + +A name is exactly that, a name. +It's like a name in a directory, but formatted as a complete URI. +For example, the path in URI C could include a file +named C, and in that case, the returned B +object would have the URI C, which can be +used by the application to get the objects in that file. +This can be applied to all schemes that can somehow support a listing +of object URIs. + +For C URIs that are used without the explicit scheme, or paths +given to L, the 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. + +At the discretion of the loader that was used to get these names, an +extra description may be attached as well. + +=item OSSL_STORE_INFO_PARAMS + +Key parameters. + +=item OSSL_STORE_INFO_PKEY + +A private/public key of some sort. + +=item OSSL_STORE_INFO_CERT + +An X.509 certificate. + +=item OSSL_STORE_INFO_CRL + +A X.509 certificate reocation list. + +=back + +=head1 RETURN VALUES + +OSSL_STORE_INFO_get_type() returns the STORE type number of the given +B. +There is no error value. + +OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(), +OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(), +OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return +a pointer to the OpenSSL object on success, NULL otherwise. + +OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(), +OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(), +OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return +a pointer to a duplicate of the OpenSSL object on success, NULL otherwise. + +OSSL_STORE_INFO_type_string() returns a string on success, or B on +failure. + +OSSL_STORE_INFO_new_NAME(), OSSL_STORE_INFO_new_PARAMS(), +OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and +OSSL_STORE_INFO_new_CRL() return a B +pointer on success, or B on failure. + +OSSL_STORE_INFO_set0_NAME_description() returns 1 on success, or 0 on +failure. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +OSSL_STORE_INFO(), OSSL_STORE_INFO_get_type(), OSSL_STORE_INFO_get0_NAME(), +OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(), +OSSL_STORE_INFO_get0_CERT(), OSSL_STORE_INFO_get0_CRL(), +OSSL_STORE_INFO_type_string(), OSSL_STORE_INFO_free(), OSSL_STORE_INFO_new_NAME(), +OSSL_STORE_INFO_new_PARAMS(), OSSL_STORE_INFO_new_PKEY(), +OSSL_STORE_INFO_new_CERT() and OSSL_STORE_INFO_new_CRL() +were added to OpenSSL 1.1.1. + +=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. + +=cut diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod new file mode 100644 index 0000000000..4386c28da3 --- /dev/null +++ b/doc/man3/OSSL_STORE_LOADER.pod @@ -0,0 +1,229 @@ +=pod + +=head1 NAME + +OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new, +OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme, +OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl, +OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof, +OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close, +OSSL_STORE_LOADER_free, OSSL_STORE_register_loader, +OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn, +OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn, +OSSL_STORE_close_fn - Types and functions to manipulate, register and +unregister STORE loaders for different URI schemes + +=head1 SYNOPSIS + + #include + + typedef struct ossl_store_loader_st OSSL_STORE_LOADER; + + OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme); + const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER + *store_loader); + const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER + *store_loader); + + /* struct ossl_store_loader_ctx_st is defined differently by each loader */ + typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX; + + typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(const char *uri, + const UI_METHOD *ui_method, + void *ui_data); + int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader, + OSSL_STORE_open_fn store_open_function); + typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd, + va_list args); + int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader, + OSSL_STORE_ctrl_fn store_ctrl_function); + typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx, + UI_METHOD *ui_method, + void *ui_data); + int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader, + OSSL_STORE_load_fn store_load_function); + typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx); + int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader, + OSSL_STORE_eof_fn store_eof_function); + typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx); + int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader, + OSSL_STORE_error_fn store_error_function); + typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); + int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader, + OSSL_STORE_close_fn store_close_function); + void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader); + + int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader); + OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme); + +=head1 DESCRIPTION + +These functions help applications and engines to create loaders for +schemes they support. + +=head2 Types + +B is the type to hold a loader. +It contains a scheme and the functions needed to implement +OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and +OSSL_STORE_close() for this scheme. + +B is a type template, to be defined by each loader +using B. + +B, B, B, +B and B are the function pointer +types used within a STORE loader. +The functions pointed at define the functionality of the given loader. + +=over 4 + +=item B + +This function takes a URI and is expected to interpret it in the best +manner possible according to the scheme the loader implements, it also +takes a B and associated data, to be used any time +something needs to be prompted for. +Furthermore, this function is expected to initialize what needs to be +initialized, to create a privata data store (B, see +above), and to return it. +If something goes wrong, this function is expected to return NULL. + +=item B + +This function takes a B pointer, a command number +B and a B B and is used to manipulate loader +specific parameters. + +=begin comment + +Globally known command numbers are documented in L, +along with what B are expected with each of them. + +=end comment + +Loader specific command numbers must begin at B. +Any number below that is reserved for future globally known command +numbers. + +This function is expected to return 1 on success, 0 on error. + +=item B + +This function takes a B pointer and a B +with associated data. +It's expected to load the next available data, mold it into a data +structure that can be wrapped in a B using one of the +L functions. +If no more data is available or an error occurs, this function is +expected to return NULL. +The B and B functions must indicate if +it was in fact the end of data or if an error occured. + +Note that this function retrives I data item only. + +=item B + +This function takes a B pointer and is expected to +return 1 to indicate that the end of available data has been reached. +It is otherwise expected to return 0. + +=item B + +This function takes a B pointer and is expected to +return 1 to indicate that an error occured in a previous call to the +B function. +It is otherwise expected to return 0. + +=item B + +This function takes a B pointer and is expected to +close or shut down what needs to be closed, and finally free the +contents of the B pointer. +It returns 1 on success and 0 on error. + +=back + +=head2 Functions + +OSSL_STORE_LOADER_new() creates a new B. +It takes an B B and a string B. +B must I be set. +Both B and B are used as is and must therefore be alive as +long as the created loader is. + +OSSL_STORE_LOADER_get0_engine() returns the engine of the B. +OSSL_STORE_LOADER_get0_scheme() returns the scheme of the B. + +OSSL_STORE_LOADER_set_open() sets the opener function for the +B. + +OSSL_STORE_LOADER_set_ctrl() sets the control function for the +B. + +OSSL_STORE_LOADER_set_load() sets the loader function for the +B. + +OSSL_STORE_LOADER_set_eof() sets the end of file checker function for the +B. + +OSSL_STORE_LOADER_set_close() sets the closing function for the +B. + +OSSL_STORE_LOADER_free() frees the given B. + +OSSL_STORE_register_loader() register the given B and thereby +makes it available for use with OSSL_STORE_open(), OSSL_STORE_load(), +OSSL_STORE_eof() and OSSL_STORE_close(). + +OSSL_STORE_unregister_loader() unregister the store loader for the given +B. + +=head1 NOTES + +The B scheme has built in support. + +=head1 RETURN VALUES + +The functions with the types B, B, +B, B and B have the +same return values as OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof() and +OSSL_STORE_close(), respectively. + +OSSL_STORE_LOADER_new() returns a pointer to a B on success, +or B on failure. + +OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(), +OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof() and +OSSL_STORE_LOADER_set_close() return 1 on success, or 0 on failure. + +OSSL_STORE_register_loader() returns 1 on success, or 0 on failure. + +OSSL_STORE_unregister_loader() returns the unregistered loader on success, +or B on failure. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +OSSL_STORE_LOADER(), OSSL_STORE_LOADER_CTX(), OSSL_STORE_LOADER_new(), +OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_set_open(), +OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(), +OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(), +OSSL_STORE_LOADER_free(), OSSL_STORE_register_loader(), +OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(), +OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn() +were added to OpenSSL 1.1.1. + +=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. + +=cut diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod new file mode 100644 index 0000000000..b63156a95c --- /dev/null +++ b/doc/man3/OSSL_STORE_open.pod @@ -0,0 +1,138 @@ +=pod + +=head1 NAME + +OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, OSSL_STORE_open, +OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof, OSSL_STORE_error, +OSSL_STORE_close - Types and functions to read objects from a URI + +=head1 SYNOPSIS + + #include + + typedef struct ossl_store_ctx_st OSSL_STORE_CTX; + + typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *, + void *); + + OSSL_STORE_CTX *OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method, + void *ui_data, + OSSL_STORE_post_process_info_fn post_process, + void *post_process_data); + int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */); + OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx); + int OSSL_STORE_eof(OSSL_STORE_CTX *ctx); + int OSSL_STORE_error(OSSL_STORE_CTX *ctx); + int OSSL_STORE_close(OSSL_STORE_CTX *ctx); + +=head1 DESCRIPTION + +These functions help the application to fetch supported objects (see +L for information on which those are) +from a given URI (see L for more information on +the supported URI schemes). +The general method to do so is to "open" the URI using OSSL_STORE_open(), +read each available and supported object using OSSL_STORE_load() as long as +OSSL_STORE_eof() hasn't been reached, and finish it off with OSSL_STORE_close(). + +The retrieved information is stored in a B, which is further +described in L. + +=head2 Types + +B is a context variable that holds all the internal +information for OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof() and +OSSL_STORE_close() to work together. + +=head2 Functions + +OSSL_STORE_open() takes a uri or path B, password UI method +B with associated data B, and post processing +callback B with associated data B, +opens a channel to the data located at that URI and returns a +B with all necessary internal information. +The given B and B will be reused by all +functions that use B when interaction is needed. +The given B and B will be reused by +OSSL_STORE_load() to manipulate or drop the value to be returned. + +OSSL_STORE_ctrl() takes a B, and command number B and +more arguments not specified here. +The available command numbers and arguments they each take depends on +the loader that's used and is documented together with that loader. + +OSSL_STORE_load() takes a B, tries to load the next available +object and return it wrapped with B. + +OSSL_STORE_eof() takes a B and checks if we've reached the end +of data. + +OSSL_STORE_error() takes a B and checks if an error occured in +the last OSSL_STORE_load() call. + +OSSL_STORE_close() takes a B, closes the channel that was opened +by OSSL_STORE_open() and frees all other information that was stored in the +B, as well as the B itself. + +=head1 SUPPORTED SCHEMES + +The basic supported scheme is B. +Any other scheme can be added dynamically, using +OSSL_STORE_register_loader(). + +=head1 NOTES + +When unsure whether a given string contains a simple file or directory +reference, or if it's a full blown URI, the question is how to figure +that out. +One way is to try OSSL_STORE_open_file() and if that fails, try +OSSL_STORE_open(). +The other way is the other way around. +Either way you choose, there are corner cases, +F might very will be a simple file reference +on a system that supports the notion of volumes. + +This manual won't tell you which way is better, that's up to each +application developer to decide on their own. +However, there are some tools that can be used together with +OSSL_STORE_open() to determine if any failure is caused by an unparsable +URI, or if it's a different error (such as memory allocation +failures); if the URI was parsable but the scheme unregistered, the +top error will have the reason C. +If you decide to use OSSL_STORE_open() with OSSL_STORE_open_file() as a +fallback, those reasons can be good tools to decide if the fallback +should be taken or not. + +=head1 RETURN VALUES + +OSSL_STORE_open() and OSSL_STORE_load() return a pointer to a B +on success, or B on failure. + +OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise +0. + +OSSL_STORE_error() returns 1 if an error occured in a OSSL_STORE_load() call, +otherwise 0. + +OSSL_STORE_ctrl() and OSSL_STORE_close() returns 1 on success, or 0 on failure. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +OSSL_STORE_CTX(), OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(), +OSSL_STORE_ctrl(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() +were added to OpenSSL 1.1.1. + +=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. + +=cut 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 + +=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, +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. +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, L, L + +=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. + +=cut -- 2.25.1