445 lines
17 KiB
Groff
Executable File
445 lines
17 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_INT 3"
|
|
.TH OSSL_PARAM_INT 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_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64,
|
|
OSSL_PARAM_long, OSSL_PARAM_size_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_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_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_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_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_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 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, uint, uint32, uint64, ulong
|
|
\& * Corresponding TYPE in function arguments is one of:
|
|
\& * double, int, int32_t, int64_t, long, size_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
|
|
\&
|
|
\& 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);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
A collection of utility functions that simplify and add type safety to the
|
|
\&\s-1OSSL_PARAM\s0 arrays. The following \fB\s-1TYPE\s0\fR names are supported:
|
|
.IP "\(bu" 1
|
|
double
|
|
.IP "\(bu" 1
|
|
int
|
|
.IP "\(bu" 1
|
|
int32 (int32_t)
|
|
.IP "\(bu" 1
|
|
int64 (int64_t)
|
|
.IP "\(bu" 1
|
|
long int (long)
|
|
.IP "\(bu" 1
|
|
size_t
|
|
.IP "\(bu" 1
|
|
uint32 (uint32_t)
|
|
.IP "\(bu" 1
|
|
uint64 (uint64_t)
|
|
.IP "\(bu" 1
|
|
unsigned int (uint)
|
|
.IP "\(bu" 1
|
|
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-1OSSL_PARAM\s0 structures.
|
|
Each of these macros defines a parameter of the specified \fB\s-1TYPE\s0\fR with the
|
|
provided \fBkey\fR and parameter variable \fBaddress\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 \fBkey\fR is defined.
|
|
The storage for this parameter is at \fBaddress\fR and is of \fBsize\fR bytes.
|
|
.PP
|
|
\&\s-1OSSL_PARAM_END\s0 provides an end of parameter list marker.
|
|
This should terminate all \s-1OSSL_PARAM\s0 arrays.
|
|
.PP
|
|
\&\fIOSSL_PARAM_construct_TYPE()\fR are a series of functions that create \s-1OSSL_PARAM\s0
|
|
records dynamically.
|
|
A parameter with name \fBkey\fR is created.
|
|
The parameter will use storage pointed to by \fBbuf\fR and return size of \fBret\fR.
|
|
.PP
|
|
\&\fIOSSL_PARAM_construct_BN()\fR is a function that constructs a large integer
|
|
\&\s-1OSSL_PARAM\s0 structure.
|
|
A parameter with name \fBkey\fR, storage \fBbuf\fR, size \fBbsize\fR and return
|
|
size \fBrsize\fR is created.
|
|
.PP
|
|
\&\fIOSSL_PARAM_construct_utf8_string()\fR is a function that constructs a \s-1UTF8\s0
|
|
string \s-1OSSL_PARAM\s0 structure.
|
|
A parameter with name \fBkey\fR, storage \fBbuf\fR and size \fBbsize\fR is created.
|
|
If \fBbsize\fR is zero, the string length is determined using \fIstrlen\fR\|(3) + 1 for the
|
|
null termination byte.
|
|
Generally pass zero for \fBbsize\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-1OSSL_PARAM\s0 structure.
|
|
A parameter with name \fBkey\fR, storage \fBbuf\fR and size \fBbsize\fR is created.
|
|
.PP
|
|
\&\fIOSSL_PARAM_construct_utf8_ptr()\fR is a function that constructes a \s-1UTF\s0 string
|
|
pointer \s-1OSSL_PARAM\s0 structure.
|
|
A parameter with name \fBkey\fR, storage pointer \fB*buf\fR and size \fBbsize\fR
|
|
is created.
|
|
.PP
|
|
\&\fIOSSL_PARAM_construct_octet_ptr()\fR is a function that constructes an \s-1OCTET\s0 string
|
|
pointer \s-1OSSL_PARAM\s0 structure.
|
|
A parameter with name \fBkey\fR, storage pointer \fB*buf\fR and size \fBbsize\fR
|
|
is created.
|
|
.PP
|
|
\&\fIOSSL_PARAM_construct_end()\fR is a function that constructs the terminating
|
|
\&\s-1OSSL_PARAM\s0 structure.
|
|
.PP
|
|
\&\fIOSSL_PARAM_locate()\fR is a function that searches an \fBarray\fR of parameters for
|
|
the one matching the \fBkey\fR name.
|
|
.PP
|
|
\&\fIOSSL_PARAM_locate_const()\fR behaves exactly like \fIOSSL_PARAM_locate()\fR except for
|
|
the presence of \fIconst\fR for the \fBarray\fR argument and its return value.
|
|
.PP
|
|
\&\fIOSSL_PARAM_get_TYPE()\fR retrieves a value of type \fB\s-1TYPE\s0\fR from the parameter \fBp\fR.
|
|
The value is copied to the address \fBval\fR.
|
|
Type coercion takes place as discussed in the \s-1NOTES\s0 section.
|
|
.PP
|
|
\&\fIOSSL_PARAM_set_TYPE()\fR stores a value \fBval\fR of type \fB\s-1TYPE\s0\fR into the parameter
|
|
\&\fBp\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 \fBp\fR.
|
|
The \s-1BIGNUM\s0 referenced by \fBval\fR is updated and is allocated if \fB*val\fR is
|
|
\&\fB\s-1NULL\s0\fR.
|
|
.PP
|
|
\&\fIOSSL_PARAM_set_BN()\fR stores the \s-1BIGNUM\s0 \fBval\fR into the parameter \fBp\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 \fBp\fR.
|
|
The string is either stored into \fB*val\fR with a length limit of \fBmax_len\fR or,
|
|
in the case when \fB*val\fR is \fB\s-1NULL\s0\fR, memory is allocated for the string and
|
|
\&\fBmax_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 \fBp\fR to the value referenced by \fBval\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_octet_string()\fR retrieves an \s-1OCTET\s0 string from the parameter
|
|
pointed to by \fBp\fR.
|
|
The OCTETs are either stored into \fB*val\fR with a length limit of \fBmax_len\fR or,
|
|
in the case when \fB*val\fR is \fB\s-1NULL\s0\fR, memory is allocated and
|
|
\&\fBmax_len\fR is ignored.
|
|
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 \fBp\fR to the value referenced by \fBval\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 \fBp\fR and stores it in \fB*val\fR.
|
|
.PP
|
|
\&\fIOSSL_PARAM_set_utf8_ptr()\fR sets the \s-1UTF8\s0 string pointer in the parameter
|
|
referenced by \fBp\fR to the values \fBval\fR.
|
|
.PP
|
|
\&\fIOSSL_PARAM_get_octet_ptr()\fR retrieves the \s-1OCTET\s0 string pointer from the parameter
|
|
referenced by \fBp\fR and stores it in \fB*val\fR.
|
|
The length of the \s-1OCTET\s0 string is stored in \fB*used_len\fR.
|
|
.PP
|
|
\&\fIOSSL_PARAM_set_octet_ptr()\fR sets the \s-1OCTET\s0 string pointer in the parameter
|
|
referenced by \fBp\fR to the values \fBval\fR.
|
|
The length of the \s-1OCTET\s0 string is provided by \fBused_len\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-1OSSL_PARAM\s0 structure.
|
|
.PP
|
|
\&\fIOSSL_PARAM_locate()\fR and \fIOSSL_PARAM_locate_const()\fR return a pointer to
|
|
the matching \s-1OSSL_PARAM\s0 object. They return \fB\s-1NULL\s0\fR on error or when
|
|
no object matching \fBkey\fR exists in the \fBarray\fR.
|
|
.PP
|
|
All other functions return \fB1\fR on success and \fB0\fR 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
|
|
For \fIOSSL_PARAM_construct_utf8_ptr()\fR and \fIOSSL_PARAM_consstruct_octet_ptr()\fR,
|
|
\&\fBbsize\fR is not relevant if the purpose is to send the \fB\s-1OSSL_PARAM\s0\fR array
|
|
to a \fIresponder\fR, i.e. to get parameter data back.
|
|
In that case, \fBbsize\fR can safely be given zero.
|
|
See \*(L"\s-1DESCRIPTION\s0\*(R" 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
|
|
\&\f(CW\*(C`OSSL_PARAM\*(C'\fR 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) + 1;
|
|
\& 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)),
|
|
\& 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 requestor 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_ptr(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 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>.
|