Debian Codegraph @

upstream/debian-unstable/man3/EVP_SealInit.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_SEALINIT 3SSL"
58 .TH EVP_SEALINIT 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_SealInit, EVP_SealUpdate, EVP_SealFinal \- EVP envelope encryption
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/evp.h>
69 \&
70 \& int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
71 \& unsigned char **ek, int *ekl, unsigned char *iv,
72 \& EVP_PKEY **pubk, int npubk);
73 \& int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
74 \& int *outl, unsigned char *in, int inl);
75 \& int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 The EVP envelope routines are a high-level interface to envelope
80 encryption. They generate a random key and IV (if required) then
81 "envelope" it by using public key encryption. Data can then be
82 encrypted using this key.
83 .PP
84 \&\fBEVP_SealInit()\fR initializes a cipher context \fBctx\fR for encryption
85 with cipher \fBtype\fR using a random secret key and IV. \fBtype\fR is normally
86 supplied by a function such as \fBEVP_aes_256_cbc()\fR. The secret key is encrypted
87 using one or more public keys, this allows the same encrypted data to be
88 decrypted using any of the corresponding private keys. \fBek\fR is an array of
89 buffers where the public key encrypted secret key will be written, each buffer
90 must contain enough room for the corresponding encrypted key: that is
91 \&\fBek[i]\fR must have room for \fBEVP_PKEY_get_size(pubk[i])\fR bytes. The actual
92 size of each encrypted secret key is written to the array \fBekl\fR. \fBpubk\fR is
93 an array of \fBnpubk\fR public keys.
94 .PP
95 The \fBiv\fR parameter is a buffer where the generated IV is written to. It must
96 contain enough room for the corresponding cipher's IV, as determined by (for
97 example) EVP_CIPHER_get_iv_length(type).
98 .PP
99 If the cipher does not require an IV then the \fBiv\fR parameter is ignored
100 and can be \fBNULL\fR.
101 .PP
102 \&\fBEVP_SealUpdate()\fR and \fBEVP_SealFinal()\fR have exactly the same properties
103 as the \fBEVP_EncryptUpdate()\fR and \fBEVP_EncryptFinal()\fR routines, as
104 documented on the \fBEVP_EncryptInit\fR\|(3) manual
105 page.
106 .SH "RETURN VALUES"
107 .IX Header "RETURN VALUES"
108 \&\fBEVP_SealInit()\fR returns 0 on error or \fBnpubk\fR if successful.
109 .PP
110 \&\fBEVP_SealUpdate()\fR and \fBEVP_SealFinal()\fR return 1 for success and 0 for
111 failure.
112 .SH NOTES
113 .IX Header "NOTES"
114 Because a random secret key is generated the random number generator
115 must be seeded when \fBEVP_SealInit()\fR is called.
116 If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
117 external circumstances (see \fBRAND\fR\|(7)), the operation will fail.
118 .PP
119 The public key must be RSA because it is the only OpenSSL public key
120 algorithm that supports key transport.
121 .PP
122 Envelope encryption is the usual method of using public key encryption
123 on large amounts of data, this is because public key encryption is slow
124 but symmetric encryption is fast. So symmetric encryption is used for
125 bulk encryption and the small random symmetric key used is transferred
126 using public key encryption.
127 .PP
128 It is possible to call \fBEVP_SealInit()\fR twice in the same way as
129 \&\fBEVP_EncryptInit()\fR. The first call should have \fBnpubk\fR set to 0
130 and (after setting any cipher parameters) it should be called again
131 with \fBtype\fR set to NULL.
132 .SH "SEE ALSO"
133 .IX Header "SEE ALSO"
134 \&\fBevp\fR\|(7), \fBRAND_bytes\fR\|(3),
135 \&\fBEVP_EncryptInit\fR\|(3),
136 \&\fBEVP_OpenInit\fR\|(3),
137 \&\fBRAND\fR\|(7)
138 .SH COPYRIGHT
139 .IX Header "COPYRIGHT"
140 Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
141 .PP
142 Licensed under the Apache License 2.0 (the "License"). You may not use
143 this file except in compliance with the License. You can obtain a copy
144 in the file LICENSE in the source distribution or at
145 <https://www.openssl.org/source/license.html>.