From 039a54e85d535affc123c351e0dc5dffa1ca85ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Thu, 9 Jul 2026 16:39:33 +0100 Subject: [PATCH] Improve return result from SSL/TLS authenticate APIs - Add CryptographicException. - Add SslErrors enum. - Update IntelliSense comments with new exceptions. - Bump assembly native version. --- .../Properties/AssemblyInfo.cs | 2 +- .../Security/CryptographicException.cs | 44 +++++++++++ nanoFramework.System.Net/Security/SslError.cs | 79 +++++++++++++++++++ .../Security/SslStream.cs | 79 +++++++++++++++++-- nanoFramework.System.Net/System.Net.nfproj | 5 +- 5 files changed, 201 insertions(+), 8 deletions(-) create mode 100644 nanoFramework.System.Net/Security/CryptographicException.cs create mode 100644 nanoFramework.System.Net/Security/SslError.cs diff --git a/nanoFramework.System.Net/Properties/AssemblyInfo.cs b/nanoFramework.System.Net/Properties/AssemblyInfo.cs index f0a0e86..4010bb4 100644 --- a/nanoFramework.System.Net/Properties/AssemblyInfo.cs +++ b/nanoFramework.System.Net/Properties/AssemblyInfo.cs @@ -16,7 +16,7 @@ //////////////////////////////////////////////////////////////// // update this whenever the native assembly signature changes // -[assembly: AssemblyNativeVersion("100.2.0.12")] +[assembly: AssemblyNativeVersion("100.2.0.14")] //////////////////////////////////////////////////////////////// // Setting ComVisible to false makes the types in this assembly not visible diff --git a/nanoFramework.System.Net/Security/CryptographicException.cs b/nanoFramework.System.Net/Security/CryptographicException.cs new file mode 100644 index 0000000..aacf75f --- /dev/null +++ b/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; + + /// + /// The exception that is thrown when an error occurs during a + /// cryptographic operation. + /// + [Serializable] + public class CryptographicException : Exception + { + private int _errorCode; + + /// + /// Initializes a new instance of the class. + /// + public CryptographicException() + { + } + + /// + /// Initializes a new instance of the + /// class with a specified error code. + /// + /// The error code. + public CryptographicException(int errorCode) + { + _errorCode = errorCode; + } + + /// + /// Gets the error code that is associated with this exception. + /// + public int ErrorCode + { + get { return _errorCode; } + } + } +} diff --git a/nanoFramework.System.Net/Security/SslError.cs b/nanoFramework.System.Net/Security/SslError.cs new file mode 100644 index 0000000..8c92cb1 --- /dev/null +++ b/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 +{ + + + /// + /// Defines error codes returned by native SSL initialisation. + /// + /// + /// Values are kept in sync with the SSL_Error enum in the native interpreter + /// (ssl_functions.h). surfaces these + /// through + /// when SSL context setup fails. + /// + /// + public enum SslError : byte + { + /// No error; SSL context initialisation succeeded. + None = 0, + + /// + /// All SSL context slots are in use. + /// Close an existing SSL connection before opening a new one. + /// + NoFreeContext, + + /// + /// A memory allocation failed while setting up the SSL context. + /// The device may be low on heap. + /// + OutOfMemory, + + /// + /// The DRBG (Deterministic Random Bit Generator) seed step failed. + /// The entropy source could not be initialised. + /// + DrbgSeedFailed, + + /// + /// Setting TLS configuration defaults failed. + /// This is an internal mbedTLS error that should not occur under normal conditions. + /// + ConfigDefaultsFailed, + + /// + /// The requested TLS protocol version is not supported on this device. + /// Use a protocol version that the target hardware supports. + /// + UnsupportedProtocolVersion, + + /// + /// The supplied private key could not be parsed. + /// Verify the key is in a supported format (PEM or DER) and is not corrupted. + /// + PrivateKeyParseFailed, + + /// + /// The supplied certificate could not be parsed. + /// Verify the certificate is in a supported format (PEM or DER) and is not corrupted. + /// + CertificateParseFailed, + + /// + /// 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. + /// + OwnCertConfigFailed, + + /// + /// Final SSL context setup failed. + /// This is an internal mbedTLS error that should not occur under normal conditions. + /// + SetupFailed, + } +} diff --git a/nanoFramework.System.Net/Security/SslStream.cs b/nanoFramework.System.Net/Security/SslStream.cs index b14b91d..fa2ad22 100644 --- a/nanoFramework.System.Net/Security/SslStream.cs +++ b/nanoFramework.System.Net/Security/SslStream.cs @@ -65,18 +65,29 @@ public SslStream(Socket socket) } /// - /// 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. /// /// The name of the server that will share this SslStream. /// The value that represents the protocol used for authentication. + /// Authentication has already been performed on this stream, or all native SSL context slots are in. + /// A memory allocation failed while setting up the SSL context. The device may be low on heap. + /// + /// SSL context initialisation failed. The property contains the + /// corresponding value: + /// — entropy source could not be initialised; + /// — internal mbedTLS configuration error; + /// — the requested TLS version is not supported on this device; + /// — final SSL context setup failed. + /// + /// The TLS handshake with the remote server failed. public void AuthenticateAsClient(string targetHost, SslProtocols enabledSslProtocols) { Authenticate(false, targetHost, null, null, enabledSslProtocols); } /// - /// 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. /// /// The name of the server that will share this SslStream. @@ -85,13 +96,27 @@ public void AuthenticateAsClient(string targetHost, SslProtocols enabledSslProto /// /// Instead of providing the client certificate in the parameter the property can be used to use the certificate stored in the device. /// + /// Authentication has already been performed on this stream, or all native SSL context slots are in. + /// A memory allocation failed while setting up the SSL context. The device may be low on heap. + /// + /// SSL context initialisation failed. The property contains the + /// corresponding value: + /// — entropy source could not be initialised; + /// — internal mbedTLS configuration error; + /// — the requested TLS version is not supported on this device; + /// — the client certificate could not be parsed; + /// — the client private key could not be parsed; + /// — configuring the certificate/key pair on the SSL context failed; + /// — final SSL context setup failed. + /// + /// The TLS handshake with the remote server failed. public void AuthenticateAsClient(string targetHost, X509Certificate clientCertificate, SslProtocols enabledSslProtocols) { Authenticate(false, targetHost, clientCertificate, null, enabledSslProtocols); } /// - /// 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. /// /// The name of the server that will share this SslStream. @@ -101,13 +126,27 @@ public void AuthenticateAsClient(string targetHost, X509Certificate clientCertif /// /// Instead of providing the client certificate in the parameter the property can be used to use the certificate stored in the device. /// + /// Authentication has already been performed on this stream, or all native SSL context slots are in. + /// A memory allocation failed while setting up the SSL context. The device may be low on heap. + /// + /// SSL context initialisation failed. The property contains the + /// corresponding value: + /// — entropy source could not be initialised; + /// — internal mbedTLS configuration error; + /// — the requested TLS version is not supported on this device; + /// — the client or CA certificate could not be parsed; + /// — the client private key could not be parsed; + /// — configuring the certificate/key pair on the SSL context failed; + /// — final SSL context setup failed. + /// + /// The TLS handshake with the remote server failed. public void AuthenticateAsClient(string targetHost, X509Certificate clientCertificate, X509Certificate ca, SslProtocols enabledSslProtocols) { Authenticate(false, targetHost, clientCertificate, ca, enabledSslProtocols); } /// - /// 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. /// /// The certificate used to authenticate the server. @@ -115,6 +154,20 @@ public void AuthenticateAsClient(string targetHost, X509Certificate clientCertif /// /// Instead of providing the server certificate in the parameter the property can be used to use the certificate stored in the device. /// + /// Authentication has already been performed on this stream, or all native SSL context slots are in. + /// A memory allocation failed while setting up the SSL context. The device may be low on heap. + /// + /// SSL context initialisation failed. The property contains the + /// corresponding value: + /// — entropy source could not be initialised; + /// — internal mbedTLS configuration error; + /// — the requested TLS version is not supported on this device; + /// — the server certificate could not be parsed; + /// — the server private key could not be parsed; + /// — configuring the certificate/key pair on the SSL context failed; + /// — final SSL context setup failed. + /// + /// The TLS handshake with the remote client failed. 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. /// /// The X509Certificate used to authenticate the server. - /// A 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. + /// A 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. /// The protocols that may be used for authentication. /// /// Instead of providing the server certificate in the parameter the property can be used to use the certificate stored in the device. /// + /// Authentication has already been performed on this stream, or all native SSL context slots are in. + /// A memory allocation failed while setting up the SSL context. The device may be low on heap. + /// + /// SSL context initialisation failed. The property contains the + /// corresponding value: + /// — entropy source could not be initialised; + /// — internal mbedTLS configuration error; + /// — the requested TLS version is not supported on this device; + /// — the server certificate could not be parsed; + /// — the server private key could not be parsed; + /// — configuring the certificate/key pair on the SSL context failed; + /// — final SSL context setup failed. + /// + /// The TLS handshake with the remote client failed. public void AuthenticateAsServer(X509Certificate serverCertificate, bool clientCertificateRequired, SslProtocols enabledSslProtocols) { SslVerification = clientCertificateRequired ? SslVerification.VerifyClientOnce : SslVerification.NoVerification; @@ -227,7 +294,7 @@ public override bool DataAvailable /// Releases the unmanaged resources used by the SslStream and optionally releases the managed resources. /// /// true to release both managed and unmanaged resources; false to release only unmanaged resources. - [MethodImplAttribute(MethodImplOptions.Synchronized)] + [MethodImpl(MethodImplOptions.Synchronized)] protected override void Dispose(bool disposing) { if (!_disposed) diff --git a/nanoFramework.System.Net/System.Net.nfproj b/nanoFramework.System.Net/System.Net.nfproj index 250d6c3..39faf81 100644 --- a/nanoFramework.System.Net/System.Net.nfproj +++ b/nanoFramework.System.Net/System.Net.nfproj @@ -12,7 +12,8 @@ 474A90F4-FA98-4011-AABB-7DAC8E218E6A Library 512 - + + System.Net v1.0 True @@ -105,7 +106,9 @@ + +