dart:io | Add documentation for the default root certificate database for secure networking.

sdk/lib/io/secure_socket.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;
 
 /**
  * A high-level class for communicating securely over a TCP socket, using
  * TLS and SSL. The [SecureSocket] exposes both a [Stream] and an
  * [IOSink] interface, making it ideal for using together with
@@ skipping 131 matching lines @@
    * [peerCertificate] will return the server's certificate.
    */
   X509Certificate get peerCertificate;
 
   /**
    * Initializes the NSS library.  If [initialize] is not called, the library
    * is automatically initialized as if [initialize] were called with no
    * arguments.
    *
    * The optional argument [database] is the path to a certificate database
-   * containing root certificates for verifying certificate paths on
+   * directory containing root certificates for verifying certificate paths on
    * client connections, and server certificates to provide on server
    * connections.  The argument [password] should be used when creating
    * secure server sockets, to allow the private key of the server
    * certificate to be fetched.  If [useBuiltinRoots] is true (the default),
    * then a built-in set of root certificates for trusted certificate
    * authorities is merged with the certificates in the database.
+   * The list of built-in root certificates, and documentation about this
+   * default database, is available at
+   * http://www.mozilla.org/projects/security/certs/included/ .
+   * If no value is provided for the [database] argument, then only the

[Lasse Reichstein Nielsen, 2013/05/31 08:49:06]

We'd usually write "If the [database] argument is omitted, then ...".

[Bill Hesse, 2013/05/31 09:08:38]

Done.

+   * builtin root certificates are used, unless they are disabled.

[Lasse Reichstein Nielsen, 2013/05/31 08:49:06]

"unless they are disabled"?
How can they be disabled? What happens if they are?
The "unless" could be seen as being relative to the "only", so if the root
certificates are disabled, more than just the root certificates are used.

How about.
"... onlt the builtin root certificates are used. If they are also disabled,
...<something happens - no certificates are used?>"

[Bill Hesse, 2013/05/31 09:08:38]

Done.

    *
    * Examples:
    *   1) Use only the builtin root certificates:
    *     SecureSocket.initialize(); or
    *
-   *   2) Use a specified database and the builtin roots:
+   *   2) Use a specified database directory and the builtin roots:
    *     SecureSocket.initialize(database: 'path/to/my/database',
    *                             password: 'my_password');
    *
-   *   3) Use a specified database, without builtin roots:
+   *   3) Use a specified database directory, without builtin roots:
    *     SecureSocket.initialize(database: 'path/to/my/database',
    *                             password: 'my_password'.
    *                             useBuiltinRoots: false);

[Lasse Reichstein Nielsen, 2013/05/31 08:49:06]

So what happens if you do:
  initialize(password: "my_password", useBuiltinRoots: false)
?

[Bill Hesse, 2013/05/31 09:08:38]

Nothing useful.  No certificates are available.  you can't do much.

    *
    * The database should be an NSS certificate database directory
    * containing a cert9.db file, not a cert8.db file.  This version of
    * the database can be created using the NSS certutil tool with "sql:" in
    * front of the absolute path of the database directory, or setting the
    * environment variable [[NSS_DEFAULT_DB_TYPE]] to "sql".
    */
   external static void initialize({String database,
                                    String password,
                                    bool useBuiltinRoots: true});
@@ skipping 784 matching lines @@
   void destroy();
   void handshake();
   void init();
   X509Certificate get peerCertificate;
   int processBuffer(int bufferIndex);
   void registerBadCertificateCallback(Function callback);
   void registerHandshakeCompleteCallback(Function handshakeCompleteHandler);
 
   List<_ExternalBuffer> get buffers;
 }