=pod

=head1 NAME

OSSL_PARAM_dup, OSSL_PARAM_merge, OSSL_PARAM_free, OSSL_PARAM_clear_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);
 void OSSL_PARAM_clear_free(OSSL_PARAM *params);

=head1 DESCRIPTION

Algorithm parameters can be exported/imported from/to providers using arrays of
L<OSSL_PARAM(3)>. The following utility functions allow the parameters to be
duplicated and merged with other L<OSSL_PARAM(3)> 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().
If the argument to OSSL_PARAM_free() is NULL, nothing is done.

OSSL_PARAM_clear_free() performs the same function as OSSL_PARAM_free() but
additionally calls OPENSSL_cleanse() on the contents copied in. Note: only
params built via the OSSL_PARAM_dup() or OSSL_PARAM_BLD_to_param() functions
will be effectively cleared, parameters built any other way will still be
freed but no cleanse operation will be performed.

=head1 RETURN VALUES

The functions OSSL_PARAM_dup() and OSSL_PARAM_merge() return a newly allocated
L<OSSL_PARAM(3)> 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 OSSL_PARAM_dup, OSSL_PARAM_merge and OSSL_PARAM_free functions were added
in OpenSSL 3.0. OSSL_PARAM_clear_free was added in OpenSSL 4.0.0.

=head1 COPYRIGHT

Copyright 2021-2024 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
