1=pod 2 3=head1 NAME 4 5evp_pkey_export_to_provider, evp_pkey_copy_downgraded, evp_pkey_get_legacy 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, OSSL_LIB_CTX *libctx, 14 EVP_KEYMGMT **keymgmt, 15 const char *propquery); 16 int evp_pkey_copy_downgraded(EVP_PKEY **dest, const EVP_PKEY *src); 17 void *evp_pkey_get_legacy(EVP_PKEY *pk); 18 19=head1 DESCRIPTION 20 21This manual uses the term "origin", which is explained in internal 22L<EVP_PKEY(7)>. 23 24evp_pkey_export_to_provider() exports the "origin" key contained in I<pk> 25to its operation cache to make it suitable for an B<EVP_KEYMGMT> given either 26with I<*keymgmt> or with an implicit fetch using I<libctx> (NULL means the 27default context), the name of the legacy type of I<pk>, and the I<propquery> 28(NULL means the default property query settings). 29 30If I<keymgmt> isn't NULL but I<*keymgmt> is, and the "origin" was successfully 31exported, then I<*keymgmt> is assigned the implicitly fetched B<EVP_KEYMGMT>. 32 33evp_pkey_copy_downgraded() makes a copy of I<src> in legacy form into I<*dest>, 34if there's a corresponding legacy implementation. This should be used if the 35use of a downgraded key is temporary. 36For example, L<PEM_write_bio_PrivateKey_traditional(3)> uses this to try its 37best to get "traditional" PEM output even if the input B<EVP_PKEY> has a 38provider-native internal key. 39 40evp_pkey_get_legacy() obtains and returns a legacy key structure. If the 41EVP_PKEY already contains a legacy key then it is simply returned. If it is a 42provider based key, then a new legacy key is constructed based on the provider 43key. The legacy key is cached inside the EVP_PKEY and its value returned from 44this function. Subsequent calls to evp_pkey_get_legacy() will return the cached 45key. Subsequent changes to the provider key are not reflected back in the 46legacy key. Similarly changes to the legacy key are not reflected back in the 47provider key. 48 49=head1 RETURN VALUES 50 51evp_pkey_export_to_provider() returns the provider key data if there was any 52allocated. It also either sets I<*keymgmt> to the B<EVP_KEYMGMT> associated 53with the returned key data, or NULL on error. 54 55evp_pkey_get_legacy() returns the legacy key or NULL on error. 56 57=head1 NOTES 58 59Some functions calling evp_pkey_export_to_provider() may have received a const 60key, and may therefore have to cast the key to non-const form to call this 61function. Since B<EVP_PKEY> is always dynamically allocated, this is OK. 62 63=head1 SEE ALSO 64 65L<OSSL_LIB_CTX(3)>, L<EVP_KEYMGMT(3)> 66 67=head1 HISTORY 68 69The functions described here were all added in OpenSSL 3.0. 70 71=head1 COPYRIGHT 72 73Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. 74 75Licensed under the Apache License 2.0 (the "License"). You may not use 76this file except in compliance with the License. You can obtain a copy 77in the file LICENSE in the source distribution or at 78L<https://www.openssl.org/source/license.html>. 79 80=cut 81