doc/internal/man3/evp_keymgmt_util_export_to_provider.pod

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