From: Pauli Date: Tue, 24 Mar 2020 05:08:00 +0000 (+1000) Subject: NEWS: note OSSL_PARAM_BLD API as public. X-Git-Tag: openssl-3.0.0-alpha1~193 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=be19d3caf0724b786ecc97ec4207c07cff63c745;p=oweals%2Fopenssl.git NEWS: note OSSL_PARAM_BLD API as public. Reviewed-by: Nicola Tuveri (Merged from https://github.com/openssl/openssl/pull/11390) --- diff --git a/CHANGES.md b/CHANGES.md index 82c186a6cd..8f7d7ee195 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -24,6 +24,14 @@ OpenSSL 3.0 ### Changes between 1.1.1 and 3.0 [xx XXX xxxx] ### + * Added OSSL_PARAM_BLD to the public interface. This allows OSSL_PARAM + arrays to be more easily constructed via a series of utility functions. + Create a parameter builder using OSSL_PARAM_BLD_new(), add parameters using + the various push functions and finally convert to a passable OSSL_PARAM + array using OSSL_PARAM_BLD_to_param(). + + * Paul Dale * + * EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH(), and EVP_PKEY_get0_EC_KEY() can now handle EVP_PKEYs with provider side internal keys, if they correspond to one of those built in types. diff --git a/NEWS.md b/NEWS.md index 10a38b2aaf..9f29a59323 100644 --- a/NEWS.md +++ b/NEWS.md @@ -31,6 +31,7 @@ OpenSSL 3.0 * enable-crypto-mdebug and enable-crypto-mdebug-backtrace were mostly disabled; the project uses address sanitize/leak-detect instead. * Added OSSL_SERIALIZER, a generic serializer API. + * Added OSSL_PARAM_BLD, an easier to use API to OSSL_PARAM. * Added error raising macros, ERR_raise() and ERR_raise_data(). * Deprecated ERR_put_error(). * Added OSSL_PROVIDER_available(), to check provider availibility. diff --git a/doc/man3/OSSL_PARAM_BLD_init.pod b/doc/man3/OSSL_PARAM_BLD_init.pod deleted file mode 100644 index 0b61ece8bc..0000000000 --- a/doc/man3/OSSL_PARAM_BLD_init.pod +++ /dev/null @@ -1,197 +0,0 @@ -=pod - -=head1 NAME - -OSSL_PARAM_BLD_init, OSSL_PARAM_BLD_to_param, -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 - -=head1 SYNOPSIS - -=for openssl generic - - #include "openssl/param_build.h" - - #define OSSL_PARAM_BLD_MAX 10 - typedef struct { ... } OSSL_PARAM_BLD; - - void OSSL_PARAM_BLD_init(OSSL_PARAM_BLD *bld); - OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld); - void OSSL_PARAM_BLD_free(OSSL_PARAM *params); - - 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); - - -=head1 DESCRIPTION - -A collection of utility functions that simplify the creation of OSSL_PARAM -arrays. The B> names are as per L. - -OSSL_PARAM_BLD_init() initialises the OSSL_PARAM_BLD structure so that values -can be added. -Any existing values are cleared. - -OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure -I into an allocated OSSL_PARAM array. -The OSSL_PARAM array and all associated storage must be freed by calling -OSSL_PARAM_BLD_free() with the functions return value. - -OSSL_PARAM_BLD_free() deallocates the memory allocated by -OSSL_PARAM_BLD_to_param(). - -=begin comment - -POD is pretty good at recognising function names and making them appropriately -bold... however, when part of the function name is variable, we have to help -the processor along - -=end comment - -B>() are a series of functions which will create -OSSL_PARAM objects of the specified size and correct type for the I -argument. -I is stored by value and an expression or auto variable can be used. - -OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object -that holds the specified BIGNUM I. -If I is marked as being securely allocated, its OSSL_PARAM representation -will also be securely allocated. -The I argument is stored by reference and the underlying BIGNUM object -must exist until after OSSL_PARAM_BLD_to_param() has been called. - -OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object -that holds the specified BIGNUM I. -The object will be padded to occupy exactly I bytes, if insufficient space -is specified an error results. -If I is marked as being securely allocated, its OSSL_PARAM representation -will also be securely allocated. -The I argument is stored by reference and the underlying BIGNUM object -must exist until after OSSL_PARAM_BLD_to_param() has been called. - -OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM -object that references the UTF8 string specified by I. -If the length of the string, I, is zero then it will be calculated. -The string that I points to is stored by reference and must remain in -scope until after OSSL_PARAM_BLD_to_param() has been called. - -OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM -object that references the octet string specified by I and . -The memory that I points to is stored by reference and must remain in -scope until after OSSL_PARAM_BLD_to_param() has been called. - -OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM -object that references the UTF8 string specified by I. -If the length of the string, I, is zero then it will be calculated. -The string I points to is stored by reference and must remain in -scope until the OSSL_PARAM array is freed. - -OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM -object that references the octet string specified by I. -The memory I points to is stored by reference and must remain in -scope until the OSSL_PARAM array is freed. - -=head1 RETURN VALUES - -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. - -=head1 NOTES - -The constant B specifies the maximum number of parameters -that can be added. -Exceeding this will result in the push functions returning errors. -The define used for this will always be at least 10 but otherwise no assumption -should be made about it's specific value. - -The structure B should be considered opaque and subject to -change between versions. - -=head1 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 */ - -=head2 Example 1 - -This example shows how to create an OSSL_PARAM array that contains an RSA -private key. - - OSSL_PARAM_BLD bld; - OSSL_PARAM *params; - - OSSL_PARAM_BLD_init(&bld, &secure); - if (!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; - /* Use params */ - ... - OSSL_PARAM_BLD_free(params); - -=head2 Example 2 - -This example shows how to create an OSSL_PARAM array that contains an RSA -public key. - - OSSL_PARAM_BLD bld; - OSSL_PARAM *params; - - OSSL_PARAM_BLD_init(&bld, &secure); - if (!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; - /* Use params */ - ... - OSSL_PARAM_BLD_free(params); - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -The functions described here were all added 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. - -=cut diff --git a/doc/man3/OSSL_PARAM_BLD_new.pod b/doc/man3/OSSL_PARAM_BLD_new.pod new file mode 100644 index 0000000000..8aeb0aadf0 --- /dev/null +++ b/doc/man3/OSSL_PARAM_BLD_new.pod @@ -0,0 +1,203 @@ +=pod + +=head1 NAME + +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 + +=head1 SYNOPSIS + +=for openssl generic + + #include "openssl/param_build.h" + + #define OSSL_PARAM_BLD_MAX 10 + typedef struct { ... } OSSL_PARAM_BLD; + + void OSSL_PARAM_BLD_init(OSSL_PARAM_BLD *bld); + 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); + + +=head1 DESCRIPTION + +A collection of utility functions that simplify the creation of OSSL_PARAM +arrays. The B> names are as per L. + +OSSL_PARAM_BLD_init() initialises the OSSL_PARAM_BLD structure so that values +can be added. +Any existing values are cleared. + +OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new(). + +OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure +I into an allocated OSSL_PARAM array. +The OSSL_PARAM array and all associated storage must be freed by calling +OSSL_PARAM_BLD_free_params() with the functions return value. +OSSL_PARAM_BLD_free() can safely be called any time after this function is. + +OSSL_PARAM_BLD_free_params() deallocates the memory allocated by +OSSL_PARAM_BLD_to_param(). + +=begin comment + +POD is pretty good at recognising function names and making them appropriately +bold... however, when part of the function name is variable, we have to help +the processor along + +=end comment + +B>() are a series of functions which will create +OSSL_PARAM objects of the specified size and correct type for the I +argument. +I is stored by value and an expression or auto variable can be used. + +OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object +that holds the specified BIGNUM I. +If I is marked as being securely allocated, its OSSL_PARAM representation +will also be securely allocated. +The I argument is stored by reference and the underlying BIGNUM object +must exist until after OSSL_PARAM_BLD_to_param() has been called. + +OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object +that holds the specified BIGNUM I. +The object will be padded to occupy exactly I bytes, if insufficient space +is specified an error results. +If I is marked as being securely allocated, its OSSL_PARAM representation +will also be securely allocated. +The I argument is stored by reference and the underlying BIGNUM object +must exist until after OSSL_PARAM_BLD_to_param() has been called. + +OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM +object that references the UTF8 string specified by I. +If the length of the string, I, is zero then it will be calculated. +The string that I points to is stored by reference and must remain in +scope until after OSSL_PARAM_BLD_to_param() has been called. + +OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM +object that references the octet string specified by I and . +The memory that I points to is stored by reference and must remain in +scope until after OSSL_PARAM_BLD_to_param() has been called. + +OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM +object that references the UTF8 string specified by I. +If the length of the string, I, is zero then it will be calculated. +The string I points to is stored by reference and must remain in +scope until the OSSL_PARAM array is freed. + +OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM +object that references the octet string specified by I. +The memory I points to is stored by reference and must remain in +scope until the OSSL_PARAM array is freed. + +=head1 RETURN VALUES + +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. + +=head1 NOTES + +The constant B specifies the maximum number of parameters +that can be added. +Exceeding this will result in the push functions returning errors. +The define used for this will always be at least 10 but otherwise no assumption +should be made about it's specific value. + +The structure B should be considered opaque and subject to +change between versions. + +=head1 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 */ + +=head2 Example 1 + +This example shows how to create an OSSL_PARAM array that contains an RSA +private key. + + OSSL_PARAM_BLD bld; + OSSL_PARAM *params; + + OSSL_PARAM_BLD_init(&bld, &secure); + if (!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); + +=head2 Example 2 + +This example shows how to create an OSSL_PARAM array that contains an RSA +public key. + + OSSL_PARAM_BLD bld; + OSSL_PARAM *params; + + OSSL_PARAM_BLD_init(&bld, &secure); + if (!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); + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The functions described here were all added 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. + +=cut diff --git a/util/libcrypto.num b/util/libcrypto.num index 1650884ffe..1f8be71fc0 100644 --- a/util/libcrypto.num +++ b/util/libcrypto.num @@ -5000,6 +5000,25 @@ EVP_PKEY_CTX_set_rsa_keygen_primes ? 3_0_0 EXIST::FUNCTION:RSA NCONF_new_with_libctx ? 3_0_0 EXIST::FUNCTION: CONF_modules_load_file_with_libctx ? 3_0_0 EXIST::FUNCTION: OPENSSL_CTX_load_config ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_init ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_to_param ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_free ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_int ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_uint ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_long ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_ulong ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_int32 ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_uint32 ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_int64 ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_uint64 ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_size_t ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_double ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_BN ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_BN_pad ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_utf8_string ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_utf8_ptr ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_octet_string ? 3_0_0 EXIST::FUNCTION: +OSSL_PARAM_BLD_push_octet_ptr ? 3_0_0 EXIST::FUNCTION: EVP_PKEY_set_type_by_keymgmt ? 3_0_0 EXIST::FUNCTION: OCSP_RESPID_set_by_key_ex ? 3_0_0 EXIST::FUNCTION:OCSP OCSP_RESPID_match_ex ? 3_0_0 EXIST::FUNCTION:OCSP