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 * The design goal of these functions are: 00037 * 00038 * - Avoid unnecessary work. 00039 * 00040 * In most cases the strings passed in do not need to be escaped at all. In 00041 * these cases the original string will be returned. 00042 * 00043 * - Lowest possible memory footprint. 00044 * 00045 * The amount of memory allocated for a given encoding is calculated based 00046 * on the exact amount of memory needed, and not the theoretical worst case 00047 * scenario. 00048 * 00049 */ 00050 00051 /** 00052 * When passing a string to one of the escape functions, this value can be 00053 * passed to indicate a string-valued key, and have the length computed 00054 * automatically. 00055 */ 00056 #define APR_ESCAPE_STRING (-1) 00057 00058 /** 00059 * Apply LDAP distinguished name escaping as per RFC4514. 00060 */ 00061 #define APR_ESCAPE_LDAP_DN (0x01) 00062 00063 /** 00064 * Apply LDAP filter escaping as per RFC4515. 00065 */ 00066 #define APR_ESCAPE_LDAP_FILTER (0x02) 00067 00068 /** 00069 * Apply both RFC4514 and RFC4515 LDAP escaping. 00070 */ 00071 #define APR_ESCAPE_LDAP_ALL (0x03) 00072 00073 /** 00074 * Perform shell escaping on the provided string. 00075 * 00076 * Shell escaping causes characters to be prefixed with a '\' character. 00077 * @param escaped Optional buffer to write the encoded string, can be 00078 * NULL 00079 * @param str The original string 00080 * @param slen The length of the original string, or APR_ESCAPE_STRING 00081 * @param len If present, returns the length of the string 00082 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00083 * detected or the string was NULL 00084 */ 00085 APR_DECLARE(apr_status_t) apr_escape_shell(char *escaped, const char *str, 00086 apr_ssize_t slen, apr_size_t *len); 00087 00088 /** 00089 * Perform shell escaping on the provided string, returning the result 00090 * from the pool. 00091 * 00092 * Shell escaping causes characters to be prefixed with a '\' character. 00093 * 00094 * If no characters were escaped, the original string is returned. 00095 * @param p Pool to allocate from 00096 * @param str The original string 00097 * @return the encoded string, allocated from the pool, or the original 00098 * string if no escaping took place or the string was NULL. 00099 */ 00100 APR_DECLARE(const char *) apr_pescape_shell(apr_pool_t *p, const char *str) 00101 __attribute__((nonnull(1))); 00102 00103 /** 00104 * Unescapes a URL, leaving reserved characters intact. 00105 * @param escaped Optional buffer to write the encoded string, can be 00106 * NULL 00107 * @param url String to be unescaped 00108 * @param slen The length of the original url, or APR_ESCAPE_STRING 00109 * @param forbid Optional list of forbidden characters, in addition to 00110 * 0x00 00111 * @param reserved Optional list of reserved characters that will be 00112 * left unescaped 00113 * @param plus If non zero, '+' is converted to ' ' as per 00114 * application/x-www-form-urlencoded encoding 00115 * @param len If set, the length of the escaped string will be returned 00116 * @return APR_SUCCESS on success, APR_NOTFOUND if no characters are 00117 * decoded or the string is NULL, APR_EINVAL if a bad escape sequence is 00118 * found, APR_BADCH if a character on the forbid list is found. 00119 */ 00120 APR_DECLARE(apr_status_t) apr_unescape_url(char *escaped, const char *url, 00121 apr_ssize_t slen, const char *forbid, const char *reserved, int plus, 00122 apr_size_t *len); 00123 00124 /** 00125 * Unescapes a URL, leaving reserved characters intact, returning the 00126 * result from a pool. 00127 * @param p Pool to allocate from 00128 * @param url String to be unescaped in place 00129 * @param forbid Optional list of forbidden characters, in addition to 00130 * 0x00 00131 * @param reserved Optional list of reserved characters that will be 00132 * left unescaped 00133 * @param plus If non zero, '+' is converted to ' ' as per 00134 * application/x-www-form-urlencoded encoding 00135 * @return A string allocated from the pool on success, the original string 00136 * if no characters are decoded, or NULL if a bad escape sequence is found 00137 * or if a character on the forbid list is found, or if the original string 00138 * was NULL. 00139 */ 00140 APR_DECLARE(const char *) apr_punescape_url(apr_pool_t *p, const char *url, 00141 const char *forbid, const char *reserved, int plus) 00142 __attribute__((nonnull(1))); 00143 00144 /** 00145 * Escape a path segment, as defined in RFC1808. 00146 * @param escaped Optional buffer to write the encoded string, can be 00147 * NULL 00148 * @param str The original string 00149 * @param slen The length of the original string, or APR_ESCAPE_STRING 00150 * @param len If present, returns the length of the string 00151 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00152 * detected or the string was NULL 00153 */ 00154 APR_DECLARE(apr_status_t) apr_escape_path_segment(char *escaped, 00155 const char *str, apr_ssize_t slen, apr_size_t *len); 00156 00157 /** 00158 * Escape a path segment, as defined in RFC1808, returning the result from a 00159 * pool. 00160 * @param p Pool to allocate from 00161 * @param str String to be escaped 00162 * @return A string allocated from the pool on success, the original string 00163 * if no characters are encoded or the string is NULL. 00164 */ 00165 APR_DECLARE(const char *) apr_pescape_path_segment(apr_pool_t *p, 00166 const char *str) __attribute__((nonnull(1))); 00167 00168 /** 00169 * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808. 00170 * In all cases if a ':' occurs before the first '/' in the URL, the URL should 00171 * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means 00172 * leaving '/' alone, but otherwise doing what escape_path_segment() does. For 00173 * efficiency reasons, we don't use escape_path_segment(), which is provided for 00174 * reference. Again, RFC 1808 is where this stuff is defined. 00175 * 00176 * If partial is set, os_escape_path() assumes that the path will be appended to 00177 * something with a '/' in it (and thus does not prefix "./"). 00178 * @param escaped Optional buffer to write the encoded string, can be 00179 * NULL 00180 * @param path The original string 00181 * @param slen The length of the original string, or APR_ESCAPE_STRING 00182 * @param partial If non zero, suppresses the prepending of "./" 00183 * @param len If present, returns the length of the string 00184 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00185 * detected or if the string was NULL 00186 */ 00187 APR_DECLARE(apr_status_t) apr_escape_path(char *escaped, const char *path, 00188 apr_ssize_t slen, int partial, apr_size_t *len); 00189 00190 /** 00191 * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808, 00192 * returning the result from a pool. 00193 * 00194 * In all cases if a ':' occurs before the first '/' in the URL, the URL should 00195 * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means 00196 * leaving '/' alone, but otherwise doing what escape_path_segment() does. For 00197 * efficiency reasons, we don't use escape_path_segment(), which is provided for 00198 * reference. Again, RFC 1808 is where this stuff is defined. 00199 * 00200 * If partial is set, os_escape_path() assumes that the path will be appended to 00201 * something with a '/' in it (and thus does not prefix "./"). 00202 * @param p Pool to allocate from 00203 * @param str The original string 00204 * @param partial If non zero, suppresses the prepending of "./" 00205 * @return A string allocated from the pool on success, the original string 00206 * if no characters are encoded or if the string was NULL. 00207 */ 00208 APR_DECLARE(const char *) apr_pescape_path(apr_pool_t *p, const char *str, 00209 int partial) __attribute__((nonnull(1))); 00210 00211 /** 00212 * Urlencode a string, as defined in 00213 * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1. 00214 * @param escaped Optional buffer to write the encoded string, can be 00215 * NULL 00216 * @param str The original string 00217 * @param slen The length of the original string, or APR_ESCAPE_STRING 00218 * @param len If present, returns the length of the string 00219 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00220 * detected or if the stirng was NULL 00221 */ 00222 APR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str, 00223 apr_ssize_t slen, apr_size_t *len); 00224 00225 /** 00226 * Urlencode a string, as defined in 00227 * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1, returning 00228 * the result from a pool. 00229 * @param p Pool to allocate from 00230 * @param str String to be escaped 00231 * @return A string allocated from the pool on success, the original string 00232 * if no characters are encoded or if the string was NULL. 00233 */ 00234 APR_DECLARE(const char *) apr_pescape_urlencoded(apr_pool_t *p, 00235 const char *str) __attribute__((nonnull(1))); 00236 00237 /** 00238 * Apply entity encoding to a string. Characters are replaced as follows: 00239 * '<' becomes '\<', '>' becomes '\>', '&' becomes '\&', the 00240 * double quote becomes '\"" and the single quote becomes '\''. 00241 * 00242 * If toasc is not zero, any non ascii character will be encoded as 00243 * '%\#ddd;', where ddd is the decimal code of the character. 00244 * @param escaped Optional buffer to write the encoded string, can be 00245 * NULL 00246 * @param str The original string 00247 * @param slen The length of the original string, or APR_ESCAPE_STRING 00248 * @param toasc If non zero, encode non ascii characters 00249 * @param len If present, returns the length of the string 00250 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00251 * detected or the string was NULL 00252 */ 00253 APR_DECLARE(apr_status_t) apr_escape_entity(char *escaped, const char *str, 00254 apr_ssize_t slen, int toasc, apr_size_t *len); 00255 00256 /** 00257 * Apply entity encoding to a string, returning the result from a pool. 00258 * Characters are replaced as follows: '<' becomes '\<', '>' becomes 00259 * '\>', '&' becomes '\&', the double quote becomes '\"" and the 00260 * single quote becomes '\''. 00261 * @param p Pool to allocate from 00262 * @param str The original string 00263 * @param toasc If non zero, encode non ascii characters 00264 * @return A string allocated from the pool on success, the original string 00265 * if no characters are encoded or the string is NULL. 00266 */ 00267 APR_DECLARE(const char *) apr_pescape_entity(apr_pool_t *p, const char *str, 00268 int toasc) __attribute__((nonnull(1))); 00269 00270 /** 00271 * Decodes html entities or numeric character references in a string. If 00272 * the string to be unescaped is syntactically incorrect, then the 00273 * following fixups will be made: 00274 * unknown entities will be left undecoded; 00275 * references to unused numeric characters will be deleted. 00276 * In particular, � will not be decoded, but will be deleted. 00277 * @param unescaped Optional buffer to write the encoded string, can be 00278 * NULL 00279 * @param str The original string 00280 * @param slen The length of the original string, or APR_ESCAPE_STRING 00281 * @param len If present, returns the length of the string 00282 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00283 * detected or the string was NULL 00284 */ 00285 APR_DECLARE(apr_status_t) apr_unescape_entity(char *unescaped, const char *str, 00286 apr_ssize_t slen, apr_size_t *len); 00287 00288 /** 00289 * Decodes html entities or numeric character references in a string. If 00290 * the string to be unescaped is syntactically incorrect, then the 00291 * following fixups will be made: 00292 * unknown entities will be left undecoded; 00293 * references to unused numeric characters will be deleted. 00294 * In particular, � will not be decoded, but will be deleted. 00295 * @param p Pool to allocate from 00296 * @param str The original string 00297 * @return A string allocated from the pool on success, the original string 00298 * if no characters are encoded or the string is NULL. 00299 */ 00300 APR_DECLARE(const char *) apr_punescape_entity(apr_pool_t *p, const char *str) 00301 __attribute__((nonnull(1))); 00302 00303 /** 00304 * Escape control characters in a string, as performed by the shell's 00305 * 'echo' command. Characters are replaced as follows: 00306 * \\a alert (bell), \\b backspace, \\f form feed, \\n new line, \\r carriage 00307 * return, \\t horizontal tab, \\v vertical tab, \\ backslash. 00308 * 00309 * Any non ascii character will be encoded as '\\xHH', where HH is the hex 00310 * code of the character. 00311 * 00312 * If quote is not zero, the double quote character will also be escaped. 00313 * @param escaped Optional buffer to write the encoded string, can be 00314 * NULL 00315 * @param str The original string 00316 * @param slen The length of the original string, or APR_ESCAPE_STRING 00317 * @param quote If non zero, encode double quotes 00318 * @param len If present, returns the length of the string 00319 * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 00320 * detected or the string was NULL 00321 */ 00322 APR_DECLARE(apr_status_t) apr_escape_echo(char *escaped, const char *str, 00323 apr_ssize_t slen, int quote, apr_size_t *len); 00324 00325 /** 00326 * Escape control characters in a string, as performed by the shell's 00327 * 'echo' command, and return the results from a pool. Characters are 00328 * replaced as follows: \\a alert (bell), \\b backspace, \\f form feed, 00329 * \\n new line, \\r carriage return, \\t horizontal tab, \\v vertical tab, 00330 * \\ backslash. 00331 * 00332 * Any non ascii character will be encoded as '\\xHH', where HH is the hex 00333 * code of the character. 00334 * 00335 * If quote is not zero, the double quote character will also be escaped. 00336 * @param p Pool to allocate from 00337 * @param str The original string 00338 * @param quote If non zero, encode double quotes 00339 * @return A string allocated from the pool on success, the original string 00340 * if no characters are encoded or the string is NULL. 00341 */ 00342 APR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str, 00343 int quote); 00344 00345 /** 00346 * Convert binary data to a hex encoding. 00347 * @param dest The destination buffer, can be NULL 00348 * @param src The original buffer 00349 * @param srclen The length of the original buffer 00350 * @param colon If not zero, insert colon characters between hex digits. 00351 * @param len If present, returns the length of the string 00352 * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL 00353 */ 00354 APR_DECLARE(apr_status_t) apr_escape_hex(char *dest, const void *src, 00355 apr_size_t srclen, int colon, apr_size_t *len); 00356 00357 /** 00358 * Convert binary data to a hex encoding, and return the results from a 00359 * pool. 00360 * @param p Pool to allocate from 00361 * @param src The original buffer 00362 * @param slen The length of the original buffer 00363 * @param colon If not zero, insert colon characters between hex digits. 00364 * @return A zero padded buffer allocated from the pool on success, or 00365 * NULL if src was NULL. 00366 */ 00367 APR_DECLARE(const char *) apr_pescape_hex(apr_pool_t *p, const void *src, 00368 apr_size_t slen, int colon) __attribute__((nonnull(1))); 00369 00370 /** 00371 * Convert hex encoded string to binary data. 00372 * @param dest The destination buffer, can be NULL 00373 * @param str The original buffer 00374 * @param slen The length of the original buffer 00375 * @param colon If not zero, ignore colon characters between hex digits. 00376 * @param len If present, returns the length of the string 00377 * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL, or APR_BADCH 00378 * if a non hex character is present. 00379 */ 00380 APR_DECLARE(apr_status_t) apr_unescape_hex(void *dest, const char *str, 00381 apr_ssize_t slen, int colon, apr_size_t *len); 00382 00383 /** 00384 * Convert hex encoding to binary data, and return the results from a pool. 00385 * If the colon character appears between pairs of hex digits, it will be 00386 * ignored. 00387 * @param p Pool to allocate from 00388 * @param str The original string 00389 * @param colon If not zero, ignore colon characters between hex digits. 00390 * @param len If present, returns the length of the final buffer 00391 * @return A buffer allocated from the pool on success, or NULL if src was 00392 * NULL, or a bad character was present. 00393 */ 00394 APR_DECLARE(const void *) apr_punescape_hex(apr_pool_t *p, const char *str, 00395 int colon, apr_size_t *len); 00396 00397 /** 00398 * Apply LDAP escaping to binary data. Characters from RFC4514 and RFC4515 00399 * are escaped with their hex equivalents. 00400 * @param dest The destination buffer, can be NULL 00401 * @param src The original buffer 00402 * @param srclen The length of the original buffer 00403 * @param flags APR_ESCAPE_LDAP_DN for RFC4514, APR_ESCAPE_LDAP_FILTER for 00404 * RFC4515, APR_ESCAPE_LDAP_ALL for both 00405 * @param len If present, returns the length of the string 00406 * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL 00407 */ 00408 APR_DECLARE(apr_status_t) apr_escape_ldap(char *dest, const void *src, 00409 apr_ssize_t srclen, int flags, apr_size_t *len); 00410 00411 /** 00412 * Apply LDAP escaping to binary data, and return the results from a 00413 * pool. Characters from RFC4514 and RFC4515 are escaped with their hex 00414 * equivalents. 00415 * @param p Pool to allocate from 00416 * @param src The original buffer 00417 * @param slen The length of the original buffer 00418 * @param flags APR_ESCAPE_LDAP_DN for RFC4514, APR_ESCAPE_LDAP_FILTER for 00419 * RFC4515, APR_ESCAPE_LDAP_ALL for both 00420 * @return A zero padded buffer allocated from the pool on success, or 00421 * NULL if src was NULL. 00422 */ 00423 APR_DECLARE(const char *) apr_pescape_ldap(apr_pool_t *p, const void *src, 00424 apr_ssize_t slen, int flags) __attribute__((nonnull(1))); 00425 00426 /** @} */ 00427 #ifdef __cplusplus 00428 } 00429 #endif 00430 00431 #endif /* !APR_ESCAPE_H */
1.5.6