dart:io | Change names for SecureSocket exceptions.

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 132 matching lines @@
   /**
    * Get the peer certificate for a connected SecureSocket.  If this
    * SecureSocket is the server end of a secure socket connection,
    * [peerCertificate] will return the client certificate, or null, if no
    * client certificate was received.  If it is the client end,
    * [peerCertificate] will return the server's certificate.
    */
   X509Certificate get peerCertificate;
 
   /**
-   * Initializes the NSS library.  If [initialize] is not called, the library
+   * Initializes the NSS library. If [initialize] is not called, the library
    * is automatically initialized as if [initialize] were called with no
-   * arguments.
+   * arguments. If [initialize] is called more than once, or called after
+   * automatic initialization has happened (when a secure connection is made),
+   * then a TlsException is thrown.
    *
    * The optional argument [database] is the path to a certificate database
    * 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
+   * 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.
    * 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 the [database] argument is omitted, then only the
-   * builtin root certificates are used.  If [useBuiltinRoots] is also false,
+   * builtin root certificates are used. If [useBuiltinRoots] is also false,
    * then no certificates are available.
    *
    * Examples:
    *   1) Use only the builtin root certificates:
    *     SecureSocket.initialize(); or
    *
    *   2) Use a specified database directory and the builtin roots:
    *     SecureSocket.initialize(database: 'path/to/my/database',
    *                             password: 'my_password');
    *
@@ skipping 249 matching lines @@
       String certificateName,
       {bool is_server,
        RawSocket socket,
        StreamSubscription subscription,
        List<int> bufferedData,
        bool requestClientCertificate: false,
        bool requireClientCertificate: false,
        bool sendClientCertificate: false,
        bool onBadCertificate(X509Certificate certificate)}) {
     var future;
+    _verifyFields(host, requestedPort, certificateName, is_server,
+                 requestClientCertificate, requireClientCertificate,
+                 sendClientCertificate, onBadCertificate);
     if (host is String) {
       if (socket != null) {
         future = new Future.value(
             (socket.address as dynamic)._cloneWithNewHost(host));
       } else {
         future = InternetAddress.lookup(host).then((addrs) => addrs.first);
       }
     } else {
       future = new Future.value(host);
     }
@@ skipping 27 matching lines @@
       bool this.onBadCertificate(X509Certificate certificate)) {
     _controller = new StreamController<RawSocketEvent>(
         sync: true,
         onListen: _onSubscriptionStateChange,
         onPause: _onPauseStateChange,
         onResume: _onPauseStateChange,
         onCancel: _onSubscriptionStateChange);
     _stream = _controller.stream;
     // Throw an ArgumentError if any field is invalid.  After this, all
     // errors will be reported through the future or the stream.
-    _verifyFields();
     _secureFilter.init();
     _filterPointer = _secureFilter._pointer();
     _secureFilter.registerHandshakeCompleteCallback(
         _secureHandshakeCompleteHandler);
     if (onBadCertificate != null) {
       _secureFilter.registerBadCertificateCallback(onBadCertificate);
     }
     var futureSocket;
     if (socket == null) {
       futureSocket = RawSocket.connect(address, requestedPort);
     } else {
       futureSocket = new Future.value(socket);
     }
     futureSocket.then((rawSocket) {
+      _connectPending = true;
       _socket = rawSocket;
       _socket.readEventsEnabled = true;
       _socket.writeEventsEnabled = false;
       if (_socketSubscription == null) {
         // If a current subscription is provided use this otherwise
         // create a new one.
         _socketSubscription = _socket.listen(_eventDispatcher,
-                                             onError: _errorHandler,
+                                             onError: _reportError,
                                              onDone: _doneHandler);
       } else {
         _socketSubscription.onData(_eventDispatcher);
-        _socketSubscription.onError(_errorHandler);
+        _socketSubscription.onError(_reportError);
         _socketSubscription.onDone(_doneHandler);
       }
-      _connectPending = true;
       _secureFilter.connect(address.host,
                             (address as dynamic)._sockaddr_storage,
                             port,
                             is_server,
                             certificateName,
                             requestClientCertificate ||
                                 requireClientCertificate,
                             requireClientCertificate,
                             sendClientCertificate);
       _secureHandshake();
     })
-    .catchError((error) {
-      _handshakeComplete.completeError(error);
-      _close();
-    });
+    .catchError(_reportError);
   }
 
   StreamSubscription listen(void onData(RawSocketEvent data),
                             {void onError(error),
                              void onDone(),
                              bool cancelOnError}) {
     _sendWriteEvent();
     return _stream.listen(onData,
                           onError: onError,
                           onDone: onDone,
                           cancelOnError: cancelOnError);
   }
 
-  void _verifyFields() {
-    assert(is_server is bool);
-    assert(_socket == null || _socket is RawSocket);
-    if (address is! InternetAddress) {
-      throw new ArgumentError(
-          "RawSecureSocket constructor: host is not an InternetAddress");
+  static void _verifyFields(host,
+                            int requestedPort,
+                            String certificateName,
+                            bool is_server,
+                            bool requestClientCertificate,
+                            bool requireClientCertificate,
+                            bool sendClientCertificate,
+                            Function onBadCertificate) {
+    if (host is! String && host is! InternetAddress) {
+      throw new ArgumentError("host is not a String or an InternetAddress");
+    }
+    if (requestedPort is! int) {
+      throw new ArgumentError("requestedPort is not an int");
+    }
+    if (requestedPort < 0 || requestedPort > 65535) {
+      throw new ArgumentError("requestedPort is not in the range 0..65535");
     }
     if (certificateName != null && certificateName is! String) {
       throw new ArgumentError("certificateName is not null or a String");
     }
     if (certificateName == null && is_server) {
       throw new ArgumentError("certificateName is null on a server");
     }
     if (requestClientCertificate is! bool) {
       throw new ArgumentError("requestClientCertificate is not a bool");
     }
@@ skipping 125 matching lines @@
   }
 
   X509Certificate get peerCertificate => _secureFilter.peerCertificate;
 
   bool setOption(SocketOption option, bool enabled) {
     if (_socket == null) return false;
     return _socket.setOption(option, enabled);
   }
 
   void _eventDispatcher(RawSocketEvent event) {
-    if (event == RawSocketEvent.READ) {
-      _readHandler();
-    } else if (event == RawSocketEvent.WRITE) {
-      _writeHandler();
-    } else if (event == RawSocketEvent.READ_CLOSED) {
-      _closeHandler();
+    try {
+      if (event == RawSocketEvent.READ) {
+        _readHandler();
+      } else if (event == RawSocketEvent.WRITE) {
+        _writeHandler();
+      } else if (event == RawSocketEvent.READ_CLOSED) {
+        _closeHandler();
+      }
+    } catch (e) {
+      _reportError(e);
     }
   }
 
   void _readHandler() {
     _readSocket();
     _scheduleFilter();
   }
 
   void _writeHandler() {
     _writeSocket();
     _scheduleFilter();
   }
 
   void _doneHandler() {
     if (_filterStatus.readEmpty) {
       _close();
     }
   }
 
-  void _errorHandler(e) {
-    _reportError(e, 'Error on underlying RawSocket');
-  }
-
-  void _reportError(e, String message) {
-    // TODO(whesse): Call _reportError from all internal functions that throw.
-    if (e is SocketException) {
-      e = new SocketException('$message (${e.message})', e.osError);
-    } else if (e is OSError) {
-      e = new SocketException(message, e);
-    } else {
-      e = new SocketException('$message (${e.toString()})', null);
-    }
+  void _reportError(e) {
     if (_connectPending) {
+      // _connectPending is true after the underlying connection has been
+      // made, but before the handshake has completed.
+      if (e is! TlsException) {
+        e = new HandshakeException("$e", null);
+      }
       _handshakeComplete.completeError(e);
     } else {
       _controller.addError(e);
     }
     _close();
   }
 
   void _closeHandler() {
     if  (_status == CONNECTED) {
       if (_closedRead) return;
       _socketClosedRead = true;
       if (_filterStatus.readEmpty) {
         _closedRead = true;
         _controller.add(RawSocketEvent.READ_CLOSED);
         if (_socketClosedWrite) {
           _close();
         }
       } else {
         _scheduleFilter();
       }
     } else if (_status == HANDSHAKE) {
       _socketClosedRead = true;
       if (_filterStatus.readEmpty) {
       _reportError(
-          new SocketException('Connection terminated during handshake'),
-          'RawSecureSocket error');
+          new HandshakeException('Connection terminated during handshake'));
       } else {
         _secureHandshake();
       }
     }
   }
 
   void _secureHandshake() {
     try {
       _secureFilter.handshake();
       _filterStatus.writeEmpty = false;
       _readSocket();
       _writeSocket();
       _scheduleFilter();
     } catch (e) {
-      _reportError(e, "RawSecureSocket error");
+      _reportError(e);
     }
   }
 
   void _secureHandshakeCompleteHandler() {
     _status = CONNECTED;
     if (_connectPending) {
       _connectPending = false;
       // We don't want user code to run synchronously in this callback.
       Timer.run(() => _handshakeComplete.complete(this));
     }
@@ skipping 45 matching lines @@
         }
         if (_filterStatus.writeEmpty && _closedWrite && !_socketClosedWrite) {
           // Checks for and handles all cases of partially closed sockets.
           shutdown(SocketDirection.SEND);
           if (_status == CLOSED) return;
         }
         if (_filterStatus.readEmpty && _socketClosedRead && !_closedRead) {
           if (_status == HANDSHAKE) {
             _secureFilter.handshake();
             if (_status == HANDSHAKE) {
-              _reportError(
-                  new SocketException('Connection terminated during handshake'),
-                  'RawSecureSocket error');
+              throw new HandshakeException(
+                  'Connection terminated during handshake');
             }
           }
           _closeHandler();
         }
         if (_status == CLOSED) return;
         if (_filterStatus.progress) {
           _filterPending = true;
           if (_filterStatus.writePlaintextNoLongerFull) _sendWriteEvent();
           if (_filterStatus.readEncryptedNoLongerFull) _readSocket();
           if (_filterStatus.writeEncryptedNoLongerEmpty) _writeSocket();
           if (_filterStatus.readPlaintextNoLongerEmpty) _scheduleReadEvent();
           if (_status == HANDSHAKE) _secureHandshake();
         }
         _tryFilter();
-      });
+      }).catchError(_reportError);
     }
   }
 
   List<int> _readSocketOrBufferedData(int bytes) {
     if (_bufferedData != null) {
       if (bytes > _bufferedData.length - _bufferedDataIndex) {
         bytes = _bufferedData.length - _bufferedDataIndex;
       }
       var result = _bufferedData.sublist(_bufferedDataIndex,
                                           _bufferedDataIndex + bytes);
       _bufferedDataIndex += bytes;
       if (_bufferedData.length == _bufferedDataIndex) {
         _bufferedData = null;
       }
       return result;
     } else if (!_socketClosedRead) {
-      try {
-        return _socket.read(bytes);
-      } catch (e) {
-        _reportError(e, "RawSecureSocket error reading encrypted socket");
-        return null;
-      }
+      return _socket.read(bytes);
     } else {
       return null;
     }
   }
 
   void _readSocket() {
     if (_status == CLOSED) return;
     var buffer = _secureFilter.buffers[READ_ENCRYPTED];
     if (buffer.writeFromSource(_readSocketOrBufferedData) > 0) {
       _filterStatus.readEmpty = false;
@@ skipping 263 matching lines @@
   void handshake();
   void init();
   X509Certificate get peerCertificate;
   int processBuffer(int bufferIndex);
   void registerBadCertificateCallback(Function callback);
   void registerHandshakeCompleteCallback(Function handshakeCompleteHandler);
   int _pointer();
 
   List<_ExternalBuffer> get buffers;
 }
+
+/** A secure networking exception caused by a failure in the
+ *  TLS/SSL protocol.
+ */
+class TlsException implements IOException {
+  final String type;
+  final String message;
+  final OSError osError;
+
+  const TlsException([String message = "",
+                      OSError osError = null])
+     : this._("TlsException", message, osError);
+
+  const TlsException._(String this.type,
+                       String this.message,
+                       OSError this.osError);
+
+  String toString() {
+    StringBuffer sb = new StringBuffer();
+    sb.write(type);
+    if (!message.isEmpty) {
+      sb.write(": $message");
+      if (osError != null) {
+        sb.write(" ($osError)");
+      }
+    } else if (osError != null) {
+      sb.write(": $osError");
+    }
+    return sb.toString();
+  }
+}
+
+
+/**
+ * An exception that happens in the handshake phase of establishing
+ * a secure network connection.
+ */
+class HandshakeException extends TlsException {
+  const HandshakeException([String message = "",
+                            OSError osError = null])
+     : super._("HandshakeException", message, osError);
+}
+
+
+/**
+ * An exception that happens in the handshake phase of establishing
+ * a secure network connection, when looking up or verifying a
+ * certificate.
+ */
+class CertificateException extends TlsException {
+  const CertificateException([String message = "",
+                            OSError osError = null])
+     : super._("CertificateException", message, osError);
+}