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_downgrade
   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  int evp_pkey_copy_downgraded(EVP_PKEY **dest, const EVP_PKEY *src);
  17  int evp_pkey_downgrade(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_downgrade() converts an B<EVP_PKEY> with a provider side "origin" key
  41 to one with a legacy "origin", if there's a corresponding legacy implementation.
  42 This clears the operation cache, except for the provider side "origin" key.
  43 This function is used in spots where provider side keys aren't yet supported,
  44 in an attempt to keep operating with available implementations.
  45
  46 =head1 RETURN VALUES
  47
  48 evp_pkey_export_to_provider() returns the provider key data if there was any
  49 allocated.  It also either sets I<*keymgmt> to the B<EVP_KEYMGMT> associated
  50 with the returned key data, or NULL on error.
  51
  52 evp_pkey_downgrade() returns 1 on success or 0 on error.
  53
  54 =head1 NOTES
  55
  56 Some functions calling evp_pkey_export_to_provider() or evp_pkey_downgrade()
  57 may have received a const key, and may therefore have to cast the key to
  58 non-const form to call this function.  Since B<EVP_PKEY> is always dynamically
  59 allocated, this is OK.
  60
  61 =head1 SEE ALSO
  62
  63 L<OPENSSL_CTX(3)>, L<EVP_KEYMGMT(3)>
  64
  65 =head1 HISTORY
  66
  67 The functions described here were all added in OpenSSL 3.0.
  68
  69 =head1 COPYRIGHT
  70
  71 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
  72
  73 Licensed under the Apache License 2.0 (the "License").  You may not use
  74 this file except in compliance with the License.  You can obtain a copy
  75 in the file LICENSE in the source distribution or at
  76 L<https://www.openssl.org/source/license.html>.
  77
  78 =cut