mirror of
https://github.com/openssl/openssl.git
synced 2025-01-06 13:26:43 +08:00
4ccad35756
This fixes numerous bugs in documentation in regards to UTF8 params and their sizes. The returned size should always be without the terminating NUL byte. On the other hand on the requestor side the size of the buffer should include the NUL byte if it expects it being included in the returned string. Also make this clear in the EVP_PKEY_get_group_name() documentation which uses utf8 string params under the hood. Fixes #16287 Reviewed-by: Viktor Dukhovni <viktor@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/16296)
121 lines
4.1 KiB
Plaintext
121 lines
4.1 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
EVP_PKEY_gettable_params, EVP_PKEY_get_params,
|
|
EVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param,
|
|
EVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param,
|
|
EVP_PKEY_get_octet_string_param
|
|
- retrieve key parameters from a key
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/evp.h>
|
|
|
|
const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey);
|
|
int EVP_PKEY_get_params(const EVP_PKEY *pkey, OSSL_PARAM params[]);
|
|
int EVP_PKEY_get_int_param(const EVP_PKEY *pkey, const char *key_name,
|
|
int *out);
|
|
int EVP_PKEY_get_size_t_param(const EVP_PKEY *pkey, const char *key_name,
|
|
size_t *out);
|
|
int EVP_PKEY_get_bn_param(const EVP_PKEY *pkey, const char *key_name,
|
|
BIGNUM **bn);
|
|
int EVP_PKEY_get_utf8_string_param(const EVP_PKEY *pkey, const char *key_name,
|
|
char *str, size_t max_buf_sz,
|
|
size_t *out_sz);
|
|
int EVP_PKEY_get_octet_string_param(const EVP_PKEY *pkey, const char *key_name,
|
|
unsigned char *buf, size_t max_buf_sz,
|
|
size_t *out_sz);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
EVP_PKEY_get_params() retrieves parameters from the key I<pkey>, according to
|
|
the contents of I<params>.
|
|
See L<OSSL_PARAM(3)> for information about parameters.
|
|
|
|
EVP_PKEY_gettable_params() returns a constant list of I<params> indicating
|
|
the names and types of key parameters that can be retrieved.
|
|
See L<OSSL_PARAM(3)> for information about parameters.
|
|
|
|
EVP_PKEY_get_int_param() retrieves a key I<pkey> integer value I<*out>
|
|
associated with a name of I<key_name>.
|
|
|
|
EVP_PKEY_get_size_t_param() retrieves a key I<pkey> size_t value I<*out>
|
|
associated with a name of I<key_name>.
|
|
|
|
EVP_PKEY_get_bn_param() retrieves a key I<pkey> BIGNUM value I<**bn>
|
|
associated with a name of I<key_name>. If I<*bn> is NULL then the BIGNUM
|
|
is allocated by the method.
|
|
|
|
EVP_PKEY_get_utf8_string_param() get a key I<pkey> UTF8 string value int a buffer
|
|
I<str> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
|
|
If I<out_sz> is not NULL the I<*out_sz> is set to the length of the string
|
|
not including the terminating NUL byte.
|
|
|
|
EVP_PKEY_get_octet_string_param() copy a I<pkey>'s octet string value into a buffer
|
|
I<buf> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
|
|
I<*out_sz> is the returned size of the buffer if it is not NULL.
|
|
|
|
=head1 NOTES
|
|
|
|
These functions only work for B<EVP_PKEY>s that contain a provider side key.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
EVP_PKEY_gettable_params() returns NULL on error or if it is not supported,
|
|
|
|
All other methods return 1 if a value associated with the key's I<key_name> was
|
|
successfully returned, or 0 if there was an error.
|
|
An error may be returned by methods EVP_PKEY_get_utf8_string_param() and
|
|
EVP_PKEY_get_octet_string_param() if I<max_buf_sz> is not big enough to hold the
|
|
value. If I<out_sz> is not NULL, I<*out_sz> will be assigned the required
|
|
buffer size to hold the value.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
#include <openssl/evp.h>
|
|
|
|
char *curve_name[64];
|
|
unsigned char pub[256];
|
|
BIGNUM *bn_priv = NULL;
|
|
|
|
/*
|
|
* NB: assumes 'key' is set up before the next step. In this example the key
|
|
* is an EC key.
|
|
*/
|
|
|
|
if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME,
|
|
curve_name, sizeof(curve_name), &len)) {
|
|
/* Error */
|
|
}
|
|
if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,
|
|
pub, sizeof(pub), &len)) {
|
|
/* Error */
|
|
}
|
|
if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {
|
|
/* Error */
|
|
}
|
|
|
|
|
|
BN_clear_free(bn_priv);
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<EVP_PKEY_CTX_new(3)>, L<provider-keymgmt(7)>, L<OSSL_PARAM(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
These functions were added in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|
|
|