diff options
author | Shane Lontis <shane.lontis@oracle.com> | 2021-04-07 11:27:18 +1000 |
---|---|---|
committer | Shane Lontis <shane.lontis@oracle.com> | 2021-04-12 16:55:29 +1000 |
commit | 884314cab786a980189206b2cab5f62878a97669 (patch) | |
tree | d9b618c36ea0ab2a5401cbf592f1c1282f6d6de5 /doc/man3 | |
parent | d36114d7cd363d505940326f5a2512d9661a67ea (diff) |
Add OSSL_PARAM_dup() and OSSL_PARAM_merge().
These functions are prerequisites for implementing EVP_PKEY_todata().
OSSL_PARAM_dup() is required to make a deep copy of the exported
params (since the provider export() uses a OSSL_PARAM_BLD which throws away the
data after the call), and then use OSSL_PARAM_merge() to add some additional params
that can be passed to the EVP_PKEY_todata().
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14785)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/OSSL_PARAM.pod | 2 | ||||
-rw-r--r-- | doc/man3/OSSL_PARAM_dup.pod | 59 |
2 files changed, 60 insertions, 1 deletions
diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod index a872de3b77..593bb21ef1 100644 --- a/doc/man3/OSSL_PARAM.pod +++ b/doc/man3/OSSL_PARAM.pod @@ -342,7 +342,7 @@ could fill in the parameters like this: =head1 SEE ALSO -L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)> +L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)> =head1 HISTORY diff --git a/doc/man3/OSSL_PARAM_dup.pod b/doc/man3/OSSL_PARAM_dup.pod new file mode 100644 index 0000000000..5130c9e1dc --- /dev/null +++ b/doc/man3/OSSL_PARAM_dup.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +OSSL_PARAM_dup, OSSL_PARAM_merge, OSSL_PARAM_free +- OSSL_PARAM array copy functions + +=head1 SYNOPSIS + + #include <openssl/params.h> + + OSSL_PARAM *OSSL_PARAM_dup(const OSSL_PARAM *params); + OSSL_PARAM *OSSL_PARAM_merge(const OSSL_PARAM *params, const OSSL_PARAM *params1); + void OSSL_PARAM_free(OSSL_PARAM *params); + +=head1 DESCRIPTION + +Algorithm parameters can be exported/imported from/to providers using arrays of +B<OSSL_PARAM>. The following utility functions allow the parameters to be +duplicated and merged with other B<OSSL_PARAM> to assist in this process. + +OSSL_PARAM_dup() duplicates the parameter array I<params>. This function does a +deep copy of the data. + +OSSL_PARAM_merge() merges the parameter arrays I<params> and I<params1> into a +new parameter array. If I<params> and I<params1> contain values with the same +'key' then the value from I<params1> will replace the I<param> value. This +function does a shallow copy of the parameters. Either I<params> or I<params1> +may be NULL. The behaviour of the merge is unpredictable if I<params> and +I<params1> contain the same key, and there are multiple entries within either +array that have the same key. + +OSSL_PARAM_free() frees the parameter array I<params> that was created using +OSSL_PARAM_dup(), OSSL_PARAM_merge() or OSSL_PARAM_BLD_to_param(). + +=head1 RETURN VALUES + +The functions OSSL_PARAM_dup() and OSSL_PARAM_merge() return a newly allocated +B<OSSL_PARAM> array, or NULL if there was an error. If both parameters are NULL + then NULL is returned. + +=head1 SEE ALSO + +L<OSSL_PARAM(3)>, L<OSSL_PARAM_BLD(3)> + +=head1 HISTORY + +The functions were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2021 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 |