1266733Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2266733Speter * contributor license agreements. See the NOTICE file distributed with 3266733Speter * this work for additional information regarding copyright ownership. 4266733Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5266733Speter * (the "License"); you may not use this file except in compliance with 6266733Speter * the License. You may obtain a copy of the License at 7266733Speter * 8266733Speter * http://www.apache.org/licenses/LICENSE-2.0 9266733Speter * 10266733Speter * Unless required by applicable law or agreed to in writing, software 11266733Speter * distributed under the License is distributed on an "AS IS" BASIS, 12266733Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13266733Speter * See the License for the specific language governing permissions and 14266733Speter * limitations under the License. 15266733Speter */ 16266733Speter/** 17266733Speter * @file apr_escape.h 18266733Speter * @brief APR-UTIL Escaping 19266733Speter */ 20266733Speter#ifndef APR_ESCAPE_H 21266733Speter#define APR_ESCAPE_H 22266733Speter#include "apr.h" 23266733Speter#include "apr_general.h" 24266733Speter#ifdef __cplusplus 25266733Speterextern "C" { 26266733Speter#endif 27266733Speter 28266733Speter/** 29266733Speter * @defgroup APR_Util_Escaping Escape functions 30266733Speter * @ingroup APR 31266733Speter * @{ 32266733Speter */ 33266733Speter 34266733Speter/* Simple escape/unescape functions. 35266733Speter * 36266733Speter */ 37266733Speter 38266733Speter/** 39266733Speter * When passing a string to one of the escape functions, this value can be 40266733Speter * passed to indicate a string-valued key, and have the length computed 41266733Speter * automatically. 42266733Speter */ 43266733Speter#define APR_ESCAPE_STRING (-1) 44266733Speter 45266733Speter/** 46266733Speter * Perform shell escaping on the provided string. 47266733Speter * 48266733Speter * Shell escaping causes characters to be prefixed with a '\' character. 49266733Speter * @param escaped Optional buffer to write the encoded string, can be 50266733Speter * NULL 51266733Speter * @param str The original string 52266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 53266733Speter * @param len If present, returns the length of the string 54266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 55266733Speter * detected or the string was NULL 56266733Speter */ 57266733SpeterAPR_DECLARE(apr_status_t) apr_escape_shell(char *escaped, const char *str, 58266733Speter apr_ssize_t slen, apr_size_t *len); 59266733Speter 60266733Speter/** 61266733Speter * Perform shell escaping on the provided string, returning the result 62266733Speter * from the pool. 63266733Speter * 64266733Speter * Shell escaping causes characters to be prefixed with a '\' character. 65266733Speter * 66266733Speter * If no characters were escaped, the original string is returned. 67266733Speter * @param p Pool to allocate from 68266733Speter * @param str The original string 69266733Speter * @return the encoded string, allocated from the pool, or the original 70266733Speter * string if no escaping took place or the string was NULL. 71266733Speter */ 72266733SpeterAPR_DECLARE(const char *) apr_pescape_shell(apr_pool_t *p, const char *str) 73266733Speter __attribute__((nonnull(1))); 74266733Speter 75266733Speter/** 76266733Speter * Unescapes a URL, leaving reserved characters intact. 77266733Speter * @param escaped Optional buffer to write the encoded string, can be 78266733Speter * NULL 79266733Speter * @param url String to be unescaped 80266733Speter * @param slen The length of the original url, or APR_ESCAPE_STRING 81266733Speter * @param forbid Optional list of forbidden characters, in addition to 82266733Speter * 0x00 83266733Speter * @param reserved Optional list of reserved characters that will be 84266733Speter * left unescaped 85266733Speter * @param plus If non zero, '+' is converted to ' ' as per 86266733Speter * application/x-www-form-urlencoded encoding 87266733Speter * @param len If set, the length of the escaped string will be returned 88266733Speter * @return APR_SUCCESS on success, APR_NOTFOUND if no characters are 89266733Speter * decoded or the string is NULL, APR_EINVAL if a bad escape sequence is 90266733Speter * found, APR_BADCH if a character on the forbid list is found. 91266733Speter */ 92266733SpeterAPR_DECLARE(apr_status_t) apr_unescape_url(char *escaped, const char *url, 93266733Speter apr_ssize_t slen, const char *forbid, const char *reserved, int plus, 94266733Speter apr_size_t *len); 95266733Speter 96266733Speter/** 97266733Speter * Unescapes a URL, leaving reserved characters intact, returning the 98266733Speter * result from a pool. 99266733Speter * @param p Pool to allocate from 100266733Speter * @param url String to be unescaped in place 101266733Speter * @param forbid Optional list of forbidden characters, in addition to 102266733Speter * 0x00 103266733Speter * @param reserved Optional list of reserved characters that will be 104266733Speter * left unescaped 105266733Speter * @param plus If non zero, '+' is converted to ' ' as per 106266733Speter * application/x-www-form-urlencoded encoding 107266733Speter * @return A string allocated from the pool on success, the original string 108266733Speter * if no characters are decoded, or NULL if a bad escape sequence is found 109266733Speter * or if a character on the forbid list is found, or if the original string 110266733Speter * was NULL. 111266733Speter */ 112266733SpeterAPR_DECLARE(const char *) apr_punescape_url(apr_pool_t *p, const char *url, 113266733Speter const char *forbid, const char *reserved, int plus) 114266733Speter __attribute__((nonnull(1))); 115266733Speter 116266733Speter/** 117266733Speter * Escape a path segment, as defined in RFC1808. 118266733Speter * @param escaped Optional buffer to write the encoded string, can be 119266733Speter * NULL 120266733Speter * @param str The original string 121266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 122266733Speter * @param len If present, returns the length of the string 123266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 124266733Speter * detected or the string was NULL 125266733Speter */ 126266733SpeterAPR_DECLARE(apr_status_t) apr_escape_path_segment(char *escaped, 127266733Speter const char *str, apr_ssize_t slen, apr_size_t *len); 128266733Speter 129266733Speter/** 130266733Speter * Escape a path segment, as defined in RFC1808, returning the result from a 131266733Speter * pool. 132266733Speter * @param p Pool to allocate from 133266733Speter * @param str String to be escaped 134266733Speter * @return A string allocated from the pool on success, the original string 135266733Speter * if no characters are encoded or the string is NULL. 136266733Speter */ 137266733SpeterAPR_DECLARE(const char *) apr_pescape_path_segment(apr_pool_t *p, 138266733Speter const char *str) __attribute__((nonnull(1))); 139266733Speter 140266733Speter/** 141266733Speter * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808. 142266733Speter * In all cases if a ':' occurs before the first '/' in the URL, the URL should 143266733Speter * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means 144266733Speter * leaving '/' alone, but otherwise doing what escape_path_segment() does. For 145266733Speter * efficiency reasons, we don't use escape_path_segment(), which is provided for 146266733Speter * reference. Again, RFC 1808 is where this stuff is defined. 147266733Speter * 148266733Speter * If partial is set, os_escape_path() assumes that the path will be appended to 149266733Speter * something with a '/' in it (and thus does not prefix "./"). 150266733Speter * @param escaped Optional buffer to write the encoded string, can be 151266733Speter * NULL 152266733Speter * @param path The original string 153266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 154266733Speter * @param partial If non zero, suppresses the prepending of "./" 155266733Speter * @param len If present, returns the length of the string 156266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 157266733Speter * detected or if the string was NULL 158266733Speter */ 159266733SpeterAPR_DECLARE(apr_status_t) apr_escape_path(char *escaped, const char *path, 160266733Speter apr_ssize_t slen, int partial, apr_size_t *len); 161266733Speter 162266733Speter/** 163266733Speter * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808, 164266733Speter * returning the result from a pool. 165266733Speter * 166266733Speter * In all cases if a ':' occurs before the first '/' in the URL, the URL should 167266733Speter * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means 168266733Speter * leaving '/' alone, but otherwise doing what escape_path_segment() does. For 169266733Speter * efficiency reasons, we don't use escape_path_segment(), which is provided for 170266733Speter * reference. Again, RFC 1808 is where this stuff is defined. 171266733Speter * 172266733Speter * If partial is set, os_escape_path() assumes that the path will be appended to 173266733Speter * something with a '/' in it (and thus does not prefix "./"). 174266733Speter * @param p Pool to allocate from 175266733Speter * @param str The original string 176266733Speter * @param partial If non zero, suppresses the prepending of "./" 177266733Speter * @return A string allocated from the pool on success, the original string 178266733Speter * if no characters are encoded or if the string was NULL. 179266733Speter */ 180266733SpeterAPR_DECLARE(const char *) apr_pescape_path(apr_pool_t *p, const char *str, 181266733Speter int partial) __attribute__((nonnull(1))); 182266733Speter 183266733Speter/** 184266733Speter * Urlencode a string, as defined in 185266733Speter * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1. 186266733Speter * @param escaped Optional buffer to write the encoded string, can be 187266733Speter * NULL 188266733Speter * @param str The original string 189266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 190266733Speter * @param len If present, returns the length of the string 191266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 192266733Speter * detected or if the stirng was NULL 193266733Speter */ 194266733SpeterAPR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str, 195266733Speter apr_ssize_t slen, apr_size_t *len); 196266733Speter 197266733Speter/** 198266733Speter * Urlencode a string, as defined in 199266733Speter * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1, returning 200266733Speter * the result from a pool. 201266733Speter * @param p Pool to allocate from 202266733Speter * @param str String to be escaped 203266733Speter * @return A string allocated from the pool on success, the original string 204266733Speter * if no characters are encoded or if the string was NULL. 205266733Speter */ 206266733SpeterAPR_DECLARE(const char *) apr_pescape_urlencoded(apr_pool_t *p, 207266733Speter const char *str) __attribute__((nonnull(1))); 208266733Speter 209266733Speter/** 210266733Speter * Apply entity encoding to a string. Characters are replaced as follows: 211266733Speter * '<' becomes '<', '>' becomes '>', '&' becomes '&', the 212266733Speter * double quote becomes '"" and the single quote becomes '''. 213266733Speter * 214266733Speter * If toasc is not zero, any non ascii character will be encoded as 215266733Speter * '%\#ddd;', where ddd is the decimal code of the character. 216266733Speter * @param escaped Optional buffer to write the encoded string, can be 217266733Speter * NULL 218266733Speter * @param str The original string 219266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 220266733Speter * @param toasc If non zero, encode non ascii characters 221266733Speter * @param len If present, returns the length of the string 222266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 223266733Speter * detected or the string was NULL 224266733Speter */ 225266733SpeterAPR_DECLARE(apr_status_t) apr_escape_entity(char *escaped, const char *str, 226266733Speter apr_ssize_t slen, int toasc, apr_size_t *len); 227266733Speter 228266733Speter/** 229266733Speter * Apply entity encoding to a string, returning the result from a pool. 230266733Speter * Characters are replaced as follows: '<' becomes '<', '>' becomes 231266733Speter * '>', '&' becomes '&', the double quote becomes '"" and the 232266733Speter * single quote becomes '''. 233266733Speter * @param p Pool to allocate from 234266733Speter * @param str The original string 235266733Speter * @param toasc If non zero, encode non ascii characters 236266733Speter * @return A string allocated from the pool on success, the original string 237266733Speter * if no characters are encoded or the string is NULL. 238266733Speter */ 239266733SpeterAPR_DECLARE(const char *) apr_pescape_entity(apr_pool_t *p, const char *str, 240266733Speter int toasc) __attribute__((nonnull(1))); 241266733Speter 242266733Speter/** 243266733Speter * Decodes html entities or numeric character references in a string. If 244266733Speter * the string to be unescaped is syntactically incorrect, then the 245266733Speter * following fixups will be made: 246266733Speter * unknown entities will be left undecoded; 247266733Speter * references to unused numeric characters will be deleted. 248266733Speter * In particular, � will not be decoded, but will be deleted. 249266733Speter * @param unescaped Optional buffer to write the encoded string, can be 250266733Speter * NULL 251266733Speter * @param str The original string 252266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 253266733Speter * @param len If present, returns the length of the string 254266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 255266733Speter * detected or the string was NULL 256266733Speter */ 257266733SpeterAPR_DECLARE(apr_status_t) apr_unescape_entity(char *unescaped, const char *str, 258266733Speter apr_ssize_t slen, apr_size_t *len); 259266733Speter 260266733Speter/** 261266733Speter * Decodes html entities or numeric character references in a string. If 262266733Speter * the string to be unescaped is syntactically incorrect, then the 263266733Speter * following fixups will be made: 264266733Speter * unknown entities will be left undecoded; 265266733Speter * references to unused numeric characters will be deleted. 266266733Speter * In particular, � will not be decoded, but will be deleted. 267266733Speter * @param p Pool to allocate from 268266733Speter * @param str The original string 269266733Speter * @return A string allocated from the pool on success, the original string 270266733Speter * if no characters are encoded or the string is NULL. 271266733Speter */ 272266733SpeterAPR_DECLARE(const char *) apr_punescape_entity(apr_pool_t *p, const char *str) 273266733Speter __attribute__((nonnull(1))); 274266733Speter 275266733Speter/** 276266733Speter * Escape control characters in a string, as performed by the shell's 277266733Speter * 'echo' command. Characters are replaced as follows: 278266733Speter * \\a alert (bell), \\b backspace, \\f form feed, \\n new line, \\r carriage 279266733Speter * return, \\t horizontal tab, \\v vertical tab, \\ backslash. 280266733Speter * 281266733Speter * Any non ascii character will be encoded as '\\xHH', where HH is the hex 282266733Speter * code of the character. 283266733Speter * 284266733Speter * If quote is not zero, the double quote character will also be escaped. 285266733Speter * @param escaped Optional buffer to write the encoded string, can be 286266733Speter * NULL 287266733Speter * @param str The original string 288266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 289266733Speter * @param quote If non zero, encode double quotes 290266733Speter * @param len If present, returns the length of the string 291266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 292266733Speter * detected or the string was NULL 293266733Speter */ 294266733SpeterAPR_DECLARE(apr_status_t) apr_escape_echo(char *escaped, const char *str, 295266733Speter apr_ssize_t slen, int quote, apr_size_t *len); 296266733Speter 297266733Speter/** 298266733Speter * Escape control characters in a string, as performed by the shell's 299266733Speter * 'echo' command, and return the results from a pool. Characters are 300266733Speter * replaced as follows: \\a alert (bell), \\b backspace, \\f form feed, 301266733Speter * \\n new line, \\r carriage return, \\t horizontal tab, \\v vertical tab, 302266733Speter * \\ backslash. 303266733Speter * 304266733Speter * Any non ascii character will be encoded as '\\xHH', where HH is the hex 305266733Speter * code of the character. 306266733Speter * 307266733Speter * If quote is not zero, the double quote character will also be escaped. 308266733Speter * @param p Pool to allocate from 309266733Speter * @param str The original string 310266733Speter * @param quote If non zero, encode double quotes 311266733Speter * @return A string allocated from the pool on success, the original string 312266733Speter * if no characters are encoded or the string is NULL. 313266733Speter */ 314266733SpeterAPR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str, 315266733Speter int quote); 316266733Speter 317266733Speter/** 318266733Speter * Convert binary data to a hex encoding. 319266733Speter * @param dest The destination buffer, can be NULL 320266733Speter * @param src The original buffer 321266733Speter * @param srclen The length of the original buffer 322266733Speter * @param colon If not zero, insert colon characters between hex digits. 323266733Speter * @param len If present, returns the length of the string 324266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL 325266733Speter */ 326266733SpeterAPR_DECLARE(apr_status_t) apr_escape_hex(char *dest, const void *src, 327266733Speter apr_size_t srclen, int colon, apr_size_t *len); 328266733Speter 329266733Speter/** 330266733Speter * Convert binary data to a hex encoding, and return the results from a 331266733Speter * pool. 332266733Speter * @param p Pool to allocate from 333266733Speter * @param src The original buffer 334266733Speter * @param slen The length of the original buffer 335266733Speter * @param colon If not zero, insert colon characters between hex digits. 336266733Speter * @return A zero padded buffer allocated from the pool on success, or 337266733Speter * NULL if src was NULL. 338266733Speter */ 339266733SpeterAPR_DECLARE(const char *) apr_pescape_hex(apr_pool_t *p, const void *src, 340266733Speter apr_size_t slen, int colon) __attribute__((nonnull(1))); 341266733Speter 342266733Speter/** 343266733Speter * Convert hex encoded string to binary data. 344266733Speter * @param dest The destination buffer, can be NULL 345266733Speter * @param str The original buffer 346266733Speter * @param slen The length of the original buffer 347266733Speter * @param colon If not zero, ignore colon characters between hex digits. 348266733Speter * @param len If present, returns the length of the string 349266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL, or APR_BADCH 350266733Speter * if a non hex character is present. 351266733Speter */ 352266733SpeterAPR_DECLARE(apr_status_t) apr_unescape_hex(void *dest, const char *str, 353266733Speter apr_ssize_t slen, int colon, apr_size_t *len); 354266733Speter 355266733Speter/** 356266733Speter * Convert hex encoding to binary data, and return the results from a pool. 357266733Speter * If the colon character appears between pairs of hex digits, it will be 358266733Speter * ignored. 359266733Speter * @param p Pool to allocate from 360266733Speter * @param str The original string 361266733Speter * @param colon If not zero, ignore colon characters between hex digits. 362266733Speter * @param len If present, returns the length of the final buffer 363266733Speter * @return A buffer allocated from the pool on success, or NULL if src was 364266733Speter * NULL, or a bad character was present. 365266733Speter */ 366266733SpeterAPR_DECLARE(const void *) apr_punescape_hex(apr_pool_t *p, const char *str, 367266733Speter int colon, apr_size_t *len); 368266733Speter 369266733Speter/** @} */ 370266733Speter#ifdef __cplusplus 371266733Speter} 372266733Speter#endif 373266733Speter 374266733Speter#endif /* !APR_ESCAPE_H */ 375