Export (0) Print
Expand All

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)

'Declaration
Public Class SslStream _
	Inherits AuthenticatedStream

The SslStream type exposes the following members.

  NameDescription
Public methodSslStream(Stream)Initializes a new instance of the SslStream class using the specified Stream.
Public methodSslStream(Stream, Boolean)Initializes a new instance of the SslStream class using the specified Stream and stream closure behavior.
Public methodSslStream(Stream, Boolean, RemoteCertificateValidationCallback)Initializes a new instance of the SslStream class using the specified Stream, stream closure behavior and certificate validation delegate.
Public methodSslStream(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.
Public methodSslStream(Stream, Boolean, RemoteCertificateValidationCallback, LocalCertificateSelectionCallback, EncryptionPolicy)Initializes a new instance of the SslStream class using the specified Stream
Top

  NameDescription
Public propertyCanReadGets a Boolean value that indicates whether the underlying stream is readable. (Overrides Stream.CanRead.)
Public propertyCanSeekGets a Boolean value that indicates whether the underlying stream is seekable. (Overrides Stream.CanSeek.)
Public propertyCanTimeoutGets a Boolean value that indicates whether the underlying stream supports time-outs. (Overrides Stream.CanTimeout.)
Public propertyCanWriteGets a Boolean value that indicates whether the underlying stream is writable. (Overrides Stream.CanWrite.)
Public propertyCheckCertRevocationStatusGets a Boolean value that indicates whether the certificate revocation list is checked during the certificate validation process.
Public propertyCipherAlgorithmGets a value that identifies the bulk encryption algorithm used by this SslStream.
Public propertyCipherStrengthGets a value that identifies the strength of the cipher algorithm used by this SslStream.
Public propertyHashAlgorithmGets the algorithm used for generating message authentication codes (MACs).
Public propertyHashStrengthGets a value that identifies the strength of the hash algorithm used by this instance.
Protected propertyInnerStreamGets the stream used by this AuthenticatedStream for sending and receiving data. (Inherited from AuthenticatedStream.)
Public propertyIsAuthenticatedGets a Boolean value that indicates whether authentication was successful. (Overrides AuthenticatedStream.IsAuthenticated.)
Public propertyIsEncryptedGets a Boolean value that indicates whether this SslStream uses data encryption. (Overrides AuthenticatedStream.IsEncrypted.)
Public propertyIsMutuallyAuthenticatedGets a Boolean value that indicates whether both server and client have been authenticated. (Overrides AuthenticatedStream.IsMutuallyAuthenticated.)
Public propertyIsServerGets a Boolean value that indicates whether the local side of the connection used by this SslStream was authenticated as the server. (Overrides AuthenticatedStream.IsServer.)
Public propertyIsSignedGets a Boolean value that indicates whether the data sent using this stream is signed. (Overrides AuthenticatedStream.IsSigned.)
Public propertyKeyExchangeAlgorithmGets the key exchange algorithm used by this SslStream.
Public propertyKeyExchangeStrengthGets a value that identifies the strength of the key exchange algorithm used by this instance.
Public propertyLeaveInnerStreamOpenGets whether the stream used by this AuthenticatedStream for sending and receiving data has been left open. (Inherited from AuthenticatedStream.)
Public propertyLengthGets the length of the underlying stream. (Overrides Stream.Length.)
Public propertyLocalCertificateGets the certificate used to authenticate the local endpoint.
Public propertyPositionGets or sets the current position in the underlying stream. (Overrides Stream.Position.)
Public propertyReadTimeoutGets or sets the amount of time a read operation blocks waiting for data. (Overrides Stream.ReadTimeout.)
Public propertyRemoteCertificateGets the certificate used to authenticate the remote endpoint.
Public propertySslProtocolGets a value that indicates the security protocol used to authenticate this connection.
Public propertyTransportContextGets the TransportContext used for authentication using extended protection.
Public propertyWriteTimeoutGets or sets the amount of time a write operation blocks waiting for data. (Overrides Stream.WriteTimeout.)
Top

  NameDescription
Public methodAuthenticateAsClient(String)Called by clients to authenticate the server and optionally the client in a client-server connection.
Public methodAuthenticateAsClient(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.
Public methodAuthenticateAsClientAsync(String)Called by clients to authenticate the server and optionally the client in a client-server connection as an asynchronous operation.
Public methodAuthenticateAsClientAsync(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.
Public methodAuthenticateAsServer(X509Certificate)Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificate.
Public methodAuthenticateAsServer(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.
Public methodAuthenticateAsServerAsync(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.
Public methodAuthenticateAsServerAsync(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.
Public methodBeginAuthenticateAsClient(String, AsyncCallback, Object)Called by clients to begin an asynchronous operation to authenticate the server and optionally the client.
Public methodBeginAuthenticateAsClient(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.
Public methodBeginAuthenticateAsServer(X509Certificate, AsyncCallback, Object)Called by servers to begin an asynchronous operation to authenticate the client and optionally the server in a client-server connection.
Public methodBeginAuthenticateAsServer(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.
Public methodBeginReadBegins 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).)
Public methodBeginWriteBegins an asynchronous write operation that writes Bytes from the specified buffer to the stream. (Overrides Stream.BeginWrite(Byte(), Int32, Int32, AsyncCallback, Object).)
Public methodCloseCloses 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.)
Public methodCopyTo(Stream)Reads the bytes from the current stream and writes them to another stream. (Inherited from Stream.)
Public methodCopyTo(Stream, Int32)Reads the bytes from the current stream and writes them to another stream, using a specified buffer size. (Inherited from Stream.)
Public methodCopyToAsync(Stream)Asynchronously reads the bytes from the current stream and writes them to another stream. (Inherited from Stream.)
Public methodCopyToAsync(Stream, Int32)Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size. (Inherited from Stream.)
Public methodCopyToAsync(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.)
Public methodCreateObjRefCreates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
Protected methodCreateWaitHandle Obsolete. Allocates a WaitHandle object. (Inherited from Stream.)
Public methodDisposeReleases all resources used by the Stream. (Inherited from Stream.)
Protected methodDispose(Boolean)Releases the unmanaged resources used by the SslStream and optionally releases the managed resources. (Overrides AuthenticatedStream.Dispose(Boolean).)
Public methodEndAuthenticateAsClientEnds a pending asynchronous server authentication operation started with a previous call to BeginAuthenticateAsServer.
Public methodEndAuthenticateAsServerEnds a pending asynchronous client authentication operation started with a previous call to BeginAuthenticateAsClient.
Public methodEndReadEnds an asynchronous read operation started with a previous call to BeginRead. (Overrides Stream.EndRead(IAsyncResult).)
Public methodEndWriteEnds an asynchronous write operation started with a previous call to BeginWrite. (Overrides Stream.EndWrite(IAsyncResult).)
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodFlushCauses any buffered data to be written to the underlying device. (Overrides Stream.Flush.)
Public methodFlushAsyncAsynchronously clears all buffers for this stream and causes any buffered data to be written to the underlying device. (Inherited from Stream.)
Public methodFlushAsync(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.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetLifetimeServiceRetrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodInitializeLifetimeServiceObtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodMemberwiseClone(Boolean)Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
Protected methodObjectInvariantInfrastructure. Obsolete. Provides support for a Contract. (Inherited from Stream.)
Public methodReadReads data from this stream and stores it in the specified array. (Overrides Stream.Read(Byte(), Int32, Int32).)
Public methodReadAsync(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.)
Public methodReadAsync(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.)
Public methodReadByteReads 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.)
Public methodSeekInfrastructure. Throws a NotSupportedException. (Overrides Stream.Seek(Int64, SeekOrigin).)
Public methodSetLengthSets the length of the underlying stream. (Overrides Stream.SetLength(Int64).)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodWrite(Byte())Writes the specified data to this stream.
Public methodWrite(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).)
Public methodWriteAsync(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.)
Public methodWriteAsync(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.)
Public methodWriteByteWrites a byte to the current position in the stream and advances the position within the stream by one byte. (Inherited from Stream.)
Top

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.

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 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

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

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