.tlshandshake Method

Function:

For the currently selected socket (selection is made through sock.num), initiates the TLS handshake process to upgrade the socket to an encrypted connection.

Syntax:

sock.tlshandshake(byref server_name as string) as enum

Returns:

0 — PL_TLS_SUCCESS — Initialization was completed successfully

1 — PL_TLS_REJECTED — Initialization attempt was rejected

2 — PL_TLS_ERROR_IN_USE — TLS is already in use on another socket

See Also:

Transport Layer Security (TLS), Establishing a Secure Connection


Parameter

Description

server_name

The fully qualified domain name of the designated server.

Details

This method's sole parameter, server_name, requires a fully qualified domain name (i.e., everything after "https://" up to the first forward slash). If you do not want to verify the server name against the certificate, pass an empty string — this is useful when connecting directly to an IP address.

Attempting to call sock.tlshandshake on a socket other than the one on which sock.tlsinit was executed will return PL_TLS_ERROR_IN_USE.

Additionally, calling sock.tlshandshake will result in PL_TLS_REJECTED in the following scenarios:

  • The selected protocol is not TCP (sock.protocol <> PL_SOCK_PROTOCOL_TCP)
  • The TCP connection is not an outgoing connection (sock.state <> PL_SST_EST_AOPENED)
  • sock.tlsinit has not been executed on any socket ( sock.tlscurrentnum = 255)

Even if sock.tlshandshake returns PL_TLS_SUCCESS, the creation of the secure connection may still fail due to a number of reasons. The final and definitive indicator of the successful establishment of the TLS link is the transition of sock.state into PL_SST_EST_TLS.