Add documentation to ALPN functionality in dart:io

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 10 matching lines @@
    * The certificate provided by the server is checked
    * using the trusted certificates set in the SecurityContext object.
    * The default SecurityContext object contains a built-in set of trusted
    * root certificates for well-known certificate authorities.
    *
    * [onBadCertificate] is an optional handler for unverifiable certificates.
    * The handler receives the [X509Certificate], and can inspect it and
    * decide (or let the user decide) whether to accept
    * the connection or not.  The handler should return true
    * to continue the [SecureSocket] connection.
+   *
+   * [supportedProtocols] is an optional list of protocols (in decreasing
+   * order of preference) to use during the ALPN protocol negogiation with the
+   * server.  Example values are "http/1.1" or "h2".  The selected protocol
+   * can be obtained via [SecureSocket.selectedProtocol].
    */
   static Future<SecureSocket> connect(host, int port,
       {SecurityContext context,
       bool onBadCertificate(X509Certificate certificate),
       List<String> supportedProtocols}) {
     return RawSecureSocket
         .connect(host, port,
             context: context,
             onBadCertificate: onBadCertificate,
             supportedProtocols: supportedProtocols)
@@ skipping 81 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;
 
   /**
-   * Get the protocol which was selected during protocol negotiation.
+   * The protocol which was selected during ALPN protocol negotiation.
+   *
+   * Returns null if one of the peers does not have support for ALPN, did not
+   * specify a list of supported ALPN protocols or there was no common
+   * protocol between client and server.
    */
   String get selectedProtocol;
 
   /**
    * Renegotiate an existing secure connection, renewing the session keys
    * and possibly changing the connection properties.
    *
    * This repeats the SSL or TLS handshake, with options that allow clearing
    * the session cache and requesting a client certificate.
    */
@@ skipping 24 matching lines @@
    * certificates set in the SecurityContext object If a certificate and key are
    * set on the client, using [SecurityContext.useCertificateChain] and
    * [SecurityContext.usePrivateKey], and the server asks for a client
    * certificate, then that client certificate is sent to the server.
    *
    * [onBadCertificate] is an optional handler for unverifiable certificates.
    * The handler receives the [X509Certificate], and can inspect it and
    * decide (or let the user decide) whether to accept
    * the connection or not.  The handler should return true
    * to continue the [RawSecureSocket] connection.
+   *
+   * [supportedProtocols] is an optional list of protocols (in decreasing
+   * order of preference) to use during the ALPN protocol negogiation with the
+   * server.  Example values are "http/1.1" or "h2".  The selected protocol
+   * can be obtained via [RawSecureSocket.selectedProtocol].
    */
   static Future<RawSecureSocket> connect(host, int port,
       {SecurityContext context,
       bool onBadCertificate(X509Certificate certificate),
       List<String> supportedProtocols}) {
     _RawSecureSocket._verifyFields(
         host, port, false, false, false, onBadCertificate);
     return RawSocket.connect(host, port).then((socket) {
       return secure(socket,
           context: context,
@@ skipping 106 matching lines @@
   /**
    * Get the peer certificate for a connected RawSecureSocket.  If this
    * RawSecureSocket 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;
 
   /**
-   * Get the protocol which was selected during protocol negotiation.
+   * The protocol which was selected during protocol negotiation.
+   *
+   * Returns null if one of the peers does not have support for ALPN, did not
+   * specify a list of supported ALPN protocols or there was no common
+   * protocol between client and server.
    */
   String get selectedProtocol;
 }
 
 /**
  * X509Certificate represents an SSL certificate, with accessors to
  * get the fields of the certificate.
  */
 abstract class X509Certificate {
   external factory X509Certificate._();
@@ skipping 895 matching lines @@
 
 /**
  * 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);
 }