Xojo Documentation 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 Handle SSLConnected BytesAvailable IsConnected SSLConnecting BytesLeftToSend LocalAddress SSLConnectionType CertificateFile NetworkInterface SSLEnabled CertificatePassword Port CertificateRejectionFile RemoteAddress

Methods

Close Listen Purge Connect Lookahead ReadAll Disconnect Poll

Notes

To establish an SSL connection, set the SSLEnabled 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.