| blob | bf9ed71ac3dd1a1210d542143c94cfb26da77628 |
1 .\" $OpenBSD: EVP_EncodeInit.3,v 1.4 2018/03/27 17:35:50 schwarze Exp $
2 .\" OpenSSL f430ba31 Jun 19 19:39:01 2016 +0200
3 .\"
4 .\" This file was written by Matt Caswell <matt@openssl.org>.
5 .\" Copyright (c) 2016 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: March 27 2018 $
52 .Dt EVP_ENCODEINIT 3
53 .Os
54 .Sh NAME
55 .Nm EVP_EncodeInit ,
56 .Nm EVP_EncodeUpdate ,
57 .Nm EVP_EncodeFinal ,
58 .Nm EVP_EncodeBlock ,
59 .Nm EVP_DecodeInit ,
60 .Nm EVP_DecodeUpdate ,
61 .Nm EVP_DecodeFinal ,
62 .Nm EVP_DecodeBlock
63 .Nd EVP base64 encode/decode routines
64 .Sh SYNOPSIS
65 .In openssl/evp.h
66 .Ft void
67 .Fo EVP_EncodeInit
68 .Fa "EVP_ENCODE_CTX *ctx"
69 .Fc
70 .Ft int
71 .Fo EVP_EncodeUpdate
72 .Fa "EVP_ENCODE_CTX *ctx"
73 .Fa "unsigned char *out"
74 .Fa "int *outl"
75 .Fa "const unsigned char *in"
76 .Fa "int inl"
77 .Fc
78 .Ft void
79 .Fo EVP_EncodeFinal
80 .Fa "EVP_ENCODE_CTX *ctx"
81 .Fa "unsigned char *out"
82 .Fa "int *outl"
83 .Fc
84 .Ft int
85 .Fo EVP_EncodeBlock
86 .Fa "unsigned char *t"
87 .Fa "const unsigned char *f"
88 .Fa "int n"
89 .Fc
90 .Ft void
91 .Fo EVP_DecodeInit
92 .Fa "EVP_ENCODE_CTX *ctx"
93 .Fc
94 .Ft int
95 .Fo EVP_DecodeUpdate
96 .Fa "EVP_ENCODE_CTX *ctx"
97 .Fa "unsigned char *out"
98 .Fa "int *outl"
99 .Fa "const unsigned char *in"
100 .Fa "int inl"
101 .Fc
102 .Ft int
103 .Fo EVP_DecodeFinal
104 .Fa "EVP_ENCODE_CTX *ctx"
105 .Fa "unsigned char *out"
106 .Fa "int *outl"
107 .Fc
108 .Ft int
109 .Fo EVP_DecodeBlock
110 .Fa "unsigned char *t"
111 .Fa "const unsigned char *f"
112 .Fa "int n"
113 .Fc
114 .Sh DESCRIPTION
115 The EVP encode routines provide a high level interface to base64
116 encoding and decoding.
117 Base64 encoding converts binary data into a printable form that uses
118 the characters A-Z, a-z, 0-9, "+" and "/" to represent the data.
119 For every 3 bytes of binary data provided, 4 bytes of base64-encoded
120 data will be produced, plus some occasional newlines.
121 If the input data length is not a multiple of 3, then the output data
122 will be padded at the end using the "=" character.
123 .Pp
124 Encoding of binary data is performed in blocks of 48 input bytes (or
125 less for the final block).
126 For each 48-byte input block encoded, 64 bytes of base64 data is output,
127 plus an additional newline character, i.e. 65 bytes in total.
128 The final block, which may be less than 48 bytes, will output 4 bytes
129 for every 3 bytes of input.
130 If the data length is not divisible by 3, then a full 4 bytes is still
131 output for the final 1 or 2 bytes of input.
132 Similarly a newline character will also be output.
133 .Pp
134 .Fn EVP_EncodeInit
135 initialises
136 .Fa ctx
137 for the start of a new encoding operation.
138 .Pp
139 .Fn EVP_EncodeUpdate
140 encodes
141 .Fa inl
142 bytes of data found in the buffer pointed to by
143 .Fa in .
144 The output is stored in the buffer
145 .Fa out
146 and the number of bytes output is stored in
147 .Pf * Fa outl .
148 It is the caller's responsibility to ensure that the buffer at
149 .Fa out
150 is sufficiently large to accommodate the output data.
151 Only full blocks of data (48 bytes) will be immediately processed and
152 output by this function.
153 Any remainder is held in the
154 .Fa ctx
155 object and will be processed by a subsequent call to
156 .Fn EVP_EncodeUpdate
157 or
158 .Fn EVP_EncodeFinal .
159 To calculate the required size of the output buffer, add together the
160 value of
161 .Fa inl
162 with the amount of unprocessed data held in
163 .Fa ctx
164 and divide the result by 48 (ignore any remainder).
165 This gives the number of blocks of data that will be processed.
166 Ensure the output buffer contains 65 bytes of storage for each block,
167 plus an additional byte for a NUL terminator.
168 .Fn EVP_EncodeUpdate
169 may be called repeatedly to process large amounts of input data.
170 In the event of an error ,
171 .Fn EVP_EncodeUpdate
172 will set
173 .Pf * Fa outl
174 to 0 and return 0.
175 On success 1 will be returned.
176 .Pp
177 .Fn EVP_EncodeFinal
178 must be called at the end of an encoding operation.
179 It will process any partial block of data remaining in the
180 .Fa ctx
181 object.
182 The output data will be stored in
183 .Fa out
184 and the length of the data written will be stored in
185 .Pf * Fa outl .
186 It is the caller's responsibility to ensure that
187 .Fa out
188 is sufficiently large to accommodate the output data, which will
189 never be more than 65 bytes plus an additional NUL terminator, i.e.
190 66 bytes in total.
191 .Pp
192 .Fn EVP_EncodeBlock
193 encodes a full block of input data in
194 .Fa f
195 and of length
196 .Fa n
197 and stores it in
198 .Fa t .
199 For every 3 bytes of input provided, 4 bytes of output data will be
200 produced.
201 If
202 .Sy n
203 is not divisible by 3, then the block is encoded as a final block
204 of data and the output is padded such that it is always divisible
205 by 4.
206 Additionally a NUL terminator character will be added.
207 For example, if 16 bytes of input data are provided, then 24 bytes
208 of encoded data is created plus 1 byte for a NUL terminator,
209 i.e. 25 bytes in total.
210 The length of the data generated
211 .Em without
212 the NUL terminator is returned from the function.
213 .Pp
214 .Fn EVP_DecodeInit
215 initialises
216 .Fa ctx
217 for the start of a new decoding operation.
218 .Pp
219 .Fn EVP_DecodeUpdate
220 decodes
221 .Fa inl
222 characters of data found in the buffer pointed to by
223 .Fa in .
224 The output is stored in the buffer
225 .Fa out
226 and the number of bytes output is stored in
227 .Pf * Fa outl .
228 It is the caller's responsibility to ensure that the buffer at
229 .Fa out
230 is sufficiently large to accommodate the output data.
231 This function will attempt to decode as much data as possible in 4-byte
232 chunks.
233 Any whitespace, newline or carriage return characters are ignored.
234 Any partial chunk of unprocessed data (1, 2 or 3 bytes) that remains at
235 the end will be held in the
236 .Fa ctx
237 object and processed by a subsequent call to
238 .Fn EVP_DecodeUpdate .
239 If any illegal base64 characters are encountered or if the base64
240 padding character "=" is encountered in the middle of the data,
241 then the function returns -1 to indicate an error.
242 A return value of 0 or 1 indicates successful processing of the data.
243 A return value of 0 additionally indicates that the last input data
244 characters processed included the base64 padding character "=" and
245 therefore no more non-padding character data is expected to be
246 processed.
247 For every 4 valid base64 bytes processed \(em ignoring whitespace,
248 carriage returns and line feeds \(em 3 bytes of binary output data
249 will be produced, or less at the end of the data where the padding
250 character "=" has been used.
251 .Pp
252 .Fn EVP_DecodeFinal
253 must be called at the end of a decoding operation.
254 If there is any unprocessed data still in
255 .Fa ctx ,
256 then the input data must not have been a multiple of 4 and therefore an
257 error has occurred.
258 The function will return -1 in this case.
259 Otherwise the function returns 1 on success.
260 .Pp
261 .Fn EVP_DecodeBlock
262 will decode the block of
263 .Fa n
264 characters of base64 data contained in
265 .Fa f
266 and store the result in
267 .Fa t .
268 Any leading whitespace will be trimmed as will any trailing whitespace,
269 newlines, carriage returns or EOF characters.
270 After such trimming the length of the data in
271 .Fa f
272 must be divisible by 4.
273 For every 4 input bytes, exactly 3 output bytes will be produced.
274 The output will be padded with 0 bits if necessary to ensure that the
275 output is always 3 bytes for every 4 input bytes.
276 This function will return the length of the data decoded or -1 on error.
277 .Sh RETURN VALUES
278 .Fn EVP_EncodeUpdate
279 returns 0 on error or 1 on success.
280 .Pp
281 .Fn EVP_EncodeBlock
282 returns the number of bytes encoded excluding the NUL terminator.
283 .Pp
284 .Fn EVP_DecodeUpdate
285 returns -1 on error and 0 or 1 on success.
286 If 0 is returned, then no more non-padding base64 characters are
287 expected.
288 .Pp
289 .Fn EVP_DecodeFinal
290 returns -1 on error or 1 on success.
291 .Pp
292 .Fn EVP_DecodeBlock
293 returns the length of the data decoded or -1 on error.
294 .Sh SEE ALSO
295 .Xr evp 3
296 .Sh HISTORY
297 These functions first appeared in SSLeay 0.5.1
298 and have been available since
299 .Ox 2.4 .