NAME

OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param, OSSL_PARAM_BLD_free_params, OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long, OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32, OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64, OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t, OSSL_PARAM_BLD_push_double, OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad, OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr, OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr - functions to assist in the creation of OSSL_PARAM arrays

SYNOPSIS

 #include "openssl/param_build.h"

 typedef struct OSSL_PARAM_BLD;

 OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
 OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
 void OSSL_PARAM_BLD_free_params(OSSL_PARAM *params);
 void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);

 int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);

 int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
                            const BIGNUM *bn);
 int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
                                const BIGNUM *bn, size_t sz);

 int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
                                     const char *buf, size_t bsize);
 int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
                                  char *buf, size_t bsize);
 int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
                                      const void *buf, size_t bsize);
 int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
                                   void *buf, size_t bsize);

DESCRIPTION

A collection of utility functions that simplify the creation of OSSL_PARAM arrays. The TYPE names are as per RETURN VALUES

OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL on error.

OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL on error.

All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0 on error.

EXAMPLES

Both examples creating an OSSL_PARAM array that contains an RSA key. For both, the predefined key variables are:

    BIGNUM *p, *q;  /* both prime */
    BIGNUM *n;      /* = p * q */
    unsigned int e; /* exponent, usually 65537 */
    BIGNUM *d;      /* e^-1 */

Example 1

This example shows how to create an OSSL_PARAM array that contains an RSA private key.

    OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
    OSSL_PARAM *params;

    if (bld == NULL
        || !OSSL_PARAM_BLD_push_BN(&bld, "p", p)
        || !OSSL_PARAM_BLD_push_BN(&bld, "q", q)
        || !OSSL_PARAM_BLD_push_uint(&bld, "e", e)
        || !OSSL_PARAM_BLD_push_BN(&bld, "n", n)
        || !OSSL_PARAM_BLD_push_BN(&bld, "d", d)
        || (params = OSSL_PARAM_BLD_to_param(&bld)) == NULL)
        goto err;
    OSSL_PARAM_BLD_free(bld);
    /* Use params */
    ...
    OSSL_PARAM_BLD_free_params(params);

Example 2

This example shows how to create an OSSL_PARAM array that contains an RSA public key.

    OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
    OSSL_PARAM *params;

    if (nld == NULL
        || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
        || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
        || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
        goto err;
    OSSL_PARAM_BLD_free(bld);
    /* Use params */
    ...
    OSSL_PARAM_BLD_free_params(params);

HISTORY

The functions described here were all added in OpenSSL 3.0.

COPYRIGHT

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.