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