.\"	$NetBSD: provider-object.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-OBJECT 7"
.TH PROVIDER-OBJECT 7 "2023-05-07" "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\-object \- A specification for a provider\-native object abstraction
.SH "LIBRARY"
libcrypto, -lcrypto
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& #include <openssl/core_object.h>
\& #include <openssl/core_names.h>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The provider-native object abstraction is a set of \s-1\fBOSSL_PARAM\s0\fR\|(3) keys and
values that can be used to pass provider-native objects to OpenSSL library
code or between different provider operation implementations with the help
of OpenSSL library code.
.PP
The intention is that certain provider-native operations can pass any sort
of object that belong with other operations, or with OpenSSL library code.
.PP
An object may be passed in the following manners:
.IP "1." 4
\&\fIBy value\fR
.Sp
This means that the \fIobject data\fR is passed as an octet string or an \s-1UTF8\s0
string, which can be handled in diverse ways by other provided implementations.
The encoding of the object depends on the context it's used in; for example,
\&\s-1\fBOSSL_DECODER\s0\fR\|(3) allows multiple encodings, depending on existing decoders.
If central OpenSSL library functionality is to handle the data directly, it
\&\fBmust\fR be encoded in \s-1DER\s0 for all object types except for \fB\s-1OSSL_OBJECT_NAME\s0\fR
(see \*(L"Parameter reference\*(R" below), where it's assumed to a plain \s-1UTF8\s0 string.
.IP "2." 4
\&\fIBy reference\fR
.Sp
This means that the \fIobject data\fR isn't passed directly, an \fIobject
reference\fR is passed instead.  It's an octet string that only the correct
provider understands correctly.
.PP
Objects \fIby value\fR can be used by anything that handles \s-1DER\s0 encoded
objects.
.PP
Objects \fIby reference\fR need a higher level of cooperation from the
implementation where the object originated (let's call it X) and its target
implementation (let's call it Y):
.IP "1." 4
\&\fIAn object loading function in the target implementation\fR
.Sp
The target implementation (Y) may have a function that can take an \fIobject
reference\fR.  This can only be used if the target implementation is from the
same provider as the one originating the object abstraction in question (X).
.Sp
The exact target implementation to use is determined from the \fIobject type\fR
and possibly the \fIobject data type\fR.
For example, when the OpenSSL library receives an object abstraction with the
\&\fIobject type\fR \fB\s-1OSSL_OBJECT_PKEY\s0\fR, it will fetch a \fBprovider\-keymgmt\fR\|(7)
using the \fIobject data type\fR as its key type (the second argument in
\&\fBEVP_KEYMGMT_fetch\fR\|(3)).
.IP "2." 4
\&\fIAn object exporter in the originating implementation\fR
.Sp
The originating implementation (X) may have an exporter function.  This
exporter function can be used to export the object in \s-1\fBOSSL_PARAM\s0\fR\|(3) form,
that can then be imported by the target implementation's imported function.
.Sp
This can be used when it's not possible to fetch the target implementation
(Y) from the same provider.
.SS "Parameter reference"
.IX Subsection "Parameter reference"
A provider-native object abstraction is an \s-1\fBOSSL_PARAM\s0\fR\|(3) with a selection
of the following parameters:
.ie n .IP """data"" (\fB\s-1OSSL_OBJECT_PARAM_DATA\s0\fR) <octet string> or <\s-1UTF8\s0 string>" 4
.el .IP "``data'' (\fB\s-1OSSL_OBJECT_PARAM_DATA\s0\fR) <octet string> or <\s-1UTF8\s0 string>" 4
.IX Item "data (OSSL_OBJECT_PARAM_DATA) <octet string> or <UTF8 string>"
The object data \fIpassed by value\fR.
.ie n .IP """reference"" (\fB\s-1OSSL_OBJECT_PARAM_REFERENCE\s0\fR) <octet string>" 4
.el .IP "``reference'' (\fB\s-1OSSL_OBJECT_PARAM_REFERENCE\s0\fR) <octet string>" 4
.IX Item "reference (OSSL_OBJECT_PARAM_REFERENCE) <octet string>"
The object data \fIpassed by reference\fR.
.ie n .IP """type"" (\fB\s-1OSSL_OBJECT_PARAM_TYPE\s0\fR) <integer>" 4
.el .IP "``type'' (\fB\s-1OSSL_OBJECT_PARAM_TYPE\s0\fR) <integer>" 4
.IX Item "type (OSSL_OBJECT_PARAM_TYPE) <integer>"
The \fIobject type\fR, a number that may have any of the following values (all
defined in \fI<openssl/core_object.h>\fR):
.RS 4
.IP "\fB\s-1OSSL_OBJECT_NAME\s0\fR" 4
.IX Item "OSSL_OBJECT_NAME"
The object data may only be \fIpassed by value\fR, and should be a \s-1UTF8\s0
string.
.Sp
This is useful for \fBprovider\-storemgmt\fR\|(7) when a \s-1URI\s0 load results in new
URIs.
.IP "\fB\s-1OSSL_OBJECT_PKEY\s0\fR" 4
.IX Item "OSSL_OBJECT_PKEY"
The object data is suitable as provider-native \fB\s-1EVP_PKEY\s0\fR key data.  The
object data may be \fIpassed by value\fR or \fIpassed by reference\fR.
.IP "\fB\s-1OSSL_OBJECT_CERT\s0\fR" 4
.IX Item "OSSL_OBJECT_CERT"
The object data is suitable as \fBX509\fR data.  The object data for this
object type can only be \fIpassed by value\fR, and should be an octet string.
.Sp
Since there's no provider-native X.509 object, OpenSSL libraries that
receive this object abstraction are expected to convert the data to a
\&\fBX509\fR object with \fBd2i_X509()\fR.
.IP "\fB\s-1OSSL_OBJECT_CRL\s0\fR" 4
.IX Item "OSSL_OBJECT_CRL"
The object data is suitable as \fBX509_CRL\fR data.  The object data can
only be \fIpassed by value\fR, and should be an octet string.
.Sp
Since there's no provider-native X.509 \s-1CRL\s0 object, OpenSSL libraries that
receive this object abstraction are expected to convert the data to a
\&\fBX509_CRL\fR object with \fBd2i_X509_CRL()\fR.
.RE
.RS 4
.RE
.ie n .IP """data-type"" (\fB\s-1OSSL_OBJECT_PARAM_DATA_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``data-type'' (\fB\s-1OSSL_OBJECT_PARAM_DATA_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "data-type (OSSL_OBJECT_PARAM_DATA_TYPE) <UTF8 string>"
The specific type of the object content.  Legitimate values depend on the
object type; if it is \fB\s-1OSSL_OBJECT_PKEY\s0\fR, the data type is expected to be a
key type suitable for fetching a \fBprovider\-keymgmt\fR\|(7) that can handle the
data.
.ie n .IP """data-structure"" (\fB\s-1OSSL_OBJECT_PARAM_DATA_STRUCTURE\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``data-structure'' (\fB\s-1OSSL_OBJECT_PARAM_DATA_STRUCTURE\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "data-structure (OSSL_OBJECT_PARAM_DATA_STRUCTURE) <UTF8 string>"
The outermost structure of the object content.  Legitimate values depend on
the object type.
.ie n .IP """desc"" (\fB\s-1OSSL_OBJECT_PARAM_DESC\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``desc'' (\fB\s-1OSSL_OBJECT_PARAM_DESC\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "desc (OSSL_OBJECT_PARAM_DESC) <UTF8 string>"
A human readable text that describes extra details on the object.
.PP
When a provider-native object abtraction is used, it \fImust\fR contain object
data in at least one form (object data \fIpassed by value\fR, i.e. the \*(L"data\*(R"
item, or object data \fIpassed by reference\fR, i.e. the \*(L"reference\*(R" item).
Both may be present at once, in which case the OpenSSL library code that
receives this will use the most optimal variant.
.PP
For objects with the object type \fB\s-1OSSL_OBJECT_NAME\s0\fR, that object type
\&\fImust\fR be given.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBprovider\fR\|(7), \s-1\fBOSSL_DECODER\s0\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The concept of providers and everything surrounding them was
introduced in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020\-2021 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>.