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 * 36362181Sdim * The design goal of these functions are: 37362181Sdim * 38362181Sdim * - Avoid unnecessary work. 39362181Sdim * 40362181Sdim * In most cases the strings passed in do not need to be escaped at all. In 41362181Sdim * these cases the original string will be returned. 42362181Sdim * 43362181Sdim * - Lowest possible memory footprint. 44362181Sdim * 45362181Sdim * The amount of memory allocated for a given encoding is calculated based 46362181Sdim * on the exact amount of memory needed, and not the theoretical worst case 47362181Sdim * scenario. 48362181Sdim * 49266733Speter */ 50266733Speter 51266733Speter/** 52266733Speter * When passing a string to one of the escape functions, this value can be 53266733Speter * passed to indicate a string-valued key, and have the length computed 54266733Speter * automatically. 55266733Speter */ 56362181Sdim#define APR_ESCAPE_STRING (-1) 57266733Speter 58266733Speter/** 59362181Sdim * Apply LDAP distinguished name escaping as per RFC4514. 60362181Sdim */ 61362181Sdim#define APR_ESCAPE_LDAP_DN (0x01) 62362181Sdim 63362181Sdim/** 64362181Sdim * Apply LDAP filter escaping as per RFC4515. 65362181Sdim */ 66362181Sdim#define APR_ESCAPE_LDAP_FILTER (0x02) 67362181Sdim 68362181Sdim/** 69362181Sdim * Apply both RFC4514 and RFC4515 LDAP escaping. 70362181Sdim */ 71362181Sdim#define APR_ESCAPE_LDAP_ALL (0x03) 72362181Sdim 73362181Sdim/** 74266733Speter * Perform shell escaping on the provided string. 75266733Speter * 76266733Speter * Shell escaping causes characters to be prefixed with a '\' character. 77266733Speter * @param escaped Optional buffer to write the encoded string, can be 78266733Speter * NULL 79266733Speter * @param str The original string 80266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 81266733Speter * @param len If present, returns the length of the string 82266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 83266733Speter * detected or the string was NULL 84266733Speter */ 85266733SpeterAPR_DECLARE(apr_status_t) apr_escape_shell(char *escaped, const char *str, 86266733Speter apr_ssize_t slen, apr_size_t *len); 87266733Speter 88266733Speter/** 89266733Speter * Perform shell escaping on the provided string, returning the result 90266733Speter * from the pool. 91266733Speter * 92266733Speter * Shell escaping causes characters to be prefixed with a '\' character. 93266733Speter * 94266733Speter * If no characters were escaped, the original string is returned. 95266733Speter * @param p Pool to allocate from 96266733Speter * @param str The original string 97266733Speter * @return the encoded string, allocated from the pool, or the original 98266733Speter * string if no escaping took place or the string was NULL. 99266733Speter */ 100266733SpeterAPR_DECLARE(const char *) apr_pescape_shell(apr_pool_t *p, const char *str) 101266733Speter __attribute__((nonnull(1))); 102266733Speter 103266733Speter/** 104266733Speter * Unescapes a URL, leaving reserved characters intact. 105266733Speter * @param escaped Optional buffer to write the encoded string, can be 106266733Speter * NULL 107266733Speter * @param url String to be unescaped 108266733Speter * @param slen The length of the original url, or APR_ESCAPE_STRING 109266733Speter * @param forbid Optional list of forbidden characters, in addition to 110266733Speter * 0x00 111266733Speter * @param reserved Optional list of reserved characters that will be 112266733Speter * left unescaped 113266733Speter * @param plus If non zero, '+' is converted to ' ' as per 114266733Speter * application/x-www-form-urlencoded encoding 115266733Speter * @param len If set, the length of the escaped string will be returned 116266733Speter * @return APR_SUCCESS on success, APR_NOTFOUND if no characters are 117266733Speter * decoded or the string is NULL, APR_EINVAL if a bad escape sequence is 118266733Speter * found, APR_BADCH if a character on the forbid list is found. 119266733Speter */ 120266733SpeterAPR_DECLARE(apr_status_t) apr_unescape_url(char *escaped, const char *url, 121266733Speter apr_ssize_t slen, const char *forbid, const char *reserved, int plus, 122266733Speter apr_size_t *len); 123266733Speter 124266733Speter/** 125266733Speter * Unescapes a URL, leaving reserved characters intact, returning the 126266733Speter * result from a pool. 127266733Speter * @param p Pool to allocate from 128266733Speter * @param url String to be unescaped in place 129266733Speter * @param forbid Optional list of forbidden characters, in addition to 130266733Speter * 0x00 131266733Speter * @param reserved Optional list of reserved characters that will be 132266733Speter * left unescaped 133266733Speter * @param plus If non zero, '+' is converted to ' ' as per 134266733Speter * application/x-www-form-urlencoded encoding 135266733Speter * @return A string allocated from the pool on success, the original string 136266733Speter * if no characters are decoded, or NULL if a bad escape sequence is found 137266733Speter * or if a character on the forbid list is found, or if the original string 138266733Speter * was NULL. 139266733Speter */ 140266733SpeterAPR_DECLARE(const char *) apr_punescape_url(apr_pool_t *p, const char *url, 141266733Speter const char *forbid, const char *reserved, int plus) 142266733Speter __attribute__((nonnull(1))); 143266733Speter 144266733Speter/** 145266733Speter * Escape a path segment, as defined in RFC1808. 146266733Speter * @param escaped Optional buffer to write the encoded string, can be 147266733Speter * NULL 148266733Speter * @param str The original string 149266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 150266733Speter * @param len If present, returns the length of the string 151266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 152266733Speter * detected or the string was NULL 153266733Speter */ 154266733SpeterAPR_DECLARE(apr_status_t) apr_escape_path_segment(char *escaped, 155266733Speter const char *str, apr_ssize_t slen, apr_size_t *len); 156266733Speter 157266733Speter/** 158266733Speter * Escape a path segment, as defined in RFC1808, returning the result from a 159266733Speter * pool. 160266733Speter * @param p Pool to allocate from 161266733Speter * @param str String to be escaped 162266733Speter * @return A string allocated from the pool on success, the original string 163266733Speter * if no characters are encoded or the string is NULL. 164266733Speter */ 165266733SpeterAPR_DECLARE(const char *) apr_pescape_path_segment(apr_pool_t *p, 166266733Speter const char *str) __attribute__((nonnull(1))); 167266733Speter 168266733Speter/** 169266733Speter * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808. 170266733Speter * In all cases if a ':' occurs before the first '/' in the URL, the URL should 171266733Speter * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means 172266733Speter * leaving '/' alone, but otherwise doing what escape_path_segment() does. For 173266733Speter * efficiency reasons, we don't use escape_path_segment(), which is provided for 174266733Speter * reference. Again, RFC 1808 is where this stuff is defined. 175266733Speter * 176266733Speter * If partial is set, os_escape_path() assumes that the path will be appended to 177266733Speter * something with a '/' in it (and thus does not prefix "./"). 178266733Speter * @param escaped Optional buffer to write the encoded string, can be 179266733Speter * NULL 180266733Speter * @param path The original string 181266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 182266733Speter * @param partial If non zero, suppresses the prepending of "./" 183266733Speter * @param len If present, returns the length of the string 184266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 185266733Speter * detected or if the string was NULL 186266733Speter */ 187266733SpeterAPR_DECLARE(apr_status_t) apr_escape_path(char *escaped, const char *path, 188266733Speter apr_ssize_t slen, int partial, apr_size_t *len); 189266733Speter 190266733Speter/** 191266733Speter * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808, 192266733Speter * returning the result from a pool. 193266733Speter * 194266733Speter * In all cases if a ':' occurs before the first '/' in the URL, the URL should 195266733Speter * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means 196266733Speter * leaving '/' alone, but otherwise doing what escape_path_segment() does. For 197266733Speter * efficiency reasons, we don't use escape_path_segment(), which is provided for 198266733Speter * reference. Again, RFC 1808 is where this stuff is defined. 199266733Speter * 200266733Speter * If partial is set, os_escape_path() assumes that the path will be appended to 201266733Speter * something with a '/' in it (and thus does not prefix "./"). 202266733Speter * @param p Pool to allocate from 203266733Speter * @param str The original string 204266733Speter * @param partial If non zero, suppresses the prepending of "./" 205266733Speter * @return A string allocated from the pool on success, the original string 206266733Speter * if no characters are encoded or if the string was NULL. 207266733Speter */ 208266733SpeterAPR_DECLARE(const char *) apr_pescape_path(apr_pool_t *p, const char *str, 209266733Speter int partial) __attribute__((nonnull(1))); 210266733Speter 211266733Speter/** 212266733Speter * Urlencode a string, as defined in 213266733Speter * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1. 214266733Speter * @param escaped Optional buffer to write the encoded string, can be 215266733Speter * NULL 216266733Speter * @param str The original string 217266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 218266733Speter * @param len If present, returns the length of the string 219266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 220266733Speter * detected or if the stirng was NULL 221266733Speter */ 222266733SpeterAPR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str, 223266733Speter apr_ssize_t slen, apr_size_t *len); 224266733Speter 225266733Speter/** 226266733Speter * Urlencode a string, as defined in 227266733Speter * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1, returning 228266733Speter * the result from a pool. 229266733Speter * @param p Pool to allocate from 230266733Speter * @param str String to be escaped 231266733Speter * @return A string allocated from the pool on success, the original string 232266733Speter * if no characters are encoded or if the string was NULL. 233266733Speter */ 234266733SpeterAPR_DECLARE(const char *) apr_pescape_urlencoded(apr_pool_t *p, 235266733Speter const char *str) __attribute__((nonnull(1))); 236266733Speter 237266733Speter/** 238266733Speter * Apply entity encoding to a string. Characters are replaced as follows: 239362181Sdim * '<' becomes '\<', '>' becomes '\>', '&' becomes '\&', the 240362181Sdim * double quote becomes '\"" and the single quote becomes '\''. 241266733Speter * 242266733Speter * If toasc is not zero, any non ascii character will be encoded as 243266733Speter * '%\#ddd;', where ddd is the decimal code of the character. 244266733Speter * @param escaped Optional buffer to write the encoded string, can be 245266733Speter * NULL 246266733Speter * @param str The original string 247266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 248266733Speter * @param toasc If non zero, encode non ascii characters 249266733Speter * @param len If present, returns the length of the string 250266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 251266733Speter * detected or the string was NULL 252266733Speter */ 253266733SpeterAPR_DECLARE(apr_status_t) apr_escape_entity(char *escaped, const char *str, 254266733Speter apr_ssize_t slen, int toasc, apr_size_t *len); 255266733Speter 256266733Speter/** 257266733Speter * Apply entity encoding to a string, returning the result from a pool. 258362181Sdim * Characters are replaced as follows: '<' becomes '\<', '>' becomes 259362181Sdim * '\>', '&' becomes '\&', the double quote becomes '\"" and the 260362181Sdim * single quote becomes '\''. 261266733Speter * @param p Pool to allocate from 262266733Speter * @param str The original string 263266733Speter * @param toasc If non zero, encode non ascii characters 264266733Speter * @return A string allocated from the pool on success, the original string 265266733Speter * if no characters are encoded or the string is NULL. 266266733Speter */ 267266733SpeterAPR_DECLARE(const char *) apr_pescape_entity(apr_pool_t *p, const char *str, 268266733Speter int toasc) __attribute__((nonnull(1))); 269266733Speter 270266733Speter/** 271266733Speter * Decodes html entities or numeric character references in a string. If 272266733Speter * the string to be unescaped is syntactically incorrect, then the 273266733Speter * following fixups will be made: 274266733Speter * unknown entities will be left undecoded; 275266733Speter * references to unused numeric characters will be deleted. 276266733Speter * In particular, � will not be decoded, but will be deleted. 277266733Speter * @param unescaped Optional buffer to write the encoded string, can be 278266733Speter * NULL 279266733Speter * @param str The original string 280266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 281266733Speter * @param len If present, returns the length of the string 282266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 283266733Speter * detected or the string was NULL 284266733Speter */ 285266733SpeterAPR_DECLARE(apr_status_t) apr_unescape_entity(char *unescaped, const char *str, 286266733Speter apr_ssize_t slen, apr_size_t *len); 287266733Speter 288266733Speter/** 289266733Speter * Decodes html entities or numeric character references in a string. If 290266733Speter * the string to be unescaped is syntactically incorrect, then the 291266733Speter * following fixups will be made: 292266733Speter * unknown entities will be left undecoded; 293266733Speter * references to unused numeric characters will be deleted. 294266733Speter * In particular, � will not be decoded, but will be deleted. 295266733Speter * @param p Pool to allocate from 296266733Speter * @param str The original string 297266733Speter * @return A string allocated from the pool on success, the original string 298266733Speter * if no characters are encoded or the string is NULL. 299266733Speter */ 300266733SpeterAPR_DECLARE(const char *) apr_punescape_entity(apr_pool_t *p, const char *str) 301266733Speter __attribute__((nonnull(1))); 302266733Speter 303266733Speter/** 304266733Speter * Escape control characters in a string, as performed by the shell's 305266733Speter * 'echo' command. Characters are replaced as follows: 306266733Speter * \\a alert (bell), \\b backspace, \\f form feed, \\n new line, \\r carriage 307266733Speter * return, \\t horizontal tab, \\v vertical tab, \\ backslash. 308266733Speter * 309266733Speter * Any non ascii character will be encoded as '\\xHH', where HH is the hex 310266733Speter * code of the character. 311266733Speter * 312266733Speter * If quote is not zero, the double quote character will also be escaped. 313266733Speter * @param escaped Optional buffer to write the encoded string, can be 314266733Speter * NULL 315266733Speter * @param str The original string 316266733Speter * @param slen The length of the original string, or APR_ESCAPE_STRING 317266733Speter * @param quote If non zero, encode double quotes 318266733Speter * @param len If present, returns the length of the string 319266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were 320266733Speter * detected or the string was NULL 321266733Speter */ 322266733SpeterAPR_DECLARE(apr_status_t) apr_escape_echo(char *escaped, const char *str, 323266733Speter apr_ssize_t slen, int quote, apr_size_t *len); 324266733Speter 325266733Speter/** 326266733Speter * Escape control characters in a string, as performed by the shell's 327266733Speter * 'echo' command, and return the results from a pool. Characters are 328266733Speter * replaced as follows: \\a alert (bell), \\b backspace, \\f form feed, 329266733Speter * \\n new line, \\r carriage return, \\t horizontal tab, \\v vertical tab, 330266733Speter * \\ backslash. 331266733Speter * 332266733Speter * Any non ascii character will be encoded as '\\xHH', where HH is the hex 333266733Speter * code of the character. 334266733Speter * 335266733Speter * If quote is not zero, the double quote character will also be escaped. 336266733Speter * @param p Pool to allocate from 337266733Speter * @param str The original string 338266733Speter * @param quote If non zero, encode double quotes 339266733Speter * @return A string allocated from the pool on success, the original string 340266733Speter * if no characters are encoded or the string is NULL. 341266733Speter */ 342266733SpeterAPR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str, 343266733Speter int quote); 344266733Speter 345266733Speter/** 346266733Speter * Convert binary data to a hex encoding. 347266733Speter * @param dest The destination buffer, can be NULL 348266733Speter * @param src The original buffer 349266733Speter * @param srclen The length of the original buffer 350266733Speter * @param colon If not zero, insert colon characters between hex digits. 351266733Speter * @param len If present, returns the length of the string 352266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL 353266733Speter */ 354266733SpeterAPR_DECLARE(apr_status_t) apr_escape_hex(char *dest, const void *src, 355266733Speter apr_size_t srclen, int colon, apr_size_t *len); 356266733Speter 357266733Speter/** 358266733Speter * Convert binary data to a hex encoding, and return the results from a 359266733Speter * pool. 360266733Speter * @param p Pool to allocate from 361266733Speter * @param src The original buffer 362266733Speter * @param slen The length of the original buffer 363266733Speter * @param colon If not zero, insert colon characters between hex digits. 364266733Speter * @return A zero padded buffer allocated from the pool on success, or 365266733Speter * NULL if src was NULL. 366266733Speter */ 367266733SpeterAPR_DECLARE(const char *) apr_pescape_hex(apr_pool_t *p, const void *src, 368266733Speter apr_size_t slen, int colon) __attribute__((nonnull(1))); 369266733Speter 370266733Speter/** 371266733Speter * Convert hex encoded string to binary data. 372266733Speter * @param dest The destination buffer, can be NULL 373266733Speter * @param str The original buffer 374266733Speter * @param slen The length of the original buffer 375266733Speter * @param colon If not zero, ignore colon characters between hex digits. 376266733Speter * @param len If present, returns the length of the string 377266733Speter * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL, or APR_BADCH 378266733Speter * if a non hex character is present. 379266733Speter */ 380266733SpeterAPR_DECLARE(apr_status_t) apr_unescape_hex(void *dest, const char *str, 381266733Speter apr_ssize_t slen, int colon, apr_size_t *len); 382266733Speter 383266733Speter/** 384266733Speter * Convert hex encoding to binary data, and return the results from a pool. 385266733Speter * If the colon character appears between pairs of hex digits, it will be 386266733Speter * ignored. 387266733Speter * @param p Pool to allocate from 388266733Speter * @param str The original string 389266733Speter * @param colon If not zero, ignore colon characters between hex digits. 390266733Speter * @param len If present, returns the length of the final buffer 391266733Speter * @return A buffer allocated from the pool on success, or NULL if src was 392266733Speter * NULL, or a bad character was present. 393266733Speter */ 394266733SpeterAPR_DECLARE(const void *) apr_punescape_hex(apr_pool_t *p, const char *str, 395266733Speter int colon, apr_size_t *len); 396266733Speter 397362181Sdim/** 398362181Sdim * Apply LDAP escaping to binary data. Characters from RFC4514 and RFC4515 399362181Sdim * are escaped with their hex equivalents. 400362181Sdim * @param dest The destination buffer, can be NULL 401362181Sdim * @param src The original buffer 402362181Sdim * @param srclen The length of the original buffer 403362181Sdim * @param flags APR_ESCAPE_LDAP_DN for RFC4514, APR_ESCAPE_LDAP_FILTER for 404362181Sdim * RFC4515, APR_ESCAPE_LDAP_ALL for both 405362181Sdim * @param len If present, returns the length of the string 406362181Sdim * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL 407362181Sdim */ 408362181SdimAPR_DECLARE(apr_status_t) apr_escape_ldap(char *dest, const void *src, 409362181Sdim apr_ssize_t srclen, int flags, apr_size_t *len); 410362181Sdim 411362181Sdim/** 412362181Sdim * Apply LDAP escaping to binary data, and return the results from a 413362181Sdim * pool. Characters from RFC4514 and RFC4515 are escaped with their hex 414362181Sdim * equivalents. 415362181Sdim * @param p Pool to allocate from 416362181Sdim * @param src The original buffer 417362181Sdim * @param slen The length of the original buffer 418362181Sdim * @param flags APR_ESCAPE_LDAP_DN for RFC4514, APR_ESCAPE_LDAP_FILTER for 419362181Sdim * RFC4515, APR_ESCAPE_LDAP_ALL for both 420362181Sdim * @return A zero padded buffer allocated from the pool on success, or 421362181Sdim * NULL if src was NULL. 422362181Sdim */ 423362181SdimAPR_DECLARE(const char *) apr_pescape_ldap(apr_pool_t *p, const void *src, 424362181Sdim apr_ssize_t slen, int flags) __attribute__((nonnull(1))); 425362181Sdim 426266733Speter/** @} */ 427266733Speter#ifdef __cplusplus 428266733Speter} 429266733Speter#endif 430266733Speter 431266733Speter#endif /* !APR_ESCAPE_H */ 432