.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .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 \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PROVIDER-STOREMGMT 7ossl" .TH PROVIDER-STOREMGMT 7ossl "2024-01-30" "3.2.1" "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" provider\-storemgmt \- The OSSL_STORE library <\-> provider functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& /* \& * None of these are actual functions, but are displayed like this for \& * the function signatures for functions that are offered as function \& * pointers in OSSL_DISPATCH arrays. \& */ \& \& void *OSSL_FUNC_store_open(void *provctx, const char *uri); \& void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio); \& const OSSL_PARAM *store_settable_ctx_params(void *provctx); \& int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]); \& int OSSL_FUNC_store_load(void *loaderctx, \& OSSL_CALLBACK *object_cb, void *object_cbarg, \& OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg); \& int OSSL_FUNC_store_eof(void *loaderctx); \& int OSSL_FUNC_store_close(void *loaderctx); \& \& int OSSL_FUNC_store_export_object \& (void *loaderctx, const void *objref, size_t objref_sz, \& OSSL_CALLBACK *export_cb, void *export_cbarg); \& void *OSSL_FUNC_store_open_ex(void *provctx, const char *uri, \& const OSSL_PARAM params[], \& OSSL_PASSPHRASE_CALLBACK *pw_cb, \& void *pw_cbarg); \& \& int OSSL_FUNC_store_delete(void *provctx, const char *uri, \& const OSSL_PARAM params[], \& OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \s-1STORE\s0 operation is the provider side of the \fIossl_store\fR\|(7) \s-1API.\s0 .PP The primary responsibility of the \s-1STORE\s0 operation is to load all sorts of objects from a container indicated by \s-1URI. \s0 These objects are given to the OpenSSL library in provider-native object abstraction form (see \&\fIprovider\-object\fR\|(7)). The OpenSSL library is then responsible for passing on that abstraction to suitable provided functions. .PP Examples of functions that the OpenSSL library can pass the abstraction to include \fIOSSL_FUNC_keymgmt_load()\fR (\fIprovider\-keymgmt\fR\|(7)), \&\fIOSSL_FUNC_store_export_object()\fR (which exports the object in parameterized form). .PP All \*(L"functions\*(R" mentioned here are passed as function pointers between \&\fIlibcrypto\fR and the provider in \s-1\fIOSSL_DISPATCH\s0\fR\|(3) arrays via \&\s-1\fIOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's \&\fIprovider_query_operation()\fR function (see \*(L"Provider Functions\*(R" in \fIprovider\-base\fR\|(7)). .PP All these \*(L"functions\*(R" have a corresponding function type definition named \&\fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the function pointer from a \s-1\fIOSSL_DISPATCH\s0\fR\|(3) element named \fBOSSL_get_{name}\fR. For example, the \*(L"function\*(R" \fIOSSL_FUNC_store_attach()\fR has these: .PP .Vb 4 \& typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx, \& OSSL_CORE_BIO * bio); \& static ossl_inline OSSL_FUNC_store_attach_fn \& OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf); .Ve .PP \&\s-1\fIOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as macros in \fIopenssl\-core_dispatch.h\fR\|(7), as follows: .PP .Vb 10 \& OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN \& OSSL_FUNC_store_attach OSSL_FUNC_STORE_ATTACH \& OSSL_FUNC_store_settable_ctx_params OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS \& OSSL_FUNC_store_set_ctx_params OSSL_FUNC_STORE_SET_CTX_PARAMS \& OSSL_FUNC_store_load OSSL_FUNC_STORE_LOAD \& OSSL_FUNC_store_eof OSSL_FUNC_STORE_EOF \& OSSL_FUNC_store_close OSSL_FUNC_STORE_CLOSE \& OSSL_FUNC_store_export_object OSSL_FUNC_STORE_EXPORT_OBJECT \& OSSL_FUNC_store_delete OSSL_FUNC_STORE_DELETE \& OSSL_FUNC_store_open_ex OSSL_FUNC_STORE_OPEN_EX .Ve .SS "Functions" .IX Subsection "Functions" \&\fIOSSL_FUNC_store_open()\fR should create a provider side context with data based on the input \fIuri\fR. The implementation is entirely responsible for the interpretation of the \s-1URI.\s0 .PP \&\fIOSSL_FUNC_store_attach()\fR should create a provider side context with the core \&\fB\s-1BIO\s0\fR \fIbio\fR attached. This is an alternative to using a \s-1URI\s0 to find storage, supporting \fIOSSL_STORE_attach\fR\|(3). .PP \&\fIOSSL_FUNC_store_settable_ctx_params()\fR should return a constant array of descriptor \s-1\fIOSSL_PARAM\s0\fR\|(3), for parameters that \fIOSSL_FUNC_store_set_ctx_params()\fR can handle. .PP \&\fIOSSL_FUNC_store_set_ctx_params()\fR should set additional parameters, such as what kind of data to expect, search criteria, and so on. More on those below, in \&\*(L"Load Parameters\*(R". Whether unrecognised parameters are an error or simply ignored is at the implementation's discretion. Passing \s-1NULL\s0 for \fIparams\fR should return true. .PP \&\fIOSSL_FUNC_store_load()\fR loads the next object from the \s-1URI\s0 opened by \&\fIOSSL_FUNC_store_open()\fR, creates an object abstraction for it (see \&\fIprovider\-object\fR\|(7)), and calls \fIobject_cb\fR with it as well as \&\fIobject_cbarg\fR. \fIobject_cb\fR will then interpret the object abstraction and do what it can to wrap it or decode it into an OpenSSL structure. In case a passphrase needs to be prompted to unlock an object, \fIpw_cb\fR should be called. .PP \&\fIOSSL_FUNC_store_eof()\fR indicates if the end of the set of objects from the \&\s-1URI\s0 has been reached. When that happens, there's no point trying to do any further loading. .PP \&\fIOSSL_FUNC_store_close()\fR frees the provider side context \fIctx\fR. .PP When a provider-native object is created by a store manager it would be unsuitable for direct use with a foreign provider. The export function allows for exporting the object to that foreign provider if the foreign provider supports the type of the object and provides an import function. .PP \&\fIOSSL_FUNC_store_export_object()\fR should export the object of size \fIobjref_sz\fR referenced by \fIobjref\fR as an \s-1\fIOSSL_PARAM\s0\fR\|(3) array and pass that to the \&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR. .PP \&\fIOSSL_FUNC_store_delete()\fR deletes the object identified by the \fIuri\fR. The implementation is entirely responsible for the interpretation of the \s-1URI. \s0 In case a passphrase needs to be prompted to remove an object, \fIpw_cb\fR should be called. .PP \&\fIOSSL_FUNC_store_open_ex()\fR is an extended variant of \fIOSSL_FUNC_store_open()\fR. If the provider does not implement this function the code internally falls back to use the original \fIOSSL_FUNC_store_open()\fR. This variant additionally accepts an \s-1\fIOSSL_PARAM\s0\fR\|(3) object and a \fIpw_cb\fR callback that can be used to request a passphrase in cases where the whole store needs to be unlocked before performing any load operation. .SS "Load Parameters" .IX Subsection "Load Parameters" .ie n .IP """expect"" (\fB\s-1OSSL_STORE_PARAM_EXPECT\s0\fR) " 4 .el .IP "``expect'' (\fB\s-1OSSL_STORE_PARAM_EXPECT\s0\fR) " 4 .IX Item "expect (OSSL_STORE_PARAM_EXPECT) " Is a hint of what type of data the OpenSSL library expects to get. This is only useful for optimization, as the library will check that the object types match the expectation too. .Sp The number that can be given through this parameter is found in \&\fI\fR, with the macros having names starting with \&\f(CW\*(C`OSSL_STORE_INFO_\*(C'\fR. These are further described in \&\*(L"\s-1SUPPORTED OBJECTS\*(R"\s0 in \s-1\fIOSSL_STORE_INFO\s0\fR\|(3). .ie n .IP """subject"" (\fB\s-1OSSL_STORE_PARAM_SUBJECT\s0\fR) " 4 .el .IP "``subject'' (\fB\s-1OSSL_STORE_PARAM_SUBJECT\s0\fR) " 4 .IX Item "subject (OSSL_STORE_PARAM_SUBJECT) " Indicates that the caller wants to search for an object with the given subject associated. This can be used to select specific certificates by subject. .Sp The contents of the octet string is expected to be in \s-1DER\s0 form. .ie n .IP """issuer"" (\fB\s-1OSSL_STORE_PARAM_ISSUER\s0\fR) " 4 .el .IP "``issuer'' (\fB\s-1OSSL_STORE_PARAM_ISSUER\s0\fR) " 4 .IX Item "issuer (OSSL_STORE_PARAM_ISSUER) " Indicates that the caller wants to search for an object with the given issuer associated. This can be used to select specific certificates by issuer. .Sp The contents of the octet string is expected to be in \s-1DER\s0 form. .ie n .IP """serial"" (\fB\s-1OSSL_STORE_PARAM_SERIAL\s0\fR) " 4 .el .IP "``serial'' (\fB\s-1OSSL_STORE_PARAM_SERIAL\s0\fR) " 4 .IX Item "serial (OSSL_STORE_PARAM_SERIAL) " Indicates that the caller wants to search for an object with the given serial number associated. .ie n .IP """digest"" (\fB\s-1OSSL_STORE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 .el .IP "``digest'' (\fB\s-1OSSL_STORE_PARAM_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4 .IX Item "digest (OSSL_STORE_PARAM_DIGEST) " .PD 0 .ie n .IP """fingerprint"" (\fB\s-1OSSL_STORE_PARAM_FINGERPRINT\s0\fR) " 4 .el .IP "``fingerprint'' (\fB\s-1OSSL_STORE_PARAM_FINGERPRINT\s0\fR) " 4 .IX Item "fingerprint (OSSL_STORE_PARAM_FINGERPRINT) " .PD Indicates that the caller wants to search for an object with the given fingerprint, computed with the given digest. .ie n .IP """alias"" (\fB\s-1OSSL_STORE_PARAM_ALIAS\s0\fR) <\s-1UTF8\s0 string>" 4 .el .IP "``alias'' (\fB\s-1OSSL_STORE_PARAM_ALIAS\s0\fR) <\s-1UTF8\s0 string>" 4 .IX Item "alias (OSSL_STORE_PARAM_ALIAS) " Indicates that the caller wants to search for an object with the given alias (some call it a \*(L"friendly name\*(R"). .ie n .IP """properties"" (\fB\s-1OSSL_STORE_PARAM_PROPERTIES\s0\fR) " 4 .el .IP "``properties'' (\fB\s-1OSSL_STORE_PARAM_PROPERTIES\s0\fR) " 4 .IX Item "properties (OSSL_STORE_PARAM_PROPERTIES) " Property string to use when querying for algorithms such as the \fB\s-1OSSL_DECODER\s0\fR decoder implementations. .ie n .IP """input-type"" (\fB\s-1OSSL_STORE_PARAM_INPUT_TYPE\s0\fR) " 4 .el .IP "``input-type'' (\fB\s-1OSSL_STORE_PARAM_INPUT_TYPE\s0\fR) " 4 .IX Item "input-type (OSSL_STORE_PARAM_INPUT_TYPE) " Type of the input format as a hint to use when decoding the objects in the store. .PP Several of these search criteria may be combined. For example, to search for a certificate by issuer+serial, both the \*(L"issuer\*(R" and the \&\*(L"serial\*(R" parameters will be given. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIprovider\fR\|(7) .SH "HISTORY" .IX Header "HISTORY" The \s-1STORE\s0 interface was introduced in OpenSSL 3.0. .PP \&\fIOSSL_FUNC_store_delete()\fR callback was added in OpenSSL 3.2 .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 .