Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_get_size.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY_GET_SIZE 3SSL"
58 .TH EVP_PKEY_GET_SIZE 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits,
65 EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_get_security_category,
66 EVP_PKEY_size
67 \&\- EVP_PKEY information functions
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/evp.h>
72 \&
73 \& int EVP_PKEY_get_size(const EVP_PKEY *pkey);
74 \& int EVP_PKEY_get_bits(const EVP_PKEY *pkey);
75 \& int EVP_PKEY_get_security_bits(const EVP_PKEY *pkey);
76 \& int EVP_PKEY_get_security_category(const EVP_PKEY *pkey);
77 \&
78 \& #define EVP_PKEY_bits EVP_PKEY_get_bits
79 \& #define EVP_PKEY_security_bits EVP_PKEY_get_security_bits
80 \& #define EVP_PKEY_size EVP_PKEY_get_size
81 .Ve
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 \&\fBEVP_PKEY_get_size()\fR returns the maximum suitable size for the output
85 buffers for almost all operations that can be done with \fIpkey\fR.
86 This corresponds to the provider parameter \fBOSSL_PKEY_PARAM_MAX_SIZE\fR.
87 The primary documented use is with \fBEVP_SignFinal\fR\|(3) and
88 \&\fBEVP_SealInit\fR\|(3), but it isn't limited there. The returned size is
89 also large enough for the output buffer of \fBEVP_PKEY_sign\fR\|(3),
90 \&\fBEVP_PKEY_encrypt\fR\|(3), \fBEVP_PKEY_decrypt\fR\|(3), \fBEVP_PKEY_derive\fR\|(3).
91 .PP
92 It must be stressed that, unless the documentation for the operation
93 that's being performed says otherwise, the size returned by
94 \&\fBEVP_PKEY_get_size()\fR is only preliminary and not exact, so the final
95 contents of the target buffer may be smaller. It is therefore crucial
96 to take note of the size given back by the function that performs the
97 operation, such as \fBEVP_PKEY_sign\fR\|(3) (the \fIsiglen\fR argument will
98 receive that length), to avoid bugs.
99 .PP
100 \&\fBEVP_PKEY_get_bits()\fR returns the cryptographic length of the cryptosystem
101 to which the key in \fIpkey\fR belongs, in bits. Note that the definition
102 of cryptographic length is specific to the key cryptosystem.
103 This length corresponds to the provider parameter \fBOSSL_PKEY_PARAM_BITS\fR.
104 .PP
105 \&\fBEVP_PKEY_get_security_bits()\fR returns the number of security bits of the given
106 \&\fIpkey\fR, bits of security is defined in NIST SP800\-57.
107 This corresponds to the provider parameter \fBOSSL_PKEY_PARAM_SECURITY_BITS\fR.
108 .PP
109 \&\fBEVP_PKEY_get_security_category()\fR returns the
110 post-quantum security category <https://nvlpubs.nist.gov/nistpubs/ir/2024/NIST.IR.8547.ipd.pdf>
111 as defined by NIST.
112 The post-quantum security category is an integer value from 0 to 5 that
113 is based on an algorithm's classification on the range of security strengths
114 offered by the existing standards in symmetric cryptography:
115 .SH "RETURN VALUES"
116 .IX Header "RETURN VALUES"
117 \&\fBEVP_PKEY_get_size()\fR, \fBEVP_PKEY_get_bits()\fR and \fBEVP_PKEY_get_security_bits()\fR
118 return a positive number, or 0 if this size isn't available.
119 .PP
120 \&\fBEVP_PKEY_get_security_category()\fR returns the post-quantum security category
121 which is an integer in the range zero to five inclusive. It returns \-1 if
122 the security category information isn't available.
123 For all classical algorithms, 0 is returned meaning that they are not
124 considered to be quantum safe.
125 .SH NOTES
126 .IX Header "NOTES"
127 Most functions that have an output buffer and are mentioned with
128 \&\fBEVP_PKEY_get_size()\fR have a functionality where you can pass NULL for the
129 buffer and still pass a pointer to an integer and get the exact size
130 that this function call delivers in the context that it's called in.
131 This allows those functions to be called twice, once to find out the
132 exact buffer size, then allocate the buffer in between, and call that
133 function again actually output the data. For those functions, it
134 isn't strictly necessary to call \fBEVP_PKEY_get_size()\fR to find out the
135 buffer size, but may be useful in cases where it's desirable to know
136 the upper limit in advance.
137 .PP
138 It should also be especially noted that \fBEVP_PKEY_get_size()\fR shouldn't be
139 used to get the output size for \fBEVP_DigestSignFinal()\fR, according to
140 "NOTES" in \fBEVP_DigestSignFinal\fR\|(3).
141 .SH "SEE ALSO"
142 .IX Header "SEE ALSO"
143 \&\fBprovider\-keymgmt\fR\|(7),
144 \&\fBEVP_SignFinal\fR\|(3),
145 \&\fBEVP_SealInit\fR\|(3),
146 \&\fBEVP_PKEY_sign\fR\|(3),
147 \&\fBEVP_PKEY_encrypt\fR\|(3),
148 \&\fBEVP_PKEY_decrypt\fR\|(3),
149 \&\fBEVP_PKEY_derive\fR\|(3)
150 .SH HISTORY
151 .IX Header "HISTORY"
152 The \fBEVP_PKEY_bits()\fR, \fBEVP_PKEY_security_bits()\fR, and \fBEVP_PKEY_size()\fR functions
153 were renamed to include \f(CW\*(C`get\*(C'\fR in their names in OpenSSL 3.0, respectively.
154 The old names are kept as non-deprecated alias macros.
155 .PP
156 \&\fBEVP_PKEY_get_security_category()\fR was added in OpenSSL 3.6.
157 .SH COPYRIGHT
158 .IX Header "COPYRIGHT"
159 Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved.
160 .PP
161 Licensed under the Apache License 2.0 (the "License"). You may not use
162 this file except in compliance with the License. You can obtain a copy
163 in the file LICENSE in the source distribution or at
164 <https://www.openssl.org/source/license.html>.