include/rfc1738.h

   1 /*
   2  * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef _SQUID_INCLUDE_RFC1738_H
  10 #define _SQUID_INCLUDE_RFC1738_H
  11
  12 #ifdef __cplusplus
  13 extern "C" {
  14 #endif
  15
  16 /* Encoder rfc1738_do_escape flag values. */
  17 #define RFC1738_ESCAPE_CTRLS       1
  18 #define RFC1738_ESCAPE_UNSAFE      2
  19 #define RFC1738_ESCAPE_RESERVED    4
  20 #define RFC1738_ESCAPE_ALL         (RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_RESERVED|RFC1738_ESCAPE_CTRLS)
  21 // exclusions
  22 #define RFC1738_ESCAPE_NOSPACE     128
  23 #define RFC1738_ESCAPE_NOPERCENT   256
  24 // Backward compatibility
  25 #define RFC1738_ESCAPE_UNESCAPED   (RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_CTRLS|RFC1738_ESCAPE_NOPERCENT)
  26
  27 /**
  28  * RFC 1738 URL-escaping
  29  *
  30  * Public API is formed of a triplet of encode functions mapping to the rfc1738_do_encode() engine.
  31  *
  32  * ASCII characters are split into four groups:
  33  * \li SAFE     Characters which are safe to occur in any URL. For example A,B,C
  34  * \li CTRLS    Binary control codes. Dangerous to include in URLs.
  35  * \li UNSAFE   Characters which are completely usafe to occur in any URL. For example; backspace, tab, space, newline.
  36  * \li RESERVED Characters which are reserved for special meaning and may only occur in certain parts of a URL.
  37  *
  38  * Returns a static buffer containing the RFC 1738 compliant, escaped version of the given url.
  39  *
  40  * \param flags  RFC1738_ESCAPE_CTRLS     Encode the blatantly dangerous binary codes.
  41  * \param flags  RFC1738_ESCAPE_UNSAFE    Encode printable unsafe characters (excluding CTRLs).
  42  * \param flags  RFC1738_ESCAPE_RESERVED  Encode reserved characters.
  43  * \param flags  RFC1738_ESCAPE_ALL       Encode all binary CTRL, unsafe and reserved characters.
  44  * \param flags  RFC1738_ESCAPE_NOSPACE   Ignore the space whitespace character.
  45  * \param flags  RFC1738_ESCAPE_NOPERCENT Ignore the escaping delimiter '%'.
  46  */
  47 extern char *rfc1738_do_escape(const char *url, int flags);
  48
  49 /* Old API functions */
  50
  51 /* Default RFC 1738 escaping. Escape all UNSAFE characters and binary CTRL codes */
  52 #define rfc1738_escape(x)  rfc1738_do_escape(x, RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_CTRLS)
  53
  54 /* Escape a partial URL. Encoding every binary code, unsafe or reserved character. */
  55 #define rfc1738_escape_part(x)  rfc1738_do_escape(x, RFC1738_ESCAPE_ALL)
  56
  57 /* Escape a URL. Encoding every unsafe characters but skipping reserved and already-encoded bytes.
  58  * Suitable for safely encoding an absolute URL which may be encoded but is not trusted. */
  59 #define rfc1738_escape_unescaped(x)  rfc1738_do_escape(x, RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_CTRLS|RFC1738_ESCAPE_NOPERCENT)
  60
  61 /**
  62  * Unescape a URL string according to RFC 1738 specification.
  63  * String is unescaped in-place
  64  */
  65 extern void rfc1738_unescape(char *url);
  66
  67 #ifdef __cplusplus
  68 }
  69 #endif
  70 #endif /* _SQUID_INCLUDE_RFC1738_H */
  71