Table of Contents

Class SslStream

Namespace
System.Net.Security
Assembly
System.Net.dll

Provides a stream used for client-server communication that uses the Secure Socket Layer (SSL) security protocol to authenticate the server and optionally the client.

public class SslStream : NetworkStream, IDisposable
Inheritance
SslStream
Implements
Inherited Members
Extension Methods

Constructors

SslStream(Socket)

Initializes a new instance of the SslStream class using the specified Socket.

public SslStream(Socket socket)

Parameters

socket Socket

A valid socket that currently has a TCP connection.

Remarks

The SslStream maintains the lifetime of the socket. When the SslStream object is disposed, the underlying TCP socket will be closed.

Properties

DataAvailable

Gets a value the indicates whether data is available in the stream. (Overrides NetworkStream. . :: . .DataAvailable.)

public override bool DataAvailable { get; }

Property Value

bool

IsServer

Gets a value that indicates whether the local side of the connection used by this SslStream was authenticated as the server.

public bool IsServer { get; }

Property Value

bool

Length

Gets the length of the stream. (Overrides NetworkStream. . :: . .Length.)

public override long Length { get; }

Property Value

long

SslVerification

Option for SSL verification. The default behaviour is CertificateRequired.

public SslVerification SslVerification { get; set; }

Property Value

SslVerification

UseStoredDeviceCertificate

Option to use the certificate stored in the device as client or server certificate. The default option is false.

public bool UseStoredDeviceCertificate { get; set; }

Property Value

bool

Remarks

This property is exclusive of .NET nanoFramework. In case there is no device certificate stored, the authentication will use whatever is provided (or not) in the parameter of the method being called.

Methods

AuthenticateAsClient(string, SslProtocols)

Called by clients to authenticate the server and optionally the client in a client-server connection. The authentication process uses the specified SSL protocols.

public void AuthenticateAsClient(string targetHost, SslProtocols enabledSslProtocols)

Parameters

targetHost string

The name of the server that will share this SslStream.

enabledSslProtocols SslProtocols

The SslProtocols value that represents the protocol used for authentication.

Exceptions

InvalidOperationException

Authentication has already been performed on this stream, or all native SSL context slots are in.

OutOfMemoryException

A memory allocation failed while setting up the SSL context. The device may be low on heap.

CryptographicException

SSL context initialisation failed. The ErrorCode property contains the corresponding SslError value: DrbgSeedFailed - entropy source could not be initialised; ConfigDefaultsFailed - internal mbedTLS configuration error; UnsupportedProtocolVersion - the requested TLS version is not supported on this device; SetupFailed - final SSL context setup failed.

InvalidOperationException

Thrown during the TLS handshake when: HandshakeBadContext - the SSL context was not valid; HandshakeSetHostname - setting the server hostname for SNI failed.

CryptographicException

Thrown during the TLS handshake. The ErrorCode property contains: for HandshakeCertVerifyFailed - the bitmask of MBEDTLS_X509_BADCERT_* verification flags; for HandshakeFailed - the raw negative mbedTLS error code.

AuthenticateAsClient(string, X509Certificate, SslProtocols)

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.

public void AuthenticateAsClient(string targetHost, X509Certificate clientCertificate, SslProtocols enabledSslProtocols)

Parameters

targetHost string

The name of the server that will share this SslStream.

clientCertificate X509Certificate

The client certificate.

enabledSslProtocols SslProtocols

The SslProtocols value that represents the protocol used for authentication.

Remarks

Instead of providing the client certificate in the clientCertificate parameter the UseStoredDeviceCertificate property can be used to use the certificate stored in the device.

Exceptions

InvalidOperationException

Authentication has already been performed on this stream, or all native SSL context slots are in.

OutOfMemoryException

A memory allocation failed while setting up the SSL context. The device may be low on heap.

CryptographicException

SSL context initialisation failed. The ErrorCode property contains the corresponding SslError value: DrbgSeedFailed - entropy source could not be initialised; ConfigDefaultsFailed - internal mbedTLS configuration error; UnsupportedProtocolVersion - the requested TLS version is not supported on this device; CertificateParseFailed - the client certificate could not be parsed; PrivateKeyParseFailed - the client private key could not be parsed; OwnCertConfigFailed - configuring the certificate/key pair on the SSL context failed; SetupFailed - final SSL context setup failed.

InvalidOperationException

Thrown during the TLS handshake when: HandshakeBadContext - the SSL context was not valid; HandshakeSetHostname - setting the server hostname for SNI failed.

CryptographicException

Thrown during the TLS handshake. The ErrorCode property contains: for HandshakeCertVerifyFailed - the bitmask of MBEDTLS_X509_BADCERT_* verification flags; for HandshakeFailed - the raw negative mbedTLS error code.

AuthenticateAsClient(string, X509Certificate, X509Certificate, SslProtocols)

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.

public void AuthenticateAsClient(string targetHost, X509Certificate clientCertificate, X509Certificate ca, SslProtocols enabledSslProtocols)

Parameters

targetHost string

The name of the server that will share this SslStream.

clientCertificate X509Certificate

The client certificate.

ca X509Certificate

Certificate Authority certificate to use for authentication with the server.

enabledSslProtocols SslProtocols

The SslProtocols value that represents the protocol used for authentication.

Remarks

Instead of providing the client certificate in the clientCertificate parameter the UseStoredDeviceCertificate property can be used to use the certificate stored in the device.

Exceptions

InvalidOperationException

Authentication has already been performed on this stream, or all native SSL context slots are in.

OutOfMemoryException

A memory allocation failed while setting up the SSL context. The device may be low on heap.

CryptographicException

SSL context initialisation failed. The ErrorCode property contains the corresponding SslError value: DrbgSeedFailed - entropy source could not be initialised; ConfigDefaultsFailed - internal mbedTLS configuration error; UnsupportedProtocolVersion - the requested TLS version is not supported on this device; CertificateParseFailed - the client or CA certificate could not be parsed; PrivateKeyParseFailed - the client private key could not be parsed; OwnCertConfigFailed - configuring the certificate/key pair on the SSL context failed; SetupFailed - final SSL context setup failed.

InvalidOperationException

Thrown during the TLS handshake when: HandshakeBadContext - the SSL context was not valid; HandshakeSetHostname - setting the server hostname for SNI failed.

CryptographicException

Thrown during the TLS handshake. The ErrorCode property contains: for HandshakeCertVerifyFailed - the bitmask of MBEDTLS_X509_BADCERT_* verification flags; for HandshakeFailed - the raw negative mbedTLS error code.

AuthenticateAsServer(X509Certificate, bool, 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.

public void AuthenticateAsServer(X509Certificate serverCertificate, bool clientCertificateRequired, SslProtocols enabledSslProtocols)

Parameters

serverCertificate X509Certificate

The X509Certificate used to authenticate the server.

clientCertificateRequired bool

A bool 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.

enabledSslProtocols SslProtocols

The protocols that may be used for authentication.

Remarks

Instead of providing the server certificate in the serverCertificate parameter the UseStoredDeviceCertificate property can be used to use the certificate stored in the device.

Exceptions

InvalidOperationException

Authentication has already been performed on this stream, or all native SSL context slots are in.

OutOfMemoryException

A memory allocation failed while setting up the SSL context. The device may be low on heap.

CryptographicException

SSL context initialisation failed. The ErrorCode property contains the corresponding SslError value: DrbgSeedFailed - entropy source could not be initialised; ConfigDefaultsFailed - internal mbedTLS configuration error; UnsupportedProtocolVersion - the requested TLS version is not supported on this device; CertificateParseFailed - the server certificate could not be parsed; PrivateKeyParseFailed - the server private key could not be parsed; OwnCertConfigFailed - configuring the certificate/key pair on the SSL context failed; SetupFailed - final SSL context setup failed.

InvalidOperationException

Thrown during the TLS handshake when HandshakeBadContext - the SSL context was not valid.

CryptographicException

Thrown during the TLS handshake. The ErrorCode property contains: for HandshakeCertVerifyFailed - the bitmask of MBEDTLS_X509_BADCERT_* verification flags (when client certificate verification is enabled); for HandshakeFailed - the raw negative mbedTLS error code.

AuthenticateAsServer(X509Certificate, SslProtocols)

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.

public void AuthenticateAsServer(X509Certificate serverCertificate, SslProtocols enabledSslProtocols)

Parameters

serverCertificate X509Certificate

The certificate used to authenticate the server.

enabledSslProtocols SslProtocols

The protocols that may be used for authentication.

Remarks

Instead of providing the server certificate in the serverCertificate parameter the UseStoredDeviceCertificate property can be used to use the certificate stored in the device.

Exceptions

InvalidOperationException

Authentication has already been performed on this stream, or all native SSL context slots are in.

OutOfMemoryException

A memory allocation failed while setting up the SSL context. The device may be low on heap.

CryptographicException

SSL context initialisation failed. The ErrorCode property contains the corresponding SslError value: DrbgSeedFailed - entropy source could not be initialised; ConfigDefaultsFailed - internal mbedTLS configuration error; UnsupportedProtocolVersion - the requested TLS version is not supported on this device; CertificateParseFailed - the server certificate could not be parsed; PrivateKeyParseFailed - the server private key could not be parsed; OwnCertConfigFailed - configuring the certificate/key pair on the SSL context failed; SetupFailed - final SSL context setup failed.

InvalidOperationException

Thrown during the TLS handshake when HandshakeBadContext - the SSL context was not valid.

CryptographicException

Thrown during the TLS handshake. The ErrorCode property contains: for HandshakeCertVerifyFailed - the bitmask of MBEDTLS_X509_BADCERT_* verification flags (when client certificate verification is enabled); for HandshakeFailed - the raw negative mbedTLS error code.

Dispose(bool)

Releases the unmanaged resources used by the SslStream and optionally releases the managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

Finalize() 

protected override void Finalize()

Read(byte[], int, int)

Reads data from this stream and stores it in the specified array.

public override int Read(byte[] buffer, int offset, int size)

Parameters

buffer byte[]

An array that receives the bytes read from this stream.

offset int

An integer that contains the zero-based location in buffer at which to begin storing the data read from this stream.

size int

The maximum number of bytes to read from this stream.

Returns

int

Write(byte[], int, int)

Write the specified number of bytes to the underlying stream using the specified buffer and offset.

public override void Write(byte[] buffer, int offset, int size)

Parameters

buffer byte[]

An array that supplies the bytes written to the stream.

offset int

he zero-based location in buffer at which to begin reading bytes to be written to the stream.

size int

The number of bytes to read from buffer.

Exceptions

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

offset or size is less than zero

-or-

offset is greater than the length of buffer.

-or-

offset + size is greater than the length of buffer.

ObjectDisposedException

The stream has been disposed.

IOException

The write operation failed.