Browse Source

OSSL_PARAM helper functions.

Provide a number of functions to allow parameters to be set and
retrieved in a type safe manner.  Functions are provided for many
integral types plus double, BIGNUM, UTF8 strings and OCTET strings.

All of the integer functions will widen the parameter data as
required.  This permits a degree of malleability in the parameter
definition.  For example a type can be changed from a thirty two bit
integer to a sixty four bit one without changing application code.
Only four and eight byte integral sizes are supported here.

A pair of real functions are available for doubles.

A pair of functions is available for BIGNUMs.  These accept any sized
unsigned integer input and convert to/from a BIGNUM.

For each OCTET and UTF8 strings, four functions are defined.  This
provide get and set functionality for string and for pointers to
strings.  The latter avoiding copies but have other inherent risks.

Finally, some utility macros and functions are defined to allow
OSSL_PARAM definition arrays to be specified in a simple manner.
There are two macro and one function for most types.  The exception
being BIGNUM, for which there is one macro and one function.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8451)
master
Pauli 3 years ago
committed by Richard Levitte
parent
commit
7ffbd7ca96
12 changed files with 1942 additions and 43 deletions
  1. +1
    -1
      crypto/build.info
  2. +725
    -0
      crypto/params.c
  3. +29
    -28
      doc/man3/OSSL_PARAM.pod
  4. +312
    -0
      doc/man3/OSSL_PARAM_TYPE.pod
  5. +20
    -13
      include/openssl/core.h
  6. +186
    -0
      include/openssl/params.h
  7. +5
    -1
      test/build.info
  8. +627
    -0
      test/params_api_test.c
  9. +12
    -0
      test/recipes/03-test_params_api.t
  10. +9
    -0
      test/testutil.h
  11. +1
    -0
      test/testutil/tests.c
  12. +15
    -0
      util/private.num

+ 1
- 1
crypto/build.info View File

@ -17,7 +17,7 @@ SOURCE[../libcrypto]=\
ebcdic.c uid.c o_time.c o_str.c o_dir.c o_fopen.c ctype.c \
threads_pthread.c threads_win.c threads_none.c getenv.c \
o_init.c o_fips.c mem_sec.c init.c context.c sparse_array.c \
trace.c provider.c \
trace.c provider.c params.c \
{- $target{cpuid_asm_src} -} {- $target{uplink_aux_src} -}
DEPEND[cversion.o]=buildinf.h


+ 725
- 0
crypto/params.c View File

@ -0,0 +1,725 @@
/*
* Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
* Copyright (c) 2019, Oracle and/or its affiliates. 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
* https://www.openssl.org/source/license.html
*/
#include <string.h>
#include <openssl/params.h>
#include "internal/thread_once.h"
#define SET_RETURN_SIZE(p, sz) \
if ((p)->return_size != NULL) \
*(p)->return_size = (sz)
const OSSL_PARAM *OSSL_PARAM_locate(const OSSL_PARAM *p, const char *key)
{
if (p != NULL && key != NULL)
for (; p->key != NULL; p++)
if (strcmp(key, p->key) == 0)
return p;
return NULL;
}
static OSSL_PARAM ossl_param_construct(const char *key, unsigned int data_type,
void *data, size_t data_size,
size_t *return_size)
{
OSSL_PARAM res;
res.key = key;
res.data_type = data_type;
res.data = data;
res.data_size = data_size;
res.return_size = return_size;
return res;
}
int OSSL_PARAM_get_int(const OSSL_PARAM *p, int *val)
{
if (val == NULL || p == NULL || p->data_type != OSSL_PARAM_INTEGER)
return 0;
switch (p->data_size) {
case sizeof(int32_t):
if (sizeof(int) >= sizeof(int32_t)) {
*val = (int)*(const int32_t *)p->data;
return 1;
}
break;
case sizeof(int64_t):
if (sizeof(int) >= sizeof(int64_t)) {
*val = (int)*(const int64_t *)p->data;
return 1;
}
break;
}
return 0;
}
int OSSL_PARAM_set_int(const OSSL_PARAM *p, int val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(int)); /* Minimum expected size */
switch (p->data_size) {
case sizeof(int32_t):
if (sizeof(int32_t) >= sizeof(int)) {
SET_RETURN_SIZE(p, sizeof(int32_t));
*(int32_t *)p->data = (int32_t)val;
return 1;
}
break;
case sizeof(int64_t):
if (sizeof(int64_t) >= sizeof(int)) {
SET_RETURN_SIZE(p, sizeof(int64_t));
*(int64_t *)p->data = (int64_t)val;
return 1;
}
break;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_int(const char *key, int *buf, size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_INTEGER, buf, sizeof(int),
rsize);
}
int OSSL_PARAM_get_uint(const OSSL_PARAM *p, unsigned int *val)
{
if (val == NULL
|| p == NULL
|| (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER))
return 0;
switch (p->data_size) {
case sizeof(uint32_t):
if (sizeof(unsigned int) >= sizeof(uint32_t)) {
*val = (unsigned int)*(const uint32_t *)p->data;
return 1;
}
break;
case sizeof(uint64_t):
if (sizeof(unsigned int) >= sizeof(uint64_t)) {
*val = (unsigned int)*(const uint64_t *)p->data;
return 1;
}
break;
}
return 0;
}
int OSSL_PARAM_set_uint(const OSSL_PARAM *p, unsigned int val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(unsigned int)); /* Minimum expected size */
switch (p->data_size) {
case sizeof(uint32_t):
if (sizeof(uint32_t) >= sizeof(unsigned int)) {
SET_RETURN_SIZE(p, sizeof(uint32_t));
*(uint32_t *)p->data = (uint32_t)val;
return 1;
}
break;
case sizeof(uint64_t):
if (sizeof(uint64_t) >= sizeof(unsigned int)) {
SET_RETURN_SIZE(p, sizeof(uint64_t));
*(uint64_t *)p->data = (uint64_t)val;
return 1;
}
break;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_uint(const char *key, unsigned int *buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_UNSIGNED_INTEGER, buf,
sizeof(unsigned int), rsize);
}
int OSSL_PARAM_get_long(const OSSL_PARAM *p, long int *val)
{
if (val == NULL || p == NULL || (p->data_type != OSSL_PARAM_INTEGER))
return 0;
switch (p->data_size) {
case sizeof(int32_t):
if (sizeof(long int) >= sizeof(int32_t)) {
*val = (long int)*(const int32_t *)p->data;
return 1;
} break;
case sizeof(int64_t):
if (sizeof(long int) >= sizeof(int64_t)) {
*val = (long int)*(const int64_t *)p->data;
return 1;
}
break;
}
return 0;
}
int OSSL_PARAM_set_long(const OSSL_PARAM *p, long int val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(long int)); /* Minimum expected size */
switch (p->data_size) {
case sizeof(int32_t):
if (sizeof(int32_t) >= sizeof(long int)) {
SET_RETURN_SIZE(p, sizeof(int32_t));
*(int32_t *)p->data = (int32_t)val;
return 1;
}
break;
case sizeof(int64_t):
if (sizeof(int64_t) >= sizeof(long int)) {
SET_RETURN_SIZE(p, sizeof(int64_t));
*(int64_t *)p->data = (int64_t)val;
return 1;
}
break;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_long(const char *key, long int *buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_INTEGER, buf, sizeof(long int),
rsize);
}
int OSSL_PARAM_get_ulong(const OSSL_PARAM *p, unsigned long int *val)
{
if (val == NULL
|| p == NULL
|| (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER))
return 0;
switch (p->data_size) {
case sizeof(uint32_t):
if (sizeof(unsigned long int) >= sizeof(uint32_t)) {
*val = (unsigned long int)*(const uint32_t *)p->data;
return 1;
}
break;
case sizeof(uint64_t):
if (sizeof(unsigned long int) >= sizeof(uint64_t)) {
*val = (unsigned long int)*(const uint64_t *)p->data;
return 1;
}
break;
}
return 0;
}
int OSSL_PARAM_set_ulong(const OSSL_PARAM *p, unsigned long int val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(unsigned long int)); /* Minimum exp size */
switch (p->data_size) {
case sizeof(uint32_t):
if (sizeof(uint32_t) >= sizeof(unsigned long int)) {
SET_RETURN_SIZE(p, sizeof(uint32_t));
*(uint32_t *)p->data = (uint32_t)val;
return 1;
}
break;
case sizeof(uint64_t):
if (sizeof(uint64_t) >= sizeof(unsigned long int)) {
SET_RETURN_SIZE(p, sizeof(uint64_t));
*(uint64_t *)p->data = (uint64_t)val;
return 1;
}
break;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_ulong(const char *key, unsigned long int *buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_UNSIGNED_INTEGER, buf,
sizeof(unsigned long int), rsize);
}
int OSSL_PARAM_get_int32(const OSSL_PARAM *p, int32_t *val)
{
if (val == NULL || p == NULL || (p->data_type != OSSL_PARAM_INTEGER))
return 0;
if (p->data_size == sizeof(int32_t)) {
*val = *(const int32_t *)p->data;
return 1;
}
return 0;
}
int OSSL_PARAM_set_int32(const OSSL_PARAM *p, int32_t val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(int32_t)); /* Minimum expected size */
switch (p->data_size) {
case sizeof(int32_t):
SET_RETURN_SIZE(p, sizeof(int32_t));
*(int32_t *)p->data = val;
return 1;
case sizeof(int64_t):
SET_RETURN_SIZE(p, sizeof(int64_t));
*(int64_t *)p->data = (int64_t)val;
return 1;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_int32(const char *key, int32_t *buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_INTEGER, buf,
sizeof(int32_t), rsize);
}
int OSSL_PARAM_get_uint32(const OSSL_PARAM *p, uint32_t *val)
{
if (val == NULL
|| p == NULL
|| (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER))
return 0;
if (p->data_size == sizeof(uint32_t)) {
*val = *(const uint32_t *)p->data;
return 1;
}
return 0;
}
int OSSL_PARAM_set_uint32(const OSSL_PARAM *p, uint32_t val)
{
if (p == NULL) return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(uint32_t)); /* Minimum expected size */
switch (p->data_size) {
case sizeof(uint32_t):
SET_RETURN_SIZE(p, sizeof(uint32_t));
*(uint32_t *)p->data = val;
return 1;
case sizeof(uint64_t):
SET_RETURN_SIZE(p, sizeof(uint64_t));
*(uint64_t *)p->data = (uint64_t)val;
return 1;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_uint32(const char *key, uint32_t *buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_UNSIGNED_INTEGER, buf,
sizeof(uint32_t), rsize);
}
int OSSL_PARAM_get_int64(const OSSL_PARAM *p, int64_t *val)
{
if (val == NULL || p == NULL || (p->data_type != OSSL_PARAM_INTEGER))
return 0;
switch (p->data_size) {
case sizeof(int32_t):
*val = (int64_t)*(const int32_t *)p->data;
return 1;
case sizeof(int64_t):
*val = *(const int64_t *)p->data;
return 1;
}
return 0;
}
int OSSL_PARAM_set_int64(const OSSL_PARAM *p, int64_t val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(int64_t)); /* Minimum expected size */
switch (p->data_size) {
case sizeof(int64_t):
SET_RETURN_SIZE(p, sizeof(int64_t));
*(int64_t *)p->data = val;
return 1;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_int64(const char *key, int64_t *buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_INTEGER, buf, sizeof(int64_t),
rsize);
}
int OSSL_PARAM_get_uint64(const OSSL_PARAM *p, uint64_t *val)
{
if (val == NULL
|| p == NULL
|| (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER))
return 0;
switch (p->data_size) {
case sizeof(uint32_t):
*val = (uint64_t)*(const uint32_t *)p->data;
return 1;
case sizeof(uint64_t):
*val = *(const uint64_t *)p->data;
return 1;
}
return 0;
}
int OSSL_PARAM_set_uint64(const OSSL_PARAM *p, uint64_t val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(uint64_t)); /* Minimum expected size */
switch (p->data_size) {
case sizeof(uint64_t):
SET_RETURN_SIZE(p, sizeof(uint64_t));
*(uint64_t *)p->data = val;
return 1;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_uint64(const char *key, uint64_t *buf,
size_t *rsize) {
return ossl_param_construct(key, OSSL_PARAM_UNSIGNED_INTEGER, buf,
sizeof(uint64_t), rsize);
}
int OSSL_PARAM_get_size_t(const OSSL_PARAM *p, size_t *val)
{
if (val == NULL
|| p == NULL
|| p->data_type != OSSL_PARAM_UNSIGNED_INTEGER)
return 0;
switch (p->data_size) {
case sizeof(uint32_t):
if (sizeof(size_t) >= sizeof(uint32_t)) {
*val = (size_t)*(const uint32_t *)p->data;
return 1;
}
break;
case sizeof(uint64_t):
if (sizeof(size_t) >= sizeof(uint64_t)) {
*val = (size_t)*(const uint64_t *)p->data;
return 1;
}
break;
}
return 0;
}
int OSSL_PARAM_set_size_t(const OSSL_PARAM *p, size_t val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_UNSIGNED_INTEGER)
return 0;
SET_RETURN_SIZE(p, sizeof(size_t)); /* Minimum expected size */
switch (p->data_size) {
case sizeof(uint32_t):
if (sizeof(uint32_t) >= sizeof(size_t)) {
SET_RETURN_SIZE(p, sizeof(uint32_t));
*(uint32_t *)p->data = (uint32_t)val;
return 1;
}
break;
case sizeof(uint64_t):
SET_RETURN_SIZE(p, sizeof(uint64_t));
if (sizeof(uint64_t) >= sizeof(size_t)) {
*(uint64_t *)p->data = (uint64_t)val;
return 1;
}
break;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_size_t(const char *key, size_t *buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_UNSIGNED_INTEGER, buf,
sizeof(size_t), rsize); }
int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val)
{
BIGNUM *b;
if (val == NULL
|| p == NULL
|| p->data_type != OSSL_PARAM_UNSIGNED_INTEGER)
return 0;
b = BN_native2bn(p->data, (int)p->data_size, *val);
if (b != NULL) {
*val = b;
return 1;
}
return 0;
}
int OSSL_PARAM_set_BN(const OSSL_PARAM *p, const BIGNUM *val)
{
size_t bytes;
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (val == NULL || p->data_type != OSSL_PARAM_UNSIGNED_INTEGER)
return 0;
bytes = (size_t)BN_num_bytes(val);
SET_RETURN_SIZE(p, bytes);
return p->data_size >= bytes
&& BN_bn2nativepad(val, p->data, bytes) >= 0;
}
OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
size_t bsize, size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_UNSIGNED_INTEGER,
buf, bsize, rsize);
}
int OSSL_PARAM_get_double(const OSSL_PARAM *p, double *val)
{
if (val == NULL || p == NULL || p->data_type != OSSL_PARAM_REAL)
return 0;
switch (p->data_size) {
case sizeof(double):
*val = *(const double *)p->data;
return 1;
}
return 0;
}
int OSSL_PARAM_set_double(const OSSL_PARAM *p, double val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (p->data_type != OSSL_PARAM_REAL)
return 0;
switch (p->data_size) {
case sizeof(double):
SET_RETURN_SIZE(p, sizeof(double));
*(double *)p->data = val;
return 1;
}
return 0;
}
OSSL_PARAM OSSL_PARAM_construct_double(const char *key, double *buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_REAL, buf, sizeof(double),
rsize);
}
static int get_string_internal(const OSSL_PARAM *p, void **val, size_t max_len,
size_t *used_len, unsigned int type)
{
size_t sz;
if (val == NULL || p == NULL || p->data_type != type)
return 0;
sz = p->data_size;
if (used_len != NULL)
*used_len = sz;
if (*val == NULL) {
char *const q = OPENSSL_malloc(sz);
if (q == NULL)
return 0;
*val = q;
memcpy(q, p->data, sz);
return 1;
}
if (max_len < sz)
return 0;
memcpy(*val, p->data, sz);
return 1;
}
int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val, size_t max_len)
{
return get_string_internal(p, (void **)val, max_len, NULL,
OSSL_PARAM_UTF8_STRING);
}
int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val, size_t max_len,
size_t *used_len)
{
return get_string_internal(p, val, max_len, used_len,
OSSL_PARAM_OCTET_STRING);
}
static int set_string_internal(const OSSL_PARAM *p, const void *val, size_t len,
unsigned int type)
{
SET_RETURN_SIZE(p, len);
if (p->data_type != type || p->data_size < len)
return 0;
memcpy(p->data, val, len);
return 1;
}
int OSSL_PARAM_set_utf8_string(const OSSL_PARAM *p, const char *val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (val == NULL)
return 0;
return set_string_internal(p, val, strlen(val) + 1, OSSL_PARAM_UTF8_STRING);
}
int OSSL_PARAM_set_octet_string(const OSSL_PARAM *p, const void *val,
size_t len)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (val == NULL)
return 0;
return set_string_internal(p, val, len, OSSL_PARAM_OCTET_STRING);
}
OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
size_t bsize, size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_UTF8_STRING, buf, bsize,
rsize);
}
OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
size_t bsize, size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_OCTET_STRING, buf, bsize,
rsize);
}
static int get_ptr_internal(const OSSL_PARAM *p, const void **val,
size_t *used_len, unsigned int type)
{
if (val == NULL || p == NULL || p->data_type != type)
return 0;
if (used_len != NULL)
*used_len = p->data_size;
*val = *(const void **)p->data;
return 1;
}
int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val)
{
return get_ptr_internal(p, (const void **)val, NULL, OSSL_PARAM_UTF8_PTR);
}
int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val,
size_t *used_len)
{
return get_ptr_internal(p, val, used_len, OSSL_PARAM_OCTET_PTR);
}
static int set_ptr_internal(const OSSL_PARAM *p, const void *val,
unsigned int type, size_t len)
{
SET_RETURN_SIZE(p, len);
if (p->data_type != type)
return 0;
*(const void **)p->data = val;
return 1;
}
int OSSL_PARAM_set_utf8_ptr(const OSSL_PARAM *p, const char *val)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (val == NULL)
return 0;
return set_ptr_internal(p, val, OSSL_PARAM_UTF8_PTR, strlen(val) + 1);
}
int OSSL_PARAM_set_octet_ptr(const OSSL_PARAM *p, const void *val,
size_t used_len)
{
if (p == NULL)
return 0;
SET_RETURN_SIZE(p, 0);
if (val == NULL)
return 0;
return set_ptr_internal(p, val, OSSL_PARAM_OCTET_PTR, used_len);
}
OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_UTF8_PTR, buf, 0, rsize);
}
OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
size_t *rsize)
{
return ossl_param_construct(key, OSSL_PARAM_OCTET_PTR, buf, 0, rsize);
}

+ 29
- 28
doc/man3/OSSL_PARAM.pod View File

@ -118,8 +118,6 @@ systems.
=item C<OSSL_PARAM_REAL>
=for comment It's still debated if we need this or not.
The parameter data is a floating point value in native form.
=item C<OSSL_PARAM_UTF8_STRING>
@ -130,47 +128,50 @@ The parameter data is a printable string.
The parameter data is an arbitrary string of bytes.
=back
Additionally, this flag can be added to any type:
=item C<OSSL_PARAM_UTF8_PTR>
=over 4
=item C<OSSL_PARAM_POINTER_FLAG>
The parameter data is a pointer to a printable string.
With this flag, C<data> doesn't point directly at the data, but at a
pointer that points at the data.
The difference between this and C<OSSL_PARAM_UTF8_STRING> is that C<data>
doesn't point directly at the data, but to a pointer that points to the data.
This can be used to indicate that constant data is or will be passed,
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.
If an C<OSSL_PARAM> with this flag set is used to set a parameter,
C<data_size> must be set to the size of the data, not the size of
the pointer to the data.
If this C<OSSL_PARAM> is used in a parameter request, C<data_size>
is not relevant.
However, the I<responder> will set C<*return_size> to the size of the
data (again, not the size of the pointer to the data).
C<data_size> 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,
C<data_size> is not relevant. However, the I<responder> will set
C<*return_size> to the size of the data.
Note that the use of this flag is B<fragile> and can only be safely
Note that the use of this type is B<fragile> 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).
=back
=item C<OSSL_PARAM_OCTET_PTR>
For convenience, these types are provided:
The parameter data is a pointer to an arbitrary string of bytes.
=over 4
The difference between this and C<OSSL_PARAM_OCTET_STRING> is that
C<data> doesn't point directly at the data, but to a pointer that
points to the data.
=item C<OSSL_PARAM_UTF8_STRING_PTR>
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.
=item C<OSSL_PARAM_OCTET_STRING_PTR>
C<data_size> 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,
C<data_size> is not relevant. However, the I<responder> will set
C<*return_size> to the size of the data.
These are combinations of C<OSSL_PARAM_UTF8_STRING> as well as
C<OSSL_PARAM_OCTET_STRING> with C<OSSL_PARAM_POINTER_FLAG>.
Note that the use of this type is B<fragile> 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).
=back
@ -283,7 +284,7 @@ could fill in the parameters like this:
=head1 SEE ALSO
L<openssl-core.h(7)>
L<openssl-core.h(7)>, L<OSSL_PARAM_get_int32_t(3)>
=head1 HISTORY


+ 312
- 0
doc/man3/OSSL_PARAM_TYPE.pod View File

@ -0,0 +1,312 @@
=pod
=head1 NAME
OSSL_PARAM_TYPE, OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string,
OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr, OSSL_PARAM_SIZED_TYPE,
OSSL_PARAM_SIZED_BN, OSSL_PARAM_SIZED_utf8_string,
OSSL_PARAM_SIZED_octet_string, OSSL_PARAM_SIZED_utf8_ptr,
OSSL_PARAM_SIZED_octet_ptr, OSSL_PARAM_END, OSSL_PARAM_construct_TYPE,
OSSL_PARAM_END,
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_locate, OSSL_PARAM_get_TYPE,
OSSL_PARAM_set_TYPE, OSSL_PARAM_get_BN, OSSL_PARAM_set_BN,
OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string,
OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string,
OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_get_octet_ptr,
OSSL_PARAM_set_octet_ptr
- OSSL_PARAM helpers
=head1 SYNOPSIS
#include <openssl/params.h>
#define OSSL_PARAM_TYPE(key, address)
#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_SIZED_TYPE(key, address, return_size)
#define OSSL_PARAM_SIZED_BN(key, address, size, return_size)
#define OSSL_PARAM_SIZED_utf8_string(key, address, size, return_size)
#define OSSL_PARAM_SIZED_octet_string(key, address, size, return_size)
#define OSSL_PARAM_SIZED_utf8_ptr(key, address, size, return_size)
#define OSSL_PARAM_SIZED_octet_ptr(key, address, size, return_size)
#define OSSL_PARAM_END
OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf, size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
size_t bsize, size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
size_t bsize, size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
size_t bsize, size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
size_t *rsize);
OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val);
int OSSL_PARAM_set_TYPE(const OSSL_PARAM *p, const char *key, TYPE val);
int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val);
int OSSL_PARAM_set_BN(const OSSL_PARAM *p, const char *key, 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(const 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(const OSSL_PARAM *p, const void *val,
size_t len);
int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, char **val);
int OSSL_PARAM_set_utf8_ptr(const OSSL_PARAM *p, char *val);
int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val,
size_t *used_len);
int OSSL_PARAM_set_octet_ptr(const OSSL_PARAM *p, 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() are macros that provide support for defining UTF8
strings and OCTET strings.
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_SIZED_TYPE() are a second series of macros designed to assist with
the initialisation of OSSL_PARAM structures.
They are similar to the OSSL_PARAM_TYPE() macros but also include a
B<return_size> argument which contains the address of a size_t variable which
will be populated with the actual size of the parameter upon return from a
OSSL_PARAM_set_TYPE() call.
OSSL_PARAM_SIZED_BN(), OSSL_PARAM_SIZED_utf8_string(),
OSSL_PARAM_SIZED_octet_string(), OSSL_PARAM_SIZED_utf8_ptr(),
OSSL_PARAM_SIZED_octet_ptr() are macros that provide support for defining large
integers, UTF8 string and OCTET strings in an OSSL_PARAM array.
A parameter with name B<key> is defined.
The storage for this parameter is at B<address> and is of B<size> bytes.
The size used by the parameter value, in bytes, is written to B<return_size>.
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>, size B<bsize> and return
size B<rsize> is created.
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>, size B<bsize> and return
size B<rsize> 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 return size B<rsize>
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 return size B<rsize>
is created.
OSSL_PARAM_locate() is a function that searches an B<array> of parameters for
the one matching the B<key> name.
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 paramter
B<p>.
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 paramater B<p>.
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>.
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>.
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() returns a pointer to the matching OSSL_PARAM object.
It returns 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
Integral types will be widened and sign extended as required.
Apart from that, the functions must be used appropriately for the
expected type of the parameter.
=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:
const char *foo = NULL;
size_t foo_l;
char bar[1024];
size_t bar_l;
const OSSL_PARAM request[] = {
OSSL_PARAM_UTF8_PTR("foo", foo, 0, foo_l),
OSSL_PARAM_UTF8_STRING("bar", bar, sizeof(bar), bar_l),
OSSL_PARAM_END
};
A I<responder> that receives this array (as C<params> in this example)
could fill in the parameters like this:
/* const OSSL_PARAM *params */
OSSL_PARAM_set_utf8_ptr(OSSL_PARAM_locate(params, "foo"), "foo value");
OSSL_PARAM_set_utf8_string(OSSL_PARAM_locate(params, "bar"), "bar value");
=head1 SEE ALSO
L<openssl-core.h(7)>, L<OSSL_PARAM(3)>
=head1 HISTORY
These APIs were introduced in OpenSSL 3.0.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

+ 20
- 13
include/openssl/core.h View File

@ -111,13 +111,12 @@ struct ossl_param_st {
* printed as a hexdump.
*/
# define OSSL_PARAM_OCTET_STRING 5
/*-
* Pointer flag
* OSSL_PARAM_UTF8_PTR
* is a pointer to a printable string. Is expteced to be printed as it is.
*
* This flag can be added to any type to signify that the buffer
* pointer is set to point at a pointer to the data instead of
* pointing directly at the data.
* The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers
* are manipulated for this type.
*
* This is more relevant for parameter requests, where the responding
* function doesn't need to copy the data to the provided buffer, but
@ -126,15 +125,23 @@ struct ossl_param_st {
* WARNING! Using these is FRAGILE, as it assumes that the actual
* data and its location are constant.
*/
# define OSSL_PARAM_POINTER_FLAG 0x80000000UL
/*
* Convenience pointer types for strings.
# define OSSL_PARAM_UTF8_PTR 6
/*-
* OSSL_PARAM_OCTET_PTR
* is a pointer to a string of bytes with no further specification. It is
* expected to be printed as a hexdump.
*
* The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers
* are manipulated for this type.
*
* This is more relevant for parameter requests, where the responding
* function doesn't need to copy the data to the provided buffer, but
* sets the provided buffer to point at the actual data instead.
*
* WARNING! Using these is FRAGILE, as it assumes that the actual
* data and its location are constant.
*/
# define OSSL_PARAM_UTF8_STRING_PTR \
(OSSL_PARAM_UTF8_STRING|OSSL_PARAM_POINTER_FLAG)
# define OSSL_PARAM_OCTET_STRING_PTR \
(OSSL_PARAM_OCTET_STRING|OSSL_PARAM_POINTER_FLAG)
# define OSSL_PARAM_OCTET_PTR 7
/*-
* Provider entry point


+ 186
- 0
include/openssl/params.h View File

@ -0,0 +1,186 @@
/*
* Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
* Copyright (c) 2019, Oracle and/or its affiliates. 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
* https://www.openssl.org/source/license.html
*/
#ifndef HEADER_PARAMS_H
# define HEADER_PARAMS_H
# include <openssl/core.h>
# include <openssl/bn.h>
# ifdef __cplusplus
extern "C" {
# endif
# define OSSL_PARAM_END \
{ NULL, 0, NULL, 0, NULL }
# define OSSL_PARAM_DEFN(key, type, addr, sz, rsz) \
{ (key), (type), (addr), (sz), (rsz) }
/* Basic parameter types without return sizes */
# define OSSL_PARAM_int(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_INTEGER, (addr), sizeof(int), NULL)
# define OSSL_PARAM_uint(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(unsigned int), NULL)
# define OSSL_PARAM_long(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_INTEGER, (addr), sizeof(long int), \
NULL)
# define OSSL_PARAM_ulong(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(unsigned long int), NULL)
# define OSSL_PARAM_int32(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_INTEGER, (addr), sizeof(int32_t), NULL)
# define OSSL_PARAM_uint32(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(uint32_t), NULL)
# define OSSL_PARAM_int64(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_INTEGER, (addr), sizeof(int64_t), NULL)
# define OSSL_PARAM_uint64(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(uint64_t), NULL)
# define OSSL_PARAM_size_t(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), sizeof(size_t), \
NULL)
# define OSSL_PARAM_double(key, addr) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_REAL, (addr), sizeof(double), NULL)
# define OSSL_PARAM_utf8_string(key, addr, sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UTF8_STRING, (addr), sz, NULL)
# define OSSL_PARAM_octet_string(key, addr, sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_OCTET_STRING, (addr), sz, NULL)
# define OSSL_PARAM_utf8_ptr(key, addr, sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UTF8_PTR, &(addr), sz, NULL)
# define OSSL_PARAM_octet_ptr(key, addr, sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_OCTET_PTR, &(addr), sz, NULL)
/* Basic parameter types including return sizes */
# define OSSL_PARAM_SIZED_int(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_INTEGER, (addr), sizeof(int), &(r_sz))
# define OSSL_PARAM_SIZED_uint(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(unsigned int), &(r_sz))
# define OSSL_PARAM_SIZED_long(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_INTEGER, (addr), sizeof(long int), \
&(r_sz))
# define OSSL_PARAM_SIZED_ulong(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(unsigned long int), &(r_sz))
# define OSSL_PARAM_SIZED_int32(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_INTEGER, (addr), sizeof(int32_t), &(r_sz))
# define OSSL_PARAM_SIZED_uint32(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(uint32_t), &(r_sz))
# define OSSL_PARAM_SIZED_int64(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_INTEGER, (addr), sizeof(int64_t), &(r_sz))
# define OSSL_PARAM_SIZED_uint64(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(uint64_t), &(r_sz))
# define OSSL_PARAM_SIZED_size_t(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), \
sizeof(size_t), &(r_sz))
# define OSSL_PARAM_SIZED_double(key, addr, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_REAL, (addr), sizeof(double), &(r_sz))
# define OSSL_PARAM_SIZED_BN(key, addr, sz, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UNSIGNED_INTEGER, (addr), sz, \
&(r_sz))
# define OSSL_PARAM_SIZED_utf8_string(key, addr, sz, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UTF8_STRING, (addr), sz, &(r_sz))
# define OSSL_PARAM_SIZED_octet_string(key, addr, sz, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_OCTET_STRING, (addr), sz, &(r_sz))
# define OSSL_PARAM_SIZED_utf8_ptr(key, addr, sz, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_UTF8_PTR, &(addr), sz, &(r_sz))
# define OSSL_PARAM_SIZED_octet_ptr(key, addr, sz, r_sz) \
OSSL_PARAM_DEFN((key), OSSL_PARAM_OCTET_PTR, &(addr), sz, &(r_sz))
/* Search an OSSL_PARAM array for a matching name */
const OSSL_PARAM *OSSL_PARAM_locate(const OSSL_PARAM *p, const char *key);
/* Basic parameter type run-time construction */
OSSL_PARAM OSSL_PARAM_construct_int(const char *key, int *buf, size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_uint(const char *key, unsigned int *buf,
size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_long(const char *key, long int *buf,
size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_ulong(const char *key, unsigned long int *buf,
size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_int32(const char *key, int32_t *buf,
size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_uint32(const char *key, uint32_t *buf,
size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_int64(const char *key, int64_t *buf,
size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_uint64(const char *key, uint64_t *buf,
size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_size_t(const char *key, size_t *buf,
size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
size_t bsize, size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_double(const char *key, double *buf,
size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
size_t bsize, size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
size_t bsize, size_t *rsize);
OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
size_t *rsize);
int OSSL_PARAM_get_int(const OSSL_PARAM *p, int *val);
int OSSL_PARAM_get_uint(const OSSL_PARAM *p, unsigned int *val);
int OSSL_PARAM_get_long(const OSSL_PARAM *p, long int *val);
int OSSL_PARAM_get_ulong(const OSSL_PARAM *p, unsigned long int *val);
int OSSL_PARAM_get_int32(const OSSL_PARAM *p, int32_t *val);
int OSSL_PARAM_get_uint32(const OSSL_PARAM *p, uint32_t *val);
int OSSL_PARAM_get_int64(const OSSL_PARAM *p, int64_t *val);
int OSSL_PARAM_get_uint64(const OSSL_PARAM *p, uint64_t *val);
int OSSL_PARAM_get_size_t(const OSSL_PARAM *p, size_t *val);
int OSSL_PARAM_set_int(const OSSL_PARAM *p, int val);
int OSSL_PARAM_set_uint(const OSSL_PARAM *p, unsigned int val);
int OSSL_PARAM_set_long(const OSSL_PARAM *p, long int val);
int OSSL_PARAM_set_ulong(const OSSL_PARAM *p, unsigned long int val);
int OSSL_PARAM_set_int32(const OSSL_PARAM *p, int32_t val);
int OSSL_PARAM_set_uint32(const OSSL_PARAM *p, uint32_t val);
int OSSL_PARAM_set_int64(const OSSL_PARAM *p, int64_t val);
int OSSL_PARAM_set_uint64(const OSSL_PARAM *p, uint64_t val);
int OSSL_PARAM_set_size_t(const OSSL_PARAM *p, size_t val);
int OSSL_PARAM_get_double(const OSSL_PARAM *p, double *val);
int OSSL_PARAM_set_double(const OSSL_PARAM *p, double val);
int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val);
int OSSL_PARAM_set_BN(const 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(const 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(const 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(const 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(const OSSL_PARAM *p, const void *val,
size_t used_len);
# ifdef __cplusplus
}
# endif
#endif

+ 5
- 1
test/build.info View File

@ -34,7 +34,7 @@ IF[{- !$disabled{tests} -}]
bftest ssltest_old dsatest dsa_no_digest_size_test exptest rsa_test \
evp_test evp_extra_test igetest v3nametest v3ext \
crltest danetest bad_dtls_test lhash_test sparse_array_test \
conf_include_test \
conf_include_test params_api_test \
constant_time_test verify_extra_test clienthellotest \
packettest asynctest secmemtest srptest memleaktest stack_test \
dtlsv1listentest ct_test threadstest afalgtest d2i_test \
@ -307,6 +307,10 @@ IF[{- !$disabled{tests} -}]
INCLUDE[bioprinttest]=../include ../apps/include
DEPEND[bioprinttest]=../libcrypto libtestutil.a
SOURCE[params_api_test]=params_api_test.c
INCLUDE[params_api_test]=../include ../apps/include
DEPEND[params_api_test]=../libcrypto libtestutil.a
SOURCE[sslapitest]=sslapitest.c ssltestlib.c
INCLUDE[sslapitest]=../include ../apps/include ..
DEPEND[sslapitest]=../libcrypto ../libssl libtestutil.a


+ 627
- 0
test/params_api_test.c View File

@ -0,0 +1,627 @@
/*
* Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
* Copyright (c) 2019, Oracle and/or its affiliates. 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
* https://www.openssl.org/source/license.html
*/
#include <string.h>
#include "testutil.h"
#include "internal/nelem.h"
#include <openssl/params.h>
#include <openssl/bn.h>
/* The maximum size of the static buffers used to test most things */
#define MAX_LEN 20
static void swap_copy(unsigned char *out, const void *in, size_t len)
{
size_t j;
for (j = 0; j < len; j++)
out[j] = ((unsigned char *)in)[len - j - 1];
}
static void copy_to_le(unsigned char *out, const void *in, size_t len)
{
#ifdef B_ENDIAN
swap_copy(out, in, len);
#else
memcpy(out, in, len);
#endif
}
static void copy_be_to_native(unsigned char *out, const void *in, size_t len)
{
#ifdef B_ENDIAN
memcpy(out, in, len);
#else
swap_copy(out, in, len);
#endif
}
static const struct {
size_t len;
unsigned char value[MAX_LEN];
} raw_values[] = {
{ 4, { 0x38, 0x27, 0xbf, 0x3b } },
{ 4, { 0x9f, 0x26, 0x48, 0x22 } },
{ 8, { 0x59, 0xb2, 0x1a, 0xe9, 0x2a, 0xd8, 0x46, 0x40 } },
{ 8, { 0xb4, 0xae, 0xbd, 0xb4, 0xdd, 0x04, 0xb1, 0x4c } },
{ 16, { 0x61, 0xe8, 0x7e, 0x31, 0xe9, 0x33, 0x83, 0x3d,
0x87, 0x99, 0xc7, 0xd8, 0x5d, 0xa9, 0x8b, 0x42 } },
{ 16, { 0xee, 0x6e, 0x8b, 0xc3, 0xec, 0xcf, 0x37, 0xcc,
0x89, 0x67, 0xf2, 0x68, 0x33, 0xa0, 0x14, 0xb0 } },
};
static int test_param_type_extra(const OSSL_PARAM *param, unsigned char *cmp,
size_t width)
{
int32_t i32;
int64_t i64;
size_t s, sz;
unsigned char buf[MAX_LEN];
const int bit32 = param->data_size == sizeof(int32_t);
const int sizet = bit32 && sizeof(size_t) > sizeof(int32_t);
const int signd = param->data_type == OSSL_PARAM_INTEGER;
if (signd) {
if ((bit32 && !TEST_true(OSSL_PARAM_get_int32(param, &i32)))
|| !TEST_true(OSSL_PARAM_get_int64(param, &i64)))
return 0;
} else {
if ((bit32
&& !TEST_true(OSSL_PARAM_get_uint32(param, (uint32_t *)&i32)))
|| !TEST_true(OSSL_PARAM_get_uint64(param, (uint64_t *)&i64))
|| (sizet && !TEST_true(OSSL_PARAM_get_size_t(param, &s))))
return 0;
}
/* Check signed types */
if (bit32) {
copy_to_le(buf, &i32, sizeof(i32));
sz = sizeof(i32) < width ? sizeof(i32) : width;
if (!TEST_mem_eq(buf, sz, cmp, sz))
return 0;
}
copy_to_le(buf, &i64, sizeof(i64));
sz = sizeof(i64) < width ? sizeof(i64) : width;
if (!TEST_mem_eq(buf, sz, cmp, sz))
return 0;
if (sizet && !signd) {
copy_to_le(buf, &s, sizeof(s));
sz = sizeof(s) < width ? sizeof(s) : width;
if (!TEST_mem_eq(buf, sz, cmp, sz))
return 0;
}
/* Check a widening write if possible */
if (sizeof(size_t) > width) {
if (signd) {
if (!TEST_true(OSSL_PARAM_set_int32(param, 12345))
|| !TEST_true(OSSL_PARAM_get_int64(param, &i64))
|| !TEST_size_t_eq(i64, 12345))
return 0;
} else {
if (!TEST_true(OSSL_PARAM_set_uint32(param, 12345))
|| !TEST_true(OSSL_PARAM_get_uint64(param, (uint64_t *)&i64))
|| !TEST_size_t_eq(i64, 12345))
return 0;
}
}
return 1;
}
/*
* The test cases for each of the bastic integral types are similar.
* For each type, a param of that type is set and an attempt to read it
* get is made. Finally, the above function is called to verify that
* the params can be read as other types.
*
* All the real work is done via byte buffers which are converted to machine
* byte order and to little endian for comparisons. Narrower values are best
* compared using little endian because their values and positions don't
* change.
*/
static int test_param_int(int n)
{
int in, out;
unsigned char buf[MAX_LEN], le[MAX_LEN], cmp[sizeof(int)];
const size_t len = raw_values[n].len >= sizeof(int) ?
sizeof(int) : raw_values[n].len;
OSSL_PARAM param = OSSL_PARAM_int("a", NULL);
memset(buf, 0, sizeof(buf));
memset(le, 0, sizeof(le));
copy_be_to_native(buf, raw_values[n].value, len);
swap_copy(le, raw_values[n].value, len);
memcpy(&in, buf, sizeof(in));
param.data = &out;
if (!TEST_true(OSSL_PARAM_set_int(&param, in)))
return 0;
copy_to_le(cmp, &out, sizeof(out));
if (!TEST_mem_eq(cmp, len, le, len))
return 0;
in = 0;
param.data = buf;
if (!TEST_true(OSSL_PARAM_get_int(&param, &in)))
return 0;
copy_to_le(cmp, &in, sizeof(in));
if (!TEST_mem_eq(cmp, sizeof(in), le, sizeof(in)))
return 0;
param.data = &out;
return test_param_type_extra(&param, le, sizeof(int));
}
static int test_param_long(int n)
{
long int in, out;
unsigned char buf[MAX_LEN], le[MAX_LEN], cmp[sizeof(long int)];
const size_t len = raw_values[n].len >= sizeof(long int)
? sizeof(long int) : raw_values[n].len;
OSSL_PARAM param = OSSL_PARAM_long("a", NULL);
memset(buf, 0, sizeof(buf));
memset(le, 0, sizeof(le));
copy_be_to_native(buf, raw_values[n].value, len);
swap_copy(le, raw_values[n].value, len);
memcpy(&in, buf, sizeof(in));
param.data = &out;
if (!TEST_true(OSSL_PARAM_set_long(&param, in)))
return 0;
copy_to_le(cmp, &out, sizeof(out));
if (!TEST_mem_eq(cmp, len, le, len))
return 0;
in = 0;
param.data = buf;
if (!TEST_true(OSSL_PARAM_get_long(&param, &in)))
return 0;
copy_to_le(cmp, &in, sizeof(in));
if (!TEST_mem_eq(cmp, sizeof(in), le, sizeof(in)))
return 0;
param.data = &out;
return test_param_type_extra(&param, le, sizeof(long int));
}
static int test_param_uint(int n)
{
unsigned int in, out;
unsigned char buf[MAX_LEN], le[MAX_LEN], cmp[sizeof(unsigned int)];
const size_t len = raw_values[n].len >= sizeof(unsigned int) ? sizeof(unsigned int) : raw_values[n].len;
OSSL_PARAM param = OSSL_PARAM_uint("a", NULL);
memset(buf, 0, sizeof(buf));
memset(le, 0, sizeof(le));
copy_be_to_native(buf, raw_values[n].value, len);
swap_copy(le, raw_values[n].value, len);
memcpy(&in, buf, sizeof(in));
param.data = &out;
if (!TEST_true(OSSL_PARAM_set_uint(&param, in)))
return 0;
copy_to_le(cmp, &out, sizeof(out));
if (!TEST_mem_eq(cmp, len, le, len))
return 0;
in = 0;
param.data = buf;
if (!TEST_true(OSSL_PARAM_get_uint(&param, &in)))
return 0;
copy_to_le(cmp, &in, sizeof(in));
if (!TEST_mem_eq(cmp, sizeof(in), le, sizeof(in)))
return 0;
param.data = &out;
return test_param_type_extra(&param, le, sizeof(unsigned int));
}
static int test_param_ulong(int n)
{
unsigned long int in, out;
unsigned char buf[MAX_LEN], le[MAX_LEN], cmp[sizeof(unsigned long int)];
const size_t len = raw_values[n].len >= sizeof(unsigned long int)
? sizeof(unsigned long int) : raw_values[n].len;
OSSL_PARAM param = OSSL_PARAM_ulong("a", NULL);
memset(buf, 0, sizeof(buf));
memset(le, 0, sizeof(le));
copy_be_to_native(buf, raw_values[n].value, len);
swap_copy(le, raw_values[n].value, len);
memcpy(&in, buf, sizeof(in));
param.data = &out;
if (!TEST_true(OSSL_PARAM_set_ulong(&param, in)))
return 0;
copy_to_le(cmp, &out, sizeof(out));
if (!TEST_mem_eq(cmp, len, le, len))