diff options
| -rw-r--r-- | core/java/android/webkit/SslErrorHandler.java | 40 | ||||
| -rw-r--r-- | core/java/android/webkit/WebViewClient.java | 48 |
2 files changed, 54 insertions, 34 deletions
diff --git a/core/java/android/webkit/SslErrorHandler.java b/core/java/android/webkit/SslErrorHandler.java index 1d5c6f1f12b1..6f229f6e0054 100644 --- a/core/java/android/webkit/SslErrorHandler.java +++ b/core/java/android/webkit/SslErrorHandler.java @@ -20,11 +20,15 @@ import android.annotation.SystemApi; import android.os.Handler; /** - * Represents a request for handling an SSL error. Instances of this class are - * created by the WebView and passed to - * {@link WebViewClient#onReceivedSslError}. The host application must call - * either {@link #proceed} or {@link #cancel} to set the WebView's response - * to the request. + * Represents a request for handling an SSL error. + * + * <p>A {@link WebView} creates an instance of this class. The instance is + * passed to {@link WebViewClient#onReceivedSslError(WebView, SslErrorHandler, + * SslError)}. + * + * <p>The host application must call {@link #cancel()} or, contrary to secure + * web communication standards, {@link #proceed()} to provide the web view's + * response to the request. */ public class SslErrorHandler extends Handler { @@ -35,17 +39,29 @@ public class SslErrorHandler extends Handler { public SslErrorHandler() {} /** - * Proceed with the SSL certificate. - * <p> - * It is not recommended to proceed past SSL errors and this method should - * generally not be used; see {@link WebViewClient#onReceivedSslError} for - * more information. + * Instructs the {@code WebView} that encountered the SSL certificate error + * to ignore the error and continue communicating with the server. + * + * <p class="warning"><b>Warning:</b> When an SSL error occurs, the host + * application should always call {@link #cancel()} rather than + * {@code proceed()} because an invalid SSL certificate means the connection + * is not secure. + * + * @see WebViewClient#onReceivedSslError(WebView, SslErrorHandler, + * SslError) */ public void proceed() {} /** - * Cancel this request and all pending requests for the WebView that had - * the error. + * Instructs the {@code WebView} that encountered the SSL certificate error + * to terminate communication with the server. Cancels the current server + * request and all pending requests for the {@code WebView}. + * + * <p>The host application must call this method to prevent a resource from + * loading when an SSL certificate is invalid. + * + * @see WebViewClient#onReceivedSslError(WebView, SslErrorHandler, + * SslError) */ public void cancel() {} } diff --git a/core/java/android/webkit/WebViewClient.java b/core/java/android/webkit/WebViewClient.java index 55f09f110f88..2dfeae3567e5 100644 --- a/core/java/android/webkit/WebViewClient.java +++ b/core/java/android/webkit/WebViewClient.java @@ -382,30 +382,34 @@ public class WebViewClient { } /** - * Notify the host application that an SSL error occurred while loading a - * resource. The host application must call either {@link SslErrorHandler#cancel} or - * {@link SslErrorHandler#proceed}. Note that the decision may be retained for use in - * response to future SSL errors. The default behavior is to cancel the - * load. - * <p> - * This API is only called for recoverable SSL certificate errors. In the case of - * non-recoverable errors (such as when the server fails the client), WebView will call {@link - * #onReceivedError(WebView, WebResourceRequest, WebResourceError)} with {@link - * #ERROR_FAILED_SSL_HANDSHAKE}. - * <p> - * Applications are advised not to prompt the user about SSL errors, as - * the user is unlikely to be able to make an informed security decision - * and WebView does not provide any UI for showing the details of the + * Notifies the host application that an SSL error occurred while loading a + * resource. The host application must call either + * {@link SslErrorHandler#cancel()} or {@link SslErrorHandler#proceed()}. + * + * <p class="warning"><b>Warning:</b> Application overrides of this method + * can be used to display custom error pages or to silently log issues, but + * the host application should always call {@code SslErrorHandler#cancel()} + * and never proceed past errors. + * + * <p class="note"><b>Note:</b> Do not prompt the user about SSL errors. + * Users are unlikely to be able to make an informed security decision, and + * {@code WebView} does not provide a UI for showing the details of the * error in a meaningful way. - * <p> - * Application overrides of this method may display custom error pages or - * silently log issues, but it is strongly recommended to always call - * {@link SslErrorHandler#cancel} and never allow proceeding past errors. * - * @param view The WebView that is initiating the callback. - * @param handler An {@link SslErrorHandler} that will handle the user's - * response. - * @param error The SSL error object. + * <p>The decision to call {@code proceed()} or {@code cancel()} may be + * retained to facilitate responses to future SSL errors. The default + * behavior is to cancel the resource loading process. + * + * <p>This API is called only for recoverable SSL certificate errors. For + * non-recoverable errors (such as when the server fails the client), the + * {@code WebView} calls {@link #onReceivedError(WebView, + * WebResourceRequest, WebResourceError) onReceivedError(WebView, + * WebResourceRequest, WebResourceError)} with the + * {@link #ERROR_FAILED_SSL_HANDSHAKE} argument. + * + * @param view {@code WebView} that initiated the callback. + * @param handler {@link SslErrorHandler} that handles the user's response. + * @param error SSL error object. */ public void onReceivedSslError(WebView view, SslErrorHandler handler, SslError error) { |