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 115The EVP encode routines provide a high level interface to base64 116encoding and decoding. 117Base64 encoding converts binary data into a printable form that uses 118the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. 119For every 3 bytes of binary data provided, 4 bytes of base64-encoded 120data will be produced, plus some occasional newlines. 121If the input data length is not a multiple of 3, then the output data 122will be padded at the end using the "=" character. 123.Pp 124Encoding of binary data is performed in blocks of 48 input bytes (or 125less for the final block). 126For each 48-byte input block encoded, 64 bytes of base64 data is output, 127plus an additional newline character, i.e. 65 bytes in total. 128The final block, which may be less than 48 bytes, will output 4 bytes 129for every 3 bytes of input. 130If the data length is not divisible by 3, then a full 4 bytes is still 131output for the final 1 or 2 bytes of input. 132Similarly a newline character will also be output. 133.Pp 134.Fn EVP_EncodeInit 135initialises 136.Fa ctx 137for the start of a new encoding operation. 138.Pp 139.Fn EVP_EncodeUpdate 140encodes 141.Fa inl 142bytes of data found in the buffer pointed to by 143.Fa in . 144The output is stored in the buffer 145.Fa out 146and the number of bytes output is stored in 147.Pf * Fa outl . 148It is the caller's responsibility to ensure that the buffer at 149.Fa out 150is sufficiently large to accommodate the output data. 151Only full blocks of data (48 bytes) will be immediately processed and 152output by this function. 153Any remainder is held in the 154.Fa ctx 155object and will be processed by a subsequent call to 156.Fn EVP_EncodeUpdate 157or 158.Fn EVP_EncodeFinal . 159To calculate the required size of the output buffer, add together the 160value of 161.Fa inl 162with the amount of unprocessed data held in 163.Fa ctx 164and divide the result by 48 (ignore any remainder). 165This gives the number of blocks of data that will be processed. 166Ensure the output buffer contains 65 bytes of storage for each block, 167plus an additional byte for a NUL terminator. 168.Fn EVP_EncodeUpdate 169may be called repeatedly to process large amounts of input data. 170In the event of an error , 171.Fn EVP_EncodeUpdate 172will set 173.Pf * Fa outl 174to 0 and return 0. 175On success 1 will be returned. 176.Pp 177.Fn EVP_EncodeFinal 178must be called at the end of an encoding operation. 179It will process any partial block of data remaining in the 180.Fa ctx 181object. 182The output data will be stored in 183.Fa out 184and the length of the data written will be stored in 185.Pf * Fa outl . 186It is the caller's responsibility to ensure that 187.Fa out 188is sufficiently large to accommodate the output data, which will 189never be more than 65 bytes plus an additional NUL terminator, i.e. 19066 bytes in total. 191.Pp 192.Fn EVP_EncodeBlock 193encodes a full block of input data in 194.Fa f 195and of length 196.Fa n 197and stores it in 198.Fa t . 199For every 3 bytes of input provided, 4 bytes of output data will be 200produced. 201If 202.Sy n 203is not divisible by 3, then the block is encoded as a final block 204of data and the output is padded such that it is always divisible 205by 4. 206Additionally a NUL terminator character will be added. 207For example, if 16 bytes of input data are provided, then 24 bytes 208of encoded data is created plus 1 byte for a NUL terminator, 209i.e. 25 bytes in total. 210The length of the data generated 211.Em without 212the NUL terminator is returned from the function. 213.Pp 214.Fn EVP_DecodeInit 215initialises 216.Fa ctx 217for the start of a new decoding operation. 218.Pp 219.Fn EVP_DecodeUpdate 220decodes 221.Fa inl 222characters of data found in the buffer pointed to by 223.Fa in . 224The output is stored in the buffer 225.Fa out 226and the number of bytes output is stored in 227.Pf * Fa outl . 228It is the caller's responsibility to ensure that the buffer at 229.Fa out 230is sufficiently large to accommodate the output data. 231This function will attempt to decode as much data as possible in 4-byte 232chunks. 233Any whitespace, newline or carriage return characters are ignored. 234Any partial chunk of unprocessed data (1, 2 or 3 bytes) that remains at 235the end will be held in the 236.Fa ctx 237object and processed by a subsequent call to 238.Fn EVP_DecodeUpdate . 239If any illegal base64 characters are encountered or if the base64 240padding character "=" is encountered in the middle of the data, 241then the function returns -1 to indicate an error. 242A return value of 0 or 1 indicates successful processing of the data. 243A return value of 0 additionally indicates that the last input data 244characters processed included the base64 padding character "=" and 245therefore no more non-padding character data is expected to be 246processed. 247For every 4 valid base64 bytes processed \(em ignoring whitespace, 248carriage returns and line feeds \(em 3 bytes of binary output data 249will be produced, or less at the end of the data where the padding 250character "=" has been used. 251.Pp 252.Fn EVP_DecodeFinal 253must be called at the end of a decoding operation. 254If there is any unprocessed data still in 255.Fa ctx , 256then the input data must not have been a multiple of 4 and therefore an 257error has occurred. 258The function will return -1 in this case. 259Otherwise the function returns 1 on success. 260.Pp 261.Fn EVP_DecodeBlock 262will decode the block of 263.Fa n 264characters of base64 data contained in 265.Fa f 266and store the result in 267.Fa t . 268Any leading whitespace will be trimmed as will any trailing whitespace, 269newlines, carriage returns or EOF characters. 270After such trimming the length of the data in 271.Fa f 272must be divisible by 4. 273For every 4 input bytes, exactly 3 output bytes will be produced. 274The output will be padded with 0 bits if necessary to ensure that the 275output is always 3 bytes for every 4 input bytes. 276This function will return the length of the data decoded or -1 on error. 277.Sh RETURN VALUES 278.Fn EVP_EncodeUpdate 279returns 0 on error or 1 on success. 280.Pp 281.Fn EVP_EncodeBlock 282returns the number of bytes encoded excluding the NUL terminator. 283.Pp 284.Fn EVP_DecodeUpdate 285returns -1 on error and 0 or 1 on success. 286If 0 is returned, then no more non-padding base64 characters are 287expected. 288.Pp 289.Fn EVP_DecodeFinal 290returns -1 on error or 1 on success. 291.Pp 292.Fn EVP_DecodeBlock 293returns the length of the data decoded or -1 on error. 294.Sh SEE ALSO 295.Xr evp 3 296.Sh HISTORY 297These functions first appeared in SSLeay 0.5.1 298and have been available since 299.Ox 2.4 . 300