SslStream Class

 

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.

Namespace:   System.Net.Security
Assembly:  System (in System.dll)

System.Object
  System.MarshalByRefObject
    System.IO.Stream
      System.Net.Security.AuthenticatedStream
        System.Net.Security.SslStream

Public Class SslStream
	Inherits AuthenticatedStream

NameDescription
System_CAPS_pubmethodSslStream(Stream)

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

System_CAPS_pubmethodSslStream(Stream, Boolean)

Initializes a new instance of the SslStream class using the specified Stream and stream closure behavior.

System_CAPS_pubmethodSslStream(Stream, Boolean, RemoteCertificateValidationCallback)

Initializes a new instance of the SslStream class using the specified Stream, stream closure behavior and certificate validation delegate.

System_CAPS_pubmethodSslStream(Stream, Boolean, RemoteCertificateValidationCallback, LocalCertificateSelectionCallback)

Initializes a new instance of the SslStream class using the specified Stream, stream closure behavior, certificate validation delegate and certificate selection delegate.

System_CAPS_pubmethodSslStream(Stream, Boolean, RemoteCertificateValidationCallback, LocalCertificateSelectionCallback, EncryptionPolicy)

Initializes a new instance of the SslStream class using the specified Stream

NameDescription
System_CAPS_pubpropertyCanRead

Gets a Boolean value that indicates whether the underlying stream is readable.(Overrides Stream.CanRead.)

System_CAPS_pubpropertyCanSeek

Gets a Boolean value that indicates whether the underlying stream is seekable.(Overrides Stream.CanSeek.)

System_CAPS_pubpropertyCanTimeout

Gets a Boolean value that indicates whether the underlying stream supports time-outs.(Overrides Stream.CanTimeout.)

System_CAPS_pubpropertyCanWrite

Gets a Boolean value that indicates whether the underlying stream is writable.(Overrides Stream.CanWrite.)

System_CAPS_pubpropertyCheckCertRevocationStatus

Gets a Boolean value that indicates whether the certificate revocation list is checked during the certificate validation process.

System_CAPS_pubpropertyCipherAlgorithm

Gets a value that identifies the bulk encryption algorithm used by this SslStream.

System_CAPS_pubpropertyCipherStrength

Gets a value that identifies the strength of the cipher algorithm used by this SslStream.

System_CAPS_pubpropertyHashAlgorithm

Gets the algorithm used for generating message authentication codes (MACs).

System_CAPS_pubpropertyHashStrength

Gets a value that identifies the strength of the hash algorithm used by this instance.

System_CAPS_protpropertyInnerStream

Gets the stream used by this AuthenticatedStream for sending and receiving data.(Inherited from AuthenticatedStream.)

System_CAPS_pubpropertyIsAuthenticated

Gets a Boolean value that indicates whether authentication was successful.(Overrides AuthenticatedStream.IsAuthenticated.)

System_CAPS_pubpropertyIsEncrypted

Gets a Boolean value that indicates whether this SslStream uses data encryption.(Overrides AuthenticatedStream.IsEncrypted.)

System_CAPS_pubpropertyIsMutuallyAuthenticated

Gets a Boolean value that indicates whether both server and client have been authenticated.(Overrides AuthenticatedStream.IsMutuallyAuthenticated.)

System_CAPS_pubpropertyIsServer

Gets a Boolean value that indicates whether the local side of the connection used by this SslStream was authenticated as the server.(Overrides AuthenticatedStream.IsServer.)

System_CAPS_pubpropertyIsSigned

Gets a Boolean value that indicates whether the data sent using this stream is signed.(Overrides AuthenticatedStream.IsSigned.)

System_CAPS_pubpropertyKeyExchangeAlgorithm

Gets the key exchange algorithm used by this SslStream.

System_CAPS_pubpropertyKeyExchangeStrength

Gets a value that identifies the strength of the key exchange algorithm used by this instance.

System_CAPS_pubpropertyLeaveInnerStreamOpen

Gets whether the stream used by this AuthenticatedStream for sending and receiving data has been left open.(Inherited from AuthenticatedStream.)

System_CAPS_pubpropertyLength

Gets the length of the underlying stream.(Overrides Stream.Length.)

System_CAPS_pubpropertyLocalCertificate

Gets the certificate used to authenticate the local endpoint.

System_CAPS_pubpropertyPosition

Gets or sets the current position in the underlying stream.(Overrides Stream.Position.)

System_CAPS_pubpropertyReadTimeout

Gets or sets the amount of time a read operation blocks waiting for data.(Overrides Stream.ReadTimeout.)

System_CAPS_pubpropertyRemoteCertificate

Gets the certificate used to authenticate the remote endpoint.

System_CAPS_pubpropertySslProtocol

Gets a value that indicates the security protocol used to authenticate this connection.

System_CAPS_pubpropertyTransportContext

Gets the TransportContext used for authentication using extended protection.

System_CAPS_pubpropertyWriteTimeout

Gets or sets the amount of time a write operation blocks waiting for data.(Overrides Stream.WriteTimeout.)

NameDescription
System_CAPS_pubmethodAuthenticateAsClient(String)

Called by clients to authenticate the server and optionally the client in a client-server connection.

System_CAPS_pubmethodAuthenticateAsClient(String, X509CertificateCollection, SslProtocols, Boolean)

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

System_CAPS_pubmethodAuthenticateAsClientAsync(String)

Called by clients to authenticate the server and optionally the client in a client-server connection as an asynchronous operation.

System_CAPS_pubmethodAuthenticateAsClientAsync(String, X509CertificateCollection, SslProtocols, Boolean)

Called by clients to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The authentication process uses the specified certificate collection and SSL protocol.

System_CAPS_pubmethodAuthenticateAsServer(X509Certificate)

Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificate.

System_CAPS_pubmethodAuthenticateAsServer(X509Certificate, Boolean, SslProtocols, Boolean)

Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates, requirements and security protocol.

System_CAPS_pubmethodAuthenticateAsServerAsync(X509Certificate)

Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificate as an asynchronous operation.

System_CAPS_pubmethodAuthenticateAsServerAsync(X509Certificate, Boolean, SslProtocols, Boolean)

Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates, requirements and security protocol as an asynchronous operation.

System_CAPS_pubmethodBeginAuthenticateAsClient(String, AsyncCallback, Object)

Called by clients to begin an asynchronous operation to authenticate the server and optionally the client.

System_CAPS_pubmethodBeginAuthenticateAsClient(String, X509CertificateCollection, SslProtocols, Boolean, AsyncCallback, Object)

Called by clients to begin an asynchronous operation to authenticate the server and optionally the client using the specified certificates and security protocol.

System_CAPS_pubmethodBeginAuthenticateAsServer(X509Certificate, AsyncCallback, Object)

Called by servers to begin an asynchronous operation to authenticate the client and optionally the server in a client-server connection.

System_CAPS_pubmethodBeginAuthenticateAsServer(X509Certificate, Boolean, SslProtocols, Boolean, AsyncCallback, Object)

Called by servers to begin an asynchronous operation to authenticate the server and optionally the client using the specified certificates, requirements and security protocol.

System_CAPS_pubmethodBeginRead(Byte(), Int32, Int32, AsyncCallback, Object)

Begins an asynchronous read operation that reads data from the stream and stores it in the specified array.(Overrides Stream.BeginRead(Byte(), Int32, Int32, AsyncCallback, Object).)

System_CAPS_pubmethodBeginWrite(Byte(), Int32, Int32, AsyncCallback, Object)

Begins an asynchronous write operation that writes Bytes from the specified buffer to the stream.(Overrides Stream.BeginWrite(Byte(), Int32, Int32, AsyncCallback, Object).)

System_CAPS_pubmethodClose()

Closes the current stream and releases any resources (such as sockets and file handles) associated with the current stream. Instead of calling this method, ensure that the stream is properly disposed.(Inherited from Stream.)

System_CAPS_pubmethodCopyTo(Stream)

Reads the bytes from the current stream and writes them to another stream.(Inherited from Stream.)

System_CAPS_pubmethodCopyTo(Stream, Int32)

Reads the bytes from the current stream and writes them to another stream, using a specified buffer size.(Inherited from Stream.)

System_CAPS_pubmethodCopyToAsync(Stream)

Asynchronously reads the bytes from the current stream and writes them to another stream.(Inherited from Stream.)

System_CAPS_pubmethodCopyToAsync(Stream, Int32)

Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size.(Inherited from Stream.)

System_CAPS_pubmethodCopyToAsync(Stream, Int32, CancellationToken)

Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size and cancellation token.(Inherited from Stream.)

System_CAPS_pubmethodCreateObjRef(Type)

Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.(Inherited from MarshalByRefObject.)

System_CAPS_protmethodCreateWaitHandle()

Obsolete.Allocates a WaitHandle object.(Inherited from Stream.)

System_CAPS_pubmethodDispose()

Releases all resources used by the Stream.(Inherited from Stream.)

System_CAPS_protmethodDispose(Boolean)

Releases the unmanaged resources used by the SslStream and optionally releases the managed resources. (Overrides AuthenticatedStream.Dispose(Boolean).)

System_CAPS_pubmethodEndAuthenticateAsClient(IAsyncResult)

Ends a pending asynchronous server authentication operation started with a previous call to BeginAuthenticateAsServer.

System_CAPS_pubmethodEndAuthenticateAsServer(IAsyncResult)

Ends a pending asynchronous client authentication operation started with a previous call to BeginAuthenticateAsClient.

System_CAPS_pubmethodEndRead(IAsyncResult)

Ends an asynchronous read operation started with a previous call to BeginRead.(Overrides Stream.EndRead(IAsyncResult).)

System_CAPS_pubmethodEndWrite(IAsyncResult)

Ends an asynchronous write operation started with a previous call to BeginWrite.(Overrides Stream.EndWrite(IAsyncResult).)

System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodFlush()

Causes any buffered data to be written to the underlying device.(Overrides Stream.Flush().)

System_CAPS_pubmethodFlushAsync()

Asynchronously clears all buffers for this stream and causes any buffered data to be written to the underlying device.(Inherited from Stream.)

System_CAPS_pubmethodFlushAsync(CancellationToken)

Asynchronously clears all buffers for this stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests.(Inherited from Stream.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetLifetimeService()

Retrieves the current lifetime service object that controls the lifetime policy for this instance.(Inherited from MarshalByRefObject.)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodInitializeLifetimeService()

Obtains a lifetime service object to control the lifetime policy for this instance.(Inherited from MarshalByRefObject.)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethodMemberwiseClone(Boolean)

Creates a shallow copy of the current MarshalByRefObject object.(Inherited from MarshalByRefObject.)

System_CAPS_protmethodObjectInvariant()

Obsolete. This API supports the product infrastructure and is not intended to be used directly from your code. Provides support for a Contract.(Inherited from Stream.)

System_CAPS_pubmethodRead(Byte(), Int32, Int32)

Reads data from this stream and stores it in the specified array.(Overrides Stream.Read(Byte(), Int32, Int32).)

System_CAPS_pubmethodReadAsync(Byte(), Int32, Int32)

Asynchronously reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.(Inherited from Stream.)

System_CAPS_pubmethodReadAsync(Byte(), Int32, Int32, CancellationToken)

Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.(Inherited from Stream.)

System_CAPS_pubmethodReadByte()

Reads a byte from the stream and advances the position within the stream by one byte, or returns -1 if at the end of the stream.(Inherited from Stream.)

System_CAPS_pubmethodSeek(Int64, SeekOrigin)

This API supports the product infrastructure and is not intended to be used directly from your code. Throws a NotSupportedException.(Overrides Stream.Seek(Int64, SeekOrigin).)

System_CAPS_pubmethodSetLength(Int64)

Sets the length of the underlying stream.(Overrides Stream.SetLength(Int64).)

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

System_CAPS_pubmethodWrite(Byte())

Writes the specified data to this stream.

System_CAPS_pubmethodWrite(Byte(), Int32, Int32)

Write the specified number of Bytes to the underlying stream using the specified buffer and offset.(Overrides Stream.Write(Byte(), Int32, Int32).)

System_CAPS_pubmethodWriteAsync(Byte(), Int32, Int32)

Asynchronously writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.(Inherited from Stream.)

System_CAPS_pubmethodWriteAsync(Byte(), Int32, Int32, CancellationToken)

Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests.(Inherited from Stream.)

System_CAPS_pubmethodWriteByte(Byte)

Writes a byte to the current position in the stream and advances the position within the stream by one byte.(Inherited from Stream.)

SSL protocols help to provide confidentiality and integrity checking for messages transmitted using an SslStream. An SSL connection, such as that provided by SslStream, should be used when communicating sensitive information between a client and a server. Using an SslStream helps to prevent anyone from reading and tampering with information while it is in transit on the network.

An SslStream instance transmits data using a stream that you supply when creating the SslStream. When you supply this underlying stream, you have the option to specify whether closing the SslStream also closes the underlying stream. Typically, the SslStream class is used with the TcpClient and TcpListener classes. The GetStream method provides a NetworkStream suitable for use with the SslStream class.

After creating an SslStream, the server and optionally, the client must be authenticated. The server must provide an X509 certificate that establishes proof of its identity and can request that the client also do so. Authentication must be performed before transmitting information using an SslStream. Clients initiate authentication using the synchronous AuthenticateAsClient methods, which block until the authentication completes, or the asynchronous BeginAuthenticateAsClient methods, which do not block waiting for the authentication to complete. Servers initiate authentication using the synchronous AuthenticateAsServer or asynchronous BeginAuthenticateAsServer methods. Both client and server must initiate the authentication.

The authentication is handled by the Security Support Provider (SSPI) channel provider. The client is given an opportunity to control validation of the server's certificate by specifying a RemoteCertificateValidationCallback delegate when creating an SslStream. The server can also control validation by supplying a RemoteCertificateValidationCallback delegate. The method referenced by the delegate includes the remote party's certificate and any errors SSPI encountered while validating the certificate. Note that if the server specifies a delegate, the delegate's method is invoked regardless of whether the server requested client authentication. If the server did not request client authentication, the server's delegate method receives a null certificate and an empty array of certificate errors.

If the server requires client authentication, the client must specify one or more certificates for authentication. If the client has more than one certificate, the client can provide a LocalCertificateSelectionCallback delegate to select the correct certificate for the server. The client's certificates must be located in the current user's "My" certificate store. Client authentication via certificates is not supported for the Ssl2 (SSL version 2) protocol.

If the authentication fails, you receive a AuthenticationException, and the SslStream is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector.

When the authentication process, also known as the SSL handshake, succeeds, the identity of the server (and optionally, the client) is established and the SslStream can be used by the client and server to exchange messages. Before sending or receiving information, the client and server should check the security services and levels provided by the SslStream to determine whether the protocol, algorithms, and strengths selected meet their requirements for integrity and confidentiality. If the current settings are not sufficient, the stream should be closed. You can check the security services provided by the SslStream using the IsEncrypted and IsSigned properties. The following table shows the elements that report the cryptographic settings used for authentication, encryption and data signing.

Element

Members

The security protocol used to authenticate the server and, optionally, the client.

The SslProtocol property and the associated SslProtocols enumeration.

The key exchange algorithm.

The KeyExchangeAlgorithm property and the associated ExchangeAlgorithmType enumeration.

The message integrity algorithm.

The HashAlgorithm property and the associated HashAlgorithmType enumeration.

The message confidentiality algorithm.

The CipherAlgorithm property and the associated CipherAlgorithmType enumeration.

The strengths of the selected algorithms.

The KeyExchangeStrength, HashStrength, and CipherStrength properties.

After a successful authentication, you can send data using the synchronous Write or asynchronous BeginWrite methods. You can receive data using the synchronous Read or asynchronous BeginRead methods.

If you specified to the SslStream that the underlying stream should be left open, you are responsible for closing that stream when you are done using it.

System_CAPS_noteNote

If the application that creates the SslStream object runs with the credentials of a Normal user, the application will not be able to access certificates installed in the local machine store unless permission has been explicitly given to the user to do so.

SslStream assumes that a timeout along with any other IOException when one is thrown from the inner stream will be treated as fatal by its caller. Reusing a SslStream instance after a timeout will return garbage. An application should Close the SslStream and throw an exception in these cases.

The .NET Framework 4.6 includes a new security feature that blocks insecure cipher and hashing algorithms for connections. Applications using TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, SslStream, etc. and targeting .NET Framework 4.6 get the more-secure behavior by default.

Developers may want to opt out of this behavior in order to maintain interoperability with their existing SSL3 services OR TLS w/ RC4 services. This article explains how to modify your code so that the new behavior is disabled.

The following code example demonstrates creating an TcpListener that uses the SslStream class to communicate with clients.

No code example is currently available or this language may not be supported.

The following code example demonstrates creating a TcpClient that uses the SslStream class to communicate with a server.

No code example is currently available or this language may not be supported.

.NET Framework
Available since 2.0

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: