Add automatic initialization of SecureSocket library.

sdk/lib/io/secure_socket.dart

 // Copyright (c) 2012, 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;
 
 /**
  * SecureSocket provides a secure (SSL or TLS) client connection to a server.
  * The certificate provided by the server is checked
- * using the certificate database provided in setCertificateDatabase.
+ * using the certificate database (optionally) provided in initialize().
  */
 abstract class SecureSocket implements Socket {
   /**
    * Constructs a new secure client socket and connect it to the given
    * host on the given port. The returned socket is not yet connected
    * but ready for registration of callbacks.  If sendClientCertificate is
    * set to true, the socket will send a client certificate if one is
    * requested by the server.  If clientCertificate is the nickname of
    * a certificate in the certificate database, that certificate will be sent.
    * If clientCertificate is null, which is the usual use case, an
@@ skipping 21 matching lines @@
 
   /**
    * Get the peerCertificate for a connected secure socket.  For a server
    * socket, this will return the client certificate, or null, if no
    * client certificate was received.  For a client socket, this
    * will return the server's certificate.
    */
   X509Certificate get peerCertificate;
 
    /**
-   * Initializes the NSS library with the path to a certificate database
+   * 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
    * client connections, and server certificates to provide on server
-   * connections.  The password argument should be used when creating
+   * 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),
+   * 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.
    *
    * Examples:
    *   1) Use only the builtin root certificates:
    *     SecureSocket.initialize(); or
    *
    *   2) Use a specified database and the builtin roots:
    *     SecureSocket.initialize(database: 'path/to/my/database',
    *                             password: 'my_password');
    *
    *   3) Use a specified database, without builtin roots:
    *     SecureSocket.initialize(database: 'path/to/my/database',
    *                             password: 'my_password'.
    *                             useBuiltinRoots: false);
    *
    * 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".
+   * environment variable [[NSS_DEFAULT_DB_TYPE]] to "sql".
    */
   external static void initialize({String database,
                                    String password,
                                    bool useBuiltinRoots: true});
 }
 
 
 /**
  * X509Certificate represents an SSL certificate, with accessors to
  * get the fields of the certificate.
@@ skipping 581 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;
 }