518 lines
21 KiB
Plaintext
518 lines
21 KiB
Plaintext
|
.\" 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 "OSSL_PARAM_INT 3ossl"
|
||
|
|
.TH OSSL_PARAM_INT 3ossl "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"
|
||
|
|
OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64,
|
||
|
|
OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint,
|
||
|
|
OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN,
|
||
|
|
OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr,
|
||
|
|
OSSL_PARAM_octet_ptr,
|
||
|
|
OSSL_PARAM_END, OSSL_PARAM_DEFN,
|
||
|
|
OSSL_PARAM_construct_double, OSSL_PARAM_construct_int,
|
||
|
|
OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64,
|
||
|
|
OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t,
|
||
|
|
OSSL_PARAM_construct_time_t, OSSL_PARAM_construct_uint,
|
||
|
|
OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64,
|
||
|
|
OSSL_PARAM_construct_ulong, OSSL_PARAM_construct_BN,
|
||
|
|
OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr,
|
||
|
|
OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr,
|
||
|
|
OSSL_PARAM_construct_end,
|
||
|
|
OSSL_PARAM_locate, OSSL_PARAM_locate_const,
|
||
|
|
OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32,
|
||
|
|
OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t,
|
||
|
|
OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32,
|
||
|
|
OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN,
|
||
|
|
OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string,
|
||
|
|
OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr,
|
||
|
|
OSSL_PARAM_get_utf8_string_ptr, OSSL_PARAM_get_octet_string_ptr,
|
||
|
|
OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32,
|
||
|
|
OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t,
|
||
|
|
OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32,
|
||
|
|
OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN,
|
||
|
|
OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string,
|
||
|
|
OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr,
|
||
|
|
OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified
|
||
|
|
\&\- OSSL_PARAM helpers
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.IX Header "SYNOPSIS"
|
||
|
|
.Vb 1
|
||
|
|
\& #include <openssl/params.h>
|
||
|
|
\&
|
||
|
|
\& /*
|
||
|
|
\& * TYPE in function names is one of:
|
||
|
|
\& * double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong
|
||
|
|
\& * Corresponding TYPE in function arguments is one of:
|
||
|
|
\& * double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t,
|
||
|
|
\& * uint64_t, unsigned long
|
||
|
|
\& */
|
||
|
|
\&
|
||
|
|
\& #define OSSL_PARAM_TYPE(key, address)
|
||
|
|
\& #define OSSL_PARAM_BN(key, address, size)
|
||
|
|
\& #define OSSL_PARAM_utf8_string(key, address, size)
|
||
|
|
\& #define OSSL_PARAM_octet_string(key, address, size)
|
||
|
|
\& #define OSSL_PARAM_utf8_ptr(key, address, size)
|
||
|
|
\& #define OSSL_PARAM_octet_ptr(key, address, size)
|
||
|
|
\& #define OSSL_PARAM_END
|
||
|
|
\&
|
||
|
|
\& #define OSSL_PARAM_UNMODIFIED
|
||
|
|
\&
|
||
|
|
\& #define OSSL_PARAM_DEFN(key, type, addr, sz) \e
|
||
|
|
\& { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED }
|
||
|
|
\&
|
||
|
|
\& OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf);
|
||
|
|
\& OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
|
||
|
|
\& size_t bsize);
|
||
|
|
\& OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
|
||
|
|
\& size_t bsize);
|
||
|
|
\& OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
|
||
|
|
\& size_t bsize);
|
||
|
|
\& OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
|
||
|
|
\& size_t bsize);
|
||
|
|
\& OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
|
||
|
|
\& size_t bsize);
|
||
|
|
\& OSSL_PARAM OSSL_PARAM_construct_end(void);
|
||
|
|
\&
|
||
|
|
\& OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
|
||
|
|
\& const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array,
|
||
|
|
\& const char *key);
|
||
|
|
\&
|
||
|
|
\& int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val);
|
||
|
|
\& int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val);
|
||
|
|
\&
|
||
|
|
\& int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val);
|
||
|
|
\& int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val);
|
||
|
|
\&
|
||
|
|
\& int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
|
||
|
|
\& size_t max_len);
|
||
|
|
\& int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val);
|
||
|
|
\&
|
||
|
|
\& int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val,
|
||
|
|
\& size_t max_len, size_t *used_len);
|
||
|
|
\& int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len);
|
||
|
|
\&
|
||
|
|
\& int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val);
|
||
|
|
\& int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val);
|
||
|
|
\&
|
||
|
|
\& int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val,
|
||
|
|
\& size_t *used_len);
|
||
|
|
\& int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val,
|
||
|
|
\& size_t used_len);
|
||
|
|
\&
|
||
|
|
\& int OSSL_PARAM_get_utf8_string_ptr(const OSSL_PARAM *p, const char **val);
|
||
|
|
\& int OSSL_PARAM_get_octet_string_ptr(const OSSL_PARAM *p, const void **val,
|
||
|
|
\& size_t *used_len);
|
||
|
|
\&
|
||
|
|
\& int OSSL_PARAM_modified(const OSSL_PARAM *param);
|
||
|
|
\& void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params);
|
||
|
|
.Ve
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.IX Header "DESCRIPTION"
|
||
|
|
A collection of utility functions that simplify and add type safety to the
|
||
|
|
\&\s-1\fIOSSL_PARAM\s0\fR\|(3) arrays. The following \fB\f(BI\s-1TYPE\s0\fB\fR names are supported:
|
||
|
|
.IP "\(bu" 2
|
||
|
|
double
|
||
|
|
.IP "\(bu" 2
|
||
|
|
int
|
||
|
|
.IP "\(bu" 2
|
||
|
|
int32 (int32_t)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
int64 (int64_t)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
long int (long)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
time_t
|
||
|
|
.IP "\(bu" 2
|
||
|
|
size_t
|
||
|
|
.IP "\(bu" 2
|
||
|
|
uint32 (uint32_t)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
uint64 (uint64_t)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
unsigned int (uint)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
unsigned long int (ulong)
|
||
|
|
.PP
|
||
|
|
\&\s-1\fIOSSL_PARAM_TYPE\s0()\fR are a series of macros designed to assist initialising an
|
||
|
|
array of \s-1\fIOSSL_PARAM\s0\fR\|(3) structures.
|
||
|
|
Each of these macros defines a parameter of the specified \fB\f(BI\s-1TYPE\s0\fB\fR with the
|
||
|
|
provided \fIkey\fR and parameter variable \fIaddress\fR.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_utf8_string()\fR, \fIOSSL_PARAM_octet_string()\fR, \fIOSSL_PARAM_utf8_ptr()\fR,
|
||
|
|
\&\fIOSSL_PARAM_octet_ptr()\fR, \s-1\fIOSSL_PARAM_BN\s0()\fR are macros that provide support
|
||
|
|
for defining \s-1UTF8\s0 strings, \s-1OCTET\s0 strings and big numbers.
|
||
|
|
A parameter with name \fIkey\fR is defined.
|
||
|
|
The storage for this parameter is at \fIaddress\fR and is of \fIsize\fR bytes.
|
||
|
|
.PP
|
||
|
|
\&\s-1OSSL_PARAM_END\s0 provides an end of parameter list marker.
|
||
|
|
This should terminate all \s-1\fIOSSL_PARAM\s0\fR\|(3) arrays.
|
||
|
|
.PP
|
||
|
|
The \s-1\fIOSSL_PARAM_DEFN\s0()\fR macro provides the ability to construct a single
|
||
|
|
\&\s-1\fIOSSL_PARAM\s0\fR\|(3) (typically used in the construction of \fB\s-1OSSL_PARAM\s0\fR arrays). The
|
||
|
|
\&\fIkey\fR, \fItype\fR, \fIaddr\fR and \fIsz\fR arguments correspond to the \fIkey\fR,
|
||
|
|
\&\fIdata_type\fR, \fIdata\fR and \fIdata_size\fR fields of the \s-1\fIOSSL_PARAM\s0\fR\|(3) structure as
|
||
|
|
described on the \s-1\fIOSSL_PARAM\s0\fR\|(3) page.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_construct_TYPE()\fR are a series of functions that create \s-1\fIOSSL_PARAM\s0\fR\|(3)
|
||
|
|
records dynamically.
|
||
|
|
A parameter with name \fIkey\fR is created.
|
||
|
|
The parameter will use storage pointed to by \fIbuf\fR and return size of \fIret\fR.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_construct_BN()\fR is a function that constructs a large integer
|
||
|
|
\&\s-1\fIOSSL_PARAM\s0\fR\|(3) structure.
|
||
|
|
A parameter with name \fIkey\fR, storage \fIbuf\fR, size \fIbsize\fR and return
|
||
|
|
size \fIrsize\fR is created.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_construct_utf8_string()\fR is a function that constructs a \s-1UTF8\s0
|
||
|
|
string \s-1\fIOSSL_PARAM\s0\fR\|(3) structure.
|
||
|
|
A parameter with name \fIkey\fR, storage \fIbuf\fR and size \fIbsize\fR is created.
|
||
|
|
If \fIbsize\fR is zero, the string length is determined using \fIstrlen\fR\|(3).
|
||
|
|
Generally pass zero for \fIbsize\fR instead of calling \fIstrlen\fR\|(3) yourself.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_construct_octet_string()\fR is a function that constructs an \s-1OCTET\s0
|
||
|
|
string \s-1\fIOSSL_PARAM\s0\fR\|(3) structure.
|
||
|
|
A parameter with name \fIkey\fR, storage \fIbuf\fR and size \fIbsize\fR is created.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_construct_utf8_ptr()\fR is a function that constructs a \s-1UTF8\s0 string
|
||
|
|
pointer \s-1\fIOSSL_PARAM\s0\fR\|(3) structure.
|
||
|
|
A parameter with name \fIkey\fR, storage pointer \fI*buf\fR and size \fIbsize\fR
|
||
|
|
is created.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_construct_octet_ptr()\fR is a function that constructs an \s-1OCTET\s0 string
|
||
|
|
pointer \s-1\fIOSSL_PARAM\s0\fR\|(3) structure.
|
||
|
|
A parameter with name \fIkey\fR, storage pointer \fI*buf\fR and size \fIbsize\fR
|
||
|
|
is created.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_construct_end()\fR is a function that constructs the terminating
|
||
|
|
\&\s-1\fIOSSL_PARAM\s0\fR\|(3) structure.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_locate()\fR is a function that searches an \fIarray\fR of parameters for
|
||
|
|
the one matching the \fIkey\fR name.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_locate_const()\fR behaves exactly like \fIOSSL_PARAM_locate()\fR except for
|
||
|
|
the presence of \fIconst\fR for the \fIarray\fR argument and its return value.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_TYPE()\fR retrieves a value of type \fB\f(BI\s-1TYPE\s0\fB\fR from the parameter
|
||
|
|
\&\fIp\fR.
|
||
|
|
The value is copied to the address \fIval\fR.
|
||
|
|
Type coercion takes place as discussed in the \s-1NOTES\s0 section.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_set_TYPE()\fR stores a value \fIval\fR of type \fB\f(BI\s-1TYPE\s0\fB\fR into the
|
||
|
|
parameter \fIp\fR.
|
||
|
|
If the parameter's \fIdata\fR field is \s-1NULL,\s0 then only its \fIreturn_size\fR field
|
||
|
|
will be assigned the size the parameter's \fIdata\fR buffer should have.
|
||
|
|
Type coercion takes place as discussed in the \s-1NOTES\s0 section.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_BN()\fR retrieves a \s-1BIGNUM\s0 from the parameter pointed to by \fIp\fR.
|
||
|
|
The \s-1BIGNUM\s0 referenced by \fIval\fR is updated and is allocated if \fI*val\fR is
|
||
|
|
\&\s-1NULL.\s0
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_set_BN()\fR stores the \s-1BIGNUM \s0\fIval\fR into the parameter \fIp\fR.
|
||
|
|
If the parameter's \fIdata\fR field is \s-1NULL,\s0 then only its \fIreturn_size\fR field
|
||
|
|
will be assigned the size the parameter's \fIdata\fR buffer should have.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_utf8_string()\fR retrieves a \s-1UTF8\s0 string from the parameter
|
||
|
|
pointed to by \fIp\fR.
|
||
|
|
The string is stored into \fI*val\fR with a size limit of \fImax_len\fR,
|
||
|
|
which must be large enough to accommodate a terminating \s-1NUL\s0 byte,
|
||
|
|
otherwise this function will fail.
|
||
|
|
If \fI*val\fR is \s-1NULL,\s0 memory is allocated for the string (including the
|
||
|
|
terminating \s-1NUL\s0 byte) and \fImax_len\fR is ignored.
|
||
|
|
If memory is allocated by this function, it must be freed by the caller.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_set_utf8_string()\fR sets a \s-1UTF8\s0 string from the parameter pointed to
|
||
|
|
by \fIp\fR to the value referenced by \fIval\fR.
|
||
|
|
If the parameter's \fIdata\fR field isn't \s-1NULL,\s0 its \fIdata_size\fR must indicate
|
||
|
|
that the buffer is large enough to accommodate the string that \fIval\fR points at,
|
||
|
|
not including the terminating \s-1NUL\s0 byte, or this function will fail.
|
||
|
|
A terminating \s-1NUL\s0 byte is added only if the parameter's \fIdata_size\fR indicates
|
||
|
|
the buffer is longer than the string length, otherwise the string will not be
|
||
|
|
\&\s-1NUL\s0 terminated.
|
||
|
|
If the parameter's \fIdata\fR field is \s-1NULL,\s0 then only its \fIreturn_size\fR field
|
||
|
|
will be assigned the minimum size the parameter's \fIdata\fR buffer should have
|
||
|
|
to accommodate the string, not including a terminating \s-1NUL\s0 byte.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_octet_string()\fR retrieves an \s-1OCTET\s0 string from the parameter
|
||
|
|
pointed to by \fIp\fR.
|
||
|
|
The OCTETs are either stored into \fI*val\fR with a length limit of \fImax_len\fR or,
|
||
|
|
in the case when \fI*val\fR is \s-1NULL,\s0 memory is allocated and
|
||
|
|
\&\fImax_len\fR is ignored. \fI*used_len\fR is populated with the number of OCTETs
|
||
|
|
stored. If \fIval\fR is \s-1NULL\s0 then the \s-1OCTETS\s0 are not stored, but \fI*used_len\fR is
|
||
|
|
still populated.
|
||
|
|
If memory is allocated by this function, it must be freed by the caller.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_set_octet_string()\fR sets an \s-1OCTET\s0 string from the parameter
|
||
|
|
pointed to by \fIp\fR to the value referenced by \fIval\fR.
|
||
|
|
If the parameter's \fIdata\fR field is \s-1NULL,\s0 then only its \fIreturn_size\fR field
|
||
|
|
will be assigned the size the parameter's \fIdata\fR buffer should have.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_utf8_ptr()\fR retrieves the \s-1UTF8\s0 string pointer from the parameter
|
||
|
|
referenced by \fIp\fR and stores it in \fI*val\fR.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_set_utf8_ptr()\fR sets the \s-1UTF8\s0 string pointer in the parameter
|
||
|
|
referenced by \fIp\fR to the values \fIval\fR.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_octet_ptr()\fR retrieves the \s-1OCTET\s0 string pointer from the parameter
|
||
|
|
referenced by \fIp\fR and stores it in \fI*val\fR.
|
||
|
|
The length of the \s-1OCTET\s0 string is stored in \fI*used_len\fR.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_set_octet_ptr()\fR sets the \s-1OCTET\s0 string pointer in the parameter
|
||
|
|
referenced by \fIp\fR to the values \fIval\fR.
|
||
|
|
The length of the \s-1OCTET\s0 string is provided by \fIused_len\fR.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_utf8_string_ptr()\fR retrieves the pointer to a \s-1UTF8\s0 string from
|
||
|
|
the parameter pointed to by \fIp\fR, and stores that pointer in \fI*val\fR.
|
||
|
|
This is different from \fIOSSL_PARAM_get_utf8_string()\fR, which copies the
|
||
|
|
string.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_octet_string_ptr()\fR retrieves the pointer to a octet string
|
||
|
|
from the parameter pointed to by \fIp\fR, and stores that pointer in \fI*val\fR,
|
||
|
|
along with the string's length in \fI*used_len\fR.
|
||
|
|
This is different from \fIOSSL_PARAM_get_octet_string()\fR, which copies the
|
||
|
|
string.
|
||
|
|
.PP
|
||
|
|
The \s-1OSSL_PARAM_UNMODIFIED\s0 macro is used to detect if a parameter was set. On
|
||
|
|
creation, via either the macros or construct calls, the \fIreturn_size\fR field
|
||
|
|
is set to this. If the parameter is set using the calls defined herein, the
|
||
|
|
\&\fIreturn_size\fR field is changed.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_modified()\fR queries if the parameter \fIparam\fR has been set or not
|
||
|
|
using the calls defined herein.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_set_all_unmodified()\fR resets the unused indicator for all parameters
|
||
|
|
in the array \fIparams\fR.
|
||
|
|
.SH "RETURN VALUES"
|
||
|
|
.IX Header "RETURN VALUES"
|
||
|
|
\&\fIOSSL_PARAM_construct_TYPE()\fR, \fIOSSL_PARAM_construct_BN()\fR,
|
||
|
|
\&\fIOSSL_PARAM_construct_utf8_string()\fR, \fIOSSL_PARAM_construct_octet_string()\fR,
|
||
|
|
\&\fIOSSL_PARAM_construct_utf8_ptr()\fR and \fIOSSL_PARAM_construct_octet_ptr()\fR
|
||
|
|
return a populated \s-1\fIOSSL_PARAM\s0\fR\|(3) structure.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_locate()\fR and \fIOSSL_PARAM_locate_const()\fR return a pointer to
|
||
|
|
the matching \s-1\fIOSSL_PARAM\s0\fR\|(3) object. They return \s-1NULL\s0 on error or when
|
||
|
|
no object matching \fIkey\fR exists in the \fIarray\fR.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_modified()\fR returns 1 if the parameter was set and 0 otherwise.
|
||
|
|
.PP
|
||
|
|
All other functions return 1 on success and 0 on failure.
|
||
|
|
.SH "NOTES"
|
||
|
|
.IX Header "NOTES"
|
||
|
|
Native types will be converted as required only if the value is exactly
|
||
|
|
representable by the target type or parameter.
|
||
|
|
Apart from that, the functions must be used appropriately for the
|
||
|
|
expected type of the parameter.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_PARAM_get_BN()\fR and \fIOSSL_PARAM_set_BN()\fR only support nonnegative
|
||
|
|
\&\fB\s-1BIGNUM\s0\fRs when the desired data type is \fB\s-1OSSL_PARAM_UNSIGNED_INTEGER\s0\fR.
|
||
|
|
\&\fIOSSL_PARAM_construct_BN()\fR currently constructs an \s-1\fIOSSL_PARAM\s0\fR\|(3) structure
|
||
|
|
with the data type \fB\s-1OSSL_PARAM_UNSIGNED_INTEGER\s0\fR.
|
||
|
|
.PP
|
||
|
|
For \fIOSSL_PARAM_construct_utf8_ptr()\fR and \fIOSSL_PARAM_consstruct_octet_ptr()\fR,
|
||
|
|
\&\fIbsize\fR is not relevant if the purpose is to send the \s-1\fIOSSL_PARAM\s0\fR\|(3) array
|
||
|
|
to a \fIresponder\fR, i.e. to get parameter data back.
|
||
|
|
In that case, \fIbsize\fR can safely be given zero.
|
||
|
|
See \*(L"\s-1DESCRIPTION\*(R"\s0 in \s-1\fIOSSL_PARAM\s0\fR\|(3) for further information on the
|
||
|
|
possible purposes.
|
||
|
|
.SH "EXAMPLES"
|
||
|
|
.IX Header "EXAMPLES"
|
||
|
|
Reusing the examples from \s-1\fIOSSL_PARAM\s0\fR\|(3) to just show how
|
||
|
|
\&\s-1\fIOSSL_PARAM\s0\fR\|(3) arrays can be handled using the macros and functions
|
||
|
|
defined herein.
|
||
|
|
.SS "Example 1"
|
||
|
|
.IX Subsection "Example 1"
|
||
|
|
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);
|
||
|
|
\& const char bar[] = "some other string";
|
||
|
|
\& const OSSL_PARAM set[] = {
|
||
|
|
\& OSSL_PARAM_utf8_ptr("foo", &foo, foo_l),
|
||
|
|
\& OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) \- 1),
|
||
|
|
\& OSSL_PARAM_END
|
||
|
|
\& };
|
||
|
|
.Ve
|
||
|
|
.SS "Example 2"
|
||
|
|
.IX Subsection "Example 2"
|
||
|
|
This example is for requesting parameters on some object, and also
|
||
|
|
demonstrates that the requester isn't obligated to request all
|
||
|
|
available parameters:
|
||
|
|
.PP
|
||
|
|
.Vb 7
|
||
|
|
\& const char *foo = NULL;
|
||
|
|
\& char bar[1024];
|
||
|
|
\& OSSL_PARAM request[] = {
|
||
|
|
\& OSSL_PARAM_utf8_ptr("foo", &foo, 0),
|
||
|
|
\& OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
|
||
|
|
\& OSSL_PARAM_END
|
||
|
|
\& };
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
A \fIresponder\fR that receives this array (as \f(CW\*(C`params\*(C'\fR in this example)
|
||
|
|
could fill in the parameters like this:
|
||
|
|
.PP
|
||
|
|
.Vb 1
|
||
|
|
\& /* OSSL_PARAM *params */
|
||
|
|
\&
|
||
|
|
\& OSSL_PARAM *p;
|
||
|
|
\&
|
||
|
|
\& if ((p = OSSL_PARAM_locate(params, "foo")) != NULL)
|
||
|
|
\& OSSL_PARAM_set_utf8_ptr(p, "foo value");
|
||
|
|
\& if ((p = OSSL_PARAM_locate(params, "bar")) != NULL)
|
||
|
|
\& OSSL_PARAM_set_utf8_string(p, "bar value");
|
||
|
|
\& if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL)
|
||
|
|
\& OSSL_PARAM_set_utf8_ptr(p, "cookie value");
|
||
|
|
.Ve
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IX Header "SEE ALSO"
|
||
|
|
\&\fIopenssl\-core.h\fR\|(7), \s-1\fIOSSL_PARAM\s0\fR\|(3)
|
||
|
|
.SH "HISTORY"
|
||
|
|
.IX Header "HISTORY"
|
||
|
|
These APIs were 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>.
|