Apache Portable Runtime
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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  * Perform shell escaping on the provided string.
47  *
48  * Shell escaping causes characters to be prefixed with a '\' character.
49  * @param escaped Optional buffer to write the encoded string, can be
50  * NULL
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
56  */
57 APR_DECLARE(apr_status_t) apr_escape_shell(char *escaped, const char *str,
58  apr_ssize_t slen, apr_size_t *len);
59 
60 /**
61  * Perform shell escaping on the provided string, returning the result
62  * from the pool.
63  *
64  * Shell escaping causes characters to be prefixed with a '\' character.
65  *
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.
71  */
72 APR_DECLARE(const char *) apr_pescape_shell(apr_pool_t *p, const char *str)
73  __attribute__((nonnull(1)));
74 
75 /**
76  * Unescapes a URL, leaving reserved characters intact.
77  * @param escaped Optional buffer to write the encoded string, can be
78  * NULL
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
82  * 0x00
83  * @param reserved Optional list of reserved characters that will be
84  * left unescaped
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.
91  */
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,
94  apr_size_t *len);
95 
96 /**
97  * Unescapes a URL, leaving reserved characters intact, returning the
98  * result from a pool.
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
102  * 0x00
103  * @param reserved Optional list of reserved characters that will be
104  * left unescaped
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
110  * was NULL.
111  */
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)));
115 
116 /**
117  * Escape a path segment, as defined in RFC1808.
118  * @param escaped Optional buffer to write the encoded string, can be
119  * NULL
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
125  */
127  const char *str, apr_ssize_t slen, apr_size_t *len);
128 
129 /**
130  * Escape a path segment, as defined in RFC1808, returning the result from a
131  * pool.
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.
136  */
138  const char *str) __attribute__((nonnull(1)));
139 
140 /**
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.
147  *
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
151  * NULL
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
158  */
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);
161 
162 /**
163  * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808,
164  * returning the result from a pool.
165  *
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.
171  *
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.
179  */
180 APR_DECLARE(const char *) apr_pescape_path(apr_pool_t *p, const char *str,
181  int partial) __attribute__((nonnull(1)));
182 
183 /**
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
187  * NULL
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
193  */
194 APR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str,
195  apr_ssize_t slen, apr_size_t *len);
196 
197 /**
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.
205  */
207  const char *str) __attribute__((nonnull(1)));
208 
209 /**
210  * Apply entity encoding to a string. Characters are replaced as follows:
211  * '<' becomes '&lt;', '>' becomes '&gt;', '&' becomes '&amp;', the
212  * double quote becomes '&quot;" and the single quote becomes '&apos;'.
213  *
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
217  * NULL
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
224  */
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);
227 
228 /**
229  * Apply entity encoding to a string, returning the result from a pool.
230  * Characters are replaced as follows: '<' becomes '&lt;', '>' becomes
231  * '&gt;', '&' becomes '&amp;', the double quote becomes '&quot;" and the
232  * single quote becomes '&apos;'.
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.
238  */
239 APR_DECLARE(const char *) apr_pescape_entity(apr_pool_t *p, const char *str,
240  int toasc) __attribute__((nonnull(1)));
241 
242 /**
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, &#00; will not be decoded, but will be deleted.
249  * @param unescaped Optional buffer to write the encoded string, can be
250  * NULL
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
256  */
257 APR_DECLARE(apr_status_t) apr_unescape_entity(char *unescaped, const char *str,
258  apr_ssize_t slen, apr_size_t *len);
259 
260 /**
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, &#00; 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.
271  */
272 APR_DECLARE(const char *) apr_punescape_entity(apr_pool_t *p, const char *str)
273  __attribute__((nonnull(1)));
274 
275 /**
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.
280  *
281  * Any non ascii character will be encoded as '\\xHH', where HH is the hex
282  * code of the character.
283  *
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
286  * NULL
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
293  */
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);
296 
297 /**
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,
302  * \\ backslash.
303  *
304  * Any non ascii character will be encoded as '\\xHH', where HH is the hex
305  * code of the character.
306  *
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.
313  */
314 APR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str,
315  int quote);
316 
317 /**
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
325  */
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);
328 
329 /**
330  * Convert binary data to a hex encoding, and return the results from a
331  * pool.
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.
338  */
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)));
341 
342 /**
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.
351  */
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);
354 
355 /**
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
358  * ignored.
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.
365  */
366 APR_DECLARE(const void *) apr_punescape_hex(apr_pool_t *p, const char *str,
367  int colon, apr_size_t *len);
368 
369 /** @} */
370 #ifdef __cplusplus
371 }
372 #endif
373 
374 #endif /* !APR_ESCAPE_H */