SSLSocket

From Xojo Documentation

Class (inherits from TCPSocket)

Use the SSLSocket class to do secure communications via TCP/IP using secure sockets layer (SSL) technology.


Events
Connected Error SendProgress
DataAvailable SendComplete


Properties
Address ConnectionType Port
BytesAvailable fa-lock-32.png Handle fa-lock-32.png RemoteAddress fa-lock-32.png
BytesLeftToSend fa-lock-32.png IsConnected fa-lock-32.png SSLConnected fa-lock-32.png
CertificateFile LastErrorCode fa-lock-32.png SSLConnecting fa-lock-32.png
CertificatePassword LocalAddress fa-lock-32.png Secure
CertificateRejectionFile NetworkInterface


Methods
Close Listen Purge
Connect Lookahead ReadAll
Disconnect Poll

Class Constants

The following class constants can be used to specify the value of the ConnectionType property.

Class Constant Value Description
SSLv23 1 A TLS/SSL connection established with this constant may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. If extensions are required (for example server name) a client will send out TLSv1 client hello messages including extensions and will indicate that it also understands TLSv1.1, TLSv1.2 and permits a fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best choice when compatibility is a concern.
TLSv1 3 TLS (Transport Layer Security) version 1. (default)
TLSv11 4 TLS (Transport Layer Security) version 1.1
TLSv12 5 TLS (Transport Layer Security) version 1.2

Notes

To establish an SSL connection, set the Secure property to True and use the Connect method. SSLSocket supports secure listening sockets.

The SSLSocket control is not listed in the Controls pane in the Window Editor. There are two ways to add an SSLSocket control to a window:

  • Drag a TCPSocket control to a window and then change its Super class to SSLSocket.
  • Display the window's contextual menu by right+clicking (Windows and Linux) or control-clicking on the window (Macintosh) and then choosing Add ↠ SocketCore ↠ TCPSocket ↠ SSLSocket.

The SSLSocket control can be instantiated via code since it is not a subclass of Control. This allows you to easily write code that does communications without adding the control to a window.

Writing to a socket is done asynchronously. This means each time the Write method is called, the data passed goes into a buffer in memory before actually being sent and then removed from the buffer. Once the socket has finished sending the data in the buffer to the computer at the other end of the socket connection, the SendComplete event handler is executed. This allows you to know when all of the data has really been sent.

Calling Read, ReadAll, or Lookahead may not fetch all of the data in the internal buffer. This is because SSL needs to read data in blocks (due to the cryptography), and it may not have a complete block in the buffer. For example, there may be 700 bytes available in the buffer, but SSL can only decrypt 512 bytes due to the remainder being an incomplete block. What occurs in this case is some data may remain stagnant in the buffer. When more data comes in, the DataAvailable event handler is called. If there are no more DataAvailable events, then upon disconnection, additional DataAvailable event will be issued to let you pick up any stagnant data that SSL can give us back. There are two things to watch out for because of this:

  1. If there is not sufficient data for SSL to decrypt, you may get a DataAvailable event but no data.
  2. Calling SSLSocket.Close may execute DataAvailable events.

When using an SSLSocket to Listen for a connection, you must specify a CertificateFile. For Linux and macOS the certificate should contain both the public and private keys, like this:

 -----BEGIN RSA PRIVATE KEY-----
 …Certificate Data Here...
 -----END RSA PRIVATE KEY-----
 
 -----BEGIN CERTIFICATE-----
 …Certificate Data Here...
 -----END CERTIFICATE-----

Xojo Cloud

Web apps running on Xojo Cloud first have to use the FirewallPort class to open the port used to connect to TCP externally.

See Also

SocketCore, TCPSocket, ServerSocket classes.