summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EVP_PKEY_size.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EVP_PKEY_size.3')
-rw-r--r--src/lib/libcrypto/man/EVP_PKEY_size.3224
1 files changed, 0 insertions, 224 deletions
diff --git a/src/lib/libcrypto/man/EVP_PKEY_size.3 b/src/lib/libcrypto/man/EVP_PKEY_size.3
deleted file mode 100644
index cd25eec9c2..0000000000
--- a/src/lib/libcrypto/man/EVP_PKEY_size.3
+++ /dev/null
@@ -1,224 +0,0 @@
1.\" $OpenBSD: EVP_PKEY_size.3,v 1.4 2024/12/06 12:51:13 schwarze Exp $
2.\" full merge up to: OpenSSL eed9d03b Jan 8 11:04:15 2020 +0100
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2022, 2023 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.\" The original file was written by Richard Levitte <levitte@openssl.org>.
22.\" Copyright (c) 2020 The OpenSSL Project. All rights reserved.
23.\"
24.\" Redistribution and use in source and binary forms, with or without
25.\" modification, are permitted provided that the following conditions
26.\" are met:
27.\"
28.\" 1. Redistributions of source code must retain the above copyright
29.\" notice, this list of conditions and the following disclaimer.
30.\"
31.\" 2. Redistributions in binary form must reproduce the above copyright
32.\" notice, this list of conditions and the following disclaimer in
33.\" the documentation and/or other materials provided with the
34.\" distribution.
35.\"
36.\" 3. All advertising materials mentioning features or use of this
37.\" software must display the following acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40.\"
41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42.\" endorse or promote products derived from this software without
43.\" prior written permission. For written permission, please contact
44.\" openssl-core@openssl.org.
45.\"
46.\" 5. Products derived from this software may not be called "OpenSSL"
47.\" nor may "OpenSSL" appear in their names without prior written
48.\" permission of the OpenSSL Project.
49.\"
50.\" 6. Redistributions of any form whatsoever must retain the following
51.\" acknowledgment:
52.\" "This product includes software developed by the OpenSSL Project
53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54.\"
55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67.\"
68.Dd $Mdocdate: December 6 2024 $
69.Dt EVP_PKEY_SIZE 3
70.Os
71.Sh NAME
72.Nm EVP_PKEY_size ,
73.Nm EVP_PKEY_bits ,
74.Nm EVP_PKEY_security_bits
75.Nd EVP_PKEY information functions
76.Sh SYNOPSIS
77.In openssl/evp.h
78.Ft int
79.Fo EVP_PKEY_size
80.Fa "const EVP_PKEY *pkey"
81.Fc
82.Ft int
83.Fo EVP_PKEY_bits
84.Fa "const EVP_PKEY *pkey"
85.Fc
86.Ft int
87.Fo EVP_PKEY_security_bits
88.Fa "const EVP_PKEY *pkey"
89.Fc
90.Sh DESCRIPTION
91.Fn EVP_PKEY_size
92returns the maximum size in bytes needed for the output buffer
93for almost any operation that can be done with
94.Fa pkey .
95The primary use is with
96.Xr EVP_SignFinal 3
97and
98.Xr EVP_SealInit 3 .
99The returned size is also large enough for the output buffer of
100.Xr EVP_PKEY_sign 3 ,
101.Xr EVP_PKEY_encrypt 3 ,
102.Xr EVP_PKEY_decrypt 3 ,
103and
104.Xr EVP_PKEY_derive 3 .
105.Pp
106Unless the documentation for the operation says otherwise,
107the size returned by
108.Fn EVP_PKEY_size
109is only an upper limit and the final content of the target
110buffer may be smaller.
111It is therefore crucial to take note of the size given back by the
112function that performs the operation.
113For example,
114.Xr EVP_PKEY_sign 3
115returns that length in the
116.Pf * Fa siglen
117argument.
118.Pp
119Using
120.Fn EVP_PKEY_size
121is discouraged with
122.Xr EVP_DigestSignFinal 3 .
123.Pp
124Most functions using an output buffer support passing
125.Dv NULL
126for the buffer and a pointer to an integer
127to get the exact size that this function call delivers
128in the context that it is called in.
129This allows those functions to be called twice, once to find out the
130exact buffer size, then allocate the buffer in between, and call that
131function again to actually output the data.
132For those functions, it isn't strictly necessary to call
133.Fn EVP_PKEY_size
134to find out the buffer size, but it may still be useful in cases
135where it's desirable to know the upper limit in advance.
136.Pp
137.Fn EVP_PKEY_size
138is supported for the following algorithms:
139.Bl -column ED25519 "EVP_MAX_BLOCK_LENGTH = 32"
140.It Ta same result as from:
141.It CMAC Ta Dv EVP_MAX_BLOCK_LENGTH No = 32
142.It DH Ta Xr DH_size 3
143.It DSA Ta Xr DSA_size 3
144.It EC Ta Xr ECDSA_size 3
145.It ED25519 Ta 64, but see below
146.It HMAC Ta Dv EVP_MAX_MD_SIZE No = 64
147.It RSA Ta Xr RSA_size 3
148.It X25519 Ta Dv X25519_KEYLEN No = 32
149.El
150.Pp
151For
152.Dv EVP_PKEY_ED25519 ,
153the situation is special: while the key size is
154.Dv ED25519_KEYLEN No = 32 bytes ,
155.Fn EVP_PKEY_size
156returns 64 because the signature is longer than the keys.
157.Pp
158.Fn EVP_PKEY_bits
159returns the cryptographic length of the cryptosystem to which the key in
160.Fa pkey
161belongs, in bits.
162The definition of cryptographic length is specific to the key cryptosystem.
163The following algorithms are supported:
164.Bl -column ED25519 "the public domain parameter p" DSA_bits(3)
165.It Ta cryptographic length = Ta same result as from:
166.It Ta significant bits in ... Ta
167.It DH Ta the public domain parameter Fa p Ta Xr DH_bits 3
168.It DSA Ta the public domain parameter Fa p Ta Xr DSA_bits 3
169.It EC Ta the order of the group Ta Xr EC_GROUP_order_bits 3
170.It ED25519 Ta 253 Ta \(em
171.It RSA Ta the public modulus Ta Xr RSA_bits 3
172.It X25519 Ta 253 Ta \(em
173.El
174.Pp
175.Fn EVP_PKEY_security_bits
176returns the security strength measured in bits of the given
177.Fa pkey
178as defined in NIST SP800-57.
179The following algorithms are supported:
180.Bl -column ED25519 DSA_security_bits(3)
181.It Ta same result as from:
182.It DH Ta Xr DH_security_bits 3
183.It DSA Ta Xr DSA_security_bits 3
184.It EC Ta Xr EC_GROUP_order_bits 3 divided by 2
185.It ED25519 Ta 128
186.It RSA Ta Xr RSA_security_bits 3
187.It X25519 Ta 128
188.El
189.Pp
190For EC keys, if the result is greater than 80, it is rounded down
191to 256, 192, 128, 112, or 80.
192.Sh RETURN VALUES
193.Fn EVP_PKEY_size
194and
195.Fn EVP_PKEY_bits
196return a positive number or 0 if this size isn't available.
197.Pp
198.Fn EVP_PKEY_security_bits
199returns a number in the range from 0 to 256 inclusive
200or \-2 if this function is unsupported for the algorithm used by
201.Fa pkey .
202It returns 0 if
203.Fa pkey
204is
205.Dv NULL .
206.Sh SEE ALSO
207.Xr EVP_PKEY_decrypt 3 ,
208.Xr EVP_PKEY_derive 3 ,
209.Xr EVP_PKEY_encrypt 3 ,
210.Xr EVP_PKEY_new 3 ,
211.Xr EVP_PKEY_sign 3 ,
212.Xr EVP_SealInit 3 ,
213.Xr EVP_SignFinal 3
214.Sh HISTORY
215.Fn EVP_PKEY_size
216first appeared in SSLeay 0.6.0 and
217.Fn EVP_PKEY_bits
218in SSLeay 0.9.0.
219Both functions have been available since
220.Ox 2.4 .
221.Pp
222.Fn EVP_PKEY_security_bits
223first appeared in OpenSSL 1.1.0 and has been available since
224.Ox 7.2 .