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