Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / EVP_SealInit.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH EVP_SealInit 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
74dab6c2 191EVP_SealInit, EVP_SealUpdate, EVP_SealFinal \- EVP envelope encryption
984263bc 192.SH "SYNOPSIS"
74dab6c2 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/evp.h>
196.Ve
197.Vb 6
198\& int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,
199\& int *ekl, unsigned char *iv,EVP_PKEY **pubk, int npubk);
200\& int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
201\& int *outl, unsigned char *in, int inl);
202\& int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
203\& int *outl);
204.Ve
205.SH "DESCRIPTION"
74dab6c2
JR
206The EVP envelope routines are a high level interface to envelope
207encryption. They generate a random key and IV (if required) then
208\*(L"envelope\*(R" it by using public key encryption. Data can then be
984263bc
MD
209encrypted using this key.
210.PP
74dab6c2
JR
211\fIEVP_SealInit()\fR initializes a cipher context \fBctx\fR for encryption
212with cipher \fBtype\fR using a random secret key and IV. \fBtype\fR is normally
984263bc
MD
213supplied by a function such as \fIEVP_des_cbc()\fR. The secret key is encrypted
214using one or more public keys, this allows the same encrypted data to be
215decrypted using any of the corresponding private keys. \fBek\fR is an array of
216buffers where the public key encrypted secret key will be written, each buffer
217must contain enough room for the corresponding encrypted key: that is
74dab6c2 218\fBek[i]\fR must have room for \fBEVP_PKEY_size(pubk[i])\fR bytes. The actual
984263bc
MD
219size of each encrypted secret key is written to the array \fBekl\fR. \fBpubk\fR is
220an array of \fBnpubk\fR public keys.
221.PP
74dab6c2
JR
222The \fBiv\fR parameter is a buffer where the generated IV is written to. It must
223contain enough room for the corresponding cipher's IV, as determined by (for
224example) \fIEVP_CIPHER_iv_length\fR\|(type).
984263bc 225.PP
74dab6c2
JR
226If the cipher does not require an IV then the \fBiv\fR parameter is ignored
227and can be \fBNULL\fR.
984263bc 228.PP
74dab6c2 229\fIEVP_SealUpdate()\fR and \fIEVP_SealFinal()\fR have exactly the same properties
984263bc
MD
230as the \fIEVP_EncryptUpdate()\fR and \fIEVP_EncryptFinal()\fR routines, as
231documented on the EVP_EncryptInit(3) manual
232page.
233.SH "RETURN VALUES"
74dab6c2 234\fIEVP_SealInit()\fR returns 0 on error or \fBnpubk\fR if successful.
984263bc 235.PP
74dab6c2 236\fIEVP_SealUpdate()\fR and \fIEVP_SealFinal()\fR return 1 for success and 0 for
984263bc
MD
237failure.
238.SH "NOTES"
984263bc
MD
239Because a random secret key is generated the random number generator
240must be seeded before calling \fIEVP_SealInit()\fR.
241.PP
74dab6c2 242The public key must be RSA because it is the only OpenSSL public key
984263bc
MD
243algorithm that supports key transport.
244.PP
245Envelope encryption is the usual method of using public key encryption
246on large amounts of data, this is because public key encryption is slow
247but symmetric encryption is fast. So symmetric encryption is used for
248bulk encryption and the small random symmetric key used is transferred
249using public key encryption.
250.PP
251It is possible to call \fIEVP_SealInit()\fR twice in the same way as
74dab6c2 252\fIEVP_EncryptInit()\fR. The first call should have \fBnpubk\fR set to 0
984263bc 253and (after setting any cipher parameters) it should be called again
74dab6c2 254with \fBtype\fR set to NULL.
984263bc 255.SH "SEE ALSO"
984263bc
MD
256evp(3), rand(3),
257EVP_EncryptInit(3),
258EVP_OpenInit(3)
259.SH "HISTORY"
74dab6c2
JR
260\fIEVP_SealFinal()\fR did not return a value before OpenSSL 0.9.7.
261
262.rn }` ''
263.IX Title "EVP_SealInit 3"
264.IX Name "EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption"
265
266.IX Header "NAME"
267
268.IX Header "SYNOPSIS"
269
270.IX Header "DESCRIPTION"
271
272.IX Header "RETURN VALUES"
273
274.IX Header "NOTES"
275
276.IX Header "SEE ALSO"
277
984263bc 278.IX Header "HISTORY"
74dab6c2 279