AW docs: README for //aw/browser/safe_browsing

No change to logic, only docs.

This adds a README file to explain WebView Safe Browsing support, and
documents how to add new Safe Browsing threats.

Bug: 918221, 934597
Test: tools/md_browser/md_browser.py
Test: Upload to gerrit > open file > click "gitiles"
Change-Id: I962183b4be247ba6c6fa81493bba5028b1972ad9
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1546640Reviewed-by: Richard Coles <torne@chromium.org>
Commit-Queue: Nate Fischer <ntfschr@chromium.org>
Cr-Commit-Position: refs/heads/master@{#664651}

android_webview/browser/safe_browsing/README.md

+# Android WebView Safe Browsing
+
+[TOC]
+
+Android WebView has supported core Safe Browsing features since 2017.
+
+*** promo
+Googlers may wish to consult [internal
+documentation](http://go/clank-webview/safebrowsing).
+***
+
+## What is Safe Browsing?
+
+See the relevant Chromium classes in
+[//components/safe\_browsing/](/components/safe_browsing).
+
+For info on the feature, see https://safebrowsing.google.com/.
+
+## Opt-in/consent/requirements
+
+### Google Play Services
+
+If Google Play Services (AKA GMSCore) is uninstalled, disabled, or out-of-date,
+WebView cannot perform Safe Browsing checks (with the exception of [hard-coded
+URLs](#hard_coded-urls)). Before trying Safe Browsing locally, make sure this is
+up-to-date:
+
+```shell
+$ adb shell am start -a "android.intent.action.VIEW" -d "market://details?id=com.google.android.gms"
+# Then, manually update GMS in the UI.
+```
+
+If Google Play Services is installed, the user must opt into Google Play
+Protect's "Verify Apps" setting: `Settings > Google > Security > Google Play
+Protect > Scan device for security threats`.
+
+### Application opt-in
+
+Safe Browsing is enabled by default, but applications can explicitly disable it
+with a manifest tag:
+
+```xml
+<manifest>
+    <application>
+        <meta-data android:name="android.webkit.WebView.EnableSafeBrowsing"
+                   android:value="false" />
+        ...
+    </application>
+</manifest>
+```
+
+## Hard-coded URLs
+
+WebView supports Safe Browsing checks (for testing purposes) on hard-coded WebUI
+URLs defined in
+[`//components/safe_browsing/web_ui/constants.cc`](/components/safe_browsing/web_ui/constants.cc)
+(ex. `chrome://safe-browsing/match?type=malware`).
+
+These URLs don't show meaningful content, but will trigger an interstitial when
+trying to navigate to them. WebView relies on these URLs in our CTS tests, so
+they **must never change** (but more URLs may be added).
+
+## Differences in support and types of interstitials
+
+See [this page](docs/differences.md).
+
+## Testing Safe Browsing
+
+Automated tests live
+[here](/android_webview/javatests/src/org/chromium/android_webview/test/SafeBrowsingTest.java).
+
+You can manually test Safe Browsing with the [WebView
+Shell](/android_webview/docs/webview-shell.md). Navigate to one of the
+[hard-coded URLs](#hard_coded-urls) mentioned above.
+
+To test more complex scenarios and WebView's Safe Browsing APIs, please try out
+the [open source WebView demo
+app](https://android.googlesource.com/platform/frameworks/support/+/HEAD/webkit/integration-tests/testapp).
+
+*** note
+**Note:** if testing Safe Browsing manually, make sure to [update GMS and
+opt-into Google Play Protect](#Google-Play-Services).
+***
+
+## Supporting new threat types
+
+As Chrome supports more threat types, so can WebView. The steps are:
+
+1. Create quiet interstitial resources for the new threat type ([example
+   CL](https://chromium-review.googlesource.com/c/chromium/src/+/1256021)).
+1. Whitelist [resources](/android_webview/ui/grit_resources_whitelist.txt) and
+   [strings](/android_webview/ui/grit_strings_whitelist.txt) (
+   [general docs](/android_webview/ui/README.md), [example
+   CL](https://chromium-review.googlesource.com/c/chromium/src/+/1270476/12/android_webview/ui/grit_strings_whitelist.txt)).
+1. Add the new threat type to our list of threats ([example
+   CL](https://chromium-review.googlesource.com/c/chromium/src/+/1270476/12/android_webview/browser/aw_url_checker_delegate_impl.cc)).
+1. Add a hard-coded URL ([example
+   CL](https://chromium-review.googlesource.com/c/chromium/src/+/1270476/12/components/safe_browsing/web_ui/constants.cc)).
+1. Write integration tests ([example
+   CL](https://chromium-review.googlesource.com/c/chromium/src/+/1270476/12/android_webview/javatests/src/org/chromium/android_webview/test/SafeBrowsingTest.java)).
+1. Add a new threat type constant to the Android SDK (constants are defined in
+   `WebViewClient.java`, please [consult a WebView team
+   member](https://groups.google.com/a/chromium.org/forum/#!forum/android-webview-dev)
+   before this step). The new threat type constant should only be used when the
+   application targets the new Android SDK: use
+   [SAFE\_BROWSING\_THREAT\_UNKNOWN](https://developer.android.com/reference/android/webkit/WebViewClient.html#SAFE_BROWSING_THREAT_UNKNOWN)
+   for apps with older targetSdkVersions (see http://crbug.com/887186#c15 and
+   http://b/117470538).

android_webview/browser/safe_browsing/docs/differences.md

+# Differences in support/behavior compared to Chrome
+
+## Quiet interstitials
+
+The main interstitials in Chrome are **Loud** interstitials, which are blocking
+pages that show detailed informational text to users and are (usually) red in
+background color. WebView supports these interstitials when we believe WebView
+is the predominant part of the application UI (such as in browser apps).
+
+When we suspect WebView is a smaller (or otherwise less prominent) part of the
+application UI, we show a gray **Quiet** interstitial, which is meant to feel
+like a less-scary error page.
+
+There are **Small**, **Medium**, and **Giant** Quiet interstitials. Medium
+interstitials are when we have enough space to show textual information, Small
+interstitials are when there's not enough space, and Giant interstitials are
+whenever part of the WebView hangs out of the viewport.
+
+| Small interstitial | 4 Medium interstitials | Giant interstitial (hanging off bottom right of viewport) |
+|---|---|---|
+| ![Small Quiet interstitial](small-interstitial.png) | ![Medium Quiet interstitials](medium-interstitials.png) | ![Giant Quiet interstitial](giant-interstitial.png) |
+
+## Network error
+
+WebView returns a particular network error to the application when the user
+clicks "back to safety." This is to stay consistent with expectations of legacy
+applications (to communicate the page failed to load).
+
+## Callback API
+
+WebView supports the `onSafeBrowsingHit()` callback, allowing applications to
+implement custom interstitials. This also involves exposing [threat type
+constants](/android_webview/java/src/org/chromium/android_webview/AwSafeBrowsingConversionHelper.java),
+to indicate what threat WebView observed.
+
+## Sometimes, no "back to safety" button
+
+WebView will not show a "back to safety" button on the interstitial if there's
+no previous page in the history, or if we're showing a Quiet interstitial.
+
+| With "back to safety" button (like Chrome) | No "back to safety" button (WebView only) |
+|---|---|
+| ![With back-to-safety button](loud-interstitial-with-back-button.png) | ![No back-to-safety button](loud-interstitial-no-back-button.png) |