.\"	$NetBSD: provider-decoder.7,v 1.2 2023/05/31 19:42:44 christos Exp $
.\"
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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-DECODER 7"
.TH PROVIDER-DECODER 7 "2023-05-31" "3.0.9" "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\-decoder \- The OSSL_DECODER library <\-> provider functions
.SH "LIBRARY"
libcrypto, -lcrypto
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/core_dispatch.h>
\&
\& /*
\&  * 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.
\&  */
\&
\& /* Decoder parameter accessor and descriptor */
\& const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx);
\& int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]);
\&
\& /* Functions to construct / destruct / manipulate the decoder context */
\& void *OSSL_FUNC_decoder_newctx(void *provctx);
\& void OSSL_FUNC_decoder_freectx(void *ctx);
\& const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx);
\& int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
\&
\& /* Functions to check selection support */
\& int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);
\&
\& /* Functions to decode object data */
\& int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
\&                              int selection,
\&                              OSSL_CALLBACK *data_cb, void *data_cbarg,
\&                              OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
\&
\& /* Functions to export a decoded object */
\& int OSSL_FUNC_decoder_export_object(void *ctx,
\&                                       const void *objref, size_t objref_sz,
\&                                       OSSL_CALLBACK *export_cb,
\&                                       void *export_cbarg);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIThe term \*(L"decode\*(R" is used throughout this manual.  This includes but is
not limited to deserialization as individual decoders can also do
decoding into intermediate data formats.\fR
.PP
The \s-1DECODER\s0 operation is a generic method to create a provider-native
object reference or intermediate decoded data from an encoded form
read from the given \fB\s-1OSSL_CORE_BIO\s0\fR. If the caller wants to decode
data from memory, it should provide a \fBBIO_s_mem\fR\|(3) \fB\s-1BIO\s0\fR. The decoded
data or object reference is passed along with eventual metadata
to the \fImetadata_cb\fR as \s-1\fBOSSL_PARAM\s0\fR\|(3) parameters.
.PP
The decoder doesn't need to know more about the \fB\s-1OSSL_CORE_BIO\s0\fR
pointer than being able to pass it to the appropriate \s-1BIO\s0 upcalls (see
\&\*(L"Core functions\*(R" in \fBprovider\-base\fR\|(7)).
.PP
The \s-1DECODER\s0 implementation may be part of a chain, where data is
passed from one to the next.  For example, there may be an
implementation to decode an object from \s-1PEM\s0 to \s-1DER,\s0 and another one
that decodes \s-1DER\s0 to a provider-native object.
.PP
The last decoding step in the decoding chain is usually supposed to create
a provider-native object referenced by an object reference. To import
that object into a different provider the \fBOSSL_FUNC_decoder_export_object()\fR
can be called as the final step of the decoding process.
.PP
All \*(L"functions\*(R" mentioned here are passed as function pointers between
\&\fIlibcrypto\fR and the provider in \s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays via
\&\s-1\fBOSSL_ALGORITHM\s0\fR\|(3) arrays that are returned by the provider's
\&\fBprovider_query_operation()\fR function
(see \*(L"Provider Functions\*(R" in \fBprovider\-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 an \s-1\fBOSSL_DISPATCH\s0\fR\|(3) element named
\&\fBOSSL_FUNC_{name}\fR.
For example, the \*(L"function\*(R" \fBOSSL_FUNC_decoder_decode()\fR has these:
.PP
.Vb 7
\& typedef int
\&     (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
\&                                   int selection,
\&                                   OSSL_CALLBACK *data_cb, void *data_cbarg,
\&                                   OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
\& static ossl_inline OSSL_FUNC_decoder_decode_fn*
\&     OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);
.Ve
.PP
\&\s-1\fBOSSL_DISPATCH\s0\fR\|(3) arrays are indexed by numbers that are provided as
macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
.PP
.Vb 2
\& OSSL_FUNC_decoder_get_params          OSSL_FUNC_DECODER_GET_PARAMS
\& OSSL_FUNC_decoder_gettable_params     OSSL_FUNC_DECODER_GETTABLE_PARAMS
\&
\& OSSL_FUNC_decoder_newctx              OSSL_FUNC_DECODER_NEWCTX
\& OSSL_FUNC_decoder_freectx             OSSL_FUNC_DECODER_FREECTX
\& OSSL_FUNC_decoder_set_ctx_params      OSSL_FUNC_DECODER_SET_CTX_PARAMS
\& OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS
\&
\& OSSL_FUNC_decoder_does_selection      OSSL_FUNC_DECODER_DOES_SELECTION
\&
\& OSSL_FUNC_decoder_decode              OSSL_FUNC_DECODER_DECODE
\&
\& OSSL_FUNC_decoder_export_object       OSSL_FUNC_DECODER_EXPORT_OBJECT
.Ve
.SS "Names and properties"
.IX Subsection "Names and properties"
The name of an implementation should match the target type of object
it decodes. For example, an implementation that decodes an \s-1RSA\s0 key
should be named \*(L"\s-1RSA\*(R".\s0 Likewise, an implementation that decodes \s-1DER\s0 data
from \s-1PEM\s0 input should be named \*(L"\s-1DER\*(R".\s0
.PP
Properties can be used to further specify details about an implementation:
.IP "input" 4
.IX Item "input"
This property is used to specify what format of input the implementation
can decode.
.Sp
This property is \fImandatory\fR.
.Sp
OpenSSL providers recognize the following input types:
.RS 4
.IP "pem" 4
.IX Item "pem"
An implementation with that input type decodes \s-1PEM\s0 formatted data.
.IP "der" 4
.IX Item "der"
An implementation with that input type decodes \s-1DER\s0 formatted data.
.IP "msblob" 4
.IX Item "msblob"
An implementation with that input type decodes \s-1MSBLOB\s0 formatted data.
.IP "pvk" 4
.IX Item "pvk"
An implementation with that input type decodes \s-1PVK\s0 formatted data.
.RE
.RS 4
.RE
.IP "structure" 4
.IX Item "structure"
This property is used to specify the structure that the decoded data is
expected to have.
.Sp
This property is \fIoptional\fR.
.Sp
Structures currently recognised by built-in decoders:
.RS 4
.ie n .IP """type-specific""" 4
.el .IP "``type-specific''" 4
.IX Item "type-specific"
Type specific structure.
.ie n .IP """pkcs8""" 4
.el .IP "``pkcs8''" 4
.IX Item "pkcs8"
Structure according to the PKCS#8 specification.
.ie n .IP """SubjectPublicKeyInfo""" 4
.el .IP "``SubjectPublicKeyInfo''" 4
.IX Item "SubjectPublicKeyInfo"
Encoding of public keys according to the Subject Public Key Info of \s-1RFC 5280.\s0
.RE
.RS 4
.RE
.PP
The possible values of both these properties is open ended.  A provider may
very well specify input types and structures that libcrypto doesn't know
anything about.
.SS "Subset selections"
.IX Subsection "Subset selections"
Sometimes, an object has more than one subset of data that is interesting to
treat separately or together.  It's possible to specify what subsets are to
be decoded, with a set of bits \fIselection\fR that are passed in an \fBint\fR.
.PP
This set of bits depend entirely on what kind of provider-side object is
to be decoded.  For example, those bits are assumed to be the same as those
used with \fBprovider\-keymgmt\fR\|(7) (see \*(L"Key Objects\*(R" in \fBprovider\-keymgmt\fR\|(7)) when
the object is an asymmetric keypair \- e.g., \fB\s-1OSSL_KEYMGMT_SELECT_PRIVATE_KEY\s0\fR
if the object to be decoded is supposed to contain private key components.
.PP
\&\fBOSSL_FUNC_decoder_does_selection()\fR should tell if a particular implementation
supports any of the combinations given by \fIselection\fR.
.SS "Context functions"
.IX Subsection "Context functions"
\&\fBOSSL_FUNC_decoder_newctx()\fR returns a context to be used with the rest of
the functions.
.PP
\&\fBOSSL_FUNC_decoder_freectx()\fR frees the given \fIctx\fR as created by
\&\fBOSSL_FUNC_decoder_newctx()\fR.
.PP
\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR sets context data according to parameters
from \fIparams\fR that it recognises.  Unrecognised parameters should be
ignored.
Passing \s-1NULL\s0 for \fIparams\fR should return true.
.PP
\&\fBOSSL_FUNC_decoder_settable_ctx_params()\fR returns a constant \s-1\fBOSSL_PARAM\s0\fR\|(3)
array describing the parameters that \fBOSSL_FUNC_decoder_set_ctx_params()\fR
can handle.
.PP
See \s-1\fBOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by
\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR and \fBOSSL_FUNC_decoder_settable_ctx_params()\fR.
.SS "Export function"
.IX Subsection "Export function"
When a provider-native object is created by a decoder it would be unsuitable
for direct use with a foreign provider. The export function allows for
exporting the object into that foreign provider if the foreign provider
supports the type of the object and provides an import function.
.PP
\&\fBOSSL_FUNC_decoder_export_object()\fR should export the object of size \fIobjref_sz\fR
referenced by \fIobjref\fR as an \s-1\fBOSSL_PARAM\s0\fR\|(3) array and pass that into the
\&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR.
.SS "Decoding functions"
.IX Subsection "Decoding functions"
\&\fBOSSL_FUNC_decoder_decode()\fR should decode the data as read from
the \fB\s-1OSSL_CORE_BIO\s0\fR \fIin\fR to produce decoded data or an object to be
passed as reference in an \s-1\fBOSSL_PARAM\s0\fR\|(3) array along with possible other
metadata that was decoded from the input. This \s-1\fBOSSL_PARAM\s0\fR\|(3) array is
then passed to the \fIdata_cb\fR callback.  The \fIselection\fR bits,
if relevant, should determine what the input data should contain.
The decoding functions also take an \s-1\fBOSSL_PASSPHRASE_CALLBACK\s0\fR\|(3) function
pointer along with a pointer to application data \fIcbarg\fR, which should be
used when a pass phrase prompt is needed.
.PP
It's important to understand that the return value from this function is
interpreted as follows:
.IP "True (1)" 4
.IX Item "True (1)"
This means \*(L"carry on the decoding process\*(R", and is meaningful even though
this function couldn't decode the input into anything, because there may be
another decoder implementation that can decode it into something.
.Sp
The \fIdata_cb\fR callback should never be called when this function can't
decode the input into anything.
.IP "False (0)" 4
.IX Item "False (0)"
This means \*(L"stop the decoding process\*(R", and is meaningful when the input
could be decoded into some sort of object that this function understands,
but further treatment of that object results into errors that won't be
possible for some other decoder implementation to get a different result.
.PP
The conditions to stop the decoding process are at the discretion of the
implementation.
.SS "Decoder operation parameters"
.IX Subsection "Decoder operation parameters"
There are currently no operation parameters currently recognised by the
built-in decoders.
.PP
Parameters currently recognised by the built-in pass phrase callback:
.ie n .IP """info"" (\fB\s-1OSSL_PASSPHRASE_PARAM_INFO\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``info'' (\fB\s-1OSSL_PASSPHRASE_PARAM_INFO\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "info (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 string>"
A string of information that will become part of the pass phrase
prompt.  This could be used to give the user information on what kind
of object it's being prompted for.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBOSSL_FUNC_decoder_newctx()\fR returns a pointer to a context, or \s-1NULL\s0 on
failure.
.PP
\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR returns 1, unless a recognised
parameter was invalid or caused an error, for which 0 is returned.
.PP
\&\fBOSSL_FUNC_decoder_settable_ctx_params()\fR returns a pointer to an array of
constant \s-1\fBOSSL_PARAM\s0\fR\|(3) elements.
.PP
\&\fBOSSL_FUNC_decoder_does_selection()\fR returns 1 if the decoder implementation
supports any of the \fIselection\fR bits, otherwise 0.
.PP
\&\fBOSSL_FUNC_decoder_decode()\fR returns 1 to signal that the decoding process
should continue, or 0 to signal that it should stop.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBprovider\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
The \s-1DECODER\s0 interface was introduced in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2019\-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
<https://www.openssl.org/source/license.html>.