1=pod 2 3=head1 NAME 4 5EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy, 6EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, 7EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, 8EVP_DecodeBlock - EVP base64 encode/decode routines 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); 16 int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx); 17 int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx); 18 void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); 19 int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, 20 const unsigned char *in, int inl); 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); 27 int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); 28 int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n); 29 30=head1 DESCRIPTION 31 32The EVP encode routines provide a high-level interface to base64 encoding and 33decoding. 34Base64 encoding converts binary data into a printable form that uses 35the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3 36bytes of binary data provided 4 bytes of base64 encoded data will be produced 37plus some occasional newlines (see below). If the input data length is not a 38multiple of 3 then the output data will be padded at the end using the "=" 39character. 40 41EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for 42the encode/decode functions. 43 44EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the 45space allocated to it. If the argument is NULL, nothing is done. 46 47Encoding of binary data is performed in blocks of 48 input bytes (or less for 48the final block). 49For each 48 byte input block encoded 64 bytes of base64 data 50is output plus an additional newline character (i.e. 65 bytes in total). The 51final block (which may be less than 48 bytes) will output 4 bytes for every 3 52bytes of input. If the data length is not divisible by 3 then a full 4 bytes is 53still output for the final 1 or 2 bytes of input. Similarly a newline character 54will also be output. 55 56EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation. 57 58EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by 59B<in>. The output is stored in the buffer B<out> and the number of bytes output 60is stored in B<*outl>. It is the caller's responsibility to ensure that the 61buffer at B<out> is sufficiently large to accommodate the output data. Only full 62blocks of data (48 bytes) will be immediately processed and output by this 63function. Any remainder is held in the B<ctx> object and will be processed by a 64subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the 65required size of the output buffer add together the value of B<inl> with the 66amount of unprocessed data held in B<ctx> and divide the result by 48 (ignore 67any remainder). This gives the number of blocks of data that will be processed. 68Ensure the output buffer contains 65 bytes of storage for each block, plus an 69additional byte for a NUL terminator. EVP_EncodeUpdate() may be called 70repeatedly to process large amounts of input data. In the event of an error 71EVP_EncodeUpdate() will set B<*outl> to 0 and return 0. On success 1 will be 72returned. 73 74EVP_EncodeFinal() must be called at the end of an encoding operation. It will 75process any partial block of data remaining in the B<ctx> object. The output 76data will be stored in B<out> and the length of the data written will be stored 77in B<*outl>. It is the caller's responsibility to ensure that B<out> is 78sufficiently large to accommodate the output data which will never be more than 7965 bytes plus an additional NUL terminator (i.e. 66 bytes in total). 80 81EVP_ENCODE_CTX_copy() can be used to copy a context B<sctx> to a context 82B<dctx>. B<dctx> must be initialized before calling this function. 83 84EVP_ENCODE_CTX_num() will return the number of as yet unprocessed bytes still to 85be encoded or decoded that are pending in the B<ctx> object. 86 87EVP_EncodeBlock() encodes a full block of input data in B<f> and of length 88B<n> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of 89output data will be produced. If B<n> is not divisible by 3 then the block is 90encoded as a final block of data and the output is padded such that it is always 91divisible by 4. Additionally a NUL terminator character will be added. For 92example if 16 bytes of input data is provided then 24 bytes of encoded data is 93created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of 94the data generated I<without> the NUL terminator is returned from the function. 95 96EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation. 97 98EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer 99pointed to by B<in>. 100The output is stored in the buffer B<out> and the number of bytes output is 101stored in B<*outl>. 102It is the caller's responsibility to ensure that the buffer at B<out> is 103sufficiently large to accommodate the output data. 104This function will attempt to decode as much data as possible in chunks of up 105to 80 base64 characters at a time. 106Residual input shorter than the internal chunk size will be buffered in B<ctx> 107if its length is not a multiple of 4 (including any padding), to be processed 108in future calls to EVP_DecodeUpdate() or EVP_DecodeFinal(). 109If the final chunk length is a multiple of 4, it is decoded immediately and 110not buffered. 111 112Any whitespace, newline or carriage return characters are ignored. 113For compatibility with B<PEM>, the B<-> (hyphen) character is treated as a soft 114end-of-input, subsequent bytes are not buffered, and the return value will be 1150 to indicate that the end of the base64 input has been detected. 116The soft end-of-input, if present, MUST occur after a multiple of 4 valid base64 117input bytes. 118The soft end-of-input condition is not remembered in B<ctx>, it is up to the 119caller to avoid further calls to EVP_DecodeUpdate() after a 0 or negative 120(error) return. 121 122If any invalid base64 characters are encountered or if the base64 padding 123character (B<=>) is encountered in the middle of the data then 124EVP_DecodeUpdate() returns -1 to indicate an error. 125A return value of 0 or 1 indicates successful processing of the data. 126A return value of 0 additionally indicates that the last 4 bytes processed 127ended with base64 padding (B<=>), or that the next 4 byte group starts with the 128soft end-of-input (B<->) character, and therefore no more input data is 129expected to be processed. 130 131For every 4 valid base64 bytes processed (ignoring whitespace, carriage returns 132and line feeds), 3 bytes of binary output data will be produced (except at the 133end of data terminated with one or two padding characters). 134 135EVP_DecodeFinal() should be called at the end of a decoding operation, 136but it will never decode additional data. If there is no residual data 137it will return 1 to indicate success. If there is residual data, its 138length is not a multiple of 4, i.e. it was not properly padded, -1 is 139is returned in that case to indicate an error. 140 141EVP_DecodeBlock() will decode the block of B<n> characters of base64 data 142contained in B<f> and store the result in B<t>. 143Any leading whitespace will be trimmed as will any trailing whitespace, 144newlines, carriage returns or EOF characters. 145Internal whitespace MUST NOT be present. 146After trimming the data in B<f> MUST consist entirely of valid base64 147characters or padding (only at the tail of the input) and its length MUST be 148divisible by 4. 149For every 4 input bytes exactly 3 output bytes will be produced. 150Padding bytes (B<=>) (even if internal) are decoded to 6 zero bits, the caller 151is responsible for taking trailing padding into account, by ignoring as many 152bytes at the tail of the returned output. 153EVP_DecodeBlock() will return the length of the data decoded or -1 on error. 154 155=head1 RETURN VALUES 156 157EVP_ENCODE_CTX_new() returns a pointer to the newly allocated EVP_ENCODE_CTX 158object or NULL on error. 159 160EVP_ENCODE_CTX_num() returns the number of bytes pending encoding or decoding in 161B<ctx>. 162 163EVP_EncodeUpdate() returns 0 on error or 1 on success. 164 165EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL 166terminator. 167 168EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned 169then no more non-padding base64 characters are expected. 170 171EVP_DecodeFinal() returns -1 on error or 1 on success. 172 173EVP_DecodeBlock() returns the length of the data decoded or -1 on error. 174 175=head1 SEE ALSO 176 177L<evp(7)> 178 179=head1 COPYRIGHT 180 181Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved. 182 183Licensed under the Apache License 2.0 (the "License"). You may not use 184this file except in compliance with the License. You can obtain a copy 185in the file LICENSE in the source distribution or at 186L<https://www.openssl.org/source/license.html>. 187 188=cut 189
