1EVP_PKEY_GET_SIZE(3ossl)            OpenSSL           EVP_PKEY_GET_SIZE(3ossl)
2
3
4

NAME

6       EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits,
7       EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_size - EVP_PKEY
8       information functions
9

SYNOPSIS

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

DESCRIPTION

22       EVP_PKEY_get_size() returns the maximum suitable size for the output
23       buffers for almost all operations that can be done with pkey.  The
24       primary documented use is with EVP_SignFinal(3) and EVP_SealInit(3),
25       but it isn't limited there.  The returned size is also large enough for
26       the output buffer of EVP_PKEY_sign(3), EVP_PKEY_encrypt(3),
27       EVP_PKEY_decrypt(3), EVP_PKEY_derive(3).
28
29       It must be stressed that, unless the documentation for the operation
30       that's being performed says otherwise, the size returned by
31       EVP_PKEY_get_size() is only preliminary and not exact, so the final
32       contents of the target buffer may be smaller.  It is therefore crucial
33       to take note of the size given back by the function that performs the
34       operation, such as EVP_PKEY_sign(3) (the siglen argument will receive
35       that length), to avoid bugs.
36
37       EVP_PKEY_get_bits() returns the cryptographic length of the
38       cryptosystem to which the key in pkey belongs, in bits.  Note that the
39       definition of cryptographic length is specific to the key cryptosystem.
40
41       EVP_PKEY_get_security_bits() returns the number of security bits of the
42       given pkey, bits of security is defined in NIST SP800-57.
43

RETURN VALUES

45       EVP_PKEY_get_size(), EVP_PKEY_get_bits() and
46       EVP_PKEY_get_security_bits() return a positive number, or 0 if this
47       size isn't available.
48

NOTES

50       Most functions that have an output buffer and are mentioned with
51       EVP_PKEY_get_size() have a functionality where you can pass NULL for
52       the buffer and still pass a pointer to an integer and get the exact
53       size that this function call delivers in the context that it's called
54       in.  This allows those functions to be called twice, once to find out
55       the exact buffer size, then allocate the buffer in between, and call
56       that function again actually output the data.  For those functions, it
57       isn't strictly necessary to call EVP_PKEY_get_size() to find out the
58       buffer size, but may be useful in cases where it's desirable to know
59       the upper limit in advance.
60
61       It should also be especially noted that EVP_PKEY_get_size() shouldn't
62       be used to get the output size for EVP_DigestSignFinal(), according to
63       "NOTES" in EVP_DigestSignFinal(3).
64

SEE ALSO

66       EVP_SignFinal(3), EVP_SealInit(3), EVP_PKEY_sign(3),
67       EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_derive(3)
68

HISTORY

70       The EVP_PKEY_bits(), EVP_PKEY_security_bits(), and EVP_PKEY_size()
71       functions were renamed to include "get" in their names in OpenSSL 3.0,
72       respectively.  The old names are kept as non-deprecated alias macros.
73

75       Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
76
77       Licensed under the Apache License 2.0 (the "License").  You may not use
78       this file except in compliance with the License.  You can obtain a copy
79       in the file LICENSE in the source distribution or at
80       <https://www.openssl.org/source/license.html>.
81
82
83
843.1.1                             2023-08-31          EVP_PKEY_GET_SIZE(3ossl)
Impressum