apr_escape.h revision 302408
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 25extern "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 */ 57APR_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 */ 72APR_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 */ 92APR_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 */ 112APR_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 */ 126APR_DECLARE(apr_status_t) apr_escape_path_segment(char *escaped, 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 */ 137APR_DECLARE(const char *) apr_pescape_path_segment(apr_pool_t *p, 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 */ 159APR_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 */ 180APR_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 */ 194APR_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 */ 206APR_DECLARE(const char *) apr_pescape_urlencoded(apr_pool_t *p, 207 const char *str) __attribute__((nonnull(1))); 208 209/** 210 * Apply entity encoding to a string. Characters are replaced as follows: 211 * '<' becomes '<', '>' becomes '>', '&' becomes '&', the 212 * double quote becomes '"" and the single quote becomes '''. 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 */ 225APR_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 '<', '>' becomes 231 * '>', '&' becomes '&', the double quote becomes '"" and the 232 * single quote becomes '''. 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 */ 239APR_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, � 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 */ 257APR_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, � 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 */ 272APR_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 */ 294APR_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 */ 314APR_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 */ 326APR_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 */ 339APR_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 */ 352APR_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 */ 366APR_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 */ 375