| 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_ENCODEINIT 3SSL" |
| 58 |
.TH EVP_ENCODEINIT 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_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy, |
| 65 |
EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, |
| 66 |
EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, |
| 67 |
EVP_DecodeBlock \- EVP base64 encode/decode routines |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
.Vb 1 |
| 71 |
\& #include <openssl/evp.h> |
| 72 |
\& |
| 73 |
\& EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void); |
| 74 |
\& void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx); |
| 75 |
\& int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx); |
| 76 |
\& int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx); |
| 77 |
\& void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); |
| 78 |
\& int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, |
| 79 |
\& const unsigned char *in, int inl); |
| 80 |
\& void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); |
| 81 |
\& int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n); |
| 82 |
\& |
| 83 |
\& void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); |
| 84 |
\& int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, |
| 85 |
\& const unsigned char *in, int inl); |
| 86 |
\& int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); |
| 87 |
\& int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n); |
| 88 |
.Ve |
| 89 |
.SH DESCRIPTION |
| 90 |
.IX Header "DESCRIPTION" |
| 91 |
The EVP encode routines provide a high-level interface to base64 encoding and |
| 92 |
decoding. |
| 93 |
Base64 encoding converts binary data into a printable form that uses |
| 94 |
the characters A\-Z, a\-z, 0\-9, "+" and "/" to represent the data. For every 3 |
| 95 |
bytes of binary data provided 4 bytes of base64 encoded data will be produced |
| 96 |
plus some occasional newlines (see below). If the input data length is not a |
| 97 |
multiple of 3 then the output data will be padded at the end using the "=" |
| 98 |
character. |
| 99 |
.PP |
| 100 |
\&\fBEVP_ENCODE_CTX_new()\fR allocates, initializes and returns a context to be used for |
| 101 |
the encode/decode functions. |
| 102 |
.PP |
| 103 |
\&\fBEVP_ENCODE_CTX_free()\fR cleans up an encode/decode context \fBctx\fR and frees up the |
| 104 |
space allocated to it. If the argument is NULL, nothing is done. |
| 105 |
.PP |
| 106 |
Encoding of binary data is performed in blocks of 48 input bytes (or less for |
| 107 |
the final block). |
| 108 |
For each 48 byte input block encoded 64 bytes of base64 data |
| 109 |
is output plus an additional newline character (i.e. 65 bytes in total). The |
| 110 |
final block (which may be less than 48 bytes) will output 4 bytes for every 3 |
| 111 |
bytes of input. If the data length is not divisible by 3 then a full 4 bytes is |
| 112 |
still output for the final 1 or 2 bytes of input. Similarly a newline character |
| 113 |
will also be output. |
| 114 |
.PP |
| 115 |
\&\fBEVP_EncodeInit()\fR initialises \fBctx\fR for the start of a new encoding operation. |
| 116 |
.PP |
| 117 |
\&\fBEVP_EncodeUpdate()\fR encode \fBinl\fR bytes of data found in the buffer pointed to by |
| 118 |
\&\fBin\fR. The output is stored in the buffer \fBout\fR and the number of bytes output |
| 119 |
is stored in \fB*outl\fR. It is the caller's responsibility to ensure that the |
| 120 |
buffer at \fBout\fR is sufficiently large to accommodate the output data. Only full |
| 121 |
blocks of data (48 bytes) will be immediately processed and output by this |
| 122 |
function. Any remainder is held in the \fBctx\fR object and will be processed by a |
| 123 |
subsequent call to \fBEVP_EncodeUpdate()\fR or \fBEVP_EncodeFinal()\fR. To calculate the |
| 124 |
required size of the output buffer add together the value of \fBinl\fR with the |
| 125 |
amount of unprocessed data held in \fBctx\fR and divide the result by 48 (ignore |
| 126 |
any remainder). This gives the number of blocks of data that will be processed. |
| 127 |
Ensure the output buffer contains 65 bytes of storage for each block, plus an |
| 128 |
additional byte for a NUL terminator. \fBEVP_EncodeUpdate()\fR may be called |
| 129 |
repeatedly to process large amounts of input data. In the event of an error |
| 130 |
\&\fBEVP_EncodeUpdate()\fR will set \fB*outl\fR to 0 and return 0. On success 1 will be |
| 131 |
returned. |
| 132 |
.PP |
| 133 |
\&\fBEVP_EncodeFinal()\fR must be called at the end of an encoding operation. It will |
| 134 |
process any partial block of data remaining in the \fBctx\fR object. The output |
| 135 |
data will be stored in \fBout\fR and the length of the data written will be stored |
| 136 |
in \fB*outl\fR. It is the caller's responsibility to ensure that \fBout\fR is |
| 137 |
sufficiently large to accommodate the output data which will never be more than |
| 138 |
65 bytes plus an additional NUL terminator (i.e. 66 bytes in total). |
| 139 |
.PP |
| 140 |
\&\fBEVP_ENCODE_CTX_copy()\fR can be used to copy a context \fBsctx\fR to a context |
| 141 |
\&\fBdctx\fR. \fBdctx\fR must be initialized before calling this function. |
| 142 |
.PP |
| 143 |
\&\fBEVP_ENCODE_CTX_num()\fR will return the number of as yet unprocessed bytes still to |
| 144 |
be encoded or decoded that are pending in the \fBctx\fR object. |
| 145 |
.PP |
| 146 |
\&\fBEVP_EncodeBlock()\fR encodes a full block of input data in \fBf\fR and of length |
| 147 |
\&\fBn\fR and stores it in \fBt\fR. For every 3 bytes of input provided 4 bytes of |
| 148 |
output data will be produced. If \fBn\fR is not divisible by 3 then the block is |
| 149 |
encoded as a final block of data and the output is padded such that it is always |
| 150 |
divisible by 4. Additionally a NUL terminator character will be added. For |
| 151 |
example if 16 bytes of input data is provided then 24 bytes of encoded data is |
| 152 |
created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of |
| 153 |
the data generated \fIwithout\fR the NUL terminator is returned from the function. |
| 154 |
.PP |
| 155 |
\&\fBEVP_DecodeInit()\fR initialises \fBctx\fR for the start of a new decoding operation. |
| 156 |
.PP |
| 157 |
\&\fBEVP_DecodeUpdate()\fR decodes \fBinl\fR characters of data found in the buffer |
| 158 |
pointed to by \fBin\fR. |
| 159 |
The output is stored in the buffer \fBout\fR and the number of bytes output is |
| 160 |
stored in \fB*outl\fR. |
| 161 |
It is the caller's responsibility to ensure that the buffer at \fBout\fR is |
| 162 |
sufficiently large to accommodate the output data. |
| 163 |
This function will attempt to decode as much data as possible in chunks of up |
| 164 |
to 80 base64 characters at a time. |
| 165 |
Residual input shorter than the internal chunk size will be buffered in \fBctx\fR |
| 166 |
if its length is not a multiple of 4 (including any padding), to be processed |
| 167 |
in future calls to \fBEVP_DecodeUpdate()\fR or \fBEVP_DecodeFinal()\fR. |
| 168 |
If the final chunk length is a multiple of 4, it is decoded immediately and |
| 169 |
not buffered. |
| 170 |
.PP |
| 171 |
Any whitespace, newline or carriage return characters are ignored. |
| 172 |
For compatibility with \fBPEM\fR, the \fB\-\fR (hyphen) character is treated as a soft |
| 173 |
end-of-input, subsequent bytes are not buffered, and the return value will be |
| 174 |
0 to indicate that the end of the base64 input has been detected. |
| 175 |
The soft end-of-input, if present, MUST occur after a multiple of 4 valid base64 |
| 176 |
input bytes. |
| 177 |
The soft end-of-input condition is not remembered in \fBctx\fR, it is up to the |
| 178 |
caller to avoid further calls to \fBEVP_DecodeUpdate()\fR after a 0 or negative |
| 179 |
(error) return. |
| 180 |
.PP |
| 181 |
If any invalid base64 characters are encountered or if the base64 padding |
| 182 |
character (\fB=\fR) is encountered in the middle of the data then |
| 183 |
\&\fBEVP_DecodeUpdate()\fR returns \-1 to indicate an error. |
| 184 |
A return value of 0 or 1 indicates successful processing of the data. |
| 185 |
A return value of 0 additionally indicates that the last 4 bytes processed |
| 186 |
ended with base64 padding (\fB=\fR), or that the next 4 byte group starts with the |
| 187 |
soft end-of-input (\fB\-\fR) character, and therefore no more input data is |
| 188 |
expected to be processed. |
| 189 |
.PP |
| 190 |
For every 4 valid base64 bytes processed (ignoring whitespace, carriage returns |
| 191 |
and line feeds), 3 bytes of binary output data will be produced (except at the |
| 192 |
end of data terminated with one or two padding characters). |
| 193 |
.PP |
| 194 |
\&\fBEVP_DecodeFinal()\fR should be called at the end of a decoding operation, |
| 195 |
but it will never decode additional data. If there is no residual data |
| 196 |
it will return 1 to indicate success. If there is residual data, its |
| 197 |
length is not a multiple of 4, i.e. it was not properly padded, \-1 is |
| 198 |
is returned in that case to indicate an error. |
| 199 |
.PP |
| 200 |
\&\fBEVP_DecodeBlock()\fR will decode the block of \fBn\fR characters of base64 data |
| 201 |
contained in \fBf\fR and store the result in \fBt\fR. |
| 202 |
Any leading whitespace will be trimmed as will any trailing whitespace, |
| 203 |
newlines, carriage returns or EOF characters. |
| 204 |
Internal whitespace MUST NOT be present. |
| 205 |
After trimming the data in \fBf\fR MUST consist entirely of valid base64 |
| 206 |
characters or padding (only at the tail of the input) and its length MUST be |
| 207 |
divisible by 4. |
| 208 |
For every 4 input bytes exactly 3 output bytes will be produced. |
| 209 |
Padding bytes (\fB=\fR) (even if internal) are decoded to 6 zero bits, the caller |
| 210 |
is responsible for taking trailing padding into account, by ignoring as many |
| 211 |
bytes at the tail of the returned output. |
| 212 |
\&\fBEVP_DecodeBlock()\fR will return the length of the data decoded or \-1 on error. |
| 213 |
.SH "RETURN VALUES" |
| 214 |
.IX Header "RETURN VALUES" |
| 215 |
\&\fBEVP_ENCODE_CTX_new()\fR returns a pointer to the newly allocated EVP_ENCODE_CTX |
| 216 |
object or NULL on error. |
| 217 |
.PP |
| 218 |
\&\fBEVP_ENCODE_CTX_num()\fR returns the number of bytes pending encoding or decoding in |
| 219 |
\&\fBctx\fR. |
| 220 |
.PP |
| 221 |
\&\fBEVP_EncodeUpdate()\fR returns 0 on error or 1 on success. |
| 222 |
.PP |
| 223 |
\&\fBEVP_EncodeBlock()\fR returns the number of bytes encoded excluding the NUL |
| 224 |
terminator. |
| 225 |
.PP |
| 226 |
\&\fBEVP_DecodeUpdate()\fR returns \-1 on error and 0 or 1 on success. If 0 is returned |
| 227 |
then no more non-padding base64 characters are expected. |
| 228 |
.PP |
| 229 |
\&\fBEVP_DecodeFinal()\fR returns \-1 on error or 1 on success. |
| 230 |
.PP |
| 231 |
\&\fBEVP_DecodeBlock()\fR returns the length of the data decoded or \-1 on error. |
| 232 |
.SH "SEE ALSO" |
| 233 |
.IX Header "SEE ALSO" |
| 234 |
\&\fBevp\fR\|(7) |
| 235 |
.SH HISTORY |
| 236 |
.IX Header "HISTORY" |
| 237 |
The \fBEVP_DecodeUpdate()\fR function was fixed in OpenSSL 3.5, |
| 238 |
so now it produces the number of bytes specified in \fBoutl*\fR |
| 239 |
and does not decode padding bytes (\fB=\fR) to 6 zero bits. |
| 240 |
.SH COPYRIGHT |
| 241 |
.IX Header "COPYRIGHT" |
| 242 |
Copyright 2016\-2025 The OpenSSL Project Authors. All Rights Reserved. |
| 243 |
.PP |
| 244 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 245 |
this file except in compliance with the License. You can obtain a copy |
| 246 |
in the file LICENSE in the source distribution or at |
| 247 |
<https://www.openssl.org/source/license.html>. |