mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-11-27 05:21:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

Fix documentation of OSSL_STORE

Browse Source 
Among others, make clear that OSSL_STORE_close() meanwhile does nothing on NULL.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11733)
This commit is contained in:
Dr. David von Oheimb 2020-05-06 13:08:45 +02:00
parent c29ba6a92e
commit 49f84002d0
2 changed files with 30 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
doc/man3/OSSL_STORE_INFO.pod
View File

@ -54,25 +54,24 @@ loaders to create B<OSSL_STORE_INFO> holders.
=head2 Types
B<OSSL_STORE_INFO> 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_<TYPE>() where <TYPE> 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<OSSL_STORE_INFO> 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_<TYPE>() extracts a duplicate (or the
same object with its reference count increased), which can be used
after the containing B<OSSL_STORE_INFO> has been freed.
The object returned by STORE_INFO_get1_TYPE() must be freed separately
The object returned by STORE_INFO_get1_<TYPE>() must be freed separately
by the caller.
See L</SUPPORTED OBJECTS> for more information on the types that are
supported.
See L</SUPPORTED OBJECTS> for more information on the types that are supported.
=head2 Functions
OSSL_STORE_INFO_get_type() takes a B<OSSL_STORE_INFO> 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<OSSL_STORE_INFO>
object to hold the given input object.
On success the input object is consumed.
Additionally, for B<OSSL_STORE_INFO_NAME>` 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<NULL> on
@ -184,13 +185,7 @@ L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_STORE_register_loader(3)>
=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

31
doc/man3/OSSL_STORE_open.pod
View File

@ -46,21 +46,22 @@ OSSL_STORE_close() to work together.
=head2 Functions
OSSL_STORE_open() takes a uri or path B<uri>, password UI method
B<ui_method> with associated data B<ui_data>, and post processing
callback B<post_process> with associated data B<post_process_data>,
OSSL_STORE_open() takes a uri or path I<uri>, password UI method
I<ui_method> with associated data I<ui_data>, and post processing
callback I<post_process> with associated data I<post_process_data>,
opens a channel to the data located at that URI and returns a
B<OSSL_STORE_CTX> with all necessary internal information.
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
The given I<ui_method> and I<ui_data> will be reused by all
functions that use B<OSSL_STORE_CTX> when interaction is needed,
for instance to provide a password.
The given I<post_process> and I<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
The I<post_process> function drops values by returning 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().
the next object, until I<post_process> returns something other than
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
OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number I<cmd> 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<OSSL_STORE_CTX>, closes the channel that was opened
by OSSL_STORE_open() and frees all other information that was stored in the
B<OSSL_STORE_CTX>, as well as the B<OSSL_STORE_CTX> itself.
If I<ctx> is NULL it does nothing.
=head1 SUPPORTED SCHEMES
@ -123,12 +125,12 @@ See L<passphrase-encoding(7)> for further information.
=head1 RETURN VALUES
OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> on success, or
B<NULL> on failure.
NULL on failure.
OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or
B<NULL> 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<NULL>.
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<ctx> argument for OSSL_STORE_close()
was introduced in OpenSSL 1.1.1h.
=head1 COPYRIGHT
Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.