DOCS: Add internal docs for EVP_PKEY and the export functions
[openssl.git] / doc / internal / man3 / evp_pkey_export_to_provider.pod
1 =pod
2
3 =head1 NAME
4
5 evp_pkey_export_to_provider, evp_pkey_upgrade_to_provider
6 - internal EVP_PKEY support functions for providers
7
8 =head1 SYNOPSIS
9
10  /* Only for EVP source */
11  #include "evp_local.h"
12
13  void *evp_pkey_export_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx,
14                                    EVP_KEYMGMT **keymgmt,
15                                    const char *propquery);
16  void *evp_pkey_upgrade_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx,
17                                     EVP_KEYMGMT **keymgmt,
18                                     const char *propquery);
19
20 =head1 DESCRIPTION
21
22 This manual uses the term "origin", which is explained in internal
23 L<EVP_PKEY(7)>.
24
25 evp_pkey_export_to_provider() exports the "origin" key contained in I<pk>
26 to its operation cache to make it suitable for an B<EVP_KEYMGMT> given either
27 with I<*keymgmt> or with an implicit fetch using I<libctx> (NULL means the
28 default context), the name of the legacy type of I<pk>, and the I<propquery>
29 (NULL means the default property query settings).
30
31 If I<keymgmt> isn't NULL but I<*keymgmt> is, and the "origin" was successfully
32 exported, then I<*keymgmt> is assigned the implicitly fetched B<EVP_KEYMGMT>.
33
34 evp_pkey_upgrade_to_provider() exports the legacy "origin" key contained in
35 I<pk> to it's provider side counterpart, then clears the legacy "origin" key
36 along with other legacy data, and resets all the caches.  Otherwise, it works
37 like evp_pkey_export_to_provider().
38
39 I<evp_pkey_upgrade_to_provider() must be used with great care, only if there's
40 no other way.>
41 Most of the time, it's sufficient to use evp_pkey_export_to_provider(), but in
42 case the key needs modification with data coming from a provided key, the key
43 will need an upgrade.
44
45 =head1 RETURN VALUES
46
47 evp_pkey_export_to_provider() and evp_pkey_upgrade_to_provider() both return
48 the provider key data that was exported if the "origin" was successfully
49 exported to its target.  Otherwise, NULL is returned.
50
51 =head1 NOTES
52
53 Some functions calling evp_pkey_export_to_provider() or
54 evp_pkey_upgrade_to_provider() may have received a const key, and may
55 therefore have to cast the key to non-const form to call this function.  Since
56 B<EVP_PKEY> is always dynamically allocated, this is OK.
57
58 =head1 SEE ALSO
59
60 L<OPENSSL_CTX(3)>, L<EVP_KEYMGMT(3)>
61
62 =head1 HISTORY
63
64 The functions described here were all added in OpenSSL 3.0.
65
66 =head1 COPYRIGHT
67
68 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
69
70 Licensed under the Apache License 2.0 (the "License").  You may not use
71 this file except in compliance with the License.  You can obtain a copy
72 in the file LICENSE in the source distribution or at
73 L<https://www.openssl.org/source/license.html>.
74
75 =cut