Apache Portable Runtime
apr_escape.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  */
16 /**
17  * @file apr_escape.h
18  * @brief APR-UTIL Escaping
19  */
20 #ifndef APR_ESCAPE_H
21 #define APR_ESCAPE_H
22 #include "apr.h"
23 #include "apr_general.h"
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /**
29  * @defgroup APR_Util_Escaping Escape functions
30  * @ingroup APR
31  * @{
32  */
33 
34 /* Simple escape/unescape functions.
35  *
36  */
37 
38 /**
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
41  * automatically.
42  */
43 #define APR_ESCAPE_STRING (-1)
44 
45 /**
46  * Apply LDAP distinguished name escaping as per RFC4514.
47  */
48 #define APR_ESCAPE_LDAP_DN (0x01)
49 
50 /**
51  * Apply LDAP filter escaping as per RFC4515.
52  */
53 #define APR_ESCAPE_LDAP_FILTER (0x02)
54 
55 /**
56  * Apply both RFC4514 and RFC4515 LDAP escaping.
57  */
58 #define APR_ESCAPE_LDAP_ALL (0x03)
59 
60 /**
61  * Perform shell escaping on the provided string.
62  *
63  * Shell escaping causes characters to be prefixed with a '\' character.
64  * @param escaped Optional buffer to write the encoded string, can be
65  * NULL
66  * @param str The original string
67  * @param slen The length of the original string, or APR_ESCAPE_STRING
68  * @param len If present, returns the length of the string
69  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
70  * detected or the string was NULL
71  */
72 APR_DECLARE(apr_status_t) apr_escape_shell(char *escaped, const char *str,
73  apr_ssize_t slen, apr_size_t *len);
74 
75 /**
76  * Perform shell escaping on the provided string, returning the result
77  * from the pool.
78  *
79  * Shell escaping causes characters to be prefixed with a '\' character.
80  *
81  * If no characters were escaped, the original string is returned.
82  * @param p Pool to allocate from
83  * @param str The original string
84  * @return the encoded string, allocated from the pool, or the original
85  * string if no escaping took place or the string was NULL.
86  */
87 APR_DECLARE(const char *) apr_pescape_shell(apr_pool_t *p, const char *str)
88  __attribute__((nonnull(1)));
89 
90 /**
91  * Unescapes a URL, leaving reserved characters intact.
92  * @param escaped Optional buffer to write the encoded string, can be
93  * NULL
94  * @param url String to be unescaped
95  * @param slen The length of the original url, or APR_ESCAPE_STRING
96  * @param forbid Optional list of forbidden characters, in addition to
97  * 0x00
98  * @param reserved Optional list of reserved characters that will be
99  * left unescaped
100  * @param plus If non zero, '+' is converted to ' ' as per
101  * application/x-www-form-urlencoded encoding
102  * @param len If set, the length of the escaped string will be returned
103  * @return APR_SUCCESS on success, APR_NOTFOUND if no characters are
104  * decoded or the string is NULL, APR_EINVAL if a bad escape sequence is
105  * found, APR_BADCH if a character on the forbid list is found.
106  */
107 APR_DECLARE(apr_status_t) apr_unescape_url(char *escaped, const char *url,
108  apr_ssize_t slen, const char *forbid, const char *reserved, int plus,
109  apr_size_t *len);
110 
111 /**
112  * Unescapes a URL, leaving reserved characters intact, returning the
113  * result from a pool.
114  * @param p Pool to allocate from
115  * @param url String to be unescaped in place
116  * @param forbid Optional list of forbidden characters, in addition to
117  * 0x00
118  * @param reserved Optional list of reserved characters that will be
119  * left unescaped
120  * @param plus If non zero, '+' is converted to ' ' as per
121  * application/x-www-form-urlencoded encoding
122  * @return A string allocated from the pool on success, the original string
123  * if no characters are decoded, or NULL if a bad escape sequence is found
124  * or if a character on the forbid list is found, or if the original string
125  * was NULL.
126  */
127 APR_DECLARE(const char *) apr_punescape_url(apr_pool_t *p, const char *url,
128  const char *forbid, const char *reserved, int plus)
129  __attribute__((nonnull(1)));
130 
131 /**
132  * Escape a path segment, as defined in RFC1808.
133  * @param escaped Optional buffer to write the encoded string, can be
134  * NULL
135  * @param str The original string
136  * @param slen The length of the original string, or APR_ESCAPE_STRING
137  * @param len If present, returns the length of the string
138  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
139  * detected or the string was NULL
140  */
142  const char *str, apr_ssize_t slen, apr_size_t *len);
143 
144 /**
145  * Escape a path segment, as defined in RFC1808, returning the result from a
146  * pool.
147  * @param p Pool to allocate from
148  * @param str String to be escaped
149  * @return A string allocated from the pool on success, the original string
150  * if no characters are encoded or the string is NULL.
151  */
153  const char *str) __attribute__((nonnull(1)));
154 
155 /**
156  * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808.
157  * In all cases if a ':' occurs before the first '/' in the URL, the URL should
158  * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means
159  * leaving '/' alone, but otherwise doing what escape_path_segment() does. For
160  * efficiency reasons, we don't use escape_path_segment(), which is provided for
161  * reference. Again, RFC 1808 is where this stuff is defined.
162  *
163  * If partial is set, os_escape_path() assumes that the path will be appended to
164  * something with a '/' in it (and thus does not prefix "./").
165  * @param escaped Optional buffer to write the encoded string, can be
166  * NULL
167  * @param path The original string
168  * @param slen The length of the original string, or APR_ESCAPE_STRING
169  * @param partial If non zero, suppresses the prepending of "./"
170  * @param len If present, returns the length of the string
171  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
172  * detected or if the string was NULL
173  */
174 APR_DECLARE(apr_status_t) apr_escape_path(char *escaped, const char *path,
175  apr_ssize_t slen, int partial, apr_size_t *len);
176 
177 /**
178  * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808,
179  * returning the result from a pool.
180  *
181  * In all cases if a ':' occurs before the first '/' in the URL, the URL should
182  * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means
183  * leaving '/' alone, but otherwise doing what escape_path_segment() does. For
184  * efficiency reasons, we don't use escape_path_segment(), which is provided for
185  * reference. Again, RFC 1808 is where this stuff is defined.
186  *
187  * If partial is set, os_escape_path() assumes that the path will be appended to
188  * something with a '/' in it (and thus does not prefix "./").
189  * @param p Pool to allocate from
190  * @param str The original string
191  * @param partial If non zero, suppresses the prepending of "./"
192  * @return A string allocated from the pool on success, the original string
193  * if no characters are encoded or if the string was NULL.
194  */
195 APR_DECLARE(const char *) apr_pescape_path(apr_pool_t *p, const char *str,
196  int partial) __attribute__((nonnull(1)));
197 
198 /**
199  * Urlencode a string, as defined in
200  * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1.
201  * @param escaped Optional buffer to write the encoded string, can be
202  * NULL
203  * @param str The original string
204  * @param slen The length of the original string, or APR_ESCAPE_STRING
205  * @param len If present, returns the length of the string
206  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
207  * detected or if the stirng was NULL
208  */
209 APR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str,
210  apr_ssize_t slen, apr_size_t *len);
211 
212 /**
213  * Urlencode a string, as defined in
214  * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1, returning
215  * the result from a pool.
216  * @param p Pool to allocate from
217  * @param str String to be escaped
218  * @return A string allocated from the pool on success, the original string
219  * if no characters are encoded or if the string was NULL.
220  */
222  const char *str) __attribute__((nonnull(1)));
223 
224 /**
225  * Apply entity encoding to a string. Characters are replaced as follows:
226  * '<' becomes '&lt;', '>' becomes '&gt;', '&' becomes '&amp;', the
227  * double quote becomes '&quot;" and the single quote becomes '&apos;'.
228  *
229  * If toasc is not zero, any non ascii character will be encoded as
230  * '%\#ddd;', where ddd is the decimal code of the character.
231  * @param escaped Optional buffer to write the encoded string, can be
232  * NULL
233  * @param str The original string
234  * @param slen The length of the original string, or APR_ESCAPE_STRING
235  * @param toasc If non zero, encode non ascii characters
236  * @param len If present, returns the length of the string
237  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
238  * detected or the string was NULL
239  */
240 APR_DECLARE(apr_status_t) apr_escape_entity(char *escaped, const char *str,
241  apr_ssize_t slen, int toasc, apr_size_t *len);
242 
243 /**
244  * Apply entity encoding to a string, returning the result from a pool.
245  * Characters are replaced as follows: '<' becomes '&lt;', '>' becomes
246  * '&gt;', '&' becomes '&amp;', the double quote becomes '&quot;" and the
247  * single quote becomes '&apos;'.
248  * @param p Pool to allocate from
249  * @param str The original string
250  * @param toasc If non zero, encode non ascii characters
251  * @return A string allocated from the pool on success, the original string
252  * if no characters are encoded or the string is NULL.
253  */
254 APR_DECLARE(const char *) apr_pescape_entity(apr_pool_t *p, const char *str,
255  int toasc) __attribute__((nonnull(1)));
256 
257 /**
258  * Decodes html entities or numeric character references in a string. If
259  * the string to be unescaped is syntactically incorrect, then the
260  * following fixups will be made:
261  * unknown entities will be left undecoded;
262  * references to unused numeric characters will be deleted.
263  * In particular, &#00; will not be decoded, but will be deleted.
264  * @param unescaped Optional buffer to write the encoded string, can be
265  * NULL
266  * @param str The original string
267  * @param slen The length of the original string, or APR_ESCAPE_STRING
268  * @param len If present, returns the length of the string
269  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
270  * detected or the string was NULL
271  */
272 APR_DECLARE(apr_status_t) apr_unescape_entity(char *unescaped, const char *str,
273  apr_ssize_t slen, apr_size_t *len);
274 
275 /**
276  * Decodes html entities or numeric character references in a string. If
277  * the string to be unescaped is syntactically incorrect, then the
278  * following fixups will be made:
279  * unknown entities will be left undecoded;
280  * references to unused numeric characters will be deleted.
281  * In particular, &#00; will not be decoded, but will be deleted.
282  * @param p Pool to allocate from
283  * @param str The original string
284  * @return A string allocated from the pool on success, the original string
285  * if no characters are encoded or the string is NULL.
286  */
287 APR_DECLARE(const char *) apr_punescape_entity(apr_pool_t *p, const char *str)
288  __attribute__((nonnull(1)));
289 
290 /**
291  * Escape control characters in a string, as performed by the shell's
292  * 'echo' command. Characters are replaced as follows:
293  * \\a alert (bell), \\b backspace, \\f form feed, \\n new line, \\r carriage
294  * return, \\t horizontal tab, \\v vertical tab, \\ backslash.
295  *
296  * Any non ascii character will be encoded as '\\xHH', where HH is the hex
297  * code of the character.
298  *
299  * If quote is not zero, the double quote character will also be escaped.
300  * @param escaped Optional buffer to write the encoded string, can be
301  * NULL
302  * @param str The original string
303  * @param slen The length of the original string, or APR_ESCAPE_STRING
304  * @param quote If non zero, encode double quotes
305  * @param len If present, returns the length of the string
306  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
307  * detected or the string was NULL
308  */
309 APR_DECLARE(apr_status_t) apr_escape_echo(char *escaped, const char *str,
310  apr_ssize_t slen, int quote, apr_size_t *len);
311 
312 /**
313  * Escape control characters in a string, as performed by the shell's
314  * 'echo' command, and return the results from a pool. Characters are
315  * replaced as follows: \\a alert (bell), \\b backspace, \\f form feed,
316  * \\n new line, \\r carriage return, \\t horizontal tab, \\v vertical tab,
317  * \\ backslash.
318  *
319  * Any non ascii character will be encoded as '\\xHH', where HH is the hex
320  * code of the character.
321  *
322  * If quote is not zero, the double quote character will also be escaped.
323  * @param p Pool to allocate from
324  * @param str The original string
325  * @param quote If non zero, encode double quotes
326  * @return A string allocated from the pool on success, the original string
327  * if no characters are encoded or the string is NULL.
328  */
329 APR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str,
330  int quote);
331 
332 /**
333  * Convert binary data to a hex encoding.
334  * @param dest The destination buffer, can be NULL
335  * @param src The original buffer
336  * @param srclen The length of the original buffer
337  * @param colon If not zero, insert colon characters between hex digits.
338  * @param len If present, returns the length of the string
339  * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL
340  */
341 APR_DECLARE(apr_status_t) apr_escape_hex(char *dest, const void *src,
342  apr_size_t srclen, int colon, apr_size_t *len);
343 
344 /**
345  * Convert binary data to a hex encoding, and return the results from a
346  * pool.
347  * @param p Pool to allocate from
348  * @param src The original buffer
349  * @param slen The length of the original buffer
350  * @param colon If not zero, insert colon characters between hex digits.
351  * @return A zero padded buffer allocated from the pool on success, or
352  * NULL if src was NULL.
353  */
354 APR_DECLARE(const char *) apr_pescape_hex(apr_pool_t *p, const void *src,
355  apr_size_t slen, int colon) __attribute__((nonnull(1)));
356 
357 /**
358  * Convert hex encoded string to binary data.
359  * @param dest The destination buffer, can be NULL
360  * @param str The original buffer
361  * @param slen The length of the original buffer
362  * @param colon If not zero, ignore colon characters between hex digits.
363  * @param len If present, returns the length of the string
364  * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL, or APR_BADCH
365  * if a non hex character is present.
366  */
367 APR_DECLARE(apr_status_t) apr_unescape_hex(void *dest, const char *str,
368  apr_ssize_t slen, int colon, apr_size_t *len);
369 
370 /**
371  * Convert hex encoding to binary data, and return the results from a pool.
372  * If the colon character appears between pairs of hex digits, it will be
373  * ignored.
374  * @param p Pool to allocate from
375  * @param str The original string
376  * @param colon If not zero, ignore colon characters between hex digits.
377  * @param len If present, returns the length of the final buffer
378  * @return A buffer allocated from the pool on success, or NULL if src was
379  * NULL, or a bad character was present.
380  */
381 APR_DECLARE(const void *) apr_punescape_hex(apr_pool_t *p, const char *str,
382  int colon, apr_size_t *len);
383 
384 /**
385  * Apply LDAP escaping to binary data. Characters from RFC4514 and RFC4515
386  * are escaped with their hex equivalents.
387  * @param dest The destination buffer, can be NULL
388  * @param src The original buffer
389  * @param srclen The length of the original buffer
390  * @param flags APR_ESCAPE_LDAP_DN for RFC4514, APR_ESCAPE_LDAP_FILTER for
391  * RFC4515, APR_ESCAPE_LDAP_ALL for both
392  * @param len If present, returns the length of the string
393  * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL
394  */
395 APR_DECLARE(apr_status_t) apr_escape_ldap(char *dest, const void *src,
396  apr_ssize_t srclen, int flags, apr_size_t *len);
397 
398 /**
399  * Apply LDAP escaping to binary data, and return the results from a
400  * pool. Characters from RFC4514 and RFC4515 are escaped with their hex
401  * equivalents.
402  * @param p Pool to allocate from
403  * @param src The original buffer
404  * @param slen The length of the original buffer
405  * @param flags APR_ESCAPE_LDAP_DN for RFC4514, APR_ESCAPE_LDAP_FILTER for
406  * RFC4515, APR_ESCAPE_LDAP_ALL for both
407  * @return A zero padded buffer allocated from the pool on success, or
408  * NULL if src was NULL.
409  */
410 APR_DECLARE(const char *) apr_pescape_ldap(apr_pool_t *p, const void *src,
411  apr_ssize_t slen, int flags) __attribute__((nonnull(1)));
412 
413 /** @} */
414 #ifdef __cplusplus
415 }
416 #endif
417 
418 #endif /* !APR_ESCAPE_H */
apr_status_t apr_escape_urlencoded(char *escaped, const char *str, apr_ssize_t slen, apr_size_t *len)
const char * apr_pescape_shell(apr_pool_t *p, const char *str)
apr_status_t apr_escape_entity(char *escaped, const char *str, apr_ssize_t slen, int toasc, apr_size_t *len)
apr_status_t apr_unescape_entity(char *unescaped, const char *str, apr_ssize_t slen, apr_size_t *len)
const char * apr_pescape_path(apr_pool_t *p, const char *str, int partial)
const char * apr_pescape_entity(apr_pool_t *p, const char *str, int toasc)
const void * apr_punescape_hex(apr_pool_t *p, const char *str, int colon, apr_size_t *len)
const char * apr_punescape_url(apr_pool_t *p, const char *url, const char *forbid, const char *reserved, int plus)
apr_status_t apr_escape_ldap(char *dest, const void *src, apr_ssize_t srclen, int flags, apr_size_t *len)
const char * apr_pescape_urlencoded(apr_pool_t *p, const char *str)
APR Miscellaneous library routines.
const char * apr_pescape_hex(apr_pool_t *p, const void *src, apr_size_t slen, int colon)
apr_status_t apr_escape_path(char *escaped, const char *path, apr_ssize_t slen, int partial, apr_size_t *len)
apr_status_t apr_escape_hex(char *dest, const void *src, apr_size_t srclen, int colon, apr_size_t *len)
const char * apr_pescape_echo(apr_pool_t *p, const char *str, int quote)
apr_status_t apr_unescape_hex(void *dest, const char *str, apr_ssize_t slen, int colon, apr_size_t *len)
#define APR_DECLARE(type)
Definition: apr.h:480
APR Platform Definitions.
const char * apr_punescape_entity(apr_pool_t *p, const char *str)
apr_status_t apr_unescape_url(char *escaped, const char *url, apr_ssize_t slen, const char *forbid, const char *reserved, int plus, apr_size_t *len)
const char * apr_pescape_path_segment(apr_pool_t *p, const char *str)
const char * apr_pescape_ldap(apr_pool_t *p, const void *src, apr_ssize_t slen, int flags)
apr_status_t apr_escape_shell(char *escaped, const char *str, apr_ssize_t slen, apr_size_t *len)
apr_status_t apr_escape_echo(char *escaped, const char *str, apr_ssize_t slen, int quote, apr_size_t *len)
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
apr_status_t apr_escape_path_segment(char *escaped, const char *str, apr_ssize_t slen, apr_size_t *len)
int apr_status_t
Definition: apr_errno.h:44