doc/internal/man3/evp_pkey_export_to_provider.pod

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