Update documentation for secure networking classes. Remove certificateName parameter.

sdk/lib/io/http.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * HTTP status codes.
  */
 abstract class HttpStatus {
@@ skipping 76 matching lines @@
  *
  * The HttpRequest exposes the request headers and provides the request body,
  * if it exists, as a Stream of data. If the body is unread, it is drained
  * when the server writes to the HttpResponse or closes it.
  *
  * ## Bind with a secure HTTPS connection
  *
  * Use [bindSecure] to create an HTTPS server.
  *
  * The server presents a certificate to the client. The certificate
- * chain and the private key are set in the SecurityContext
+ * chain and the private key are set in the [SecurityContext]
  * object that is passed to [bindSecure].
  *
  *     import 'dart:io';
  *     import "dart:isolate";
  *
  *     main() {
  *       SecurityContext context = new SecurityContext();
  *       var chain =
  *           Platform.script.resolve('certificates/server_chain.pem')
  *           .toFilePath();
  *       var key =
  *           Platform.script.resolve('certificates/server_key.pem')
  *           .toFilePath();
  *       context.useCertificateChain(chain);
  *       context.usePrivateKey(key, password: 'dartdart');
  *
  *       HttpServer
  *           .bindSecure(InternetAddress.ANY_IP_V6,
  *                       443,
  *                       context)
  *           .then((server) {
  *             server.listen((HttpRequest request) {
  *               request.response.write('Hello, world!');
  *               request.response.close();
  *             });
  *           });
  *     }
  *
- *  The certificates and keys are pem files, which can be created and
- *  managed with the tools in OpenSSL and BoringSSL.
+ *  The certificates and keys are PEM files, which can be created and
+ *  managed with the tools in OpenSSL.
  *
  * ## Connect to a server socket
  *
  * You can use the [listenOn] constructor to attach an HTTP server to
  * a [ServerSocket].
  *
  *     import 'dart:io';
  *
  *     main() {
  *       ServerSocket.bind(InternetAddress.ANY_IP_V6, 80)
@@ skipping 92 matching lines @@
    *
    * If [port] has the value [:0:] an ephemeral port will be chosen by
    * the system. The actual port used can be retrieved using the
    * [port] getter.
    *
    * The optional argument [backlog] can be used to specify the listen
    * backlog for the underlying OS listen setup. If [backlog] has the
    * value of [:0:] (the default) a reasonable value will be chosen by
    * the system.
    *
-   * The optional argument [shared] specify whether additional binds
-   * to the same `address`, `port` and `v6Only` combination is
-   * possible from the same Dart process. If `shared` is `true` and
-   * additional binds are performed, then the incoming connections
-   * will be distributed between that set of `HttpServer`s. One way of
-   * using this is to have number of isolates between which incoming
-   * connections are distributed.
+   * The optional argument [shared] specifies whether additional HttpServer
+   * objects can bind to the same combination of `address`, `port` and `v6Only`.
+   * If `shared` is `true` and more `HttpServer`s from this isolate or other
+   * isolates are bound to the port, then the incoming connections will be
+   * distributed among all the bound `HttpServer`s. Connections can be
+   * distributed over multiple isolates this way.
    */
   static Future<HttpServer> bind(address,
                                  int port,
                                  {int backlog: 0,
                                   bool v6Only: false,
                                   bool shared: false})
       => _HttpServer.bind(address, port, backlog, v6Only, shared);
 
   /**
    * The [address] can either be a [String] or an
@@ skipping 14 matching lines @@
    *
    * If [port] has the value [:0:] an ephemeral port will be chosen by
    * the system. The actual port used can be retrieved using the
    * [port] getter.
    *
    * The optional argument [backlog] can be used to specify the listen
    * backlog for the underlying OS listen setup. If [backlog] has the
    * value of [:0:] (the default) a reasonable value will be chosen by
    * the system.
    *
-   * 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
+   * If [requestClientCertificate] is true, the server will
    * request clients to authenticate with a client certificate.
+   * The server will advertise the names of trusted issuers of client
+   * certificates, getting them from [context], where they have been
+   * set using [SecurityContext.setClientAuthorities].
    *
-   * The optional argument [shared] specify whether additional binds
-   * to the same `address`, `port` and `v6Only` combination is
-   * possible from the same Dart process. If `shared` is `true` and
-   * additional binds are performed, then the incoming connections
-   * will be distributed between that set of `HttpServer`s. One way of
-   * using this is to have number of isolates between which incoming
-   * connections are distributed.
+   * The optional argument [shared] specifies whether additional HttpServer
+   * objects can bind to the same combination of `address`, `port` and `v6Only`.
+   * If `shared` is `true` and more `HttpServer`s from this isolate or other
+   * isolates are bound to the port, then the incoming connections will be
+   * distributed among all the bound `HttpServer`s. Connections can be
+   * distributed over multiple isolates this way.
    */
 
   static Future<HttpServer> bindSecure(address,
                                        int port,
                                        SecurityContext context,
                                        {int backlog: 0,
                                         bool v6Only: false,
-                                        String certificateName,
                                         bool requestClientCertificate: false,
                                         bool shared: false})
       => _HttpServer.bindSecure(address,
                                 port,
                                 context,
                                 backlog,
                                 v6Only,
-                                certificateName,
                                 requestClientCertificate,
                                 shared);
 
   /**
    * Attaches the HTTP server to an existing [ServerSocket]. When the
    * [HttpServer] is closed, the [HttpServer] will just detach itself,
    * closing current connections but not closing [serverSocket].
    */
   factory HttpServer.listenOn(ServerSocket serverSocket)
       => new _HttpServer.listenOn(serverSocket);
@@ skipping 918 matching lines @@
  *           return request.close();
  *         })
  *         .then((HttpClientResponse response) {
  *           // Process the response.
  *           ...
  *         });
  *
  * The future for [HttpClientRequest] is created by methods such as
  * [getUrl] and [open].
  *
+ * ## HTTPS connections
+ *
+ * An HttpClient can make HTTPS requests, connecting to a server using
+ * the TLS (SSL) secure networking protocol. Calling [getUrl] with an
+ * https: scheme will work automatically, if the server's certificate is
+ * signed by a well-known root CA (certificate authority) on the list of
+ * trusted CAs from Mozilla's Firefox browser.

[Søren Gjesse, 2015/11/02 16:15:35]

Are the CA's from Mozilla's Firefox browser?

+ *
+ * To add a custom trusted certificate authority, or to send a client
+ * certificate to servers that request one, pass a [SecurityContext] object
+ * as the optional [context] argument to the `HttpClient` constructor.
+ * The desired security options can be set on the [SecurityContext] object.
+ *
  * ## Headers
  *
  * All HttpClient requests set the following header by default:
  *
  *     Accept-Encoding: gzip
  *
  * This allows the HTTP server to use gzip compression for the body if
  * possible. If this behavior is not desired set the
  * `Accept-Encoding` header to something else.
  * To turn off gzip compression of the response, clear this header:
@@ skipping 755 matching lines @@
 class RedirectException implements HttpException {
   final String message;
   final List<RedirectInfo> redirects;
 
   const RedirectException(this.message, this.redirects);
 
   String toString() => "RedirectException: $message";
 
   Uri get uri => redirects.last.location;
 }