Debian Codegraph @

upstream/debian-trixie/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.5.6 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_size
66 \&\- EVP_PKEY information functions
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/evp.h>
71 \&
72 \& int EVP_PKEY_get_size(const EVP_PKEY *pkey);
73 \& int EVP_PKEY_get_bits(const EVP_PKEY *pkey);
74 \& int EVP_PKEY_get_security_bits(const EVP_PKEY *pkey);
75 \&
76 \& #define EVP_PKEY_bits EVP_PKEY_get_bits
77 \& #define EVP_PKEY_security_bits EVP_PKEY_get_security_bits
78 \& #define EVP_PKEY_size EVP_PKEY_get_size
79 .Ve
80 .SH DESCRIPTION
81 .IX Header "DESCRIPTION"
82 \&\fBEVP_PKEY_get_size()\fR returns the maximum suitable size for the output
83 buffers for almost all operations that can be done with \fIpkey\fR.
84 This corresponds to the provider parameter \fBOSSL_PKEY_PARAM_MAX_SIZE\fR.
85 The primary documented use is with \fBEVP_SignFinal\fR\|(3) and
86 \&\fBEVP_SealInit\fR\|(3), but it isn't limited there. The returned size is
87 also large enough for the output buffer of \fBEVP_PKEY_sign\fR\|(3),
88 \&\fBEVP_PKEY_encrypt\fR\|(3), \fBEVP_PKEY_decrypt\fR\|(3), \fBEVP_PKEY_derive\fR\|(3).
89 .PP
90 It must be stressed that, unless the documentation for the operation
91 that's being performed says otherwise, the size returned by
92 \&\fBEVP_PKEY_get_size()\fR is only preliminary and not exact, so the final
93 contents of the target buffer may be smaller. It is therefore crucial
94 to take note of the size given back by the function that performs the
95 operation, such as \fBEVP_PKEY_sign\fR\|(3) (the \fIsiglen\fR argument will
96 receive that length), to avoid bugs.
97 .PP
98 \&\fBEVP_PKEY_get_bits()\fR returns the cryptographic length of the cryptosystem
99 to which the key in \fIpkey\fR belongs, in bits. Note that the definition
100 of cryptographic length is specific to the key cryptosystem.
101 This length corresponds to the provider parameter \fBOSSL_PKEY_PARAM_BITS\fR.
102 .PP
103 \&\fBEVP_PKEY_get_security_bits()\fR returns the number of security bits of the given
104 \&\fIpkey\fR, bits of security is defined in NIST SP800\-57.
105 This corresponds to the provider parameter \fBOSSL_PKEY_PARAM_SECURITY_BITS\fR.
106 .SH "RETURN VALUES"
107 .IX Header "RETURN VALUES"
108 \&\fBEVP_PKEY_get_size()\fR, \fBEVP_PKEY_get_bits()\fR and \fBEVP_PKEY_get_security_bits()\fR
109 return a positive number, or 0 if this size isn't available.
110 .SH NOTES
111 .IX Header "NOTES"
112 Most functions that have an output buffer and are mentioned with
113 \&\fBEVP_PKEY_get_size()\fR have a functionality where you can pass NULL for the
114 buffer and still pass a pointer to an integer and get the exact size
115 that this function call delivers in the context that it's called in.
116 This allows those functions to be called twice, once to find out the
117 exact buffer size, then allocate the buffer in between, and call that
118 function again actually output the data. For those functions, it
119 isn't strictly necessary to call \fBEVP_PKEY_get_size()\fR to find out the
120 buffer size, but may be useful in cases where it's desirable to know
121 the upper limit in advance.
122 .PP
123 It should also be especially noted that \fBEVP_PKEY_get_size()\fR shouldn't be
124 used to get the output size for \fBEVP_DigestSignFinal()\fR, according to
125 "NOTES" in \fBEVP_DigestSignFinal\fR\|(3).
126 .SH "SEE ALSO"
127 .IX Header "SEE ALSO"
128 \&\fBprovider\-keymgmt\fR\|(7),
129 \&\fBEVP_SignFinal\fR\|(3),
130 \&\fBEVP_SealInit\fR\|(3),
131 \&\fBEVP_PKEY_sign\fR\|(3),
132 \&\fBEVP_PKEY_encrypt\fR\|(3),
133 \&\fBEVP_PKEY_decrypt\fR\|(3),
134 \&\fBEVP_PKEY_derive\fR\|(3)
135 .SH HISTORY
136 .IX Header "HISTORY"
137 The \fBEVP_PKEY_bits()\fR, \fBEVP_PKEY_security_bits()\fR, and \fBEVP_PKEY_size()\fR functions
138 were renamed to include \f(CW\*(C`get\*(C'\fR in their names in OpenSSL 3.0, respectively.
139 The old names are kept as non-deprecated alias macros.
140 .SH COPYRIGHT
141 .IX Header "COPYRIGHT"
142 Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved.
143 .PP
144 Licensed under the Apache License 2.0 (the "License"). You may not use
145 this file except in compliance with the License. You can obtain a copy
146 in the file LICENSE in the source distribution or at
147 <https://www.openssl.org/source/license.html>.