From: Dr. David von Oheimb Date: Wed, 6 May 2020 11:08:45 +0000 (+0200) Subject: Fix documentation of OSSL_STORE X-Git-Tag: openssl-3.0.0-alpha4~161 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=49f84002d07a0fef5f673aff4c3a4be475563b27;p=oweals%2Fopenssl.git Fix documentation of OSSL_STORE Among others, make clear that OSSL_STORE_close() meanwhile does nothing on NULL. Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/11733) --- diff --git a/doc/man3/OSSL_STORE_INFO.pod b/doc/man3/OSSL_STORE_INFO.pod index bf69474977..095a4028b0 100644 --- a/doc/man3/OSSL_STORE_INFO.pod +++ b/doc/man3/OSSL_STORE_INFO.pod @@ -54,25 +54,24 @@ 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. +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(). +STORE_INFO_get0_() where can be NAME, PARAMS, PKEY, CERT, or CRL. 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 +As an alternative, STORE_INFO_get1_() 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 +The object returned by STORE_INFO_get1_() must be freed separately by the caller. -See L for more information on the types that are -supported. +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. @@ -94,6 +93,8 @@ 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. +On success the input object is consumed. + Additionally, for B` objects, OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra description. @@ -162,9 +163,9 @@ 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 +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 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 @@ -184,13 +185,7 @@ 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 in OpenSSL 1.1.1. +The OSSL_STORE API was added in OpenSSL 1.1.1. =head1 COPYRIGHT diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod index be61ad5b73..6d4ae01809 100644 --- a/doc/man3/OSSL_STORE_open.pod +++ b/doc/man3/OSSL_STORE_open.pod @@ -46,21 +46,22 @@ 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, +OSSL_STORE_open() takes a uri or path I, password UI method +I with associated data I, and post processing +callback I with associated data I, 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 +The given I and I will be reused by all +functions that use B when interaction is needed, +for instance to provide a password. +The given I and I will be reused by OSSL_STORE_load() to manipulate or drop the value to be returned. -The B function drops values by returning B, which +The I function drops values by returning NULL, which will cause OSSL_STORE_load() to start its process over with loading -the next object, until B returns something other than -B, or the end of data is reached as indicated by OSSL_STORE_eof(). +the next object, until I returns something other than +NULL, or the end of data is reached as indicated by OSSL_STORE_eof(). -OSSL_STORE_ctrl() takes a B, and command number B and +OSSL_STORE_ctrl() takes a B, and command number I and more arguments not specified here. The available loader specific command numbers and arguments they each take depends on the loader that's used and is documented together with @@ -94,6 +95,7 @@ OSSL_STORE_eof() shows that the end of data has been reached. 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. +If I is NULL it does nothing. =head1 SUPPORTED SCHEMES @@ -123,12 +125,12 @@ See L for further information. =head1 RETURN VALUES OSSL_STORE_open() returns a pointer to a B on success, or -B on failure. +NULL on failure. OSSL_STORE_load() returns a pointer to a B on success, or -B on error or when end of data is reached. +NULL on error or when end of data is reached. Use OSSL_STORE_error() and OSSL_STORE_eof() to determine the meaning of a -returned B. +returned NULL. OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise 0. @@ -149,6 +151,9 @@ 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 in OpenSSL 1.1.1. +Handling of NULL I argument for OSSL_STORE_close() +was introduced in OpenSSL 1.1.1h. + =head1 COPYRIGHT Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.