1=pod
2
3=head1 NAME
4
5evp_keymgmt_util_export,
6evp_keymgmt_util_export_to_provider,
7evp_keymgmt_util_find_operation_cache,
8evp_keymgmt_util_clear_operation_cache,
9evp_keymgmt_util_cache_keydata,
10evp_keymgmt_util_cache_keyinfo,
11evp_keymgmt_util_fromdata,
12OP_CACHE_ELEM
13- internal KEYMGMT utility functions
14
15=head1 SYNOPSIS
16
17 #include "crypto/evp.h"
18
19 typedef struct OP_CACHE_ELEM;
20
21 int evp_keymgmt_util_export(const EVP_PKEY *pk, int selection,
22                             OSSL_CALLBACK *export_cb, void *export_cbarg);
23 void *evp_keymgmt_util_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt,
24                                           int selection);
25 OP_CACHE_ELEM *evp_keymgmt_util_find_operation_cache(EVP_PKEY *pk,
26                                                      EVP_KEYMGMT *keymgmt,
27                                                      int selection);
28 int evp_keymgmt_util_clear_operation_cache(EVP_PKEY *pk);
29 int evp_keymgmt_util_cache_keydata(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt,
30                                    void *keydata, int selection);
31 void evp_keymgmt_util_cache_keyinfo(EVP_PKEY *pk);
32 void *evp_keymgmt_util_fromdata(EVP_PKEY *target, EVP_KEYMGMT *keymgmt,
33                                 int selection, const OSSL_PARAM params[]);
34
35=head1 DESCRIPTION
36
37evp_keymgmt_util_export() calls L<evp_keymgmt_export(3)> with the
38I<keymgmt> and I<keydata> from I<pk>.  This is used as a
39helper for L<EVP_PKEY_todata(3)>.
40
41evp_keymgmt_util_export_to_provider() exports cached key material
42(provider side key material) from the given key I<pk> to a provider
43via a B<EVP_KEYMGMT> interface, if this hasn't already been done.
44It maintains a cache of provider key references in I<pk> to keep track
45of all provider side keys.
46
47To export a legacy key, use L<evp_pkey_export_to_provider(3)> instead,
48as this function ignores any legacy key data.
49
50evp_keymgmt_util_find_operation_cache() finds
51I<keymgmt> in I<pk>'s cache of provided keys for operations.
52It should only be called while holding I<pk>'s lock (read or write).
53
54evp_keymgmt_util_clear_operation_cache() can be used to explicitly
55clear the cache of operation key references. If required the lock must already
56have been obtained.
57
58evp_keymgmt_util_cache_keydata() can be used to add a provider key
59object to a B<PKEY>.
60
61evp_keymgmt_util_cache_keyinfo() can be used to get all kinds of
62information from the provvider "origin" and save it in I<pk>'s
63information cache.
64
65evp_keymgmt_util_fromdata() can be used to add key object data to a
66given key I<target> via a B<EVP_KEYMGMT> interface.  This is used as a
67helper for L<EVP_PKEY_fromdata(3)>.
68
69In all functions that take a I<selection> argument, the selection is used to
70constraint the information requested on export. It is also used in the cache
71so that key data is guaranteed to contain all the information requested in
72the selection.
73
74=head1 RETURN VALUES
75
76evp_keymgmt_export_to_provider() and evp_keymgmt_util_fromdata()
77return a pointer to the appropriate provider side key (created or
78found again), or NULL on error.
79
80evp_keymgmt_util_find_operation_cache() returns a pointer to the
81operation cache slot.  If I<keymgmt> is NULL, or if there is no slot
82with a match for I<keymgmt>, NULL is returned.
83
84evp_keymgmt_util_cache_keydata() and evp_keymgmt_util_clear_operation_cache()
85return 1 on success or 0 otherwise.
86
87=head1 NOTES
88
89"Legacy key" is the term used for any key that has been assigned to an
90B<EVP_PKEY> with EVP_PKEY_assign_RSA() and similar functions.
91
92=head1 SEE ALSO
93
94L<EVP_PKEY_ASN1_METHOD(3)>, L<EVP_PKEY_assign_RSA(3)>
95
96=head1 COPYRIGHT
97
98Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
99
100Licensed under the Apache License 2.0 (the "License").  You may not use
101this file except in compliance with the License.  You can obtain a copy
102in the file LICENSE in the source distribution or at
103L<https://www.openssl.org/source/license.html>.
104
105=cut
106