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