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, int locking);
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 I<locking> is set to 1 then
56then I<pk>'s lock will be obtained while doing the clear. Otherwise it will be
57assumed that the lock has already been obtained or is not required.
58
59evp_keymgmt_util_cache_keydata() can be used to add a provider key
60object to a B<PKEY>.
61
62evp_keymgmt_util_cache_keyinfo() can be used to get all kinds of
63information from the provvider "origin" and save it in I<pk>'s
64information cache.
65
66evp_keymgmt_util_fromdata() can be used to add key object data to a
67given key I<target> via a B<EVP_KEYMGMT> interface.  This is used as a
68helper for L<EVP_PKEY_fromdata(3)>.
69
70In all functions that take a I<selection> argument, the selection is used to
71constraint the information requested on export. It is also used in the cache
72so that key data is guaranteed to contain all the information requested in
73the selection.
74
75=head1 RETURN VALUES
76
77evp_keymgmt_export_to_provider() and evp_keymgmt_util_fromdata()
78return a pointer to the appropriate provider side key (created or
79found again), or NULL on error.
80
81evp_keymgmt_util_find_operation_cache() returns a pointer to the
82operation cache slot.  If I<keymgmt> is NULL, or if there is no slot
83with a match for I<keymgmt>, NULL is returned.
84
85evp_keymgmt_util_cache_keydata() and evp_keymgmt_util_clear_operation_cache()
86return 1 on success or 0 otherwise.
87
88=head1 NOTES
89
90"Legacy key" is the term used for any key that has been assigned to an
91B<EVP_PKEY> with EVP_PKEY_assign_RSA() and similar functions.
92
93=head1 SEE ALSO
94
95L<EVP_PKEY_ASN1_METHOD(3)>, L<EVP_PKEY_assign_RSA(3)>
96
97=head1 COPYRIGHT
98
99Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
100
101Licensed under the Apache License 2.0 (the "License").  You may not use
102this file except in compliance with the License.  You can obtain a copy
103in the file LICENSE in the source distribution or at
104L<https://www.openssl.org/source/license.html>.
105
106=cut
107