diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OSSL_STORE_INFO.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OSSL_STORE_INFO.3 | 113 |
1 files changed, 73 insertions, 40 deletions
diff --git a/secure/lib/libcrypto/man/man3/OSSL_STORE_INFO.3 b/secure/lib/libcrypto/man/man3/OSSL_STORE_INFO.3 index 124b4a0ca576..c3c147e6ace0 100644 --- a/secure/lib/libcrypto/man/man3/OSSL_STORE_INFO.3 +++ b/secure/lib/libcrypto/man/man3/OSSL_STORE_INFO.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,26 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "OSSL_STORE_INFO 3" -.TH OSSL_STORE_INFO 3 "2022-07-05" "1.1.1q" "OpenSSL" +.IX Title "OSSL_STORE_INFO 3ossl" +.TH OSSL_STORE_INFO 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_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 +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_PUBKEY, +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_PUBKEY, +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_PUBKEY, +OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL, +OSSL_STORE_INFO_new, OSSL_STORE_INFO_get0_data +\&\- Functions to manipulate OSSL_STORE_INFO objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 @@ -155,6 +165,8 @@ OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME, OSSL_STORE \& 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_PUBKEY(const OSSL_STORE_INFO *info); +\& EVP_PKEY *OSSL_STORE_INFO_get1_PUBKEY(const OSSL_STORE_INFO *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); @@ -169,9 +181,13 @@ OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME, OSSL_STORE \& 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_PUBKEY(EVP_PKEY *pubkey); \& 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); +\& +\& OSSL_STORE_INFO *OSSL_STORE_INFO_new(int type, void *data); +\& void *OSSL_STORE_INFO_get0_data(int type, const OSSL_STORE_INFO *info); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" @@ -181,50 +197,68 @@ loaders to create \fB\s-1OSSL_STORE_INFO\s0\fR holders. .SS "Types" .IX Subsection "Types" \&\fB\s-1OSSL_STORE_INFO\s0\fR is an opaque type that's just an intermediary holder for -the objects that have been retrieved by \fBOSSL_STORE_load()\fR and similar -functions. +the objects that have been retrieved by \fBOSSL_STORE_load()\fR and similar functions. Supported OpenSSL type object can be extracted using one of -\&\fBSTORE_INFO_get0_TYPE()\fR. +STORE_INFO_get0_<\s-1TYPE\s0>() where <\s-1TYPE\s0> can be \s-1NAME, PARAMS, PKEY, CERT,\s0 or \s-1CRL.\s0 The life time of this extracted object is as long as the life time of the \fB\s-1OSSL_STORE_INFO\s0\fR it was extracted from, so care should be taken not to free the latter too early. -As an alternative, \fBSTORE_INFO_get1_TYPE()\fR extracts a duplicate (or the +As an alternative, STORE_INFO_get1_<\s-1TYPE\s0>() extracts a duplicate (or the same object with its reference count increased), which can be used after the containing \fB\s-1OSSL_STORE_INFO\s0\fR has been freed. -The object returned by \fBSTORE_INFO_get1_TYPE()\fR must be freed separately +The object returned by STORE_INFO_get1_<\s-1TYPE\s0>() must be freed separately by the caller. -See \*(L"\s-1SUPPORTED OBJECTS\*(R"\s0 for more information on the types that are -supported. +See \*(L"\s-1SUPPORTED OBJECTS\*(R"\s0 for more information on the types that are supported. .SS "Functions" .IX Subsection "Functions" \&\fBOSSL_STORE_INFO_get_type()\fR takes a \fB\s-1OSSL_STORE_INFO\s0\fR and returns the \s-1STORE\s0 type number for the object inside. +.PP \&\fBSTORE_INFO_get_type_string()\fR takes a \s-1STORE\s0 type number and returns a short string describing it. .PP \&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR, -\&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR, -\&\fBOSSL_STORE_INFO_get0_CERT()\fR and \fBOSSL_STORE_INFO_get0_CRL()\fR all take a -\&\fB\s-1OSSL_STORE_INFO\s0\fR and return the held object of the appropriate OpenSSL -type provided that's what's held. +\&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PUBKEY()\fR, +\&\fBOSSL_STORE_INFO_get0_PKEY()\fR, \fBOSSL_STORE_INFO_get0_CERT()\fR, +\&\fBOSSL_STORE_INFO_get0_CRL()\fR +all take a \fB\s-1OSSL_STORE_INFO\s0\fR and return the object it holds if the +\&\fB\s-1OSSL_STORE_INFO\s0\fR type (as returned by \fBOSSL_STORE_INFO_get_type()\fR) +matches the function, otherwise \s-1NULL.\s0 .PP \&\fBOSSL_STORE_INFO_get1_NAME()\fR, \fBOSSL_STORE_INFO_get1_NAME_description()\fR, -\&\fBOSSL_STORE_INFO_get1_PARAMS()\fR, \fBOSSL_STORE_INFO_get1_PKEY()\fR, -\&\fBOSSL_STORE_INFO_get1_CERT()\fR and \fBOSSL_STORE_INFO_get1_CRL()\fR all take a -\&\fB\s-1OSSL_STORE_INFO\s0\fR and return a duplicate of the held object of the -appropriate OpenSSL type provided that's what's held. +\&\fBOSSL_STORE_INFO_get1_PARAMS()\fR, \fBOSSL_STORE_INFO_get1_PUBKEY()\fR, +\&\fBOSSL_STORE_INFO_get1_PKEY()\fR, \fBOSSL_STORE_INFO_get1_CERT()\fR and +\&\fBOSSL_STORE_INFO_get1_CRL()\fR +all take a \fB\s-1OSSL_STORE_INFO\s0\fR and return a duplicate the object it +holds if the \fB\s-1OSSL_STORE_INFO\s0\fR type (as returned by +\&\fBOSSL_STORE_INFO_get_type()\fR) matches the function, otherwise \s-1NULL.\s0 .PP \&\fBOSSL_STORE_INFO_free()\fR frees a \fB\s-1OSSL_STORE_INFO\s0\fR and its contained type. .PP \&\fBOSSL_STORE_INFO_new_NAME()\fR , \fBOSSL_STORE_INFO_new_PARAMS()\fR, -\&\fBOSSL_STORE_INFO_new_PKEY()\fR, \fBOSSL_STORE_INFO_new_CERT()\fR and -\&\fBOSSL_STORE_INFO_new_CRL()\fR create a \fB\s-1OSSL_STORE_INFO\s0\fR -object to hold the given input object. -Additionally, for \fB\s-1OSSL_STORE_INFO_NAME\s0\fR` objects, +, \fBOSSL_STORE_INFO_new_PUBKEY()\fR, \fBOSSL_STORE_INFO_new_PKEY()\fR, +\&\fBOSSL_STORE_INFO_new_CERT()\fR and \fBOSSL_STORE_INFO_new_CRL()\fR +create a \fB\s-1OSSL_STORE_INFO\s0\fR object to hold the given input object. +On success the input object is consumed. +.PP +Additionally, for \fB\s-1OSSL_STORE_INFO_NAME\s0\fR objects, \&\fBOSSL_STORE_INFO_set0_NAME_description()\fR can be used to add an extra description. This description is meant to be human readable and should be used for information printout. +.PP +\&\fBOSSL_STORE_INFO_new()\fR creates a \fB\s-1OSSL_STORE_INFO\s0\fR with an arbitrary \fItype\fR +number and \fIdata\fR structure. It's the responsibility of the caller to +define type numbers other than the ones defined by \fI<openssl/store.h>\fR, +and to handle freeing the associated data structure on their own. +\&\fIUsing type numbers that are defined by \fI<openssl/store.h>\fI may cause +undefined behaviours, including crashes\fR. +.PP +\&\fBOSSL_STORE_INFO_get0_data()\fR returns the data pointer that was passed to +\&\fBOSSL_STORE_INFO_new()\fR if \fItype\fR matches the type number in \fIinfo\fR. +.PP +\&\fBOSSL_STORE_INFO_new()\fR and \fBOSSL_STORE_INFO_get0_data()\fR may be useful for +applications that define their own \s-1STORE\s0 data, but must be used with care. .SH "SUPPORTED OBJECTS" .IX Header "SUPPORTED OBJECTS" Currently supported object types are: @@ -259,7 +293,10 @@ extra description may be attached as well. Key parameters. .IP "\s-1OSSL_STORE_INFO_PKEY\s0" 4 .IX Item "OSSL_STORE_INFO_PKEY" -A private/public key of some sort. +A keypair or just a private key (possibly with key parameters). +.IP "\s-1OSSL_STORE_INFO_PUBKEY\s0" 4 +.IX Item "OSSL_STORE_INFO_PUBKEY" +A public key (possibly with key parameters). .IP "\s-1OSSL_STORE_INFO_CERT\s0" 4 .IX Item "OSSL_STORE_INFO_CERT" An X.509 certificate. @@ -277,18 +314,18 @@ There is no error value. \&\fBOSSL_STORE_INFO_get0_CERT()\fR and \fBOSSL_STORE_INFO_get0_CRL()\fR all return a pointer to the OpenSSL object on success, \s-1NULL\s0 otherwise. .PP -\&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR, -\&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR, -\&\fBOSSL_STORE_INFO_get0_CERT()\fR and \fBOSSL_STORE_INFO_get0_CRL()\fR all return +\&\fBOSSL_STORE_INFO_get1_NAME()\fR, \fBOSSL_STORE_INFO_get1_NAME_description()\fR, +\&\fBOSSL_STORE_INFO_get1_PARAMS()\fR, \fBOSSL_STORE_INFO_get1_PKEY()\fR, +\&\fBOSSL_STORE_INFO_get1_CERT()\fR and \fBOSSL_STORE_INFO_get1_CRL()\fR all return a pointer to a duplicate of the OpenSSL object on success, \s-1NULL\s0 otherwise. .PP -\&\fBOSSL_STORE_INFO_type_string()\fR returns a string on success, or \fB\s-1NULL\s0\fR on +\&\fBOSSL_STORE_INFO_type_string()\fR returns a string on success, or \s-1NULL\s0 on failure. .PP \&\fBOSSL_STORE_INFO_new_NAME()\fR, \fBOSSL_STORE_INFO_new_PARAMS()\fR, \&\fBOSSL_STORE_INFO_new_PKEY()\fR, \fBOSSL_STORE_INFO_new_CERT()\fR and \&\fBOSSL_STORE_INFO_new_CRL()\fR return a \fB\s-1OSSL_STORE_INFO\s0\fR -pointer on success, or \fB\s-1NULL\s0\fR on failure. +pointer on success, or \s-1NULL\s0 on failure. .PP \&\fBOSSL_STORE_INFO_set0_NAME_description()\fR returns 1 on success, or 0 on failure. @@ -297,18 +334,14 @@ failure. \&\fBossl_store\fR\|(7), \fBOSSL_STORE_open\fR\|(3), \fBOSSL_STORE_register_loader\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" -\&\s-1\fBOSSL_STORE_INFO\s0()\fR, \fBOSSL_STORE_INFO_get_type()\fR, \fBOSSL_STORE_INFO_get0_NAME()\fR, -\&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR, -\&\fBOSSL_STORE_INFO_get0_CERT()\fR, \fBOSSL_STORE_INFO_get0_CRL()\fR, -\&\fBOSSL_STORE_INFO_type_string()\fR, \fBOSSL_STORE_INFO_free()\fR, \fBOSSL_STORE_INFO_new_NAME()\fR, -\&\fBOSSL_STORE_INFO_new_PARAMS()\fR, \fBOSSL_STORE_INFO_new_PKEY()\fR, -\&\fBOSSL_STORE_INFO_new_CERT()\fR and \fBOSSL_STORE_INFO_new_CRL()\fR -were added in OpenSSL 1.1.1. +The \s-1OSSL_STORE API\s0 was added in OpenSSL 1.1.1. +.PP +The \s-1OSSL_STORE_INFO_PUBKEY\s0 object type was added in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2016\-2017 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>. |