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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @brief APR-UTIL Escaping
23 #include "apr_general.h"
29 * @defgroup APR_Util_Escaping Escape functions
34 /* Simple escape/unescape functions.
39 * When passing a string to one of the escape functions, this value can be
40 * passed to indicate a string-valued key, and have the length computed
43 #define APR_ESCAPE_STRING (-1)
46 * Perform shell escaping on the provided string.
48 * Shell escaping causes characters to be prefixed with a '\' character.
49 * @param escaped Optional buffer to write the encoded string, can be
51 * @param str The original string
52 * @param slen The length of the original string, or APR_ESCAPE_STRING
53 * @param len If present, returns the length of the string
54 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
55 * detected or the string was NULL
57 APR_DECLARE(apr_status_t) apr_escape_shell(char *escaped, const char *str,
58 apr_ssize_t slen, apr_size_t *len);
61 * Perform shell escaping on the provided string, returning the result
64 * Shell escaping causes characters to be prefixed with a '\' character.
66 * If no characters were escaped, the original string is returned.
67 * @param p Pool to allocate from
68 * @param str The original string
69 * @return the encoded string, allocated from the pool, or the original
70 * string if no escaping took place or the string was NULL.
72 APR_DECLARE(const char *) apr_pescape_shell(apr_pool_t *p, const char *str)
73 __attribute__((nonnull(1)));
76 * Unescapes a URL, leaving reserved characters intact.
77 * @param escaped Optional buffer to write the encoded string, can be
79 * @param url String to be unescaped
80 * @param slen The length of the original url, or APR_ESCAPE_STRING
81 * @param forbid Optional list of forbidden characters, in addition to
83 * @param reserved Optional list of reserved characters that will be
85 * @param plus If non zero, '+' is converted to ' ' as per
86 * application/x-www-form-urlencoded encoding
87 * @param len If set, the length of the escaped string will be returned
88 * @return APR_SUCCESS on success, APR_NOTFOUND if no characters are
89 * decoded or the string is NULL, APR_EINVAL if a bad escape sequence is
90 * found, APR_BADCH if a character on the forbid list is found.
92 APR_DECLARE(apr_status_t) apr_unescape_url(char *escaped, const char *url,
93 apr_ssize_t slen, const char *forbid, const char *reserved, int plus,
97 * Unescapes a URL, leaving reserved characters intact, returning the
99 * @param p Pool to allocate from
100 * @param url String to be unescaped in place
101 * @param forbid Optional list of forbidden characters, in addition to
103 * @param reserved Optional list of reserved characters that will be
105 * @param plus If non zero, '+' is converted to ' ' as per
106 * application/x-www-form-urlencoded encoding
107 * @return A string allocated from the pool on success, the original string
108 * if no characters are decoded, or NULL if a bad escape sequence is found
109 * or if a character on the forbid list is found, or if the original string
112 APR_DECLARE(const char *) apr_punescape_url(apr_pool_t *p, const char *url,
113 const char *forbid, const char *reserved, int plus)
114 __attribute__((nonnull(1)));
117 * Escape a path segment, as defined in RFC1808.
118 * @param escaped Optional buffer to write the encoded string, can be
120 * @param str The original string
121 * @param slen The length of the original string, or APR_ESCAPE_STRING
122 * @param len If present, returns the length of the string
123 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
124 * detected or the string was NULL
126 APR_DECLARE(apr_status_t) apr_escape_path_segment(char *escaped,
127 const char *str, apr_ssize_t slen, apr_size_t *len);
130 * Escape a path segment, as defined in RFC1808, returning the result from a
132 * @param p Pool to allocate from
133 * @param str String to be escaped
134 * @return A string allocated from the pool on success, the original string
135 * if no characters are encoded or the string is NULL.
137 APR_DECLARE(const char *) apr_pescape_path_segment(apr_pool_t *p,
138 const char *str) __attribute__((nonnull(1)));
141 * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808.
142 * In all cases if a ':' occurs before the first '/' in the URL, the URL should
143 * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means
144 * leaving '/' alone, but otherwise doing what escape_path_segment() does. For
145 * efficiency reasons, we don't use escape_path_segment(), which is provided for
146 * reference. Again, RFC 1808 is where this stuff is defined.
148 * If partial is set, os_escape_path() assumes that the path will be appended to
149 * something with a '/' in it (and thus does not prefix "./").
150 * @param escaped Optional buffer to write the encoded string, can be
152 * @param path The original string
153 * @param slen The length of the original string, or APR_ESCAPE_STRING
154 * @param partial If non zero, suppresses the prepending of "./"
155 * @param len If present, returns the length of the string
156 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
157 * detected or if the string was NULL
159 APR_DECLARE(apr_status_t) apr_escape_path(char *escaped, const char *path,
160 apr_ssize_t slen, int partial, apr_size_t *len);
163 * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808,
164 * returning the result from a pool.
166 * In all cases if a ':' occurs before the first '/' in the URL, the URL should
167 * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means
168 * leaving '/' alone, but otherwise doing what escape_path_segment() does. For
169 * efficiency reasons, we don't use escape_path_segment(), which is provided for
170 * reference. Again, RFC 1808 is where this stuff is defined.
172 * If partial is set, os_escape_path() assumes that the path will be appended to
173 * something with a '/' in it (and thus does not prefix "./").
174 * @param p Pool to allocate from
175 * @param str The original string
176 * @param partial If non zero, suppresses the prepending of "./"
177 * @return A string allocated from the pool on success, the original string
178 * if no characters are encoded or if the string was NULL.
180 APR_DECLARE(const char *) apr_pescape_path(apr_pool_t *p, const char *str,
181 int partial) __attribute__((nonnull(1)));
184 * Urlencode a string, as defined in
185 * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1.
186 * @param escaped Optional buffer to write the encoded string, can be
188 * @param str The original string
189 * @param slen The length of the original string, or APR_ESCAPE_STRING
190 * @param len If present, returns the length of the string
191 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
192 * detected or if the stirng was NULL
194 APR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str,
195 apr_ssize_t slen, apr_size_t *len);
198 * Urlencode a string, as defined in
199 * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1, returning
200 * the result from a pool.
201 * @param p Pool to allocate from
202 * @param str String to be escaped
203 * @return A string allocated from the pool on success, the original string
204 * if no characters are encoded or if the string was NULL.
206 APR_DECLARE(const char *) apr_pescape_urlencoded(apr_pool_t *p,
207 const char *str) __attribute__((nonnull(1)));
210 * Apply entity encoding to a string. Characters are replaced as follows:
211 * '<' becomes '<', '>' becomes '>', '&' becomes '&', the
212 * double quote becomes '"" and the single quote becomes '''.
214 * If toasc is not zero, any non ascii character will be encoded as
215 * '%\#ddd;', where ddd is the decimal code of the character.
216 * @param escaped Optional buffer to write the encoded string, can be
218 * @param str The original string
219 * @param slen The length of the original string, or APR_ESCAPE_STRING
220 * @param toasc If non zero, encode non ascii characters
221 * @param len If present, returns the length of the string
222 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
223 * detected or the string was NULL
225 APR_DECLARE(apr_status_t) apr_escape_entity(char *escaped, const char *str,
226 apr_ssize_t slen, int toasc, apr_size_t *len);
229 * Apply entity encoding to a string, returning the result from a pool.
230 * Characters are replaced as follows: '<' becomes '<', '>' becomes
231 * '>', '&' becomes '&', the double quote becomes '"" and the
232 * single quote becomes '''.
233 * @param p Pool to allocate from
234 * @param str The original string
235 * @param toasc If non zero, encode non ascii characters
236 * @return A string allocated from the pool on success, the original string
237 * if no characters are encoded or the string is NULL.
239 APR_DECLARE(const char *) apr_pescape_entity(apr_pool_t *p, const char *str,
240 int toasc) __attribute__((nonnull(1)));
243 * Decodes html entities or numeric character references in a string. If
244 * the string to be unescaped is syntactically incorrect, then the
245 * following fixups will be made:
246 * unknown entities will be left undecoded;
247 * references to unused numeric characters will be deleted.
248 * In particular, � will not be decoded, but will be deleted.
249 * @param unescaped Optional buffer to write the encoded string, can be
251 * @param str The original string
252 * @param slen The length of the original string, or APR_ESCAPE_STRING
253 * @param len If present, returns the length of the string
254 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
255 * detected or the string was NULL
257 APR_DECLARE(apr_status_t) apr_unescape_entity(char *unescaped, const char *str,
258 apr_ssize_t slen, apr_size_t *len);
261 * Decodes html entities or numeric character references in a string. If
262 * the string to be unescaped is syntactically incorrect, then the
263 * following fixups will be made:
264 * unknown entities will be left undecoded;
265 * references to unused numeric characters will be deleted.
266 * In particular, � will not be decoded, but will be deleted.
267 * @param p Pool to allocate from
268 * @param str The original string
269 * @return A string allocated from the pool on success, the original string
270 * if no characters are encoded or the string is NULL.
272 APR_DECLARE(const char *) apr_punescape_entity(apr_pool_t *p, const char *str)
273 __attribute__((nonnull(1)));
276 * Escape control characters in a string, as performed by the shell's
277 * 'echo' command. Characters are replaced as follows:
278 * \\a alert (bell), \\b backspace, \\f form feed, \\n new line, \\r carriage
279 * return, \\t horizontal tab, \\v vertical tab, \\ backslash.
281 * Any non ascii character will be encoded as '\\xHH', where HH is the hex
282 * code of the character.
284 * If quote is not zero, the double quote character will also be escaped.
285 * @param escaped Optional buffer to write the encoded string, can be
287 * @param str The original string
288 * @param slen The length of the original string, or APR_ESCAPE_STRING
289 * @param quote If non zero, encode double quotes
290 * @param len If present, returns the length of the string
291 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
292 * detected or the string was NULL
294 APR_DECLARE(apr_status_t) apr_escape_echo(char *escaped, const char *str,
295 apr_ssize_t slen, int quote, apr_size_t *len);
298 * Escape control characters in a string, as performed by the shell's
299 * 'echo' command, and return the results from a pool. Characters are
300 * replaced as follows: \\a alert (bell), \\b backspace, \\f form feed,
301 * \\n new line, \\r carriage return, \\t horizontal tab, \\v vertical tab,
304 * Any non ascii character will be encoded as '\\xHH', where HH is the hex
305 * code of the character.
307 * If quote is not zero, the double quote character will also be escaped.
308 * @param p Pool to allocate from
309 * @param str The original string
310 * @param quote If non zero, encode double quotes
311 * @return A string allocated from the pool on success, the original string
312 * if no characters are encoded or the string is NULL.
314 APR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str,
318 * Convert binary data to a hex encoding.
319 * @param dest The destination buffer, can be NULL
320 * @param src The original buffer
321 * @param srclen The length of the original buffer
322 * @param colon If not zero, insert colon characters between hex digits.
323 * @param len If present, returns the length of the string
324 * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL
326 APR_DECLARE(apr_status_t) apr_escape_hex(char *dest, const void *src,
327 apr_size_t srclen, int colon, apr_size_t *len);
330 * Convert binary data to a hex encoding, and return the results from a
332 * @param p Pool to allocate from
333 * @param src The original buffer
334 * @param slen The length of the original buffer
335 * @param colon If not zero, insert colon characters between hex digits.
336 * @return A zero padded buffer allocated from the pool on success, or
337 * NULL if src was NULL.
339 APR_DECLARE(const char *) apr_pescape_hex(apr_pool_t *p, const void *src,
340 apr_size_t slen, int colon) __attribute__((nonnull(1)));
343 * Convert hex encoded string to binary data.
344 * @param dest The destination buffer, can be NULL
345 * @param str The original buffer
346 * @param slen The length of the original buffer
347 * @param colon If not zero, ignore colon characters between hex digits.
348 * @param len If present, returns the length of the string
349 * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL, or APR_BADCH
350 * if a non hex character is present.
352 APR_DECLARE(apr_status_t) apr_unescape_hex(void *dest, const char *str,
353 apr_ssize_t slen, int colon, apr_size_t *len);
356 * Convert hex encoding to binary data, and return the results from a pool.
357 * If the colon character appears between pairs of hex digits, it will be
359 * @param p Pool to allocate from
360 * @param str The original string
361 * @param colon If not zero, ignore colon characters between hex digits.
362 * @param len If present, returns the length of the final buffer
363 * @return A buffer allocated from the pool on success, or NULL if src was
364 * NULL, or a bad character was present.
366 APR_DECLARE(const void *) apr_punescape_hex(apr_pool_t *p, const char *str,
367 int colon, apr_size_t *len);
374 #endif /* !APR_ESCAPE_H */