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