diff options
Diffstat (limited to '')
-rw-r--r-- | src/lib/libcrypto/man/EVP_SealInit.3 | 191 |
1 files changed, 0 insertions, 191 deletions
diff --git a/src/lib/libcrypto/man/EVP_SealInit.3 b/src/lib/libcrypto/man/EVP_SealInit.3 deleted file mode 100644 index da53535274..0000000000 --- a/src/lib/libcrypto/man/EVP_SealInit.3 +++ /dev/null | |||
@@ -1,191 +0,0 @@ | |||
1 | .\" $OpenBSD: EVP_SealInit.3,v 1.9 2023/11/16 20:27:43 schwarze Exp $ | ||
2 | .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 | ||
3 | .\" | ||
4 | .\" This file was written by Dr. Stephen Henson <steve@openssl.org>. | ||
5 | .\" Copyright (c) 2000, 2002, 2003, 2005, 2015 The OpenSSL Project. | ||
6 | .\" All rights reserved. | ||
7 | .\" | ||
8 | .\" Redistribution and use in source and binary forms, with or without | ||
9 | .\" modification, are permitted provided that the following conditions | ||
10 | .\" are met: | ||
11 | .\" | ||
12 | .\" 1. Redistributions of source code must retain the above copyright | ||
13 | .\" notice, this list of conditions and the following disclaimer. | ||
14 | .\" | ||
15 | .\" 2. Redistributions in binary form must reproduce the above copyright | ||
16 | .\" notice, this list of conditions and the following disclaimer in | ||
17 | .\" the documentation and/or other materials provided with the | ||
18 | .\" distribution. | ||
19 | .\" | ||
20 | .\" 3. All advertising materials mentioning features or use of this | ||
21 | .\" software must display the following acknowledgment: | ||
22 | .\" "This product includes software developed by the OpenSSL Project | ||
23 | .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" | ||
24 | .\" | ||
25 | .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to | ||
26 | .\" endorse or promote products derived from this software without | ||
27 | .\" prior written permission. For written permission, please contact | ||
28 | .\" openssl-core@openssl.org. | ||
29 | .\" | ||
30 | .\" 5. Products derived from this software may not be called "OpenSSL" | ||
31 | .\" nor may "OpenSSL" appear in their names without prior written | ||
32 | .\" permission of the OpenSSL Project. | ||
33 | .\" | ||
34 | .\" 6. Redistributions of any form whatsoever must retain the following | ||
35 | .\" acknowledgment: | ||
36 | .\" "This product includes software developed by the OpenSSL Project | ||
37 | .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" | ||
38 | .\" | ||
39 | .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY | ||
40 | .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
41 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | ||
42 | .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR | ||
43 | .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | ||
44 | .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | ||
45 | .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | ||
46 | .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||
47 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | ||
48 | .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | ||
49 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | ||
50 | .\" OF THE POSSIBILITY OF SUCH DAMAGE. | ||
51 | .\" | ||
52 | .Dd $Mdocdate: November 16 2023 $ | ||
53 | .Dt EVP_SEALINIT 3 | ||
54 | .Os | ||
55 | .Sh NAME | ||
56 | .Nm EVP_SealInit , | ||
57 | .Nm EVP_SealUpdate , | ||
58 | .Nm EVP_SealFinal | ||
59 | .Nd EVP envelope encryption | ||
60 | .Sh SYNOPSIS | ||
61 | .In openssl/evp.h | ||
62 | .Ft int | ||
63 | .Fo EVP_SealInit | ||
64 | .Fa "EVP_CIPHER_CTX *ctx" | ||
65 | .Fa "const EVP_CIPHER *type" | ||
66 | .Fa "unsigned char **ek" | ||
67 | .Fa "int *ekl" | ||
68 | .Fa "unsigned char *iv" | ||
69 | .Fa "EVP_PKEY **pubk" | ||
70 | .Fa "int npubk" | ||
71 | .Fc | ||
72 | .Ft int | ||
73 | .Fo EVP_SealUpdate | ||
74 | .Fa "EVP_CIPHER_CTX *ctx" | ||
75 | .Fa "unsigned char *out" | ||
76 | .Fa "int *outl" | ||
77 | .Fa "unsigned char *in" | ||
78 | .Fa "int inl" | ||
79 | .Fc | ||
80 | .Ft int | ||
81 | .Fo EVP_SealFinal | ||
82 | .Fa "EVP_CIPHER_CTX *ctx" | ||
83 | .Fa "unsigned char *out" | ||
84 | .Fa "int *outl" | ||
85 | .Fc | ||
86 | .Sh DESCRIPTION | ||
87 | The EVP envelope routines are a high level interface to envelope | ||
88 | encryption. | ||
89 | They generate a random key and IV (if required) then "envelope" it by | ||
90 | using public key encryption. | ||
91 | Data can then be encrypted using this key. | ||
92 | .Pp | ||
93 | .Fn EVP_SealInit | ||
94 | initializes a cipher context | ||
95 | .Fa ctx | ||
96 | for encryption with cipher | ||
97 | .Fa type | ||
98 | using a random secret key and IV. | ||
99 | .Fa type | ||
100 | is normally supplied by a function such as | ||
101 | .Xr EVP_aes_256_cbc 3 ; | ||
102 | see | ||
103 | .Xr EVP_EncryptInit 3 | ||
104 | for details. | ||
105 | The secret key is encrypted using one or more public keys. | ||
106 | This allows the same encrypted data to be decrypted using any of | ||
107 | the corresponding private keys. | ||
108 | .Fa ek | ||
109 | is an array of buffers where the public key encrypted secret key will be | ||
110 | written. | ||
111 | Each buffer must contain enough room for the corresponding encrypted | ||
112 | key: that is | ||
113 | .Fa ek[i] | ||
114 | must have room for | ||
115 | .Fn EVP_PKEY_size pubk[i] | ||
116 | bytes. | ||
117 | The actual size of each encrypted secret key is written to the array | ||
118 | .Fa ekl . | ||
119 | .Fa pubk | ||
120 | is an array of | ||
121 | .Fa npubk | ||
122 | public keys. | ||
123 | .Pp | ||
124 | The | ||
125 | .Fa iv | ||
126 | parameter is a buffer where the generated IV is written to. | ||
127 | It must contain enough room for the corresponding cipher's IV, as | ||
128 | determined by (for example) | ||
129 | .Fn EVP_CIPHER_iv_length type . | ||
130 | .Pp | ||
131 | If the cipher does not require an IV then the | ||
132 | .Fa iv | ||
133 | parameter is ignored and can be | ||
134 | .Dv NULL . | ||
135 | .Pp | ||
136 | .Fn EVP_SealUpdate | ||
137 | and | ||
138 | .Fn EVP_SealFinal | ||
139 | have exactly the same properties as the | ||
140 | .Xr EVP_EncryptUpdate 3 | ||
141 | and | ||
142 | .Xr EVP_EncryptFinal 3 | ||
143 | routines. | ||
144 | .Pp | ||
145 | The public key must be RSA because it is the only OpenSSL public key | ||
146 | algorithm that supports key transport. | ||
147 | .Pp | ||
148 | Envelope encryption is the usual method of using public key encryption | ||
149 | on large amounts of data. | ||
150 | This is because public key encryption is slow but symmetric encryption | ||
151 | is fast. | ||
152 | So symmetric encryption is used for bulk encryption and the small random | ||
153 | symmetric key used is transferred using public key encryption. | ||
154 | .Pp | ||
155 | It is possible to call | ||
156 | .Fn EVP_SealInit | ||
157 | twice in the same way as | ||
158 | .Xr EVP_EncryptInit 3 . | ||
159 | The first call should have | ||
160 | .Fa npubk | ||
161 | set to 0 and (after setting any cipher parameters) it should be called | ||
162 | again with | ||
163 | .Fa type | ||
164 | set to NULL. | ||
165 | .Pp | ||
166 | .Fn EVP_SealUpdate | ||
167 | is implemented as a macro. | ||
168 | .Sh RETURN VALUES | ||
169 | .Fn EVP_SealInit | ||
170 | returns 0 on error or | ||
171 | .Fa npubk | ||
172 | if successful. | ||
173 | .Pp | ||
174 | .Fn EVP_SealUpdate | ||
175 | and | ||
176 | .Fn EVP_SealFinal | ||
177 | return 1 for success and 0 for failure. | ||
178 | .Sh SEE ALSO | ||
179 | .Xr evp 3 , | ||
180 | .Xr EVP_EncryptInit 3 , | ||
181 | .Xr EVP_OpenInit 3 | ||
182 | .Sh HISTORY | ||
183 | .Fn EVP_SealInit , | ||
184 | .Fn EVP_SealUpdate , | ||
185 | and | ||
186 | .Fn EVP_SealFinal | ||
187 | first appeared in SSLeay 0.5.1 and have been available since | ||
188 | .Ox 2.4 . | ||
189 | .Pp | ||
190 | .Fn EVP_SealFinal | ||
191 | did not return a value before OpenSSL 0.9.7. | ||