Apache Portable Runtime

apr_escape.h

Go to the documentation of this file.
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 '&lt;', '>' becomes '&gt;', '&' becomes '&amp;', the
00227  * double quote becomes '&quot;" and the single quote becomes '&apos;'.
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 '&lt;', '>' becomes
00246  * '&gt;', '&' becomes '&amp;', the double quote becomes '&quot;" and the
00247  * single quote becomes '&apos;'.
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, &#00; 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, &#00; 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 */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines