TLSClient Class

Properties   Methods   Events   Config Settings   Errors  

The TLSClient class provides client-side functionality of the TLS protocol.

Syntax

secureblackbox.Tlsclient

Remarks

Use this component to set up secure connections from your application.

TLSClient offers comprehensive support for all versions of the TLS protocol, including the most popular TLS 1.2 and the newest TLS 1.3. Among other features this component can offer are:

• Certificate-based and PSK authentication types are supported, making this component the ideal fit for all sorts of Internet environments.
• Support for efficient reconnections using TLS session resume approach.
• Comprehensive support for all existing cipher suites.
• DH and Elliptic Curve key exchange algorithms.
• Support for SNI, Extended Master Secret, Cookie, and other protocol extensions included as standard.
• Support for secure renegotiation.
• Resistant to all known TLS attacks (heartbleed, POODLE, BEAST, and others).

With TLS mode switched off, this component turns to an efficient TCP socket client.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

BlockedCertificates Property (TLSClient Class)

The certificates that must be rejected as trust anchors.

Syntax

public CertificateList getBlockedCertificates();


public void setBlockedCertificates(CertificateList blockedCertificates);

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ClientChain Property (TLSClient Class)

The TLS client certificate chain.

Syntax

public CertificateList getClientChain();


public void setClientChain(CertificateList clientChain);

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the class. Note that the client's end-entity certificate should have a private key associated with it.

Use CertificateStorage or CertificateManager components to import the certificate from a file, system store, or PKCS11 device.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Connected Property (TLSClient Class)

Indicates whether the connection is active.

Syntax

public boolean isConnected();

Default Value

False

Remarks

Use this property to check if the connection is alive.

This property is read-only and not available at design time.

ConnectionInfo Property (TLSClient Class)

Returns the details of the underlying network connection.

Syntax

public ConnectionInfo getConnectionInfo();

Remarks

Use this property to learn about the connection setup, such as the protocol security details and amounts of data transferred each way.

This property is read-only and not available at design time.

Please refer to the ConnectionInfo type for a complete list of fields.

ErrorOrigin Property (TLSClient Class)

Indicates the endpoint where the error originates from.

Syntax

public int getErrorOrigin();


public void setErrorOrigin(int errorOrigin);


Enumerated values:
  public final static int eoLocal = 0;
  public final static int eoRemote = 1;

Default Value

0

Remarks

Use this property to establish whether the reported error originates from a local or remote endpoint.

This property is not available at design time.

ErrorSeverity Property (TLSClient Class)

The severity of the error that happened.

Syntax

public int getErrorSeverity();


public void setErrorSeverity(int errorSeverity);


Enumerated values:
  public final static int esInfo = 0;
  public final static int esWarning = 1;
  public final static int esFatal = 2;

Default Value

1

Remarks

Use this property to establish whether the error is fatal.

This property is not available at design time.

ExternalCrypto Property (TLSClient Class)

Provides access to external signing and DC parameters.

Syntax

public ExternalCrypto getExternalCrypto();

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

Please refer to the ExternalCrypto type for a complete list of fields.

FIPSMode Property (TLSClient Class)

Reserved.

Syntax

public boolean isFIPSMode();


public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

KnownCertificates Property (TLSClient Class)

Additional certificates for chain validation.

Syntax

public CertificateList getKnownCertificates();


public void setKnownCertificates(CertificateList knownCertificates);

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the class manually.

The purpose of the certificates to be added to this collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

KnownCRLs Property (TLSClient Class)

Additional CRLs for chain validation.

Syntax

public CRLList getKnownCRLs();


public void setKnownCRLs(CRLList knownCRLs);

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the CRL type for a complete list of fields.

KnownOCSPs Property (TLSClient Class)

Additional OCSP responses for chain validation.

Syntax

public OCSPResponseList getKnownOCSPs();


public void setKnownOCSPs(OCSPResponseList knownOCSPs);

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the OCSPResponse type for a complete list of fields.

OutputBytes Property (TLSClient Class)

A memory buffer where the incoming data is collected.

Syntax

public byte[] getOutputBytes();

Remarks

Use this property to access the cached incoming data after a ReceiveData or ReceiveAllData call.

This property is read-only and not available at design time.

OutputString Property (TLSClient Class)

A string where the incoming data is collected.

Syntax

public String getOutputString();

Default Value

""

Remarks

Use this property to access the stored incoming data in the string interpretation.

This property is read-only and not available at design time.

Proxy Property (TLSClient Class)

The proxy server settings.

Syntax

public ProxySettings getProxy();

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

Please refer to the ProxySettings type for a complete list of fields.

ServerChain Property (TLSClient Class)

The TLS server's certificate chain.

Syntax

public CertificateList getServerChain();

Remarks

Use this property to access the certificate chain sent by the TLS server. This property is ready to read when OnCertificateValidate event is fired by the client component.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

SocketSettings Property (TLSClient Class)

Manages network connection settings.

Syntax

public SocketSettings getSocketSettings();

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Please refer to the SocketSettings type for a complete list of fields.

TLSSettings Property (TLSClient Class)

Manages TLS layer settings.

Syntax

public TLSSettings getTLSSettings();

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Please refer to the TLSSettings type for a complete list of fields.

TrustedCertificates Property (TLSClient Class)

A list of trusted certificates for chain validation.

Syntax

public CertificateList getTrustedCertificates();


public void setTrustedCertificates(CertificateList trustedCertificates);

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same as that of the Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Config Method (Tlsclient Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Connect Method (Tlsclient Class)

Establishes connection to a remote server.

Syntax

public void connect(String address, int port);

Remarks

Call this method to establish connection to a TLS server at Address:Port.

Disconnect Method (Tlsclient Class)

Disconnects from the server.

Syntax

public void disconnect();

Remarks

Call this method to close an active connection to the server.

DoAction Method (Tlsclient Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

ExportKeyMaterial Method (Tlsclient Class)

Derives key material from the session's master key using the TLS exporters scheme.

Syntax

public void exportKeyMaterial(String lbl, byte[] context, int len);

Remarks

Some protocols - for example, SRTP - use TLS exporters to derive their own session keys from the TLS master key. This method lets you employ the exporters scheme to obtain such keys, or to generate secure keys for your own needs from the current TLS session.

The exported keys depend on the master key, and are different for every TLS session. However, a client and server sharing a session will always end up with the same key material, as long as they use the same values of Lbl, Context, and Len.

ReceiveAllData Method (Tlsclient Class)

Reads data from the connection.

Syntax

public void receiveAllData(int size);

Remarks

Use this method to read Size bytes from the connection. The method will block until the requested number of bytes is received.

Use OutputBytes (or OutputString) to access the received data.

Use ReceiveData method to read all the data there is and return without waiting for the whole piece.

ReceiveData Method (Tlsclient Class)

Reads data from the connection.

Syntax

public void receiveData(int size);

Remarks

Use this method to read Size or less bytes from the connection. The method will read as much data is possible (but no more than Size) and return without blocking.

Use OutputBytes (or OutputString) to access the received data.

SendData Method (Tlsclient Class)

Sends a buffer to the server.

Syntax

public void sendData(byte[] buffer);

Remarks

Use this method to send a byte array to the server.

SendKeepAlive Method (Tlsclient Class)

Sends a keep-alive packet.

Syntax

public boolean sendKeepAlive();

Remarks

Use this method to send a keep-alive packet to the server. Keep alive is an empty packet; keep-alive signals sent occasionally can be used to keep connection up.

SendStream Method (Tlsclient Class)

Sends data contained in a stream to the server.

Syntax

public void sendStream(java.io.InputStream stream);

Remarks

Use this method to send the content of a stream to the server.

SendText Method (Tlsclient Class)

Sends a text string to the server.

Syntax

public void sendText(String text);

Remarks

Use this method to send a text string to the server.

StartTLS Method (Tlsclient Class)

Starts TLS negotiation on an established TCP connection.

Syntax

public void startTLS();

Remarks

Use this method to initiate a TLS handshake on a plain TCP connection. This method is handy for establishing explicit TLS connections manually.

StopTLS Method (Tlsclient Class)

Downgrades the protected connection to plain TCP.

Syntax

public void stopTLS(boolean quiet);

Remarks

Use this method to make the component stop encrypting session data with TLS and downgrade the connection to plain unencrypted TCP. Use the Quiet parameter to suppress sending of the close_notify alert upon closing the TLS session.

Error Event (Tlsclient Class)

Information about errors during data delivery.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void error(TlsclientErrorEvent e) {}
  ...
}

public class TlsclientErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the HTTPS section.

ExternalSign Event (Tlsclient Class)

Handles remote or external signing initiated by the SignExternal method or other source.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void externalSign(TlsclientExternalSignEvent e) {}
  ...
}

public class TlsclientExternalSignEvent {
  public String operationId;
  public String hashAlgorithm;
  public String pars;
  public String data;
  public String signedData;
}

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the class via the SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact class being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contains algorithm-dependent parameters.

The class uses base16 (hex) encoding for the Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses the .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

Notification Event (Tlsclient Class)

This event notifies the application about an underlying control flow event.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void notification(TlsclientNotificationEvent e) {}
  ...
}

public class TlsclientNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the class, the exact action it is performing, or the document being processed, one or both may be omitted.

TLSCertNeeded Event (Tlsclient Class)

Fires when a remote TLS party requests a client certificate.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void TLSCertNeeded(TlsclientTLSCertNeededEvent e) {}
  ...
}

public class TlsclientTLSCertNeededEvent {
  public String host;
  public String CANames;
}

Remarks

This event fires to notify the implementation that a remote TLS server has requested a client certificate. The Host parameter identifies the host that makes a request, and the CANames parameter (optional, according to the TLS spec) advises on the accepted issuing CAs.

Use the TLSClientChain property in response to this event to provide the requested certificate. Please make sure the client certificate includes the associated private key. Note that you may set the certificates before the connection without waiting for this event to fire.

This event is preceded by the TLSHandshake event for the given host and, if the certificate was accepted, succeeded by the TLSEstablished event.

TLSCertValidate Event (Tlsclient Class)

This event is fired upon receipt of the TLS server's certificate, allowing the user to control its acceptance.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void TLSCertValidate(TlsclientTLSCertValidateEvent e) {}
  ...
}

public class TlsclientTLSCertValidateEvent {
  public String serverHost;
  public String serverIP;
  public boolean accept;
}

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, classes may contact a number of TLS endpoints during their work, depending on their configuration.

Accept is assigned in accordance with the outcome of the internal validation check performed by the class, and can be adjusted if needed.

TLSEstablished Event (Tlsclient Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void TLSEstablished(TlsclientTLSEstablishedEvent e) {}
  ...
}

public class TlsclientTLSEstablishedEvent {
  public String host;
  public String version;
  public String ciphersuite;
  public byte[] connectionId;
  public boolean abort;
}

Remarks

The class uses this event to notify the application about a successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate the security parameters of the new connection. Use the Abort parameter if you need to terminate the connection at this stage.

TLSHandshake Event (Tlsclient Class)

Fires when a new TLS handshake is initiated, before the handshake commences.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void TLSHandshake(TlsclientTLSHandshakeEvent e) {}
  ...
}

public class TlsclientTLSHandshakeEvent {
  public String host;
  public boolean abort;
}

Remarks

The class uses this event to notify the application about the start of a new TLS handshake to Host. If the handshake is successful, this event will be followed by the TLSEstablished event. If the server chooses to request a client certificate, the TLSCertNeeded event will also be fired.

TLSPSK Event (Tlsclient Class)

Notifies the application about the PSK key exchange.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void TLSPSK(TlsclientTLSPSKEvent e) {}
  ...
}

public class TlsclientTLSPSKEvent {
  public String host;
  public String hint;
}

Remarks

The class fires this event to notify the application about the beginning of TLS-PSK key exchange with Host. The Hint parameter may be used by the server to identify the key or service to use. Use the PreSharedKey field of TLSSettings to provide the pre-shared key to the component.

TLSShutdown Event (Tlsclient Class)

Reports the graceful closure of a TLS connection.

Syntax

public class DefaultTlsclientEventListener implements TlsclientEventListener {
  ...
  public void TLSShutdown(TlsclientTLSShutdownEvent e) {}
  ...
}

public class TlsclientTLSShutdownEvent {
  public String host;
}

Remarks

This event notifies the application about the closure of an earlier established TLS connection. Note that only graceful connection closures are reported.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

public Certificate( bytes,  startIndex,  count,  password);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( bytes,  startIndex,  count);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

public Certificate( path,  password);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certPath,  keyPath,  password);

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

public Certificate( path);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

public Certificate( stream);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

public Certificate( stream,  password);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certStream,  keyStream,  password);

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

public Certificate();

Creates a new object with default field values.

ConnectionInfo Type

Contains information about a network connection.

Remarks

Use this property to check various details of the network connection. These include the total amounts of data transferred, the availability of TLS, and its parameters.

Fields

Constructors

public ConnectionInfo();

Creates a new ConnectionInfo object.

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

Constructors

public CRL( bytes,  startIndex,  count);

Creates a CRL object from a memory buffer. Bytes is a buffer containing raw (DER) CRL data, StartIndex and Count specify the starting position and the length of the CRL data in the buffer, respectively.

public CRL( location);

Creates a CRL object by downloading it from a remote location.

public CRL( stream);

Creates a CRL object from data contained in a stream.

public CRL();

Creates an empty CRL object.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

public ExternalCrypto();

Creates a new ExternalCrypto object with default field values.

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Remarks

OCSP is a protocol that allows verification of certificate status in real-time, and is an alternative to Certificate Revocation Lists (CRLs).

An OCSP response is a snapshot of the certificate status at a given time.

Fields

Constructors

public OCSPResponse( bytes,  startIndex,  count);

Initializes the response from a memory buffer. Bytes is a buffer containing raw OCSP response data, StartIndex and Count specify the starting position and the number of bytes to be read from this buffer.

public OCSPResponse( location);

Downloads an OCSP response from a remote location.

public OCSPResponse( stream);

Initializes the response with the data from a stream.

public OCSPResponse();

Creates an empty OCSP response object.

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

Constructors

public ProxySettings();

Creates a new ProxySettings object.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

public SocketSettings();

Creates a new SocketSettings object.

TLSSettings Type

A container for TLS connection settings.

Remarks

The TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

public TLSSettings();

Creates a new TLSSettings object.

Config Settings (Tlsclient Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

TLSClient Config Settings

Base Config Settings

Trappable Errors (Tlsclient Class)

TLSClient Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Class is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER)