mirror of
https://github.com/openssl/openssl.git
synced 2024-12-21 06:09:35 +08:00
bb82531f65
OpenSSL uses some POD directives masquerading as 'comment'
('=for comment' etc). This is abusive and confusing. Instead, we use
our own keyword.
=for openssl whatever
=begin openssl
whatever
=end openssl
(we have never used the multiline form, but might start one day)
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10048)
345 lines
12 KiB
Plaintext
345 lines
12 KiB
Plaintext
=pod
|
|
|
|
=head1 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
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
=for openssl generic
|
|
|
|
#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);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
A collection of utility functions that simplify and add type safety to the
|
|
OSSL_PARAM arrays. The following B<TYPE> names are supported:
|
|
|
|
=over 1
|
|
|
|
=item *
|
|
|
|
double
|
|
|
|
=item *
|
|
|
|
int
|
|
|
|
=item *
|
|
|
|
int32 (int32_t)
|
|
|
|
=item *
|
|
|
|
int64 (int64_t)
|
|
|
|
=item *
|
|
|
|
long int (long)
|
|
|
|
=item *
|
|
|
|
size_t
|
|
|
|
=item *
|
|
|
|
uint32 (uint32_t)
|
|
|
|
=item *
|
|
|
|
uint64 (uint64_t)
|
|
|
|
=item *
|
|
|
|
unsigned int (uint)
|
|
|
|
=item *
|
|
|
|
unsigned long int (ulong)
|
|
|
|
=back
|
|
|
|
OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an
|
|
array of OSSL_PARAM structures.
|
|
Each of these macros defines a parameter of the specified B<TYPE> with the
|
|
provided B<key> and parameter variable B<address>.
|
|
|
|
OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(),
|
|
OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support
|
|
for defining UTF8 strings, OCTET strings and big numbers.
|
|
A parameter with name B<key> is defined.
|
|
The storage for this parameter is at B<address> and is of B<size> bytes.
|
|
|
|
OSSL_PARAM_END provides an end of parameter list marker.
|
|
This should terminate all OSSL_PARAM arrays.
|
|
|
|
OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM
|
|
records dynamically.
|
|
A parameter with name B<key> is created.
|
|
The parameter will use storage pointed to by B<buf> and return size of B<ret>.
|
|
|
|
OSSL_PARAM_construct_BN() is a function that constructs a large integer
|
|
OSSL_PARAM structure.
|
|
A parameter with name B<key>, storage B<buf>, size B<bsize> and return
|
|
size B<rsize> is created.
|
|
|
|
OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8
|
|
string OSSL_PARAM structure.
|
|
A parameter with name B<key>, storage B<buf> and size B<bsize> is created.
|
|
If B<bsize> is zero, the string length is determined using strlen(3).
|
|
|
|
OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET
|
|
string OSSL_PARAM structure.
|
|
A parameter with name B<key>, storage B<buf> and size B<bsize> is created.
|
|
|
|
OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string
|
|
pointer OSSL_PARAM structure.
|
|
A parameter with name B<key>, storage pointer B<*buf> and size B<bsize>
|
|
is created.
|
|
|
|
OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string
|
|
pointer OSSL_PARAM structure.
|
|
A parameter with name B<key>, storage pointer B<*buf> and size B<bsize>
|
|
is created.
|
|
|
|
OSSL_PARAM_construct_end() is a function that constructs the terminating
|
|
OSSL_PARAM structure.
|
|
|
|
OSSL_PARAM_locate() is a function that searches an B<array> of parameters for
|
|
the one matching the B<key> name.
|
|
|
|
OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for
|
|
the presence of I<const> for the B<array> argument and its return value.
|
|
|
|
OSSL_PARAM_get_TYPE() retrieves a value of type B<TYPE> from the parameter B<p>.
|
|
The value is copied to the address B<val>.
|
|
Type coercion takes place as discussed in the NOTES section.
|
|
|
|
OSSL_PARAM_set_TYPE() stores a value B<val> of type B<TYPE> into the parameter
|
|
B<p>.
|
|
If the parameter's I<data> field is NULL, then only its I<return_size> field
|
|
will be assigned the size the parameter's I<data> buffer should have.
|
|
Type coercion takes place as discussed in the NOTES section.
|
|
|
|
OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by B<p>.
|
|
The BIGNUM referenced by B<val> is updated and is allocated if B<*val> is
|
|
B<NULL>.
|
|
|
|
OSSL_PARAM_set_BN() stores the BIGNUM B<val> into the parameter B<p>.
|
|
If the parameter's I<data> field is NULL, then only its I<return_size> field
|
|
will be assigned the size the parameter's I<data> buffer should have.
|
|
|
|
OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter
|
|
pointed to by B<p>.
|
|
The string is either stored into B<*val> with a length limit of B<max_len> or,
|
|
in the case when B<*val> is B<NULL>, memory is allocated for the string and
|
|
B<max_len> is ignored.
|
|
If memory is allocated by this function, it must be freed by the caller.
|
|
|
|
OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to
|
|
by B<p> to the value referenced by B<val>.
|
|
If the parameter's I<data> field is NULL, then only its I<return_size> field
|
|
will be assigned the size the parameter's I<data> buffer should have.
|
|
|
|
OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter
|
|
pointed to by B<p>.
|
|
The OCTETs are either stored into B<*val> with a length limit of B<max_len> or,
|
|
in the case when B<*val> is B<NULL>, memory is allocated and
|
|
B<max_len> is ignored.
|
|
If memory is allocated by this function, it must be freed by the caller.
|
|
|
|
OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter
|
|
pointed to by B<p> to the value referenced by B<val>.
|
|
If the parameter's I<data> field is NULL, then only its I<return_size> field
|
|
will be assigned the size the parameter's I<data> buffer should have.
|
|
|
|
OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter
|
|
referenced by B<p> and stores it in B<*val>.
|
|
|
|
OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter
|
|
referenced by B<p> to the values B<val>.
|
|
|
|
OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter
|
|
referenced by B<p> and stores it in B<*val>.
|
|
The length of the OCTET string is stored in B<*used_len>.
|
|
|
|
OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter
|
|
referenced by B<p> to the values B<val>.
|
|
The length of the OCTET string is provided by B<used_len>.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(),
|
|
OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(),
|
|
OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr()
|
|
return a populated OSSL_PARAM structure.
|
|
|
|
OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to
|
|
the matching OSSL_PARAM object. They return B<NULL> on error or when
|
|
no object matching B<key> exists in the B<array>.
|
|
|
|
All other functions return B<1> on success and B<0> on failure.
|
|
|
|
=head1 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.
|
|
|
|
For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(),
|
|
B<bsize> is not relevant if the purpose is to send the B<OSSL_PARAM> array
|
|
to a I<responder>, i.e. to get parameter data back.
|
|
In that case, B<bsize> can safely be given zero.
|
|
See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the
|
|
possible purposes.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Reusing the examples from L<OSSL_PARAM(3)> to just show how
|
|
C<OSSL_PARAM> arrays can be handled using the macros and functions
|
|
defined herein.
|
|
|
|
=head2 Example 1
|
|
|
|
This example is for setting parameters on some object:
|
|
|
|
#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
|
|
};
|
|
|
|
=head2 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:
|
|
|
|
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
|
|
};
|
|
|
|
A I<responder> that receives this array (as C<params> in this example)
|
|
could fill in the parameters like this:
|
|
|
|
/* 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");
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<openssl-core.h(7)>, L<OSSL_PARAM(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
These APIs were introduced in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|