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