doc/man3/EVP_KEYMGMT.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_KEYMGMT,
   6 EVP_KEYMGMT_fetch,
   7 EVP_KEYMGMT_up_ref,
   8 EVP_KEYMGMT_free,
   9 EVP_KEYMGMT_provider,
  10 EVP_KEYMGMT_is_a,
  11 EVP_KEYMGMT_number,
  12 EVP_KEYMGMT_do_all_provided,
  13 EVP_KEYMGMT_names_do_all,
  14 EVP_KEYMGMT_gettable_params,
  15 EVP_KEYMGMT_settable_params,
  16 EVP_KEYMGMT_gen_settable_params
  17 - EVP key management routines
  18
  19 =head1 SYNOPSIS
  20
  21  #include <openssl/evp.h>
  22
  23  typedef struct evp_keymgmt_st EVP_KEYMGMT;
  24
  25  EVP_KEYMGMT *EVP_KEYMGMT_fetch(OPENSSL_CTX *ctx, const char *algorithm,
  26                                 const char *properties);
  27  int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);
  28  void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);
  29  const OSSL_PROVIDER *EVP_KEYMGMT_provider(const EVP_KEYMGMT *keymgmt);
  30  int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);
  31  int EVP_KEYMGMT_number(const EVP_KEYMGMT *keymgmt);
  32  void EVP_KEYMGMT_do_all_provided(OPENSSL_CTX *libctx,
  33                                   void (*fn)(EVP_KEYMGMT *keymgmt, void *arg),
  34                                   void *arg);
  35  void EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt,
  36                                void (*fn)(const char *name, void *data),
  37                                void *data);
  38  const OSSL_PARAM *EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT *keymgmt);
  39  const OSSL_PARAM *EVP_KEYMGMT_settable_params(const EVP_KEYMGMT *keymgmt);
  40  const OSSL_PARAM *EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT *keymgmt);
  41
  42 =head1 DESCRIPTION
  43
  44 B<EVP_KEYMGMT> is a method object that represents key management
  45 implementations for different cryptographic algorithms.
  46 This method object provides functionality to have providers import key
  47 material from the outside, as well as export key material to the
  48 outside.
  49 Most of the functionality can only be used internally and has no
  50 public interface, this object is simply passed into other functions
  51 when needed.
  52
  53 EVP_KEYMGMT_fetch() looks for an algorithm within the provider that
  54 has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the
  55 name given by I<algorithm> and the properties given by I<properties>.
  56
  57 EVP_KEYMGMT_up_ref() increments the reference count for the given
  58 B<EVP_KEYMGMT> I<keymgmt>.
  59
  60 EVP_KEYMGMT_free() decrements the reference count for the given
  61 B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it.
  62
  63 EVP_KEYMGMT_provider() returns the provider that has this particular
  64 implementation.
  65
  66 EVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an
  67 algorithm that's identifiable with I<name>.
  68
  69 EVP_KEYMGMT_number() returns the internal dynamic number assigned to
  70 the I<keymgmt>.
  71
  72 EVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and
  73 calls I<fn> with each name and I<data>.
  74
  75 EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by
  76 all activated providers in the library context I<libctx>, and for each
  77 of the implementations, calls I<fn> with the implementation method and
  78 I<data> as arguments.
  79
  80 EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a
  81 constant B<OSSL_PARAM> array that describes the names and types of key
  82 parameters that can be retrieved or set.
  83 EVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>.
  84 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
  85
  86 EVP_KEYMGMT_gen_settable_params() returns a constant B<OSSL_PARAM> array that
  87 describes the names and types of key generation parameters that can be set via
  88 L<EVP_PKEY_CTX_set_params(3)>.
  89
  90 =head1 NOTES
  91
  92 EVP_KEYMGMT_fetch() may be called implicitly by other fetching
  93 functions, using the same library context and properties.
  94 Any other API that uses keys will typically do this.
  95
  96 =head1 RETURN VALUES
  97
  98 EVP_KEYMGMT_fetch() returns a pointer to the key management
  99 implementation represented by an EVP_KEYMGMT object, or NULL on
 100 error.
 101
 102 EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error.
 103
 104 EVP_KEYMGMT_free() doesn't return any value.
 105
 106 EVP_KEYMGMT_provider() returns a pointer to a provider object, or NULL
 107 on error.
 108
 109 EVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable,
 110 otherwise 0.
 111
 112 EVP_KEYMGMT_number() returns an integer.
 113
 114 EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and
 115 EVP_KEYMGMT_gen_settable_params() return a constant B<OSSL_PARAM> array or
 116 NULL on error.
 117
 118 =head1 SEE ALSO
 119
 120 L<EVP_MD_fetch(3)>, L<OPENSSL_CTX(3)>
 121
 122 =head1 HISTORY
 123
 124 The functions described here were added in OpenSSL 3.0.
 125
 126 =head1 COPYRIGHT
 127
 128 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 129
 130 Licensed under the Apache License 2.0 (the "License").  You may not use
 131 this file except in compliance with the License.  You can obtain a copy
 132 in the file LICENSE in the source distribution or at
 133 L<https://www.openssl.org/source/license.html>.
 134
 135 =cut