NAME
EVP_PKEY_size,
EVP_PKEY_bits,
EVP_PKEY_security_bits —
EVP_PKEY information
functions
SYNOPSIS
#include
<openssl/evp.h>
int
EVP_PKEY_size(const EVP_PKEY
*pkey);
int
EVP_PKEY_bits(const EVP_PKEY
*pkey);
int
EVP_PKEY_security_bits(const EVP_PKEY
*pkey);
DESCRIPTION
EVP_PKEY_size()
returns the maximum size in bytes needed for the output buffer for almost
any operation that can be done with pkey. The primary
use is with
EVP_SignFinal(3) and
EVP_SealInit(3). The returned size is also large enough for
the output buffer of
EVP_PKEY_sign(3),
EVP_PKEY_encrypt(3),
EVP_PKEY_decrypt(3), and
EVP_PKEY_derive(3).
Unless the documentation for the operation
says otherwise, the size returned by
EVP_PKEY_size()
is only an upper limit and the final content of the target buffer may be
smaller. It is therefore crucial to take note of the size given back by the
function that performs the operation. For example,
EVP_PKEY_sign(3) returns that length in the
*siglen argument.
Using
EVP_PKEY_size()
is discouraged with
EVP_DigestSignFinal(3).
Most functions using an output buffer support
passing NULL for the buffer and a pointer to an
integer to get the exact size that this function call delivers in the
context that it is called in. This allows those functions to be called
twice, once to find out the exact buffer size, then allocate the buffer in
between, and call that function again to actually output the data. For those
functions, it isn't strictly necessary to call
EVP_PKEY_size()
to find out the buffer size, but it may still be useful in cases where it's
desirable to know the upper limit in advance.
By default,
EVP_PKEY_size()
is supported for the following algorithms:
| same result as from: | |
| CMAC | EVP_MAX_BLOCK_LENGTH
= 32 |
| DH | DH_size(3) |
| DSA | DSA_size(3) |
| EC | ECDSA_size(3) |
| GOST01 | 64 or 128 |
| HMAC | EVP_MAX_MD_SIZE
= 64 |
| RSA | RSA_size(3) |
The application program can support additional algorithms by calling EVP_PKEY_asn1_set_public(3).
EVP_PKEY_bits()
returns the cryptographic length of the cryptosystem to which the key in
pkey belongs, in bits. The definition of cryptographic
length is specific to the key cryptosystem. By default, the following
algorithms are supported:
| cryptographic length = | same result as from: | |
| significant bits in ... | ||
| DH | the public domain parameter p | DH_bits(3) |
| DSA | the public domain parameter p | DSA_bits(3) |
| EC | the order of the group | EC_GROUP_order_bits(3) |
| GOST01 | 256 or 512 | — |
| RSA | the public modulus | RSA_bits(3) |
The application program can support additional algorithms by calling EVP_PKEY_asn1_set_public(3).
EVP_PKEY_security_bits()
returns the security strength measured in bits of the given
pkey as defined in NIST SP800-57. By default, the
following algorithms are supported:
| same result as from: | |
| DH | DH_security_bits(3) |
| DSA | DSA_security_bits(3) |
| EC | EC_GROUP_order_bits(3) divided by 2 |
| GOST01 | not supported, return value is -2 |
| RSA | RSA_security_bits(3) |
For EC keys, if the result is greater than 80, it is rounded down to 256, 192, 128, 112, or 80.
The application program can support additional algorithms by calling EVP_PKEY_asn1_set_security_bits(3).
RETURN VALUES
EVP_PKEY_size() and
EVP_PKEY_bits() return a positive number or 0 if
this size isn't available.
EVP_PKEY_security_bits() returns a number
in the range from 0 to 256 inclusive or -2 if this function is unsupported
for the algorithm used by pkey. It returns 0 if
pkey is NULL.
SEE ALSO
EVP_PKEY_decrypt(3), EVP_PKEY_derive(3), EVP_PKEY_encrypt(3), EVP_PKEY_new(3), EVP_PKEY_sign(3), EVP_SealInit(3), EVP_SignFinal(3)
HISTORY
EVP_PKEY_size() first appeared in SSLeay
0.6.0 and EVP_PKEY_bits() in SSLeay 0.9.0. Both
functions have been available since OpenBSD 2.4.
EVP_PKEY_security_bits() first appeared in
OpenSSL 1.1.0 and has been available since OpenBSD
7.2.