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