1=pod 2 3=head1 NAME 4 5EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, EVP_EncodeBlock, 6EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, EVP_DecodeBlock - EVP base 64 7encode/decode routines 8 9=head1 SYNOPSIS 10 11 #include <openssl/evp.h> 12 13 void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); 14 void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, 15 const unsigned char *in, int inl); 16 void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); 17 int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n); 18 19 void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); 20 int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, 21 const unsigned char *in, int inl); 22 int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned 23 char *out, int *outl); 24 int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n); 25 26=head1 DESCRIPTION 27 28The EVP encode routines provide a high level interface to base 64 encoding and 29decoding. Base 64 encoding converts binary data into a printable form that uses 30the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3 31bytes of binary data provided 4 bytes of base 64 encoded data will be produced 32plus some occasional newlines (see below). If the input data length is not a 33multiple of 3 then the output data will be padded at the end using the "=" 34character. 35 36Encoding of binary data is performed in blocks of 48 input bytes (or less for 37the final block). For each 48 byte input block encoded 64 bytes of base 64 data 38is output plus an additional newline character (i.e. 65 bytes in total). The 39final block (which may be less than 48 bytes) will output 4 bytes for every 3 40bytes of input. If the data length is not divisible by 3 then a full 4 bytes is 41still output for the final 1 or 2 bytes of input. Similarly a newline character 42will also be output. 43 44EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation. 45 46EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by 47B<in>. The output is stored in the buffer B<out> and the number of bytes output 48is stored in B<*outl>. It is the caller's responsibility to ensure that the 49buffer at B<out> is sufficiently large to accommodate the output data. Only full 50blocks of data (48 bytes) will be immediately processed and output by this 51function. Any remainder is held in the B<ctx> object and will be processed by a 52subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the 53required size of the output buffer add together the value of B<inl> with the 54amount of unprocessed data held in B<ctx> and divide the result by 48 (ignore 55any remainder). This gives the number of blocks of data that will be processed. 56Ensure the output buffer contains 65 bytes of storage for each block, plus an 57additional byte for a NUL terminator. EVP_EncodeUpdate() may be called 58repeatedly to process large amounts of input data. In the event of an error 59EVP_EncodeUpdate() will set B<*outl> to 0. 60 61EVP_EncodeFinal() must be called at the end of an encoding operation. It will 62process any partial block of data remaining in the B<ctx> object. The output 63data will be stored in B<out> and the length of the data written will be stored 64in B<*outl>. It is the caller's responsibility to ensure that B<out> is 65sufficiently large to accommodate the output data which will never be more than 6665 bytes plus an additional NUL terminator (i.e. 66 bytes in total). 67 68EVP_EncodeBlock() encodes a full block of input data in B<f> and of length 69B<dlen> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of 70output data will be produced. If B<dlen> is not divisible by 3 then the block is 71encoded as a final block of data and the output is padded such that it is always 72divisible by 4. Additionally a NUL terminator character will be added. For 73example if 16 bytes of input data is provided then 24 bytes of encoded data is 74created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of 75the data generated I<without> the NUL terminator is returned from the function. 76 77EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation. 78 79EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer pointed 80to by B<in>. The output is stored in the buffer B<out> and the number of bytes 81output is stored in B<*outl>. It is the caller's responsibility to ensure that 82the buffer at B<out> is sufficiently large to accommodate the output data. This 83function will attempt to decode as much data as possible in 4 byte chunks. Any 84whitespace, newline or carriage return characters are ignored. Any partial chunk 85of unprocessed data (1, 2 or 3 bytes) that remains at the end will be held in 86the B<ctx> object and processed by a subsequent call to EVP_DecodeUpdate(). If 87any illegal base 64 characters are encountered or if the base 64 padding 88character "=" is encountered in the middle of the data then the function returns 89-1 to indicate an error. A return value of 0 or 1 indicates successful 90processing of the data. A return value of 0 additionally indicates that the last 91input data characters processed included the base 64 padding character "=" and 92therefore no more non-padding character data is expected to be processed. For 93every 4 valid base 64 bytes processed (ignoring whitespace, carriage returns and 94line feeds), 3 bytes of binary output data will be produced (or less at the end 95of the data where the padding character "=" has been used). 96 97EVP_DecodeFinal() must be called at the end of a decoding operation. If there 98is any unprocessed data still in B<ctx> then the input data must not have been 99a multiple of 4 and therefore an error has occurred. The function will return -1 100in this case. Otherwise the function returns 1 on success. 101 102EVP_DecodeBlock() will decode the block of B<n> characters of base 64 data 103contained in B<f> and store the result in B<t>. Any leading whitespace will be 104trimmed as will any trailing whitespace, newlines, carriage returns or EOF 105characters. After such trimming the length of the data in B<f> must be divisbile 106by 4. For every 4 input bytes exactly 3 output bytes will be produced. The 107output will be padded with 0 bits if necessary to ensure that the output is 108always 3 bytes for every 4 input bytes. This function will return the length of 109the data decoded or -1 on error. 110 111=head1 RETURN VALUES 112 113EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL 114terminator. 115 116EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned 117then no more non-padding base 64 characters are expected. 118 119EVP_DecodeFinal() returns -1 on error or 1 on success. 120 121EVP_DecodeBlock() returns the length of the data decoded or -1 on error. 122 123=head1 SEE ALSO 124 125L<evp(3)> 126 127=cut 128