apr_escape.h
Go to the documentation of this file.00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 /** 00017 * @file apr_escape.h 00018 * @brief APR-UTIL Escaping 00019 */ 00020 #ifndef APR_ESCAPE_H 00021 #define APR_ESCAPE_H 00022 #include "apr.h" 00023 #include "apr_general.h" 00024 #ifdef __cplusplus 00025 extern "C" { 00026 #endif 00027 00028 /** 00029 * @defgroup APR_Util_Escaping Escape functions 00030 * @ingroup APR 00031 * @{ 00032 */ 00033 00034 /* Simple escape/unescape functions. 00035 * 00036 */ 00037 00038 /** 00039 * When passing a string to one of the escape functions, this value can be 00040 * passed to indicate a string-valued key, and have the length computed 00041 * automatically. 00042 */ 00043 #define APR_ESCAPE_STRING (-1) 00044 00045 /** 00046 * Perform shell escaping on the provided string. 00047 * 00048 * Shell escaping causes characters to be prefixed with a '\' character. 00049 * @param escaped Optional buffer to write the encoded string, can be 00050 * NULL 00051 * @param str The original string 00052 * @param slen The length of the original string, or APR_ESCAPE_STRING 00053 * @param len If present, returns the length of the string 00054 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00055 * detected or the string was NULL 00056 */ 00057 APR_DECLARE(apr_status_t) apr_escape_shell(char *escaped, const char *str, 00058 apr_ssize_t slen, apr_size_t *len); 00059 00060 /** 00061 * Perform shell escaping on the provided string, returning the result 00062 * from the pool. 00063 * 00064 * Shell escaping causes characters to be prefixed with a '\' character. 00065 * 00066 * If no characters were escaped, the original string is returned. 00067 * @param p Pool to allocate from 00068 * @param str The original string 00069 * @return the encoded string, allocated from the pool, or the original 00070 * string if no escaping took place or the string was NULL. 00071 */ 00072 APR_DECLARE(const char *) apr_pescape_shell(apr_pool_t *p, const char *str) 00073 __attribute__((nonnull(1))); 00074 00075 /** 00076 * Unescapes a URL, leaving reserved characters intact. 00077 * @param escaped Optional buffer to write the encoded string, can be 00078 * NULL 00079 * @param url String to be unescaped 00080 * @param slen The length of the original url, or APR_ESCAPE_STRING 00081 * @param forbid Optional list of forbidden characters, in addition to 00082 * 0x00 00083 * @param reserved Optional list of reserved characters that will be 00084 * left unescaped 00085 * @param plus If non zero, '+' is converted to ' ' as per 00086 * application/x-www-form-urlencoded encoding 00087 * @param len If set, the length of the escaped string will be returned 00088 * @return APR_SUCCESS on success, APR_NOTFOUND if no characters are 00089 * decoded or the string is NULL, APR_EINVAL if a bad escape sequence is 00090 * found, APR_BADCH if a character on the forbid list is found. 00091 */ 00092 APR_DECLARE(apr_status_t) apr_unescape_url(char *escaped, const char *url, 00093 apr_ssize_t slen, const char *forbid, const char *reserved, int plus, 00094 apr_size_t *len); 00095 00096 /** 00097 * Unescapes a URL, leaving reserved characters intact, returning the 00098 * result from a pool. 00099 * @param p Pool to allocate from 00100 * @param url String to be unescaped in place 00101 * @param forbid Optional list of forbidden characters, in addition to 00102 * 0x00 00103 * @param reserved Optional list of reserved characters that will be 00104 * left unescaped 00105 * @param plus If non zero, '+' is converted to ' ' as per 00106 * application/x-www-form-urlencoded encoding 00107 * @return A string allocated from the pool on success, the original string 00108 * if no characters are decoded, or NULL if a bad escape sequence is found 00109 * or if a character on the forbid list is found, or if the original string 00110 * was NULL. 00111 */ 00112 APR_DECLARE(const char *) apr_punescape_url(apr_pool_t *p, const char *url, 00113 const char *forbid, const char *reserved, int plus) 00114 __attribute__((nonnull(1))); 00115 00116 /** 00117 * Escape a path segment, as defined in RFC1808. 00118 * @param escaped Optional buffer to write the encoded string, can be 00119 * NULL 00120 * @param str The original string 00121 * @param slen The length of the original string, or APR_ESCAPE_STRING 00122 * @param len If present, returns the length of the string 00123 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00124 * detected or the string was NULL 00125 */ 00126 APR_DECLARE(apr_status_t) apr_escape_path_segment(char *escaped, 00127 const char *str, apr_ssize_t slen, apr_size_t *len); 00128 00129 /** 00130 * Escape a path segment, as defined in RFC1808, returning the result from a 00131 * pool. 00132 * @param p Pool to allocate from 00133 * @param str String to be escaped 00134 * @return A string allocated from the pool on success, the original string 00135 * if no characters are encoded or the string is NULL. 00136 */ 00137 APR_DECLARE(const char *) apr_pescape_path_segment(apr_pool_t *p, 00138 const char *str) __attribute__((nonnull(1))); 00139 00140 /** 00141 * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808. 00142 * In all cases if a ':' occurs before the first '/' in the URL, the URL should 00143 * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means 00144 * leaving '/' alone, but otherwise doing what escape_path_segment() does. For 00145 * efficiency reasons, we don't use escape_path_segment(), which is provided for 00146 * reference. Again, RFC 1808 is where this stuff is defined. 00147 * 00148 * If partial is set, os_escape_path() assumes that the path will be appended to 00149 * something with a '/' in it (and thus does not prefix "./"). 00150 * @param escaped Optional buffer to write the encoded string, can be 00151 * NULL 00152 * @param path The original string 00153 * @param slen The length of the original string, or APR_ESCAPE_STRING 00154 * @param partial If non zero, suppresses the prepending of "./" 00155 * @param len If present, returns the length of the string 00156 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00157 * detected or if the string was NULL 00158 */ 00159 APR_DECLARE(apr_status_t) apr_escape_path(char *escaped, const char *path, 00160 apr_ssize_t slen, int partial, apr_size_t *len); 00161 00162 /** 00163 * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808, 00164 * returning the result from a pool. 00165 * 00166 * In all cases if a ':' occurs before the first '/' in the URL, the URL should 00167 * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means 00168 * leaving '/' alone, but otherwise doing what escape_path_segment() does. For 00169 * efficiency reasons, we don't use escape_path_segment(), which is provided for 00170 * reference. Again, RFC 1808 is where this stuff is defined. 00171 * 00172 * If partial is set, os_escape_path() assumes that the path will be appended to 00173 * something with a '/' in it (and thus does not prefix "./"). 00174 * @param p Pool to allocate from 00175 * @param str The original string 00176 * @param partial If non zero, suppresses the prepending of "./" 00177 * @return A string allocated from the pool on success, the original string 00178 * if no characters are encoded or if the string was NULL. 00179 */ 00180 APR_DECLARE(const char *) apr_pescape_path(apr_pool_t *p, const char *str, 00181 int partial) __attribute__((nonnull(1))); 00182 00183 /** 00184 * Urlencode a string, as defined in 00185 * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1. 00186 * @param escaped Optional buffer to write the encoded string, can be 00187 * NULL 00188 * @param str The original string 00189 * @param slen The length of the original string, or APR_ESCAPE_STRING 00190 * @param len If present, returns the length of the string 00191 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00192 * detected or if the stirng was NULL 00193 */ 00194 APR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str, 00195 apr_ssize_t slen, apr_size_t *len); 00196 00197 /** 00198 * Urlencode a string, as defined in 00199 * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1, returning 00200 * the result from a pool. 00201 * @param p Pool to allocate from 00202 * @param str String to be escaped 00203 * @return A string allocated from the pool on success, the original string 00204 * if no characters are encoded or if the string was NULL. 00205 */ 00206 APR_DECLARE(const char *) apr_pescape_urlencoded(apr_pool_t *p, 00207 const char *str) __attribute__((nonnull(1))); 00208 00209 /** 00210 * Apply entity encoding to a string. Characters are replaced as follows: 00211 * '<' becomes '<', '>' becomes '>', '&' becomes '&', the 00212 * double quote becomes '"" and the single quote becomes '''. 00213 * 00214 * If toasc is not zero, any non ascii character will be encoded as 00215 * '%\#ddd;', where ddd is the decimal code of the character. 00216 * @param escaped Optional buffer to write the encoded string, can be 00217 * NULL 00218 * @param str The original string 00219 * @param slen The length of the original string, or APR_ESCAPE_STRING 00220 * @param toasc If non zero, encode non ascii characters 00221 * @param len If present, returns the length of the string 00222 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00223 * detected or the string was NULL 00224 */ 00225 APR_DECLARE(apr_status_t) apr_escape_entity(char *escaped, const char *str, 00226 apr_ssize_t slen, int toasc, apr_size_t *len); 00227 00228 /** 00229 * Apply entity encoding to a string, returning the result from a pool. 00230 * Characters are replaced as follows: '<' becomes '<', '>' becomes 00231 * '>', '&' becomes '&', the double quote becomes '"" and the 00232 * single quote becomes '''. 00233 * @param p Pool to allocate from 00234 * @param str The original string 00235 * @param toasc If non zero, encode non ascii characters 00236 * @return A string allocated from the pool on success, the original string 00237 * if no characters are encoded or the string is NULL. 00238 */ 00239 APR_DECLARE(const char *) apr_pescape_entity(apr_pool_t *p, const char *str, 00240 int toasc) __attribute__((nonnull(1))); 00241 00242 /** 00243 * Decodes html entities or numeric character references in a string. If 00244 * the string to be unescaped is syntactically incorrect, then the 00245 * following fixups will be made: 00246 * unknown entities will be left undecoded; 00247 * references to unused numeric characters will be deleted. 00248 * In particular, � will not be decoded, but will be deleted. 00249 * @param unescaped Optional buffer to write the encoded string, can be 00250 * NULL 00251 * @param str The original string 00252 * @param slen The length of the original string, or APR_ESCAPE_STRING 00253 * @param len If present, returns the length of the string 00254 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00255 * detected or the string was NULL 00256 */ 00257 APR_DECLARE(apr_status_t) apr_unescape_entity(char *unescaped, const char *str, 00258 apr_ssize_t slen, apr_size_t *len); 00259 00260 /** 00261 * Decodes html entities or numeric character references in a string. If 00262 * the string to be unescaped is syntactically incorrect, then the 00263 * following fixups will be made: 00264 * unknown entities will be left undecoded; 00265 * references to unused numeric characters will be deleted. 00266 * In particular, � will not be decoded, but will be deleted. 00267 * @param p Pool to allocate from 00268 * @param str The original string 00269 * @return A string allocated from the pool on success, the original string 00270 * if no characters are encoded or the string is NULL. 00271 */ 00272 APR_DECLARE(const char *) apr_punescape_entity(apr_pool_t *p, const char *str) 00273 __attribute__((nonnull(1))); 00274 00275 /** 00276 * Escape control characters in a string, as performed by the shell's 00277 * 'echo' command. Characters are replaced as follows: 00278 * \\a alert (bell), \\b backspace, \\f form feed, \\n new line, \\r carriage 00279 * return, \\t horizontal tab, \\v vertical tab, \\ backslash. 00280 * 00281 * Any non ascii character will be encoded as '\\xHH', where HH is the hex 00282 * code of the character. 00283 * 00284 * If quote is not zero, the double quote character will also be escaped. 00285 * @param escaped Optional buffer to write the encoded string, can be 00286 * NULL 00287 * @param str The original string 00288 * @param slen The length of the original string, or APR_ESCAPE_STRING 00289 * @param quote If non zero, encode double quotes 00290 * @param len If present, returns the length of the string 00291 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00292 * detected or the string was NULL 00293 */ 00294 APR_DECLARE(apr_status_t) apr_escape_echo(char *escaped, const char *str, 00295 apr_ssize_t slen, int quote, apr_size_t *len); 00296 00297 /** 00298 * Escape control characters in a string, as performed by the shell's 00299 * 'echo' command, and return the results from a pool. Characters are 00300 * replaced as follows: \\a alert (bell), \\b backspace, \\f form feed, 00301 * \\n new line, \\r carriage return, \\t horizontal tab, \\v vertical tab, 00302 * \\ backslash. 00303 * 00304 * Any non ascii character will be encoded as '\\xHH', where HH is the hex 00305 * code of the character. 00306 * 00307 * If quote is not zero, the double quote character will also be escaped. 00308 * @param p Pool to allocate from 00309 * @param str The original string 00310 * @param quote If non zero, encode double quotes 00311 * @return A string allocated from the pool on success, the original string 00312 * if no characters are encoded or the string is NULL. 00313 */ 00314 APR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str, 00315 int quote); 00316 00317 /** 00318 * Convert binary data to a hex encoding. 00319 * @param dest The destination buffer, can be NULL 00320 * @param src The original buffer 00321 * @param srclen The length of the original buffer 00322 * @param colon If not zero, insert colon characters between hex digits. 00323 * @param len If present, returns the length of the string 00324 * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL 00325 */ 00326 APR_DECLARE(apr_status_t) apr_escape_hex(char *dest, const void *src, 00327 apr_size_t srclen, int colon, apr_size_t *len); 00328 00329 /** 00330 * Convert binary data to a hex encoding, and return the results from a 00331 * pool. 00332 * @param p Pool to allocate from 00333 * @param src The original buffer 00334 * @param slen The length of the original buffer 00335 * @param colon If not zero, insert colon characters between hex digits. 00336 * @return A zero padded buffer allocated from the pool on success, or 00337 * NULL if src was NULL. 00338 */ 00339 APR_DECLARE(const char *) apr_pescape_hex(apr_pool_t *p, const void *src, 00340 apr_size_t slen, int colon) __attribute__((nonnull(1))); 00341 00342 /** 00343 * Convert hex encoded string to binary data. 00344 * @param dest The destination buffer, can be NULL 00345 * @param str The original buffer 00346 * @param slen The length of the original buffer 00347 * @param colon If not zero, ignore colon characters between hex digits. 00348 * @param len If present, returns the length of the string 00349 * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL, or APR_BADCH 00350 * if a non hex character is present. 00351 */ 00352 APR_DECLARE(apr_status_t) apr_unescape_hex(void *dest, const char *str, 00353 apr_ssize_t slen, int colon, apr_size_t *len); 00354 00355 /** 00356 * Convert hex encoding to binary data, and return the results from a pool. 00357 * If the colon character appears between pairs of hex digits, it will be 00358 * ignored. 00359 * @param p Pool to allocate from 00360 * @param str The original string 00361 * @param colon If not zero, ignore colon characters between hex digits. 00362 * @param len If present, returns the length of the final buffer 00363 * @return A buffer allocated from the pool on success, or NULL if src was 00364 * NULL, or a bad character was present. 00365 */ 00366 APR_DECLARE(const void *) apr_punescape_hex(apr_pool_t *p, const char *str, 00367 int colon, apr_size_t *len); 00368 00369 /** @} */ 00370 #ifdef __cplusplus 00371 } 00372 #endif 00373 00374 #endif /* !APR_ESCAPE_H */
