Improve return result from SSL/TLS authenticate APIs (#407)

***NO_CI***

(cherry picked from commit 923b423)

Author: josesimoes

nanoFramework.System.Net/Security/CryptographicException.cs

@@ -0,0 +1,44 @@
+//
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+//
+
+namespace System.Security.Cryptography
+{
+    using System;
+
+    /// <summary>
+    /// The exception that is thrown when an error occurs during a
+    /// cryptographic operation.
+    /// </summary>
+    [Serializable]
+    public class CryptographicException : Exception
+    {
+        private int _errorCode;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CryptographicException"/> class.
+        /// </summary>
+        public CryptographicException()
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CryptographicException"/>
+        /// class with a specified error code.
+        /// </summary>
+        /// <param name="errorCode">The error code.</param>
+        public CryptographicException(int errorCode)
+        {
+            _errorCode = errorCode;
+        }
+
+        /// <summary>
+        /// Gets the error code that is associated with this exception.
+        /// </summary>
+        public int ErrorCode
+        {
+            get { return _errorCode; }
+        }
+    }
+}

nanoFramework.System.Net/Security/SslError.cs

@@ -0,0 +1,79 @@
+//
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+//
+
+namespace System.Net.Sockets
+{
+
+
+    /// <summary>
+    /// Defines error codes returned by native SSL initialisation.
+    /// </summary>
+    /// <remarks>
+    /// Values are kept in sync with the <c>SSL_Error</c> enum in the native interpreter
+    /// (<c>ssl_functions.h</c>). <see cref="System.Net.Security.SslStream"/> surfaces these
+    /// through <see cref="System.Security.Cryptography.CryptographicException.ErrorCode"/>
+    /// when SSL context setup fails.
+    /// </remarks>
+    ///
+    public enum SslError : byte
+    {
+        /// <summary>No error; SSL context initialisation succeeded.</summary>
+        None = 0,
+
+        /// <summary>
+        /// All SSL context slots are in use.
+        /// Close an existing SSL connection before opening a new one.
+        /// </summary>
+        NoFreeContext,
+
+        /// <summary>
+        /// A memory allocation failed while setting up the SSL context.
+        /// The device may be low on heap.
+        /// </summary>
+        OutOfMemory,
+
+        /// <summary>
+        /// The DRBG (Deterministic Random Bit Generator) seed step failed.
+        /// The entropy source could not be initialised.
+        /// </summary>
+        DrbgSeedFailed,
+
+        /// <summary>
+        /// Setting TLS configuration defaults failed.
+        /// This is an internal mbedTLS error that should not occur under normal conditions.
+        /// </summary>
+        ConfigDefaultsFailed,
+
+        /// <summary>
+        /// The requested TLS protocol version is not supported on this device.
+        /// Use a protocol version that the target hardware supports.
+        /// </summary>
+        UnsupportedProtocolVersion,
+
+        /// <summary>
+        /// The supplied private key could not be parsed.
+        /// Verify the key is in a supported format (PEM or DER) and is not corrupted.
+        /// </summary>
+        PrivateKeyParseFailed,
+
+        /// <summary>
+        /// The supplied certificate could not be parsed.
+        /// Verify the certificate is in a supported format (PEM or DER) and is not corrupted.
+        /// </summary>
+        CertificateParseFailed,
+
+        /// <summary>
+        /// Configuring the own certificate and private key pair on the SSL context failed.
+        /// This is an internal mbedTLS error that should not occur under normal conditions.
+        /// </summary>
+        OwnCertConfigFailed,
+
+        /// <summary>
+        /// Final SSL context setup failed.
+        /// This is an internal mbedTLS error that should not occur under normal conditions.
+        /// </summary>
+        SetupFailed,
+    }
+}

nanoFramework.System.Net/Security/SslStream.cs

@@ -65,18 +65,29 @@ public SslStream(Socket socket)
         }
 
         /// <summary>
-        /// Called by clients to authenticate the server and optionally the client in a client-server connection. 
+        /// Called by clients to authenticate the server and optionally the client in a client-server connection.
         /// The authentication process uses the specified SSL protocols.
         /// </summary>
         /// <param name="targetHost">The name of the server that will share this SslStream.</param>
         /// <param name="enabledSslProtocols">The <see cref="SslProtocols"/> value that represents the protocol used for authentication.</param>
+        /// <exception cref="InvalidOperationException">Authentication has already been performed on this stream, or all native SSL context slots are in.</exception>
+        /// <exception cref="OutOfMemoryException">A memory allocation failed while setting up the SSL context. The device may be low on heap.</exception>
+        /// <exception cref="System.Security.Cryptography.CryptographicException">
+        /// SSL context initialisation failed. The <see cref="System.Security.Cryptography.CryptographicException.ErrorCode"/> property contains the
+        /// corresponding <see cref="SslError"/> value:
+        /// <see cref="SslError.DrbgSeedFailed"/> — entropy source could not be initialised;
+        /// <see cref="SslError.ConfigDefaultsFailed"/> — internal mbedTLS configuration error;
+        /// <see cref="SslError.UnsupportedProtocolVersion"/> — the requested TLS version is not supported on this device;
+        /// <see cref="SslError.SetupFailed"/> — final SSL context setup failed.
+        /// </exception>
+        /// <exception cref="SocketException">The TLS handshake with the remote server failed.</exception>
         public void AuthenticateAsClient(string targetHost, SslProtocols enabledSslProtocols)
         {
             Authenticate(false, targetHost, null, null, enabledSslProtocols);
         }
 
         /// <summary>
-        /// Called by clients to authenticate the server and optionally the client in a client-server connection. 
+        /// Called by clients to authenticate the server and optionally the client in a client-server connection.
         /// The authentication process uses the specified certificate collections and SSL protocols.
         /// </summary>
         /// <param name="targetHost">The name of the server that will share this SslStream.</param>
@@ -85,13 +96,27 @@ public void AuthenticateAsClient(string targetHost, SslProtocols enabledSslProto
         /// <remarks>
         /// Instead of providing the client certificate in the <paramref name="clientCertificate"/> parameter the <see cref="UseStoredDeviceCertificate"/> property can be used to use the certificate stored in the device.
         /// </remarks>
+        /// <exception cref="InvalidOperationException">Authentication has already been performed on this stream, or all native SSL context slots are in.</exception>
+        /// <exception cref="OutOfMemoryException">A memory allocation failed while setting up the SSL context. The device may be low on heap.</exception>
+        /// <exception cref="System.Security.Cryptography.CryptographicException">
+        /// SSL context initialisation failed. The <see cref="System.Security.Cryptography.CryptographicException.ErrorCode"/> property contains the
+        /// corresponding <see cref="SslError"/> value:
+        /// <see cref="SslError.DrbgSeedFailed"/> — entropy source could not be initialised;
+        /// <see cref="SslError.ConfigDefaultsFailed"/> — internal mbedTLS configuration error;
+        /// <see cref="SslError.UnsupportedProtocolVersion"/> — the requested TLS version is not supported on this device;
+        /// <see cref="SslError.CertificateParseFailed"/> — the client certificate could not be parsed;
+        /// <see cref="SslError.PrivateKeyParseFailed"/> — the client private key could not be parsed;
+        /// <see cref="SslError.OwnCertConfigFailed"/> — configuring the certificate/key pair on the SSL context failed;
+        /// <see cref="SslError.SetupFailed"/> — final SSL context setup failed.
+        /// </exception>
+        /// <exception cref="SocketException">The TLS handshake with the remote server failed.</exception>
         public void AuthenticateAsClient(string targetHost, X509Certificate clientCertificate, SslProtocols enabledSslProtocols)
         {
             Authenticate(false, targetHost, clientCertificate, null, enabledSslProtocols);
         }
 
         /// <summary>
-        /// Called by clients to authenticate the server and optionally the client in a client-server connection. 
+        /// Called by clients to authenticate the server and optionally the client in a client-server connection.
         /// The authentication process uses the specified certificate collections and SSL protocols.
         /// </summary>
         /// <param name="targetHost">The name of the server that will share this SslStream.</param>
@@ -101,20 +126,48 @@ public void AuthenticateAsClient(string targetHost, X509Certificate clientCertif
         /// <remarks>
         /// Instead of providing the client certificate in the <paramref name="clientCertificate"/> parameter the <see cref="UseStoredDeviceCertificate"/> property can be used to use the certificate stored in the device.
         /// </remarks>
+        /// <exception cref="InvalidOperationException">Authentication has already been performed on this stream, or all native SSL context slots are in.</exception>
+        /// <exception cref="OutOfMemoryException">A memory allocation failed while setting up the SSL context. The device may be low on heap.</exception>
+        /// <exception cref="System.Security.Cryptography.CryptographicException">
+        /// SSL context initialisation failed. The <see cref="System.Security.Cryptography.CryptographicException.ErrorCode"/> property contains the
+        /// corresponding <see cref="SslError"/> value:
+        /// <see cref="SslError.DrbgSeedFailed"/> — entropy source could not be initialised;
+        /// <see cref="SslError.ConfigDefaultsFailed"/> — internal mbedTLS configuration error;
+        /// <see cref="SslError.UnsupportedProtocolVersion"/> — the requested TLS version is not supported on this device;
+        /// <see cref="SslError.CertificateParseFailed"/> — the client or CA certificate could not be parsed;
+        /// <see cref="SslError.PrivateKeyParseFailed"/> — the client private key could not be parsed;
+        /// <see cref="SslError.OwnCertConfigFailed"/> — configuring the certificate/key pair on the SSL context failed;
+        /// <see cref="SslError.SetupFailed"/> — final SSL context setup failed.
+        /// </exception>
+        /// <exception cref="SocketException">The TLS handshake with the remote server failed.</exception>
         public void AuthenticateAsClient(string targetHost, X509Certificate clientCertificate, X509Certificate ca, SslProtocols enabledSslProtocols)
         {
             Authenticate(false, targetHost, clientCertificate, ca, enabledSslProtocols);
         }
 
         /// <summary>
-        /// Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificate, 
+        /// Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificate,
         /// verification requirements and security protocol.
         /// </summary>
         /// <param name="serverCertificate">The certificate used to authenticate the server.</param>
         /// <param name="enabledSslProtocols">The protocols that may be used for authentication.</param>
         /// <remarks>
         /// Instead of providing the server certificate in the <paramref name="serverCertificate"/> parameter the <see cref="UseStoredDeviceCertificate"/> property can be used to use the certificate stored in the device.
         /// </remarks>
+        /// <exception cref="InvalidOperationException">Authentication has already been performed on this stream, or all native SSL context slots are in.</exception>
+        /// <exception cref="OutOfMemoryException">A memory allocation failed while setting up the SSL context. The device may be low on heap.</exception>
+        /// <exception cref="System.Security.Cryptography.CryptographicException">
+        /// SSL context initialisation failed. The <see cref="System.Security.Cryptography.CryptographicException.ErrorCode"/> property contains the
+        /// corresponding <see cref="SslError"/> value:
+        /// <see cref="SslError.DrbgSeedFailed"/> — entropy source could not be initialised;
+        /// <see cref="SslError.ConfigDefaultsFailed"/> — internal mbedTLS configuration error;
+        /// <see cref="SslError.UnsupportedProtocolVersion"/> — the requested TLS version is not supported on this device;
+        /// <see cref="SslError.CertificateParseFailed"/> — the server certificate could not be parsed;
+        /// <see cref="SslError.PrivateKeyParseFailed"/> — the server private key could not be parsed;
+        /// <see cref="SslError.OwnCertConfigFailed"/> — configuring the certificate/key pair on the SSL context failed;
+        /// <see cref="SslError.SetupFailed"/> — final SSL context setup failed.
+        /// </exception>
+        /// <exception cref="SocketException">The TLS handshake with the remote client failed.</exception>
         public void AuthenticateAsServer(X509Certificate serverCertificate, SslProtocols enabledSslProtocols)
         {
             Authenticate(true, "", serverCertificate, null, enabledSslProtocols);
@@ -124,11 +177,25 @@ public void AuthenticateAsServer(X509Certificate serverCertificate, SslProtocols
         /// Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates, requirements and security protocol.
         /// </summary>
         /// <param name="serverCertificate">The X509Certificate used to authenticate the server.</param>
-        /// <param name="clientCertificateRequired">A <see cref="Boolean"/> value that specifies whether the client is asked for a certificate for authentication. Note that this is only a request, if no certificate is provided, the server still accepts the connection request.</param>
+        /// <param name="clientCertificateRequired">A <see cref="Boolean"/> value that specifies whether the client is asked for a certificate for authentication. Note that this is only a request — if no certificate is provided, the server still accepts the connection request.</param>
         /// <param name="enabledSslProtocols">The protocols that may be used for authentication.</param>
         /// <remarks>
         /// Instead of providing the server certificate in the <paramref name="serverCertificate"/> parameter the <see cref="UseStoredDeviceCertificate"/> property can be used to use the certificate stored in the device.
         /// </remarks>
+        /// <exception cref="InvalidOperationException">Authentication has already been performed on this stream, or all native SSL context slots are in.</exception>
+        /// <exception cref="OutOfMemoryException">A memory allocation failed while setting up the SSL context. The device may be low on heap.</exception>
+        /// <exception cref="System.Security.Cryptography.CryptographicException">
+        /// SSL context initialisation failed. The <see cref="System.Security.Cryptography.CryptographicException.ErrorCode"/> property contains the
+        /// corresponding <see cref="SslError"/> value:
+        /// <see cref="SslError.DrbgSeedFailed"/> — entropy source could not be initialised;
+        /// <see cref="SslError.ConfigDefaultsFailed"/> — internal mbedTLS configuration error;
+        /// <see cref="SslError.UnsupportedProtocolVersion"/> — the requested TLS version is not supported on this device;
+        /// <see cref="SslError.CertificateParseFailed"/> — the server certificate could not be parsed;
+        /// <see cref="SslError.PrivateKeyParseFailed"/> — the server private key could not be parsed;
+        /// <see cref="SslError.OwnCertConfigFailed"/> — configuring the certificate/key pair on the SSL context failed;
+        /// <see cref="SslError.SetupFailed"/> — final SSL context setup failed.
+        /// </exception>
+        /// <exception cref="SocketException">The TLS handshake with the remote client failed.</exception>
         public void AuthenticateAsServer(X509Certificate serverCertificate, bool clientCertificateRequired, SslProtocols enabledSslProtocols)
         {
             SslVerification = clientCertificateRequired ? SslVerification.VerifyClientOnce : SslVerification.NoVerification;

nanoFramework.System.Net/System.Net.nfproj

@@ -12,7 +12,8 @@
     <ProjectGuid>474A90F4-FA98-4011-AABB-7DAC8E218E6A</ProjectGuid>
     <OutputType>Library</OutputType>
     <FileAlignment>512</FileAlignment>
-    <RootNamespace></RootNamespace>
+    <RootNamespace>
+    </RootNamespace>
     <AssemblyName>System.Net</AssemblyName>
     <TargetFrameworkVersion>v1.0</TargetFrameworkVersion>
     <NF_IsCoreLibrary>True</NF_IsCoreLibrary>
@@ -61,7 +62,9 @@
     <Compile Include="NetworkInformation\WirelessAPConfiguration.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
     <Compile Include="Security\CertificateManager.cs" />
+    <Compile Include="Security\CryptographicException.cs" />
     <Compile Include="Security\NetworkSecurity.cs" />
+    <Compile Include="Security\SslError.cs" />
     <Compile Include="Security\SslStream.cs" />
     <Compile Include="SocketAddress.cs" />
     <Compile Include="SocketException.cs" />