1 /* 2 * Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OPENSSL_HEADER_BASE64_H 11 #define OPENSSL_HEADER_BASE64_H 12 13 #include <openssl/base.h> 14 15 #if defined(__cplusplus) 16 extern "C" { 17 #endif 18 19 20 // base64 functions. 21 // 22 // For historical reasons, these functions have the EVP_ prefix but just do 23 // base64 encoding and decoding. Note that BoringSSL is a cryptography library, 24 // so these functions are implemented with side channel protections, at a 25 // performance cost. For other base64 uses, use a general-purpose base64 26 // implementation. 27 28 29 // Encoding 30 31 // EVP_EncodeBlock encodes |src_len| bytes from |src| and writes the 32 // result to |dst| with a trailing NUL. It returns the number of bytes 33 // written, not including this trailing NUL. 34 OPENSSL_EXPORT size_t EVP_EncodeBlock(uint8_t *dst, const uint8_t *src, 35 size_t src_len); 36 37 // EVP_EncodedLength sets |*out_len| to the number of bytes that will be needed 38 // to call |EVP_EncodeBlock| on an input of length |len|. This includes the 39 // final NUL that |EVP_EncodeBlock| writes. It returns one on success or zero 40 // on error. 41 OPENSSL_EXPORT int EVP_EncodedLength(size_t *out_len, size_t len); 42 43 44 // Decoding 45 46 // EVP_DecodedLength sets |*out_len| to the maximum number of bytes that will 47 // be needed to call |EVP_DecodeBase64| on an input of length |len|. It returns 48 // one on success or zero if |len| is not a valid length for a base64-encoded 49 // string. 50 OPENSSL_EXPORT int EVP_DecodedLength(size_t *out_len, size_t len); 51 52 // EVP_DecodeBase64 decodes |in_len| bytes from base64 and writes 53 // |*out_len| bytes to |out|. |max_out| is the size of the output 54 // buffer. If it is not enough for the maximum output size, the 55 // operation fails. It returns one on success or zero on error. 56 OPENSSL_EXPORT int EVP_DecodeBase64(uint8_t *out, size_t *out_len, 57 size_t max_out, const uint8_t *in, 58 size_t in_len); 59 60 61 // Deprecated functions. 62 // 63 // OpenSSL provides a streaming base64 implementation, however its behavior is 64 // very specific to PEM. It is also very lenient of invalid input. Use of any of 65 // these functions is thus deprecated. 66 67 // EVP_ENCODE_CTX_new returns a newly-allocated |EVP_ENCODE_CTX| or NULL on 68 // error. The caller must release the result with |EVP_ENCODE_CTX_free| when 69 // done. 70 OPENSSL_EXPORT EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void); 71 72 // EVP_ENCODE_CTX_free releases memory associated with |ctx|. 73 OPENSSL_EXPORT void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx); 74 75 // EVP_EncodeInit initialises |*ctx|, which is typically stack 76 // allocated, for an encoding operation. 77 // 78 // NOTE: The encoding operation breaks its output with newlines every 79 // 64 characters of output (48 characters of input). Use 80 // EVP_EncodeBlock to encode raw base64. 81 OPENSSL_EXPORT void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); 82 83 // EVP_EncodeUpdate encodes |in_len| bytes from |in| and writes an encoded 84 // version of them to |out| and sets |*out_len| to the number of bytes written. 85 // Some state may be contained in |ctx| so |EVP_EncodeFinal| must be used to 86 // flush it before using the encoded data. 87 OPENSSL_EXPORT void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, uint8_t *out, 88 int *out_len, const uint8_t *in, 89 size_t in_len); 90 91 // EVP_EncodeFinal flushes any remaining output bytes from |ctx| to |out| and 92 // sets |*out_len| to the number of bytes written. 93 OPENSSL_EXPORT void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, uint8_t *out, 94 int *out_len); 95 96 // EVP_DecodeInit initialises |*ctx|, which is typically stack allocated, for 97 // a decoding operation. 98 // 99 // TODO(davidben): This isn't a straight-up base64 decode either. Document 100 // and/or fix exactly what's going on here; maximum line length and such. 101 OPENSSL_EXPORT void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); 102 103 // EVP_DecodeUpdate decodes |in_len| bytes from |in| and writes the decoded 104 // data to |out| and sets |*out_len| to the number of bytes written. Some state 105 // may be contained in |ctx| so |EVP_DecodeFinal| must be used to flush it 106 // before using the encoded data. 107 // 108 // It returns -1 on error, one if a full line of input was processed and zero 109 // if the line was short (i.e. it was the last line). 110 OPENSSL_EXPORT int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, uint8_t *out, 111 int *out_len, const uint8_t *in, 112 size_t in_len); 113 114 // EVP_DecodeFinal flushes any remaining output bytes from |ctx| to |out| and 115 // sets |*out_len| to the number of bytes written. It returns one on success 116 // and minus one on error. 117 OPENSSL_EXPORT int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, uint8_t *out, 118 int *out_len); 119 120 // EVP_DecodeBlock encodes |src_len| bytes from |src| and writes the result to 121 // |dst|. It returns the number of bytes written or -1 on error. 122 // 123 // WARNING: EVP_DecodeBlock's return value does not take padding into 124 // account. It also strips leading whitespace and trailing 125 // whitespace and minuses. 126 OPENSSL_EXPORT int EVP_DecodeBlock(uint8_t *dst, const uint8_t *src, 127 size_t src_len); 128 129 130 struct evp_encode_ctx_st { 131 // data_used indicates the number of bytes of |data| that are valid. When 132 // encoding, |data| will be filled and encoded as a lump. When decoding, only 133 // the first four bytes of |data| will be used. 134 unsigned data_used; 135 uint8_t data[48]; 136 137 // eof_seen indicates that the end of the base64 data has been seen when 138 // decoding. Only whitespace can follow. 139 char eof_seen; 140 141 // error_encountered indicates that invalid base64 data was found. This will 142 // cause all future calls to fail. 143 char error_encountered; 144 }; 145 146 147 #if defined(__cplusplus) 148 } // extern C 149 #endif 150 151 #endif // OPENSSL_HEADER_BASE64_H 152