doc/internal/man3/evp_pkey_export_to_provider.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 evp_pkey_export_to_provider, evp_pkey_upgrade_to_provider
   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, OPENSSL_CTX *libctx,
  14                                    EVP_KEYMGMT **keymgmt,
  15                                    const char *propquery);
  16  void *evp_pkey_upgrade_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx,
  17                                     EVP_KEYMGMT **keymgmt,
  18                                     const char *propquery);
  19
  20 =head1 DESCRIPTION
  21
  22 This manual uses the term "origin", which is explained in internal
  23 L<EVP_PKEY(7)>.
  24
  25 evp_pkey_export_to_provider() exports the "origin" key contained in I<pk>
  26 to its operation cache to make it suitable for an B<EVP_KEYMGMT> given either
  27 with I<*keymgmt> or with an implicit fetch using I<libctx> (NULL means the
  28 default context), the name of the legacy type of I<pk>, and the I<propquery>
  29 (NULL means the default property query settings).
  30
  31 If I<keymgmt> isn't NULL but I<*keymgmt> is, and the "origin" was successfully
  32 exported, then I<*keymgmt> is assigned the implicitly fetched B<EVP_KEYMGMT>.
  33
  34 evp_pkey_upgrade_to_provider() exports the legacy "origin" key contained in
  35 I<pk> to it's provider side counterpart, then clears the legacy "origin" key
  36 along with other legacy data, and resets all the caches.  Otherwise, it works
  37 like evp_pkey_export_to_provider().
  38
  39 I<evp_pkey_upgrade_to_provider() must be used with great care, only if there's
  40 no other way.>
  41 Most of the time, it's sufficient to use evp_pkey_export_to_provider(), but in
  42 case the key needs modification with data coming from a provided key, the key
  43 will need an upgrade.
  44
  45 =head1 RETURN VALUES
  46
  47 evp_pkey_export_to_provider() and evp_pkey_upgrade_to_provider() both return
  48 the provider key data that was exported if the "origin" was successfully
  49 exported to its target.  Otherwise, NULL is returned.
  50
  51 =head1 NOTES
  52
  53 Some functions calling evp_pkey_export_to_provider() or
  54 evp_pkey_upgrade_to_provider() may have received a const key, and may
  55 therefore have to cast the key to non-const form to call this function.  Since
  56 B<EVP_PKEY> is always dynamically allocated, this is OK.
  57
  58 =head1 SEE ALSO
  59
  60 L<OPENSSL_CTX(3)>, L<EVP_KEYMGMT(3)>
  61
  62 =head1 HISTORY
  63
  64 The functions described here were all added in OpenSSL 3.0.
  65
  66 =head1 COPYRIGHT
  67
  68 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
  69
  70 Licensed under the Apache License 2.0 (the "License").  You may not use
  71 this file except in compliance with the License.  You can obtain a copy
  72 in the file LICENSE in the source distribution or at
  73 L<https://www.openssl.org/source/license.html>.
  74
  75 =cut