422 lines
15 KiB
Groff
Executable File
422 lines
15 KiB
Groff
Executable File
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
|
|
.\"
|
|
.\" 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" ''
|
|
'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.
|
|
.ie \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.el \{\
|
|
. de IX
|
|
..
|
|
.\}
|
|
.\"
|
|
.\" 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 "OSSL_PARAM 3"
|
|
.TH OSSL_PARAM 3 "2020-03-02" "3.0.0-dev" "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_PARAM \- a structure to pass or request object parameters
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/core.h>
|
|
\&
|
|
\& typedef struct ossl_param_st OSSL_PARAM;
|
|
\& struct ossl_param_st {
|
|
\& const char *key; /* the name of the parameter */
|
|
\& unsigned char data_type; /* declare what kind of content is in data */
|
|
\& void *data; /* value being passed in or out */
|
|
\& size_t data_size; /* data size */
|
|
\& size_t return_size; /* returned size */
|
|
\& };
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
\&\fB\s-1OSSL_PARAM\s0\fR is a type that allows passing arbitrary data for some
|
|
object between two parties that have no or very little shared
|
|
knowledge about their respective internal structures for that object.
|
|
.PP
|
|
A typical usage example could be an application that wants to set some
|
|
parameters for an object, or wants to find out some parameters of an
|
|
object.
|
|
.PP
|
|
Arrays of this type can be used for the following purposes:
|
|
.IP "\(bu" 4
|
|
Setting parameters for some object
|
|
.Sp
|
|
The caller sets up the \fB\s-1OSSL_PARAM\s0\fR array and calls some function
|
|
(the \fIsetter\fR) that has intimate knowledge about the object that can
|
|
take the data from the \fB\s-1OSSL_PARAM\s0\fR array and assign them in a
|
|
suitable form for the internal structure of the object.
|
|
.IP "\(bu" 4
|
|
Request parameters of some object
|
|
.Sp
|
|
The caller (the \fIrequestor\fR) sets up the \fB\s-1OSSL_PARAM\s0\fR array and
|
|
calls some function (the \fIresponder\fR) that has intimate knowledge
|
|
about the object, which can take the internal data of the object and
|
|
copy (possibly convert) that to the memory prepared by the
|
|
\&\fIrequestor\fR and pointed at with the \fB\s-1OSSL_PARAM\s0\fR \fIdata\fR.
|
|
.IP "\(bu" 4
|
|
Request parameter descriptors
|
|
.Sp
|
|
The caller gets an array of constant \fB\s-1OSSL_PARAM\s0\fR, which describe
|
|
available parameters and some of their properties; name, data type and
|
|
expected data size.
|
|
For a detailed description of each field for this use, see the field
|
|
descriptions below.
|
|
.Sp
|
|
The caller may then use the information from this descriptor array to
|
|
build up its own \fB\s-1OSSL_PARAM\s0\fR array to pass down to a \fIsetter\fR or
|
|
\&\fIresponder\fR.
|
|
.PP
|
|
Normally, the order of the an \fB\s-1OSSL_PARAM\s0\fR array is not relevant.
|
|
However, if the \fIresponder\fR can handle multiple elements with the
|
|
same key, those elements must be handled in the order they are in.
|
|
.SS "\fB\s-1OSSL_PARAM\s0\fP fields"
|
|
.IX Subsection "OSSL_PARAM fields"
|
|
.IP "\fIkey\fR" 4
|
|
.IX Item "key"
|
|
The identity of the parameter in the form of a string.
|
|
.IP "\fIdata_type\fR" 4
|
|
.IX Item "data_type"
|
|
The \fIdata_type\fR is a value that describes the type and organization of
|
|
the data.
|
|
See \*(L"Supported types\*(R" below for a description of the types.
|
|
.IP "\fIdata\fR" 4
|
|
.IX Item "data"
|
|
.PD 0
|
|
.IP "\fIdata_size\fR" 4
|
|
.IX Item "data_size"
|
|
.PD
|
|
\&\fIdata\fR is a pointer to the memory where the parameter data is (when
|
|
setting parameters) or shall (when requesting parameters) be stored,
|
|
and \fIdata_size\fR is its size in bytes.
|
|
The organization of the data depends on the parameter type and flag.
|
|
.Sp
|
|
When \fIrequesting parameters\fR, it's acceptable for \fIdata\fR to be \s-1NULL\s0.
|
|
This can be used by the \fIrequestor\fR to figure out dynamically exactly
|
|
how much buffer space is needed to store the parameter data.
|
|
In this case, \fIdata_size\fR is ignored.
|
|
.Sp
|
|
When the \fB\s-1OSSL_PARAM\s0\fR is used as a parameter descriptor, \fIdata\fR
|
|
should be ignored.
|
|
If \fIdata_size\fR is zero, it means that an arbitrary data size is
|
|
accepted, otherwise it specifies the maximum size allowed.
|
|
.IP "\fIreturn_size\fR" 4
|
|
.IX Item "return_size"
|
|
When an array of \fB\s-1OSSL_PARAM\s0\fR is used to request data, the
|
|
\&\fIresponder\fR must set this field to indicate size of the parameter
|
|
data, including padding as the case may be.
|
|
In case the \fIdata_size\fR is an unsuitable size for the data, the
|
|
\&\fIresponder\fR must still set this field to indicate the minimum data
|
|
size required.
|
|
(further notes on this in \*(L"\s-1NOTES\s0\*(R" below).
|
|
.Sp
|
|
When the \fB\s-1OSSL_PARAM\s0\fR is used as a parameter descriptor,
|
|
\&\fIreturn_size\fR should be ignored.
|
|
.PP
|
|
\&\fB\s-1NOTE:\s0\fR
|
|
.PP
|
|
The key names and associated types are defined by the entity that
|
|
offers these parameters, i.e. names for parameters provided by the
|
|
OpenSSL libraries are defined by the libraries, and names for
|
|
parameters provided by providers are defined by those providers,
|
|
except for the pointer form of strings (see data type descriptions
|
|
below).
|
|
Entities that want to set or request parameters need to know what
|
|
those keys are and of what type, any functionality between those two
|
|
entities should remain oblivious and just pass the \fB\s-1OSSL_PARAM\s0\fR array
|
|
along.
|
|
.SS "Supported types"
|
|
.IX Subsection "Supported types"
|
|
The \fIdata_type\fR field can be one of the following types:
|
|
.IP "\fB\s-1OSSL_PARAM_INTEGER\s0\fR" 4
|
|
.IX Item "OSSL_PARAM_INTEGER"
|
|
.PD 0
|
|
.IP "\fB\s-1OSSL_PARAM_UNSIGNED_INTEGER\s0\fR" 4
|
|
.IX Item "OSSL_PARAM_UNSIGNED_INTEGER"
|
|
.PD
|
|
The parameter data is an integer (signed or unsigned) of arbitrary
|
|
length, organized in native form, i.e. most significant byte first on
|
|
Big-Endian systems, and least significant byte first on Little-Endian
|
|
systems.
|
|
.IP "\fB\s-1OSSL_PARAM_REAL\s0\fR" 4
|
|
.IX Item "OSSL_PARAM_REAL"
|
|
The parameter data is a floating point value in native form.
|
|
.IP "\fB\s-1OSSL_PARAM_UTF8_STRING\s0\fR" 4
|
|
.IX Item "OSSL_PARAM_UTF8_STRING"
|
|
The parameter data is a printable string.
|
|
.IP "\fB\s-1OSSL_PARAM_OCTET_STRING\s0\fR" 4
|
|
.IX Item "OSSL_PARAM_OCTET_STRING"
|
|
The parameter data is an arbitrary string of bytes.
|
|
.IP "\fB\s-1OSSL_PARAM_UTF8_PTR\s0\fR" 4
|
|
.IX Item "OSSL_PARAM_UTF8_PTR"
|
|
The parameter data is a pointer to a printable string.
|
|
.Sp
|
|
The difference between this and \fB\s-1OSSL_PARAM_UTF8_STRING\s0\fR is that \fIdata\fR
|
|
doesn't point directly at the data, but to a pointer that points to the data.
|
|
.Sp
|
|
This is used to indicate that constant data is or will be passed,
|
|
and there is therefore no need to copy the data that is passed, just
|
|
the pointer to it.
|
|
.Sp
|
|
\&\fIdata_size\fR must be set to the size of the data, not the size of the
|
|
pointer to the data.
|
|
If this is used in a parameter request,
|
|
\&\fIdata_size\fR is not relevant. However, the \fIresponder\fR will set
|
|
\&\fIreturn_size\fR to the size of the data.
|
|
.Sp
|
|
Note that the use of this type is \fBfragile\fR and can only be safely
|
|
used for data that remains constant and in a constant location for a
|
|
long enough duration (such as the life-time of the entity that
|
|
offers these parameters).
|
|
.IP "\fB\s-1OSSL_PARAM_OCTET_PTR\s0\fR" 4
|
|
.IX Item "OSSL_PARAM_OCTET_PTR"
|
|
The parameter data is a pointer to an arbitrary string of bytes.
|
|
.Sp
|
|
The difference between this and \fB\s-1OSSL_PARAM_OCTET_STRING\s0\fR is that
|
|
\&\fIdata\fR doesn't point directly at the data, but to a pointer that
|
|
points to the data.
|
|
.Sp
|
|
This is used to indicate that constant data is or will be passed, and
|
|
there is therefore no need to copy the data that is passed, just the
|
|
pointer to it.
|
|
.Sp
|
|
\&\fIdata_size\fR must be set to the size of the data, not the size of the
|
|
pointer to the data.
|
|
If this is used in a parameter request,
|
|
\&\fIdata_size\fR is not relevant. However, the \fIresponder\fR will set
|
|
\&\fIreturn_size\fR to the size of the data.
|
|
.Sp
|
|
Note that the use of this type is \fBfragile\fR and can only be safely
|
|
used for data that remains constant and in a constant location for a
|
|
long enough duration (such as the life-time of the entity that
|
|
offers these parameters).
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
Both when setting and requesting parameters, the functions that are
|
|
called will have to decide what is and what is not an error.
|
|
The recommended behaviour is:
|
|
.IP "\(bu" 4
|
|
Keys that a \fIsetter\fR or \fIresponder\fR doesn't recognise should simply
|
|
be ignored.
|
|
That in itself isn't an error.
|
|
.IP "\(bu" 4
|
|
If the keys that a called \fIsetter\fR recognises form a consistent
|
|
enough set of data, that call should succeed.
|
|
.IP "\(bu" 4
|
|
Apart from the \fIreturn_size\fR, a \fIresponder\fR must never change the fields
|
|
of an \fB\s-1OSSL_PARAM\s0\fR.
|
|
To return a value, it should change the contents of the memory that
|
|
\&\fIdata\fR points at.
|
|
.IP "\(bu" 4
|
|
If the data type for a key that it's associated with is incorrect,
|
|
the called function may return an error.
|
|
.Sp
|
|
The called function may also try to convert the data to a suitable
|
|
form (for example, it's plausible to pass a large number as an octet
|
|
string, so even though a given key is defined as an
|
|
\&\fB\s-1OSSL_PARAM_UNSIGNED_INTEGER\s0\fR, is plausible to pass the value as an
|
|
\&\fB\s-1OSSL_PARAM_OCTET_STRING\s0\fR), but this is in no way mandatory.
|
|
.IP "\(bu" 4
|
|
If a \fIresponder\fR finds that some data sizes are too small for the
|
|
requested data, it must set \fIreturn_size\fR for each such
|
|
\&\fB\s-1OSSL_PARAM\s0\fR item to the minimum required size, and eventually return
|
|
an error.
|
|
.IP "\(bu" 4
|
|
For the integer type parameters (\fB\s-1OSSL_PARAM_UNSIGNED_INTEGER\s0\fR and
|
|
\&\fB\s-1OSSL_PARAM_INTEGER\s0\fR), a \fIresponder\fR may choose to return an error
|
|
if the \fIdata_size\fR isn't a suitable size (even if \fIdata_size\fR is
|
|
bigger than needed). If the \fIresponder\fR finds the size suitable, it
|
|
must fill all \fIdata_size\fR bytes and ensure correct padding for the
|
|
native endianness, and set \fIreturn_size\fR to the same value as
|
|
\&\fIdata_size\fR.
|
|
.SH "EXAMPLES"
|
|
.IX Header "EXAMPLES"
|
|
A couple of examples to just show how \fB\s-1OSSL_PARAM\s0\fR arrays could be
|
|
set up.
|
|
.PP
|
|
\fIExample 1\fR
|
|
.IX Subsection "Example 1"
|
|
.PP
|
|
This example is for setting parameters on some object:
|
|
.PP
|
|
.Vb 1
|
|
\& #include <openssl/core.h>
|
|
\&
|
|
\& const char *foo = "some string";
|
|
\& size_t foo_l = strlen(foo) + 1;
|
|
\& const char bar[] = "some other string";
|
|
\& OSSL_PARAM set[] = {
|
|
\& { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, 0 },
|
|
\& { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
|
|
\& { NULL, 0, NULL, 0, NULL }
|
|
\& };
|
|
.Ve
|
|
.PP
|
|
\fIExample 2\fR
|
|
.IX Subsection "Example 2"
|
|
.PP
|
|
This example is for requesting parameters on some object:
|
|
.PP
|
|
.Vb 9
|
|
\& const char *foo = NULL;
|
|
\& size_t foo_l;
|
|
\& char bar[1024];
|
|
\& size_t bar_l;
|
|
\& OSSL_PARAM request[] = {
|
|
\& { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, 0 },
|
|
\& { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
|
|
\& { NULL, 0, NULL, 0, NULL }
|
|
\& };
|
|
.Ve
|
|
.PP
|
|
A \fIresponder\fR that receives this array (as \fIparams\fR in this example)
|
|
could fill in the parameters like this:
|
|
.PP
|
|
.Vb 1
|
|
\& /* OSSL_PARAM *params */
|
|
\&
|
|
\& int i;
|
|
\&
|
|
\& for (i = 0; params[i].key != NULL; i++) {
|
|
\& if (strcmp(params[i].key, "foo") == 0) {
|
|
\& *(char **)params[i].data = "foo value";
|
|
\& params[i].return_size = 10; /* size of "foo value" */
|
|
\& } else if (strcmp(params[i].key, "bar") == 0) {
|
|
\& memcpy(params[i].data, "bar value", 10);
|
|
\& params[i].return_size = 10; /* size of "bar value" */
|
|
\& }
|
|
\& /* Ignore stuff we don\*(Aqt know */
|
|
\& }
|
|
.Ve
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fIopenssl\-core.h\fR\|(7), \fIOSSL_PARAM_get_int\fR\|(3)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
\&\fB\s-1OSSL_PARAM\s0\fR was added in OpenSSL 3.0.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2019 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>.
|