dart:io | Add badCertificateCallback to HttpClient.

sdk/lib/io/http.dart

Index: sdk/lib/io/http.dart
diff --git a/sdk/lib/io/http.dart b/sdk/lib/io/http.dart
index 4b490c215e38af660cf1f716f77513fb077dd059..f7156b8b5c1de400973aba37b2400011af4caee9 100644
--- a/sdk/lib/io/http.dart
+++ b/sdk/lib/io/http.dart
@@ -142,10 +142,10 @@ abstract class HttpServer implements Stream<HttpRequest> {
    * value of [:0:] (the default) a reasonable value will be chosen by
    * the system.
    *
-   * The certificate with Distinguished Name [certificateName] is looked
-   * up in the certificate database, and is used as the server certificate.
-   * if [requestClientCertificate] is true, the server will request clients
-   * to authenticate with a client certificate.
+   * The certificate with nickname or distinguished name (DN) [certificateName]
+   * is looked up in the certificate database, and is used as the server
+   * certificate. If [requestClientCertificate] is true, the server will
+   * request clients to authenticate with a client certificate.
    */
 
   static Future<HttpServer> bindSecure(address,
@@ -1172,6 +1172,24 @@ abstract class HttpClient {
                            HttpClientCredentials credentials);
 
   /**
+   * Set a callback that will decide whether to accept a secure connection
+   * with a server certificate that cannot be authenticated by any of our
+   * trusted root certificates.
+   *
+   * The callback takes an [X509Certificate] object and the server's hostname
+   * and port, and returns true if the connection should be accepted.
+   * If the callback returns true, the future completes

[Søren Gjesse, 2013/08/13 16:56:08]

"the future" - please be more specific to what future that is (HttpClient.open
and friends I assume).

[Bill Hesse, 2013/08/14 09:25:48]

Done.

+   * with an HttpRequest object.  Otherwise, the future completes with an error.

[Søren Gjesse, 2013/08/13 16:56:08]

Maybe mention explicitly that "otherwise" includes the calback throwing.

[Bill Hesse, 2013/08/14 09:25:48]

Done.

+   *
+   * Each [open] or [get] call uses the value of badCertificateCallback

[Søren Gjesse, 2013/08/13 16:56:08]

We have all of open, openUrl, get, getUrl, port, postUrl, but I don't think we
are normally mentioning all of them...

[Bill Hesse, 2013/08/14 09:25:48]

Done.

+   * at the time the call is made, to handle a bad certificate that is received
+   * while making the connection with the server asynchronously at a later time.
+   */
+  set badCertificateCallback(bool callback(X509Certificate cert,
+                                           String host,
+                                           int port));
+
+  /**
    * Shutdown the HTTP client. If [force] is [:false:] (the default)
    * the [:HttpClient:] will be kept alive until all active
    * connections are done. If [force] is [:true:] any active
@@ -1314,8 +1332,8 @@ abstract class HttpClientResponse implements Stream<List<int>> {
   String get reasonPhrase;
 
   /**
-   * Returns the content length of the request body. Returns -1 if the size of
-   * the request body is not known in advance.
+   * Returns the content length of the response body. Returns -1 if the size of
+   * the response body is not known in advance.
    */
   int get contentLength;