Apache Portable Runtime
apr_base64.h
Go to the documentation of this file.
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2  * contributor license agreements. See the NOTICE file distributed with
3  * this work for additional information regarding copyright ownership.
4  * The ASF licenses this file to You under the Apache License, Version 2.0
5  * (the "License"); you may not use this file except in compliance with
6  * the License. You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  * The apr_vsnprintf/apr_snprintf functions are based on, and used with the
16  * permission of, the SIO stdio-replacement strx_* functions by Panos
17  * Tsirigotis <panos@alumni.cs.colorado.edu> for xinetd.
18  */
19 
20 /**
21  * @file apr_base64.h
22  * @brief APR-UTIL Base64 Encoding
23  */
24 #ifndef APR_BASE64_H
25 #define APR_BASE64_H
26 
27 #include "apu.h"
28 #include "apr_general.h"
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /**
35  * @defgroup APR_Util_Base64 Base64 Encoding
36  * @ingroup APR
37  * @{
38  */
39 
40 /* Simple BASE64 encode/decode functions.
41  *
42  * As we might encode binary strings, hence we require the length of
43  * the incoming plain source. And return the length of what we decoded.
44  *
45  * The decoding function takes any non valid char (i.e. whitespace, \0
46  * or anything non A-Z,0-9 etc) as terminal.
47  *
48  * The handling of terminating \0 characters differs from function to
49  * function.
50  *
51  */
52 
53 /**
54  * Given the length of an un-encoded string, get the length of the
55  * encoded string.
56  * @param len the length of an unencoded string.
57  * @return the length of the string after it is encoded, including the
58  * trailing \0
59  */
60 APR_DECLARE(int) apr_base64_encode_len(int len) __attribute__((pure));
61 
62 /**
63  * Encode a text string using base64encoding. On EBCDIC machines, the input
64  * is first converted to ASCII.
65  * @param coded_dst The destination string for the encoded string. A \0 is
66  * appended.
67  * @param plain_src The original string in plain text
68  * @param len_plain_src The length of the plain text string
69  * @return the length of the encoded string, including the trailing \0
70  */
71 APR_DECLARE(int) apr_base64_encode(char * coded_dst, const char *plain_src,
72  int len_plain_src)
73  __attribute__((nonnull(1,2)));
74 
75 /**
76  * Encode an text string using base64encoding. This is the same as
77  * apr_base64_encode() except on EBCDIC machines, where the conversion of the
78  * input to ASCII is left out.
79  * @param coded_dst The destination string for the encoded string. A \0 is
80  * appended.
81  * @param plain_src The original string in plain text
82  * @param len_plain_src The length of the plain text string
83  * @return the length of the encoded string, including the trailing \0
84  */
85 APR_DECLARE(int) apr_base64_encode_binary(char * coded_dst,
86  const unsigned char *plain_src,
87  int len_plain_src)
88  __attribute__((nonnull(1,2)));
89 
90 /**
91  * Encode a string into memory allocated from a pool in base 64 format
92  * @param p The pool to allocate from
93  * @param string The plaintext string
94  * @return The encoded string
95  */
96 APR_DECLARE(char *) apr_pbase64_encode(apr_pool_t *p, const char *string)
97  __attribute__((nonnull(1,2)));
98 
99 /**
100  * Determine the maximum buffer length required to decode the plain text
101  * string given the encoded string.
102  * @param coded_src The encoded string
103  * @return the maximum required buffer length for the plain text string
104  */
105 APR_DECLARE(int) apr_base64_decode_len(const char * coded_src)
106  __attribute__((nonnull(1))) __attribute__((pure));
107 
108 /**
109  * Decode a string to plain text. On EBCDIC machines, the result is then
110  * converted to EBCDIC.
111  * @param plain_dst The destination string for the plain text. A \0 is
112  * appended.
113  * @param coded_src The encoded string
114  * @return the length of the plain text string (excluding the trailing \0)
115  */
116 APR_DECLARE(int) apr_base64_decode(char * plain_dst, const char *coded_src)
117  __attribute__((nonnull(1,2)));
118 
119 /**
120  * Decode an string to plain text. This is the same as apr_base64_decode()
121  * except no \0 is appended and on EBCDIC machines, the conversion of the
122  * output to EBCDIC is left out.
123  * @param plain_dst The destination string for the plain text. The string is
124  * not \0-terminated.
125  * @param coded_src The encoded string
126  * @return the length of the plain text string
127  */
128 APR_DECLARE(int) apr_base64_decode_binary(unsigned char * plain_dst,
129  const char *coded_src)
130  __attribute__((nonnull(1,2)));
131 
132 /**
133  * Decode a base64 encoded string into memory allocated from a pool
134  * @param p The pool to allocate from
135  * @param bufcoded The encoded string
136  * @return The decoded string
137  */
138 APR_DECLARE(char *) apr_pbase64_decode(apr_pool_t *p, const char *bufcoded)
139  __attribute__((nonnull(1,2)));
140 
141 /** @} */
142 #ifdef __cplusplus
143 }
144 #endif
145 
146 #endif /* !APR_BASE64_H */
int apr_base64_encode(char *coded_dst, const char *plain_src, int len_plain_src)
int apr_base64_decode_len(const char *coded_src)
int apr_base64_decode_binary(unsigned char *plain_dst, const char *coded_src)
APR Miscellaneous library routines.
char * apr_pbase64_decode(apr_pool_t *p, const char *bufcoded)
char * apr_pbase64_encode(apr_pool_t *p, const char *string)
#define APR_DECLARE(type)
Definition: apr.h:500
int apr_base64_encode_binary(char *coded_dst, const unsigned char *plain_src, int len_plain_src)
int apr_base64_encode_len(int len)
int apr_base64_decode(char *plain_dst, const char *coded_src)
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60