Make EVP_PKEY_CTX_[get|set]_ec_paramgen_curve_name more generic
[openssl.git] / doc / man3 / EVP_PKEY_gettable_params.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_PKEY_gettable_params, EVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param,
6 EVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param,
7 EVP_PKEY_get_octet_string_param
8 - retrieve key parameters from a key
9
10 =head1 SYNOPSIS
11
12  #include <openssl/evp.h>
13
14  const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey);
15  int EVP_PKEY_get_int_param(EVP_PKEY *pkey, const char *key_name, int *out);
16  int EVP_PKEY_get_size_t_param(EVP_PKEY *pkey, const char *key_name, size_t *out);
17  int EVP_PKEY_get_bn_param(EVP_PKEY *pkey, const char *key_name, BIGNUM **bn);
18  int EVP_PKEY_get_utf8_string_param(EVP_PKEY *pkey, const char *key_name,
19                                     char *str, size_t max_buf_sz, size_t *out_sz);
20  int EVP_PKEY_get_octet_string_param(EVP_PKEY *pkey, const char *key_name,
21                                     unsigned char *buf, size_t max_buf_sz,
22                                     size_t *out_sz);
23
24 =head1 DESCRIPTION
25
26 EVP_PKEY_gettable_params() returns a constant list of I<params> indicating
27 the names and types of key parameters that can be retrieved.
28 See L<OSSL_PARAM(3)> for information about parameters.
29
30 EVP_PKEY_get_int_param() retrieves a key I<pkey> integer value I<*out>
31 associated with a name of I<key_name>.
32
33 EVP_PKEY_get_size_t_param() retrieves a key I<pkey> size_t value I<*out>
34 associated with a name of I<key_name>.
35
36 EVP_PKEY_get_bn_param() retrieves a key I<pkey> BIGNUM value I<**bn>
37 associated with a name of I<key_name>. If I<*bn> is NULL then the BIGNUM
38 is allocated by the method.
39
40 EVP_PKEY_get_utf8_string_param() get a key I<pkey> UTF8 string value int a buffer
41 I<str> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
42 I<*out_sz> is the returned size of the string if it is not NULL.
43
44 EVP_PKEY_get_octet_string_param() copy a I<pkey>'s octet string value into a buffer
45 I<buf> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
46 I<*out_sz> is the returned size of the buffer if it is not NULL.
47
48 =head1 NOTES
49
50 These functions only work for B<EVP_PKEY>s that contain a provider side key.
51
52 =head1 RETURN VALUES
53
54 EVP_PKEY_gettable_params() returns NULL on error or if it is not supported,
55
56 All other methods return 1 if a value associated with the key's I<key_name> was
57 successfully returned, or 0 if there was an error.
58 An error may be returned by methods EVP_PKEY_get_utf8_string_param() and
59 EVP_PKEY_get_octet_string_param() if I<max_buf_sz> is not big enough to hold the
60 value.
61
62 =head1 EXAMPLES
63
64  #include <openssl/evp.h>
65
66  char *curve_name[64];
67  unsigned char pub[256];
68  BIGNUM *bn_priv = NULL;
69
70  /*
71   * NB: assumes 'key' is set up before the next step. In this example the key
72   * is an EC key.
73   */
74
75  if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME,
76                                      curve_name, sizeof(curve_name), &len)) {
77    /* Error */
78  }
79  if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,
80                                       pub, sizeof(pub), &len)) {
81      /* Error */
82  }
83  if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {
84      /* Error */
85  }
86
87
88  BN_clear_free(bn_priv);
89
90 =head1 SEE ALSO
91
92 L<EVP_PKEY_CTX_new(3)>, L<provider-keymgmt(7)>, L<OSSL_PARAM(3)>
93
94 =head1 HISTORY
95
96 These functions were added in OpenSSL 3.0.
97
98 =head1 COPYRIGHT
99
100 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
101
102 Licensed under the Apache License 2.0 (the "License").  You may not use
103 this file except in compliance with the License.  You can obtain a copy
104 in the file LICENSE in the source distribution or at
105 L<https://www.openssl.org/source/license.html>.
106
107 =cut
108