1=pod 2 3=head1 NAME 4 5EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits, 6EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_size 7- EVP_PKEY information functions 8 9=head1 SYNOPSIS 10 11 #include <openssl/evp.h> 12 13 int EVP_PKEY_get_size(const EVP_PKEY *pkey); 14 int EVP_PKEY_get_bits(const EVP_PKEY *pkey); 15 int EVP_PKEY_get_security_bits(const EVP_PKEY *pkey); 16 17 #define EVP_PKEY_bits EVP_PKEY_get_bits 18 #define EVP_PKEY_security_bits EVP_PKEY_get_security_bits 19 #define EVP_PKEY_size EVP_PKEY_get_size 20 21=head1 DESCRIPTION 22 23EVP_PKEY_get_size() returns the maximum suitable size for the output 24buffers for almost all operations that can be done with I<pkey>. 25This corresponds to the provider parameter B<OSSL_PKEY_PARAM_MAX_SIZE>. 26The primary documented use is with L<EVP_SignFinal(3)> and 27L<EVP_SealInit(3)>, but it isn't limited there. The returned size is 28also large enough for the output buffer of L<EVP_PKEY_sign(3)>, 29L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt(3)>, L<EVP_PKEY_derive(3)>. 30 31It must be stressed that, unless the documentation for the operation 32that's being performed says otherwise, the size returned by 33EVP_PKEY_get_size() is only preliminary and not exact, so the final 34contents of the target buffer may be smaller. It is therefore crucial 35to take note of the size given back by the function that performs the 36operation, such as L<EVP_PKEY_sign(3)> (the I<siglen> argument will 37receive that length), to avoid bugs. 38 39EVP_PKEY_get_bits() returns the cryptographic length of the cryptosystem 40to which the key in I<pkey> belongs, in bits. Note that the definition 41of cryptographic length is specific to the key cryptosystem. 42This length corresponds to the provider parameter B<OSSL_PKEY_PARAM_BITS>. 43 44EVP_PKEY_get_security_bits() returns the number of security bits of the given 45I<pkey>, bits of security is defined in NIST SP800-57. 46This corresponds to the provider parameter B<OSSL_PKEY_PARAM_SECURITY_BITS>. 47 48=head1 RETURN VALUES 49 50EVP_PKEY_get_size(), EVP_PKEY_get_bits() and EVP_PKEY_get_security_bits() 51return a positive number, or 0 if this size isn't available. 52 53=head1 NOTES 54 55Most functions that have an output buffer and are mentioned with 56EVP_PKEY_get_size() have a functionality where you can pass NULL for the 57buffer and still pass a pointer to an integer and get the exact size 58that this function call delivers in the context that it's called in. 59This allows those functions to be called twice, once to find out the 60exact buffer size, then allocate the buffer in between, and call that 61function again actually output the data. For those functions, it 62isn't strictly necessary to call EVP_PKEY_get_size() to find out the 63buffer size, but may be useful in cases where it's desirable to know 64the upper limit in advance. 65 66It should also be especially noted that EVP_PKEY_get_size() shouldn't be 67used to get the output size for EVP_DigestSignFinal(), according to 68L<EVP_DigestSignFinal(3)/NOTES>. 69 70=head1 SEE ALSO 71 72L<provider-keymgmt(7)>, 73L<EVP_SignFinal(3)>, 74L<EVP_SealInit(3)>, 75L<EVP_PKEY_sign(3)>, 76L<EVP_PKEY_encrypt(3)>, 77L<EVP_PKEY_decrypt(3)>, 78L<EVP_PKEY_derive(3)> 79 80=head1 HISTORY 81 82The EVP_PKEY_bits(), EVP_PKEY_security_bits(), and EVP_PKEY_size() functions 83were renamed to include C<get> in their names in OpenSSL 3.0, respectively. 84The old names are kept as non-deprecated alias macros. 85 86=head1 COPYRIGHT 87 88Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. 89 90Licensed under the Apache License 2.0 (the "License"). You may not use 91this file except in compliance with the License. You can obtain a copy 92in the file LICENSE in the source distribution or at 93L<https://www.openssl.org/source/license.html>. 94 95=cut 96
