doc/man3/EVP_PKEY_gettable_params.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_gettable_params, EVP_PKEY_get_params,
   6 EVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param,
   7 EVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param,
   8 EVP_PKEY_get_octet_string_param
   9 - retrieve key parameters from a key
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/evp.h>
  14
  15  const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey);
  16  int EVP_PKEY_get_params(const EVP_PKEY *pkey, OSSL_PARAM params[]);
  17  int EVP_PKEY_get_int_param(const EVP_PKEY *pkey, const char *key_name,
  18                             int *out);
  19  int EVP_PKEY_get_size_t_param(const EVP_PKEY *pkey, const char *key_name,
  20                                size_t *out);
  21  int EVP_PKEY_get_bn_param(const EVP_PKEY *pkey, const char *key_name,
  22                            BIGNUM **bn);
  23  int EVP_PKEY_get_utf8_string_param(const EVP_PKEY *pkey, const char *key_name,
  24                                     char *str, size_t max_buf_sz,
  25                                     size_t *out_len);
  26  int EVP_PKEY_get_octet_string_param(const EVP_PKEY *pkey, const char *key_name,
  27                                      unsigned char *buf, size_t max_buf_sz,
  28                                      size_t *out_len);
  29
  30 =head1 DESCRIPTION
  31
  32 EVP_PKEY_get_params() retrieves parameters from the key I<pkey>, according to
  33 the contents of I<params>.
  34 See L<OSSL_PARAM(3)> for information about parameters.
  35
  36 EVP_PKEY_gettable_params() returns a constant list of I<params> indicating
  37 the names and types of key parameters that can be retrieved.
  38 See L<OSSL_PARAM(3)> for information about parameters.
  39
  40 An B<OSSL_PARAM> of type B<OSSL_PARAM_INTEGER> or
  41 B<OSSL_PARAM_UNSIGNED_INTEGER> is of arbitrary length. Such a parameter can be
  42 obtained using any of the functions EVP_PKEY_get_int_param(),
  43 EVP_PKEY_get_size_t_param() or EVP_PKEY_get_bn_param(). Attempting to
  44 obtain an integer value that does not fit into a native C B<int> type will cause
  45 EVP_PKEY_get_int_param() to fail. Similarly attempting to obtain an integer
  46 value that is negative or does not fit into a native C B<size_t> type using
  47 EVP_PKEY_get_size_t_param() will also fail.
  48
  49 EVP_PKEY_get_int_param() retrieves a key I<pkey> integer value I<*out>
  50 associated with a name of I<key_name> if it fits into C<int> type. For
  51 parameters that do not fit into C<int> use EVP_PKEY_get_bn_param().
  52
  53 EVP_PKEY_get_size_t_param() retrieves a key I<pkey> size_t value I<*out>
  54 associated with a name of I<key_name> if it fits into C<size_t> type. For
  55 parameters that do not fit into C<size_t> use EVP_PKEY_get_bn_param().
  56
  57 EVP_PKEY_get_bn_param() retrieves a key I<pkey> BIGNUM value I<**bn>
  58 associated with a name of I<key_name>. If I<*bn> is NULL then the BIGNUM
  59 is allocated by the method.
  60
  61 EVP_PKEY_get_utf8_string_param() get a key I<pkey> UTF8 string value into a
  62 buffer I<str> of maximum size I<max_buf_sz> associated with a name of
  63 I<key_name>.  The maximum size must be large enough to accommodate the string
  64 value including a terminating NUL byte, or this function will fail.
  65 If I<out_len> is not NULL, I<*out_len> is set to the length of the string
  66 not including the terminating NUL byte. The required buffer size not including
  67 the terminating NUL byte can be obtained from I<*out_len> by calling the
  68 function with I<str> set to NULL.
  69
  70 EVP_PKEY_get_octet_string_param() get a key I<pkey>'s octet string value into a
  71 buffer I<buf> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
  72 If I<out_len> is not NULL, I<*out_len> is set to the length of the contents.
  73 The required buffer size can be obtained from I<*out_len> by calling the
  74 function with I<buf> set to NULL.
  75
  76 =head1 NOTES
  77
  78 These functions only work for B<EVP_PKEY>s that contain a provider side key.
  79
  80 =head1 RETURN VALUES
  81
  82 EVP_PKEY_gettable_params() returns NULL on error or if it is not supported.
  83
  84 All other methods return 1 if a value associated with the key's I<key_name> was
  85 successfully returned, or 0 if there was an error.
  86 An error may be returned by methods EVP_PKEY_get_utf8_string_param() and
  87 EVP_PKEY_get_octet_string_param() if I<max_buf_sz> is not big enough to hold the
  88 value.  If I<out_len> is not NULL, I<*out_len> will be assigned the required
  89 buffer size to hold the value.
  90
  91 =head1 EXAMPLES
  92
  93  #include <openssl/evp.h>
  94
  95  char *curve_name[64];
  96  unsigned char pub[256];
  97  BIGNUM *bn_priv = NULL;
  98
  99  /*
 100   * NB: assumes 'key' is set up before the next step. In this example the key
 101   * is an EC key.
 102   */
 103
 104  if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME,
 105                                      curve_name, sizeof(curve_name), &len)) {
 106    /* Error */
 107  }
 108  if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,
 109                                       pub, sizeof(pub), &len)) {
 110      /* Error */
 111  }
 112  if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {
 113      /* Error */
 114  }
 115
 116
 117  BN_clear_free(bn_priv);
 118
 119 =head1 SEE ALSO
 120
 121 L<EVP_PKEY_CTX_new(3)>, L<provider-keymgmt(7)>, L<OSSL_PARAM(3)>
 122
 123 =head1 HISTORY
 124
 125 These functions were added in OpenSSL 3.0.
 126
 127 =head1 COPYRIGHT
 128
 129 Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
 130
 131 Licensed under the Apache License 2.0 (the "License").  You may not use
 132 this file except in compliance with the License.  You can obtain a copy
 133 in the file LICENSE in the source distribution or at
 134 L<https://www.openssl.org/source/license.html>.
 135
 136 =cut
 137