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