escape.h 8.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174
  1. // Copyright 2020 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef BASE_STRINGS_ESCAPE_H_
  5. #define BASE_STRINGS_ESCAPE_H_
  6. #include <stdint.h>
  7. #include <set>
  8. #include <string>
  9. #include "base/base_export.h"
  10. #include "base/strings/string_piece.h"
  11. #include "base/strings/utf_offset_string_conversions.h"
  12. namespace base {
  13. // Escaping --------------------------------------------------------------------
  14. // Escapes all characters except unreserved characters. Unreserved characters,
  15. // as defined in RFC 3986, include alphanumerics and -._~
  16. BASE_EXPORT std::string EscapeAllExceptUnreserved(StringPiece text);
  17. // Escapes characters in text suitable for use as a query parameter value.
  18. // We %XX everything except alphanumerics and -_.!~*'()
  19. // Spaces change to "+" unless you pass usePlus=false.
  20. // This is basically the same as encodeURIComponent in javascript.
  21. BASE_EXPORT std::string EscapeQueryParamValue(StringPiece text, bool use_plus);
  22. // Escapes a partial or complete file/pathname. This includes:
  23. // non-printable, non-7bit, and (including space) "#%:<>?[\]^`{|}
  24. BASE_EXPORT std::string EscapePath(StringPiece path);
  25. #if BUILDFLAG(IS_APPLE)
  26. // Escapes characters as per expectations of NSURL. This includes:
  27. // non-printable, non-7bit, and (including space) "#%<>[\]^`{|}
  28. BASE_EXPORT std::string EscapeNSURLPrecursor(StringPiece precursor);
  29. #endif // BUILDFLAG(IS_APPLE)
  30. // Escapes application/x-www-form-urlencoded content. This includes:
  31. // non-printable, non-7bit, and (including space) ?>=<;+'&%$#"![\]^`{|}
  32. // Space is escaped as + (if use_plus is true) and other special characters
  33. // as %XX (hex).
  34. BASE_EXPORT std::string EscapeUrlEncodedData(StringPiece path, bool use_plus);
  35. // Escapes all non-ASCII input, as well as escaping % to %25.
  36. BASE_EXPORT std::string EscapeNonASCIIAndPercent(StringPiece input);
  37. // Escapes all non-ASCII input. Note this function leaves % unescaped, which
  38. // means the unescaping the resulting string will not give back the original
  39. // input.
  40. BASE_EXPORT std::string EscapeNonASCII(StringPiece input);
  41. // Escapes characters in text suitable for use as an external protocol handler
  42. // command.
  43. // We %XX everything except alphanumerics and -_.!~*'() and the restricted
  44. // characters (;/?:@&=+$,#[]) and a valid percent escape sequence (%XX).
  45. BASE_EXPORT std::string EscapeExternalHandlerValue(StringPiece text);
  46. // Appends the given character to the output string, escaping the character if
  47. // the character would be interpreted as an HTML delimiter.
  48. BASE_EXPORT void AppendEscapedCharForHTML(char c, std::string* output);
  49. // Escapes chars that might cause this text to be interpreted as HTML tags.
  50. BASE_EXPORT std::string EscapeForHTML(StringPiece text);
  51. BASE_EXPORT std::u16string EscapeForHTML(StringPiece16 text);
  52. // Unescaping ------------------------------------------------------------------
  53. class UnescapeRule {
  54. public:
  55. // A combination of the following flags that is passed to the unescaping
  56. // functions.
  57. typedef uint32_t Type;
  58. // Don't unescape anything at all.
  59. static constexpr Type NONE = 0;
  60. // Don't unescape anything special, but all normal unescaping will happen.
  61. // This is a placeholder and can't be combined with other flags (since it's
  62. // just the absence of them). All other unescape rules imply "normal" in
  63. // addition to their special meaning. Things like escaped letters, digits,
  64. // and most symbols will get unescaped with this mode.
  65. static constexpr Type NORMAL = 1 << 0;
  66. // Convert %20 to spaces. In some places where we're showing URLs, we may
  67. // want this. In places where the URL may be copied and pasted out, then
  68. // you wouldn't want this since it might not be interpreted in one piece
  69. // by other applications. Other UTF-8 spaces will not be unescaped.
  70. static constexpr Type SPACES = 1 << 1;
  71. // Unescapes '/' and '\\'. If these characters were unescaped, the resulting
  72. // URL won't be the same as the source one. Moreover, they are dangerous to
  73. // unescape in strings that will be used as file paths or names. This value
  74. // should only be used when slashes don't have special meaning, like data
  75. // URLs.
  76. static constexpr Type PATH_SEPARATORS = 1 << 2;
  77. // Unescapes various characters that will change the meaning of URLs,
  78. // including '%', '+', '&', '#'. Does not unescape path separators.
  79. // If these characters were unescaped, the resulting URL won't be the same
  80. // as the source one. This flag is used when generating final output like
  81. // filenames for URLs where we won't be interpreting as a URL and want to do
  82. // as much unescaping as possible.
  83. static constexpr Type URL_SPECIAL_CHARS_EXCEPT_PATH_SEPARATORS = 1 << 3;
  84. // URL queries use "+" for space. This flag controls that replacement.
  85. static constexpr Type REPLACE_PLUS_WITH_SPACE = 1 << 4;
  86. };
  87. // Unescapes |escaped_text| and returns the result.
  88. // Unescaping consists of looking for the exact pattern "%XX", where each X is
  89. // a hex digit, and converting to the character with the numerical value of
  90. // those digits. Thus "i%20=%203%3b" unescapes to "i = 3;", if the
  91. // "UnescapeRule::SPACES" used.
  92. //
  93. // This method does not ensure that the output is a valid string using any
  94. // character encoding. However, it does leave escaped certain byte sequences
  95. // that would be dangerous to display to the user, because if interpreted as
  96. // UTF-8, they could be used to mislead the user. Callers that want to
  97. // unconditionally unescape everything for uses other than displaying data to
  98. // the user should use UnescapeBinaryURLComponent().
  99. BASE_EXPORT std::string UnescapeURLComponent(StringPiece escaped_text,
  100. UnescapeRule::Type rules);
  101. // Unescapes the given substring as a URL, and then tries to interpret the
  102. // result as being encoded as UTF-8. If the result is convertible into UTF-8, it
  103. // will be returned as converted. If it is not, the original escaped string will
  104. // be converted into a std::u16string and returned. |adjustments| provides
  105. // information on how the original string was adjusted to get the string
  106. // returned.
  107. BASE_EXPORT std::u16string UnescapeAndDecodeUTF8URLComponentWithAdjustments(
  108. StringPiece text,
  109. UnescapeRule::Type rules,
  110. OffsetAdjuster::Adjustments* adjustments);
  111. // Unescapes a component of a URL for use as binary data. Unlike
  112. // UnescapeURLComponent, leaves nothing unescaped, including nulls, invalid
  113. // characters, characters that are unsafe to display, etc. This should *not*
  114. // be used when displaying the decoded data to the user.
  115. //
  116. // Only the NORMAL and REPLACE_PLUS_WITH_SPACE rules are allowed.
  117. BASE_EXPORT std::string UnescapeBinaryURLComponent(
  118. StringPiece escaped_text,
  119. UnescapeRule::Type rules = UnescapeRule::NORMAL);
  120. // Variant of UnescapeBinaryURLComponent(). Writes output to |unescaped_text|.
  121. // Returns true on success, returns false and clears |unescaped_text| on
  122. // failure. Fails on characters escaped that are unsafe to unescape in some
  123. // contexts, which are defined as characters "\0" through "\x1F" (Which includes
  124. // CRLF but not space), and optionally path separators. Path separators include
  125. // both forward and backward slashes on all platforms. Does not fail if any of
  126. // those characters appear unescaped in the input string.
  127. BASE_EXPORT bool UnescapeBinaryURLComponentSafe(StringPiece escaped_text,
  128. bool fail_on_path_separators,
  129. std::string* unescaped_text);
  130. // Returns true if |escaped_text| contains any element of |bytes| in
  131. // percent-encoded form.
  132. //
  133. // For example, if |bytes| is {'%', '/'}, returns true if |escaped_text|
  134. // contains "%25" or "%2F", but not if it just contains bare '%' or '/'
  135. // characters.
  136. BASE_EXPORT bool ContainsEncodedBytes(StringPiece escaped_text,
  137. const std::set<unsigned char>& bytes);
  138. // Unescapes the following ampersand character codes from |text|:
  139. // &lt; &gt; &amp; &quot; &#39;
  140. BASE_EXPORT std::u16string UnescapeForHTML(StringPiece16 text);
  141. } // namespace base
  142. #endif // BASE_STRINGS_ESCAPE_H_