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