Class

class TlsSessionContext

public class TlsSessionContext <: Equatable<TlsSessionContext> & ToString

Description: This class indicates the TLS session context and provides information for the client to ensure that the server connected to the client is the same instance, and is used to verify the validity of the client during connection reuse.

Note:

When a client attempts to resume a session, both parties must ensure that they are resuming the session with an authorized peer.

Parent Type:

static func fromName(String)

public static func fromName(name: String): TlsSessionContext

Description: Creates a TlsSessionContext instance by name.

Obtains the TlsSessionContext object through the name saved by TlsSessionContext. This name is used to distinguish TLS servers so clients rely on this name to avoid accidental attempts to resume connection to the wrong server. It is not necessarily to use crypto-secure names here as the underlying implementation does the job. Two TlsSessionContext instances returned from this function with the same name could be non-equal and not guaranteed to be replaceable despite the same name they are created from. Although they are created from the same name, the server instance should create a TlsSessionContext throughout the lifecycle and use it with every TlsSocket.server() calling.

Parameters:

  • name: String: session context name

Returns:

func toString()

public override func toString(): String

Description: Generates a session context name string.

Returns:

operator func !=(TlsSessionContext)

public override operator func !=(other: TlsSessionContext)

Description: Checks whether the names of two TlsSessionContext instances are different.

Parameters:

Returns:

  • Unit: If the names of the two TlsSessionContext objects are different, true is returned. Otherwise, false is returned.

operator func ==(TlsSessionContext)

public override operator func ==(other: TlsSessionContext)

Description: Checks whether the names of two TlsSessionContext instances are the same.

Parameters:

Returns:

  • Unit: If the names of the two TlsSessionContext objects are the same, true is returned. Otherwise, false is returned.

class TlsSocket

public class TlsSocket <: StreamingSocket & ToString & Equatable<TlsSocket> & Hashable

Description: TlsSocket is used to create an encrypted transmission channel between a client and server.

Parent Type:

prop alpnProtocolName

public prop alpnProtocolName: ?String

Description: Reads the negotiated application layer protocol name.

Type: ?String

Throws:

  • TlsException: If the TLS handshake on socket is not complete or the local TLS socket is closed, this exception is thrown.
  • IllegalMemoryException: If memory allocation fails, this exception is thrown.

prop cipherSuite

public prop cipherSuite: CipherSuite

Description: Gets the cipher suite negotiated after a handshake.

Note:

The cipher suite includes an encryption algorithm, a hash function used for message authentication, and a key exchange algorithm.

Type: CipherSuite

Throws:

  • TlsException: If the TLS handshake on socket is not complete or the local TLS socket is closed, this exception is thrown.

prop clientCertificate

public prop clientCertificate: ?Array<X509Certificate>

Description: Obtains the client certificate provided by the client. On a client, it is the local certificate. On a server, it is the peer certificate.

Note:

If the peer end does not send a certificate, the API may fail to obtain the peer certificate and None is returned. For details, see peerCertificate.

Type: ?Array<X509Certificate>

Throws:

  • TlsException: If the TLS handshake on socket is not complete or the local TLS socket is closed, this exception is thrown.

prop domain

public prop domain: ?String

Description: Reads the negotiated server host name.

  • TlsException: If the TLS handshake on socket is not complete or the local TLS socket is closed, this exception is thrown.

Type: ?String

prop localAddress

public override prop localAddress: SocketAddress

Description: Reads the local address of TlsSocket.

Type: SocketAddress

Throws:

  • SocketException: If the underlying TCP socket is closed on the local end, this exception is thrown.
  • TlsException: If the TLS socket on the local end is closed, this exception is thrown.

prop peerCertificate

public prop peerCertificate: ?Array<X509Certificate>

Description: Obtains the peer certificate. On a client, this function is the same as that of serverCertificate. On a server, this function is the same as that of clientCertificate on the server.

Note:

  • If the peer end is not required to send the certificate during the handshake, the peer certificate cannot be obtained and None is returned.

  • When the session mechanism is used to restore the connection, neither party sends the certificate. The API behavior is as follows:

    • On the server, if the peer certificate is obtained when the original connection is restored, the server caches the peer certificate and obtains the cached certificate.
    • On the client, the peer certificate of the original connection is not cached. In this case, the peer certificate cannot be obtained and None is returned.

Type: ?Array<X509Certificate>

Throws:

  • TlsException: If the TLS handshake on socket is not complete or the local TLS socket is closed, this exception is thrown.

prop readTimeout

public override mut prop readTimeout: ?Duration

Description: Sets and obtains the read timeout for reading and writing TlsSocket.

Type: ?Duration

Throws:

  • SocketException: If the underlying TCP socket is closed on the local end, this exception is thrown.
  • TlsException: If the TLS socket on the local end is closed, this exception is thrown.
  • IllegalArgumentException: If the set read timeout is negative, this exception is thrown.

prop remoteAddress

public override prop remoteAddress: SocketAddress

Description: Reads the remote address of TlsSocket.

Type: SocketAddress

Throws:

  • SocketException: If the underlying TCP socket is closed on the local end, this exception is thrown.
  • TlsException: If the TLS socket on the local end is closed, this exception is thrown.

prop serverCertificate

public prop serverCertificate: Array<X509Certificate>

Description: The server certificate chain is provided by the server or preconfigured in the server configuration. On a server, it is the local certificate obtained from the client. On a client, it is the peer certificate obtained from the server.

Note:

If the peer end does not send a certificate, the API may fail to obtain the peer certificate and None is returned. For details, see peerCertificate.

Type: Array<X509Certificate>

Throws:

  • TlsException: If the TLS handshake on socket is not complete or the local TLS socket is closed, this exception is thrown.

prop session

public prop session: ?TlsSession

Description: Reads the TLS session ID. After the handshake is successful, the client captures the ID of the current session. The ID can be used to reuse the session, saving the time for establishing a TLS connection. If the connection fails to be established, None is returned.

Note:

The server does not capture the ID of the current session. Therefore, the value is always None.

Type: ?TlsSession

Throws:

  • TlsException: If the TLS handshake on socket is not complete, this exception is thrown.

prop socket

public prop socket: StreamingSocket

Description: Obtains StreamingSocket used for TlsSocket creation.

Type: StreamingSocket

Throws:

  • TlsException: If the TLS socket on the local end is closed, this exception is thrown.

prop tlsVersion

public prop tlsVersion: TlsVersion

Description: Reads the negotiated TLS version.

Type: TlsVersion

Throws:

  • TlsException: If the TLS handshake on socket is not complete or the local TLS socket is closed, this exception is thrown.

prop writeTimeout

public override mut prop writeTimeout: ?Duration

Description: Sets and obtains the write timeout for reading and writing TlsSocket.

Type: ?Duration

Throws:

  • SocketException: If the underlying TCP socket is closed on the local end, this exception is thrown.
  • TlsException: If the TLS socket on the local end is closed, this exception is thrown.
  • IllegalArgumentException: If the set write timeout is negative, this exception is thrown.

static func client(StreamingSocket, ?TlsSession, TlsClientConfig)

public static func client(
    socket: StreamingSocket,
    session!: ?TlsSession = None,
    clientConfig!: TlsClientConfig = TlsClientConfig()
): TlsSocket

Description: Creates a client TLS socket at a specified address according to the passed StreamingSocket instance. The socket can be used for client TLS handshakes and sessions.

Parameters:

  • socket: StreamingSocket: client TCP socket that has connected to the server
  • session!: ?TlsSession: TLS session ID. If there is available TLS session, this ID can be used to restore the historical TLS session, saving the time for establishing a TLS connection. However, negotiation may still fail even this session is used. The default value is None.
  • clientConfig!: TlsClientConfig: client configuration. The default value is TlsClientConfig().

Returns:

static func server(StreamingSocket, ?TlsSessionContext, TlsServerConfig)

public static func server(
    socket: StreamingSocket,
    sessionContext!: ?TlsSessionContext = None,
    serverConfig!: TlsServerConfig
): TlsSocket

Description: Creates a server TLS socket at a specified address according to the passed StreamingSocket instance. The socket can be used for server TLS handshakes and sessions.

Parameters:

  • socket: StreamingSocket: socket received after the TCP connection is established.
  • sessionContext!: ?TlsSessionContext: TLS session ID. If there is available TLS session, this ID can be used to restore the historical TLS session, saving the time for establishing a TLS connection. However, negotiation may still fail even this session is used. The default value is None.
  • serverConfig!: TlsServerConfig: server configuration. The default value is TlsServerConfig().

Returns:

func close()

public func close(): Unit

Description: Closes a socket.

Throws:

  • SocketException: If the underlying connection cannot be closed, this exception is thrown.

func handshake(?Duration)

public func handshake(timeout!: ?Duration = None): Unit

Function: Performs a TLS handshake. Renegotiation handshake is not supported. Therefore, this function can be called only once. The called object can be TlsSocket of the client or server.

Parameters:

  • timeout!: ?Duration: handshake timeout. The default value is None. In this case, the timeout is not set, and the default timeout (30s) is used.

Throws:

  • SocketException: If the underlying TCP socket is closed on the local end, this exception is thrown.
  • SocketTimeoutException: If the underlying TCP socket connection times out, this exception is thrown.
  • TlsException: When the handshake starts or ends or when a system error occurs during the handshake, this exception is thrown.
  • IllegalArgumentException: If the set handshake timeout is negative, this exception is thrown.

func hashCode()

public override func hashCode(): Int64

Description: Returns the hash value of the TLS socket object.

Returns:

  • Int64: result obtained after hash calculation is performed on the TLS socket object

func isClosed()

public func isClosed(): Bool

Description: Indicates whether the socket is closed.

Returns:

  • Bool: If the socket is closed, true is returned. Otherwise, false is returned.

func read(Array<Byte>)

public override func read(buffer: Array<Byte>): Int64

Description: Reads data from TlsSocket.

Parameters:

  • buffer: Array<Byte>: array for storing the read data

Returns:

  • Int64: number of bytes of the data read

Throws:

  • SocketException: If the underlying TCP socket is closed on the local end, this exception is thrown.
  • TlsException: If buffer is empty, TlsSocket is not connected, or a system error occurs when data is read, this exception is thrown.

func toString()

public func toString(): String

Description: Obtains the string representation of a socket. The string content indicates the current socket status.

Note:

For example, when the current socket is ready for handshake, the API returns "TlsSocket(TcpSocket (${local address} - > ${peer address}), ready for handshake)".

Returns:

  • String: TLS connection string

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

Description: Writes data to TlsSocket.

Parameters:

  • buffer: Array<Byte>: array for storing the data to be sent

Throws:

  • SocketException: If the underlying TCP socket is closed on the local end, this exception is thrown.
  • TlsException: If the socket is closed, TlsSocket is not connected, or a system error occurs when data is written, this exception is thrown.

operator func !=(TlsSocket)

public override operator func !=(other: TlsSocket)

Description: Checks whether two TlsSocket sockets reference different instances.

Parameters:

  • other: TlsSocket: the other TLS socket to be compared with

Returns:

  • Unit: If the two instances compared are different, true is returned. Otherwise, false is returned.

operator func ==(TlsSocket)

public override operator func ==(other: TlsSocket)

Description: Check whether two TlsSocket sockets reference the same instance.

Parameters:

  • other: TlsSocket: the other TLS socket to be compared with

Returns:

  • Unit: If the two instances compared are the same, true is returned. Otherwise, false is returned.