Skip to main content
StreamSocket.UpgradeToSslAsync | upgradeToSslAsync method

Applies to Windows and Windows Phone

Starts an asynchronous operation to upgrade a connected socket to use SSL on a StreamSocket object.

Syntax


streamSocket.upgradeToSslAsync(protectionLevel, validationHostName).done( /* Your success and error handlers */ );

public IAsyncAction UpgradeToSslAsync(
  SocketProtectionLevel protectionLevel, 
  HostName validationHostName
)

Public Function UpgradeToSslAsync(
  protectionLevel As SocketProtectionLevel,  
  validationHostName As HostName 
) As IAsyncAction

public:
IAsyncAction^ UpgradeToSslAsync(
  SocketProtectionLevel protectionLevel, 
  HostName^ validationHostName
)

Parameters

protectionLevel

Type: SocketProtectionLevel

The protection level that represents the integrity and encryption on the StreamSocket object.

validationHostName

Type: HostName

The hostname of the remote network destination that is used for validation when upgrading to SSL.

Return value

Type: IAsyncAction

An asynchronous operation to upgrade to use SSL on a StreamSocket object.

Remarks

The UpgradeToSslAsync method can only be used to upgrade an already established connection made with a SocketProtectionLevel of PlainSocket.

The typical order of operations to establish an SSL connection is as follows:

  • Create the StreamSocket.
  • Get socket control data on a StreamSocketControl object using the Control property and set any properties before calling one of the ConnectAsync methods.
  • Call one of the ConnectAsync methods to establish a connection with the remote endpoint. If an SSL/TLS connection is required immediately, this can be specified using some of the ConnectAsync methods. If an SSL/TLS connection is desired after sending and receiving some initial data, then the UpgradeToSslAsync method can be called later to upgrade the connection to use SSL.
  • Get the OutputStream property to write data to the remote host.
  • Get the InputStream property to read data from the remote host.
  • Read and write data as needed.
  • Call the Close method to abort any pending operations and release all unmanaged resources associated with the StreamSocket object.

The UpgradeToSslAsync method requires that the remote server to which the connection was established is able to upgrade a TCP connection to an SSL connection.

The UpgradeToSslAsync method can only be used for client connections. This method can't be used to upgrade a connection accepted by the StreamSocketListener to an SSL connection. The UpgradeToSslAsync method only implements the client parts of the SSL protocol negotiation, not the server parts that would be needed to listen for and accept SSL connections.

The UpgradeToSslAsync method does not support the use of client certificates.

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8

Namespace

Windows.Networking.Sockets
Windows::Networking::Sockets [C++]

Metadata

Windows.winmd

DLL

Windows.Networking.dll

Capabilities

ID_CAP_NETWORKING [Windows Phone]

See also

HostName
How to secure socket connections with TLS/SSL
SocketProtectionLevel
StreamSocket