1.\" $OpenBSD: EVP_EncodeInit.3,v 1.7 2019/06/06 01:06:58 schwarze Exp $ 2.\" full merge up to: OpenSSL f430ba31 Jun 19 19:39:01 2016 +0200 3.\" selective merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 4.\" 5.\" This file was written by Matt Caswell <matt@openssl.org>. 6.\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: June 6 2019 $ 53.Dt EVP_ENCODEINIT 3 54.Os 55.Sh NAME 56.Nm EVP_ENCODE_CTX_new , 57.Nm EVP_ENCODE_CTX_free , 58.Nm EVP_EncodeInit , 59.Nm EVP_EncodeUpdate , 60.Nm EVP_EncodeFinal , 61.Nm EVP_EncodeBlock , 62.Nm EVP_DecodeInit , 63.Nm EVP_DecodeUpdate , 64.Nm EVP_DecodeFinal , 65.Nm EVP_DecodeBlock 66.Nd EVP base64 encode/decode routines 67.Sh SYNOPSIS 68.In openssl/evp.h 69.Ft EVP_ENCODE_CTX * 70.Fn EVP_ENCODE_CTX_new void 71.Ft void 72.Fo EVP_ENCODE_CTX_free 73.Fa "EVP_ENCODE_CTX *ctx" 74.Fc 75.Ft void 76.Fo EVP_EncodeInit 77.Fa "EVP_ENCODE_CTX *ctx" 78.Fc 79.Ft int 80.Fo EVP_EncodeUpdate 81.Fa "EVP_ENCODE_CTX *ctx" 82.Fa "unsigned char *out" 83.Fa "int *outl" 84.Fa "const unsigned char *in" 85.Fa "int inl" 86.Fc 87.Ft void 88.Fo EVP_EncodeFinal 89.Fa "EVP_ENCODE_CTX *ctx" 90.Fa "unsigned char *out" 91.Fa "int *outl" 92.Fc 93.Ft int 94.Fo EVP_EncodeBlock 95.Fa "unsigned char *t" 96.Fa "const unsigned char *f" 97.Fa "int n" 98.Fc 99.Ft void 100.Fo EVP_DecodeInit 101.Fa "EVP_ENCODE_CTX *ctx" 102.Fc 103.Ft int 104.Fo EVP_DecodeUpdate 105.Fa "EVP_ENCODE_CTX *ctx" 106.Fa "unsigned char *out" 107.Fa "int *outl" 108.Fa "const unsigned char *in" 109.Fa "int inl" 110.Fc 111.Ft int 112.Fo EVP_DecodeFinal 113.Fa "EVP_ENCODE_CTX *ctx" 114.Fa "unsigned char *out" 115.Fa "int *outl" 116.Fc 117.Ft int 118.Fo EVP_DecodeBlock 119.Fa "unsigned char *t" 120.Fa "const unsigned char *f" 121.Fa "int n" 122.Fc 123.Sh DESCRIPTION 124The EVP encode routines provide a high level interface to base64 125encoding and decoding. 126Base64 encoding converts binary data into a printable form that uses 127the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. 128For every 3 bytes of binary data provided, 4 bytes of base64-encoded 129data will be produced, plus some occasional newlines. 130If the input data length is not a multiple of 3, then the output data 131will be padded at the end using the "=" character. 132.Pp 133.Fn EVP_ENCODE_CTX_new 134allocates, initializes and returns a context to be used for the encode 135and decode functions. 136.Pp 137.Fn EVP_ENCODE_CTX_free 138frees 139.Fa ctx . 140.Pp 141Encoding of binary data is performed in blocks of 48 input bytes (or 142less for the final block). 143For each 48-byte input block encoded, 64 bytes of base64 data is output, 144plus an additional newline character, i.e. 65 bytes in total. 145The final block, which may be less than 48 bytes, will output 4 bytes 146for every 3 bytes of input. 147If the data length is not divisible by 3, then a full 4 bytes is still 148output for the final 1 or 2 bytes of input. 149Similarly a newline character will also be output. 150.Pp 151.Fn EVP_EncodeInit 152initialises 153.Fa ctx 154for the start of a new encoding operation. 155.Pp 156.Fn EVP_EncodeUpdate 157encodes 158.Fa inl 159bytes of data found in the buffer pointed to by 160.Fa in . 161The output is stored in the buffer 162.Fa out 163and the number of bytes output is stored in 164.Pf * Fa outl . 165It is the caller's responsibility to ensure that the buffer at 166.Fa out 167is sufficiently large to accommodate the output data. 168Only full blocks of data (48 bytes) will be immediately processed and 169output by this function. 170Any remainder is held in the 171.Fa ctx 172object and will be processed by a subsequent call to 173.Fn EVP_EncodeUpdate 174or 175.Fn EVP_EncodeFinal . 176To calculate the required size of the output buffer, add together the 177value of 178.Fa inl 179with the amount of unprocessed data held in 180.Fa ctx 181and divide the result by 48 (ignore any remainder). 182This gives the number of blocks of data that will be processed. 183Ensure the output buffer contains 65 bytes of storage for each block, 184plus an additional byte for a NUL terminator. 185.Fn EVP_EncodeUpdate 186may be called repeatedly to process large amounts of input data. 187In the event of an error , 188.Fn EVP_EncodeUpdate 189will set 190.Pf * Fa outl 191to 0 and return 0. 192On success 1 will be returned. 193.Pp 194.Fn EVP_EncodeFinal 195must be called at the end of an encoding operation. 196It will process any partial block of data remaining in the 197.Fa ctx 198object. 199The output data will be stored in 200.Fa out 201and the length of the data written will be stored in 202.Pf * Fa outl . 203It is the caller's responsibility to ensure that 204.Fa out 205is sufficiently large to accommodate the output data, which will 206never be more than 65 bytes plus an additional NUL terminator, i.e. 20766 bytes in total. 208.Pp 209.Fn EVP_EncodeBlock 210encodes a full block of input data in 211.Fa f 212and of length 213.Fa n 214and stores it in 215.Fa t . 216For every 3 bytes of input provided, 4 bytes of output data will be 217produced. 218If 219.Sy n 220is not divisible by 3, then the block is encoded as a final block 221of data and the output is padded such that it is always divisible 222by 4. 223Additionally a NUL terminator character will be added. 224For example, if 16 bytes of input data are provided, then 24 bytes 225of encoded data is created plus 1 byte for a NUL terminator, 226i.e. 25 bytes in total. 227The length of the data generated 228.Em without 229the NUL terminator is returned from the function. 230.Pp 231.Fn EVP_DecodeInit 232initialises 233.Fa ctx 234for the start of a new decoding operation. 235.Pp 236.Fn EVP_DecodeUpdate 237decodes 238.Fa inl 239characters of data found in the buffer pointed to by 240.Fa in . 241The output is stored in the buffer 242.Fa out 243and the number of bytes output is stored in 244.Pf * Fa outl . 245It is the caller's responsibility to ensure that the buffer at 246.Fa out 247is sufficiently large to accommodate the output data. 248This function will attempt to decode as much data as possible in 4-byte 249chunks. 250Any whitespace, newline or carriage return characters are ignored. 251Any partial chunk of unprocessed data (1, 2 or 3 bytes) that remains at 252the end will be held in the 253.Fa ctx 254object and processed by a subsequent call to 255.Fn EVP_DecodeUpdate . 256If any illegal base64 characters are encountered or if the base64 257padding character "=" is encountered in the middle of the data, 258then the function returns -1 to indicate an error. 259A return value of 0 or 1 indicates successful processing of the data. 260A return value of 0 additionally indicates that the last input data 261characters processed included the base64 padding character "=" and 262therefore no more non-padding character data is expected to be 263processed. 264For every 4 valid base64 bytes processed \(em ignoring whitespace, 265carriage returns and line feeds \(em 3 bytes of binary output data 266will be produced, or less at the end of the data where the padding 267character "=" has been used. 268.Pp 269.Fn EVP_DecodeFinal 270must be called at the end of a decoding operation. 271If there is any unprocessed data still in 272.Fa ctx , 273then the input data must not have been a multiple of 4 and therefore an 274error has occurred. 275The function will return -1 in this case. 276Otherwise the function returns 1 on success. 277.Pp 278.Fn EVP_DecodeBlock 279will decode the block of 280.Fa n 281characters of base64 data contained in 282.Fa f 283and store the result in 284.Fa t . 285Any leading whitespace will be trimmed as will any trailing whitespace, 286newlines, carriage returns or EOF characters. 287After such trimming the length of the data in 288.Fa f 289must be divisible by 4. 290For every 4 input bytes, exactly 3 output bytes will be produced. 291The output will be padded with 0 bits if necessary to ensure that the 292output is always 3 bytes for every 4 input bytes. 293This function will return the length of the data decoded or -1 on error. 294.Sh RETURN VALUES 295.Fn EVP_ENCODE_CTX_new 296returns a pointer to the newly allocated 297.Vt EVP_ENCODE_CTX 298object or 299.Dv NULL 300on error. 301.Pp 302.Fn EVP_EncodeUpdate 303returns 0 on error or 1 on success. 304.Pp 305.Fn EVP_EncodeBlock 306returns the number of bytes encoded excluding the NUL terminator. 307.Pp 308.Fn EVP_DecodeUpdate 309returns -1 on error and 0 or 1 on success. 310If 0 is returned, then no more non-padding base64 characters are 311expected. 312.Pp 313.Fn EVP_DecodeFinal 314returns -1 on error or 1 on success. 315.Pp 316.Fn EVP_DecodeBlock 317returns the length of the data decoded or -1 on error. 318.Sh SEE ALSO 319.Xr BIO_f_base64 3 , 320.Xr evp 3 321.Sh HISTORY 322The 323.Fn EVP_Encode* 324and 325.Fn EVP_Decode* 326functions first appeared in SSLeay 0.5.1 327and have been available since 328.Ox 2.4 . 329.Pp 330.Fn EVP_ENCODE_CTX_new 331and 332.Fn EVP_ENCODE_CTX_free 333first appeared in OpenSSL 1.1.0 and have been available since 334.Ox 6.5 . 335