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