diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OSSL_STORE_open.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OSSL_STORE_open.3 | 79 |
1 files changed, 51 insertions, 28 deletions
diff --git a/secure/lib/libcrypto/man/man3/OSSL_STORE_open.3 b/secure/lib/libcrypto/man/man3/OSSL_STORE_open.3 index 19615e8c6c24..f8f64dfddf5f 100644 --- a/secure/lib/libcrypto/man/man3/OSSL_STORE_open.3 +++ b/secure/lib/libcrypto/man/man3/OSSL_STORE_open.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .rr rF -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ @@ -132,14 +130,18 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "OSSL_STORE_OPEN 3" -.TH OSSL_STORE_OPEN 3 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "OSSL_STORE_OPEN 3ossl" +.TH OSSL_STORE_OPEN 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "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 +OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, +OSSL_STORE_open, OSSL_STORE_open_ex, +OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof, +OSSL_STORE_error, OSSL_STORE_close +\&\- Types and functions to read objects from a URI .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 @@ -154,18 +156,31 @@ OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, OSSL_STORE_open, OSSL_STORE_ctr \& 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_CTX * +\& OSSL_STORE_open_ex(const char *uri, OSSL_LIB_CTX *libctx, const char *propq, +\& const UI_METHOD *ui_method, void *ui_data, +\& const OSSL_PARAM params[], +\& OSSL_STORE_post_process_info_fn post_process, +\& void *post_process_data); +\& \& 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); .Ve +.PP +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */); +.Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" These functions help the application to fetch supported objects (see \&\*(L"\s-1SUPPORTED OBJECTS\*(R"\s0 in \s-1\fBOSSL_STORE_INFO\s0\fR\|(3) for information on which those are) -from a given \s-1URI\s0 (see \*(L"\s-1SUPPORTED SCHEMES\*(R"\s0 for more information on -the supported \s-1URI\s0 schemes). +from a given \s-1URI.\s0 The general method to do so is to \*(L"open\*(R" the \s-1URI\s0 using \fBOSSL_STORE_open()\fR, read each available and supported object using \fBOSSL_STORE_load()\fR as long as \&\fBOSSL_STORE_eof()\fR hasn't been reached, and finish it off with \fBOSSL_STORE_close()\fR. @@ -175,18 +190,22 @@ described in \s-1\fBOSSL_STORE_INFO\s0\fR\|(3). .SS "Types" .IX Subsection "Types" \&\fB\s-1OSSL_STORE_CTX\s0\fR is a context variable that holds all the internal -information for \fBOSSL_STORE_open()\fR, \fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR and -\&\fBOSSL_STORE_close()\fR to work together. +information for \fBOSSL_STORE_open()\fR, \fBOSSL_STORE_open_ex()\fR, +\&\fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR to work +together. .SS "Functions" .IX Subsection "Functions" -\&\fBOSSL_STORE_open()\fR takes a uri or path \fIuri\fR, password \s-1UI\s0 method +\&\fBOSSL_STORE_open_ex()\fR takes a uri or path \fIuri\fR, password \s-1UI\s0 method \&\fIui_method\fR with associated data \fIui_data\fR, and post processing callback \fIpost_process\fR with associated data \fIpost_process_data\fR, -opens a channel to the data located at that \s-1URI\s0 and returns a +a library context \fIlibctx\fR with an associated property query \fIpropq\fR, +and opens a channel to the data located at the \s-1URI\s0 and returns a \&\fB\s-1OSSL_STORE_CTX\s0\fR with all necessary internal information. The given \fIui_method\fR and \fIui_data\fR will be reused by all functions that use \fB\s-1OSSL_STORE_CTX\s0\fR when interaction is needed, for instance to provide a password. +The auxiliary \s-1\fBOSSL_PARAM\s0\fR\|(3) parameters in \fIparams\fR can be set to further +modify the store operation. The given \fIpost_process\fR and \fIpost_process_data\fR will be reused by \&\fBOSSL_STORE_load()\fR to manipulate or drop the value to be returned. The \fIpost_process\fR function drops values by returning \s-1NULL,\s0 which @@ -194,6 +213,9 @@ will cause \fBOSSL_STORE_load()\fR to start its process over with loading the next object, until \fIpost_process\fR returns something other than \&\s-1NULL,\s0 or the end of data is reached as indicated by \fBOSSL_STORE_eof()\fR. .PP +\&\fBOSSL_STORE_open()\fR is similar to \fBOSSL_STORE_open_ex()\fR but uses \s-1NULL\s0 for +the \fIparams\fR, the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP \&\fBOSSL_STORE_ctrl()\fR takes a \fB\s-1OSSL_STORE_CTX\s0\fR, and command number \fIcmd\fR and more arguments not specified here. The available loader specific command numbers and arguments they each @@ -205,12 +227,12 @@ There are also global controls available: .IX Item "OSSL_STORE_C_USE_SECMEM" Controls if the loader should attempt to use secure memory for any allocated \fB\s-1OSSL_STORE_INFO\s0\fR and its contents. -This control expects one argument, a pointer to an \fBint\fR that is expected to +This control expects one argument, a pointer to an \fIint\fR that is expected to have the value 1 (yes) or 0 (no). Any other value is an error. .PP -\&\fBOSSL_STORE_load()\fR takes a \fB\s-1OSSL_STORE_CTX\s0\fR, tries to load the next available -object and return it wrapped with \fB\s-1OSSL_STORE_INFO\s0\fR. +\&\fBOSSL_STORE_load()\fR takes a \fB\s-1OSSL_STORE_CTX\s0\fR and tries to load the next +available object and return it wrapped with \fB\s-1OSSL_STORE_INFO\s0\fR. .PP \&\fBOSSL_STORE_eof()\fR takes a \fB\s-1OSSL_STORE_CTX\s0\fR and checks if we've reached the end of data. @@ -224,11 +246,6 @@ Note that it may still be meaningful to try and load more objects, unless by \fBOSSL_STORE_open()\fR and frees all other information that was stored in the \&\fB\s-1OSSL_STORE_CTX\s0\fR, as well as the \fB\s-1OSSL_STORE_CTX\s0\fR itself. If \fIctx\fR is \s-1NULL\s0 it does nothing. -.SH "SUPPORTED SCHEMES" -.IX Header "SUPPORTED SCHEMES" -The basic supported scheme is \fBfile:\fR. -Any other scheme can be added dynamically, using -\&\fBOSSL_STORE_register_loader()\fR. .SH "NOTES" .IX Header "NOTES" A string without a scheme prefix (that is, a non-URI string) is @@ -252,13 +269,13 @@ See \fBpassphrase\-encoding\fR\|(7) for further information. \&\fBOSSL_STORE_open()\fR returns a pointer to a \fB\s-1OSSL_STORE_CTX\s0\fR on success, or \&\s-1NULL\s0 on failure. .PP -\&\fBOSSL_STORE_load()\fR returns a pointer to a \fB\s-1OSSL_STORE_INFO\s0\fR on success, or -\&\s-1NULL\s0 on error or when end of data is reached. +\&\fBOSSL_STORE_load()\fR returns a pointer to a \fB\s-1OSSL_STORE_INFO\s0\fR on success, or \s-1NULL\s0 +on error or when end of data is reached. Use \fBOSSL_STORE_error()\fR and \fBOSSL_STORE_eof()\fR to determine the meaning of a returned \s-1NULL.\s0 .PP -\&\fBOSSL_STORE_eof()\fR returns 1 if the end of data has been reached, otherwise -0. +\&\fBOSSL_STORE_eof()\fR returns 1 if the end of data has been reached +or an error occurred, 0 otherwise. .PP \&\fBOSSL_STORE_error()\fR returns 1 if an error occurred in an \fBOSSL_STORE_load()\fR call, otherwise 0. @@ -270,17 +287,23 @@ otherwise 0. \&\fBpassphrase\-encoding\fR\|(7) .SH "HISTORY" .IX Header "HISTORY" -\&\s-1\fBOSSL_STORE_CTX\s0()\fR, \fBOSSL_STORE_post_process_info_fn()\fR, \fBOSSL_STORE_open()\fR, +\&\fBOSSL_STORE_open_ex()\fR was added in OpenSSL 3.0. +.PP +\&\fB\s-1OSSL_STORE_CTX\s0\fR, \fBOSSL_STORE_post_process_info_fn()\fR, \fBOSSL_STORE_open()\fR, \&\fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR were added in OpenSSL 1.1.1. .PP Handling of \s-1NULL\s0 \fIctx\fR argument for \fBOSSL_STORE_close()\fR was introduced in OpenSSL 1.1.1h. +.PP +\&\fBOSSL_STORE_open_ex()\fR was added in OpenSSL 3.0. +.PP +\&\fBOSSL_STORE_ctrl()\fR and \fBOSSL_STORE_vctrl()\fR were deprecated in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2016\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>. |