EVP: Add evp_pkey_upgrade_to_provider(), for EVP_PKEY upgrades
[openssl.git] / doc / internal / man3 / evp_pkey_make_provided.pod
1 =pod
2
3 =head1 NAME
4
5 evp_pkey_make_provided - internal EVP_PKEY support functions for providers
6
7 =head1 SYNOPSIS
8
9  /* Only for EVP source */
10  #include "evp_local.h"
11
12  void *evp_pkey_make_provided(EVP_PKEY *pk, OPENSSL_CTX *libctx,
13                               EVP_KEYMGMT **keymgmt, const char *propquery);
14
15 =head1 DESCRIPTION
16
17 evp_pkey_make_provided() ensures that the B<EVP_PKEY> I<pk> is provided within
18 the library context I<libctx> (NULL means the default context).  I<keymgmt>
19 may point at a reference to a B<EVP_KEYMGMT>, and works as an input/output
20 parameter.
21 As input to this function, it can be used to specify a B<EVP_KEYMGMT> to be
22 used for exporting.  If not (I<*keymgmt> is NULL), then this function will
23 fetch an B<EVP_KEYMGMT> implicitly, using I<propquery> as property query string.
24 As output from this function, I<*keymgmt> will be assigned the B<EVP_KEYMGMT>
25 that was used, if the export was successful, otherwise it will be assigned NULL.
26
27 If I<pk> has an assigned legacy key, a check is done to see if any of
28 its key material has changed since last export, by comparing the
29 result of the legacy key's dirty_cnt() method with a copy of that
30 result from last time evp_pkey_make_provided() was run with this
31 B<EVP_PKEY>.
32 If it has, the cache of already exported keys is cleared, and a new
33 export is made with the new legacy key material.
34
35 =head1 RETURN VALUES
36
37 evp_pkey_make_provided() returns the provider key data that was exported if
38 I<pk> was successfully provided.  Otherwise, NULL is returned.
39
40 =head1 NOTES
41
42 Some functions calling evp_pkey_make_provided() may have received a const
43 key, and may therefore have to cast the key to non-const form to call this
44 function.  Since B<EVP_PKEY> is always dynamically allocated, this is OK.
45
46 =head1 SEE ALSO
47
48 L<OPENSSL_CTX(3)>, L<EVP_KEYMGMT(3)>
49
50 =head1 HISTORY
51
52 The functions described here were all added in OpenSSL 3.0.
53
54 =head1 COPYRIGHT
55
56 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
57
58 Licensed under the Apache License 2.0 (the "License").  You may not use
59 this file except in compliance with the License.  You can obtain a copy
60 in the file LICENSE in the source distribution or at
61 L<https://www.openssl.org/source/license.html>.
62
63 =cut