doc/internal/man3/evp_keymgmt_util_export_to_provider.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 evp_keymgmt_util_export_to_provider,
   6 evp_keymgmt_util_find_operation_cache_index,
   7 evp_keymgmt_util_clear_operation_cache,
   8 evp_keymgmt_util_cache_keydata,
   9 evp_keymgmt_util_cache_keyinfo,
  10 evp_keymgmt_util_fromdata
  11 - internal KEYMGMT utility functions
  12
  13 =head1 SYNOPSIS
  14
  15  #include "crypto/evp.h"
  16
  17  void *evp_keymgmt_util_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
  18  size_t evp_keymgmt_util_find_operation_cache_index(EVP_PKEY *pk,
  19                                                     EVP_KEYMGMT *keymgmt);
  20  void evp_keymgmt_util_clear_operation_cache(EVP_PKEY *pk);
  21  void evp_keymgmt_util_cache_keydata(EVP_PKEY *pk, size_t index,
  22                                      EVP_KEYMGMT *keymgmt, void *keydata);
  23  void evp_keymgmt_util_cache_keyinfo(EVP_PKEY *pk);
  24  void *evp_keymgmt_util_fromdata(EVP_PKEY *target, EVP_KEYMGMT *keymgmt,
  25                                  int selection, const OSSL_PARAM params[]);
  26
  27 =head1 DESCRIPTION
  28
  29 evp_keymgmt_util_export_to_provider() exports cached key material
  30 (provider side key material) from the given key I<pk> to a provider
  31 via a B<EVP_KEYMGMT> interface, if this hasn't already been done.
  32 It maintains a cache of provider key references in I<pk> to keep track
  33 of all provider side keys.
  34
  35 To export a legacy key, use L<evp_pkey_export_to_provider(3)> instead,
  36 as this function ignores any legacy key data.
  37
  38 evp_keymgmt_util_find_operation_cache_index() finds the location if
  39 I<keymgmt> in I<pk>'s cache of provided keys for operations.  If
  40 I<keymgmt> is NULL or couldn't be found in the cache, it finds the
  41 first empty slot instead if there is any.
  42
  43 evp_keymgmt_util_clear_operation_cache() can be used to explicitly
  44 clear the cache of operation key references.
  45
  46 evp_keymgmt_util_cache_keydata() can be used to assign a provider key
  47 object to a specific cache slot in the given I<target>.
  48 I<Use extreme care>.
  49
  50 evp_keymgmt_util_cache_keyinfo() can be used to get all kinds of
  51 information from the provvider "origin" and save it in I<pk>'s
  52 information cache.
  53
  54 evp_keymgmt_util_fromdata() can be used to add key object data to a
  55 given key I<target> via a B<EVP_KEYMGMT> interface.  This is used as a
  56 helper for L<EVP_PKEY_fromdata(3)>.
  57
  58 =head1 RETURN VALUES
  59
  60 evp_keymgmt_export_to_provider() and evp_keymgmt_util_fromdata()
  61 return a pointer to the appropriate provider side key (created or
  62 found again), or NULL on error.
  63
  64 evp_keymgmt_util_find_operation_cache_index() returns the index of the
  65 operation cache slot.  If I<keymgmt> is NULL, or if there is no slot
  66 with a match for I<keymgmt>, the index of the first empty slot is
  67 returned, or the maximum number of slots if there isn't an empty one.
  68
  69 =head1 NOTES
  70
  71 "Legacy key" is the term used for any key that has been assigned to an
  72 B<EVP_PKEY> with EVP_PKEY_assign_RSA() and similar functions.
  73
  74 =head1 SEE ALSO
  75
  76 L<EVP_PKEY_ASN1_METHOD(3)>, L<EVP_PKEY_assign_RSA(3)>
  77
  78 =head1 COPYRIGHT
  79
  80 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
  81
  82 Licensed under the Apache License 2.0 (the "License").  You may not use
  83 this file except in compliance with the License.  You can obtain a copy
  84 in the file LICENSE in the source distribution or at
  85 L<https://www.openssl.org/source/license.html>.
  86
  87 =cut