]>
Commit | Line | Data |
---|---|---|
d202a602 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c1054bb4 JZ |
5 | EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy, |
6 | EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, | |
7 | EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, | |
8 | EVP_DecodeBlock - EVP base 64 encode/decode routines | |
d202a602 MC |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/evp.h> | |
13 | ||
14 | EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void); | |
15 | void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx); | |
c1054bb4 | 16 | int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx); |
d202a602 MC |
17 | int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx); |
18 | void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); | |
cf3404fc MC |
19 | int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, |
20 | const unsigned char *in, int inl); | |
d202a602 MC |
21 | void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); |
22 | int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n); | |
23 | ||
24 | void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); | |
25 | int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, | |
26 | const unsigned char *in, int inl); | |
e9b77246 | 27 | int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); |
d202a602 MC |
28 | int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n); |
29 | ||
30 | =head1 DESCRIPTION | |
31 | ||
32 | The EVP encode routines provide a high level interface to base 64 encoding and | |
33 | decoding. Base 64 encoding converts binary data into a printable form that uses | |
34 | the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3 | |
35 | bytes of binary data provided 4 bytes of base 64 encoded data will be produced | |
36 | plus some occasional newlines (see below). If the input data length is not a | |
37 | multiple of 3 then the output data will be padded at the end using the "=" | |
38 | character. | |
39 | ||
40 | EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for | |
41 | the encode/decode functions. | |
42 | ||
43 | EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the | |
44 | space allocated to it. | |
45 | ||
46 | Encoding of binary data is performed in blocks of 48 input bytes (or less for | |
47 | the final block). For each 48 byte input block encoded 64 bytes of base 64 data | |
48 | is output plus an additional newline character (i.e. 65 bytes in total). The | |
49 | final block (which may be less than 48 bytes) will output 4 bytes for every 3 | |
50 | bytes of input. If the data length is not divisible by 3 then a full 4 bytes is | |
51 | still output for the final 1 or 2 bytes of input. Similarly a newline character | |
52 | will also be output. | |
53 | ||
54 | EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation. | |
55 | ||
56 | EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by | |
57 | B<in>. The output is stored in the buffer B<out> and the number of bytes output | |
58 | is stored in B<*outl>. It is the caller's responsibility to ensure that the | |
59 | buffer at B<out> is sufficiently large to accommodate the output data. Only full | |
60 | blocks of data (48 bytes) will be immediately processed and output by this | |
61 | function. Any remainder is held in the B<ctx> object and will be processed by a | |
62 | subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the | |
63 | required size of the output buffer add together the value of B<inl> with the | |
64 | amount of unprocessed data held in B<ctx> and divide the result by 48 (ignore | |
65 | any remainder). This gives the number of blocks of data that will be processed. | |
66 | Ensure the output buffer contains 65 bytes of storage for each block, plus an | |
67 | additional byte for a NUL terminator. EVP_EncodeUpdate() may be called | |
68 | repeatedly to process large amounts of input data. In the event of an error | |
f430ba31 | 69 | EVP_EncodeUpdate() will set B<*outl> to 0 and return 0. On success 1 will be |
cf3404fc | 70 | returned. |
d202a602 MC |
71 | |
72 | EVP_EncodeFinal() must be called at the end of an encoding operation. It will | |
73 | process any partial block of data remaining in the B<ctx> object. The output | |
74 | data will be stored in B<out> and the length of the data written will be stored | |
75 | in B<*outl>. It is the caller's responsibility to ensure that B<out> is | |
76 | sufficiently large to accommodate the output data which will never be more than | |
77 | 65 bytes plus an additional NUL terminator (i.e. 66 bytes in total). | |
78 | ||
c1054bb4 JZ |
79 | EVP_ENCODE_CTX_copy() can be used to copy a context B<sctx> to a context |
80 | B<dctx>. B<dctx> must be initialized before calling this function. | |
81 | ||
d202a602 MC |
82 | EVP_ENCODE_CTX_num() will return the number of as yet unprocessed bytes still to |
83 | be encoded or decoded that are pending in the B<ctx> object. | |
84 | ||
85 | EVP_EncodeBlock() encodes a full block of input data in B<f> and of length | |
86 | B<dlen> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of | |
87 | output data will be produced. If B<dlen> is not divisible by 3 then the block is | |
88 | encoded as a final block of data and the output is padded such that it is always | |
89 | divisible by 4. Additionally a NUL terminator character will be added. For | |
90 | example if 16 bytes of input data is provided then 24 bytes of encoded data is | |
91 | created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of | |
92 | the data generated I<without> the NUL terminator is returned from the function. | |
93 | ||
94 | EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation. | |
95 | ||
96 | EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer pointed | |
97 | to by B<in>. The output is stored in the buffer B<out> and the number of bytes | |
98 | output is stored in B<*outl>. It is the caller's responsibility to ensure that | |
99 | the buffer at B<out> is sufficiently large to accommodate the output data. This | |
100 | function will attempt to decode as much data as possible in 4 byte chunks. Any | |
101 | whitespace, newline or carriage return characters are ignored. Any partial chunk | |
102 | of unprocessed data (1, 2 or 3 bytes) that remains at the end will be held in | |
103 | the B<ctx> object and processed by a subsequent call to EVP_DecodeUpdate(). If | |
104 | any illegal base 64 characters are encountered or if the base 64 padding | |
105 | character "=" is encountered in the middle of the data then the function returns | |
106 | -1 to indicate an error. A return value of 0 or 1 indicates successful | |
107 | processing of the data. A return value of 0 additionally indicates that the last | |
108 | input data characters processed included the base 64 padding character "=" and | |
109 | therefore no more non-padding character data is expected to be processed. For | |
110 | every 4 valid base 64 bytes processed (ignoring whitespace, carriage returns and | |
111 | line feeds), 3 bytes of binary output data will be produced (or less at the end | |
112 | of the data where the padding character "=" has been used). | |
113 | ||
114 | EVP_DecodeFinal() must be called at the end of a decoding operation. If there | |
115 | is any unprocessed data still in B<ctx> then the input data must not have been | |
116 | a multiple of 4 and therefore an error has occurred. The function will return -1 | |
117 | in this case. Otherwise the function returns 1 on success. | |
118 | ||
119 | EVP_DecodeBlock() will decode the block of B<n> characters of base 64 data | |
120 | contained in B<f> and store the result in B<t>. Any leading whitespace will be | |
121 | trimmed as will any trailing whitespace, newlines, carriage returns or EOF | |
f430ba31 | 122 | characters. After such trimming the length of the data in B<f> must be divisible |
d202a602 MC |
123 | by 4. For every 4 input bytes exactly 3 output bytes will be produced. The |
124 | output will be padded with 0 bits if necessary to ensure that the output is | |
125 | always 3 bytes for every 4 input bytes. This function will return the length of | |
126 | the data decoded or -1 on error. | |
127 | ||
128 | =head1 RETURN VALUES | |
129 | ||
130 | EVP_ENCODE_CTX_new() returns a pointer to the newly allocated EVP_ENCODE_CTX | |
131 | object or NULL on error. | |
132 | ||
133 | EVP_ENCODE_CTX_num() returns the number of bytes pending encoding or decoding in | |
134 | B<ctx>. | |
135 | ||
cf3404fc MC |
136 | EVP_EncodeUpdate() returns 0 on error or 1 on success. |
137 | ||
d202a602 MC |
138 | EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL |
139 | terminator. | |
140 | ||
141 | EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned | |
142 | then no more non-padding base 64 characters are expected. | |
143 | ||
144 | EVP_DecodeFinal() returns -1 on error or 1 on success. | |
145 | ||
146 | EVP_DecodeBlock() returns the length of the data decoded or -1 on error. | |
147 | ||
148 | =head1 SEE ALSO | |
149 | ||
b97fdb57 | 150 | L<evp(7)> |
d202a602 | 151 | |
e2f92610 RS |
152 | =head1 COPYRIGHT |
153 | ||
154 | Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. | |
155 | ||
4746f25a | 156 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
157 | this file except in compliance with the License. You can obtain a copy |
158 | in the file LICENSE in the source distribution or at | |
159 | L<https://www.openssl.org/source/license.html>. | |
160 | ||
161 | =cut |