TLSServer Class

Properties   Methods   Events   Config Settings   Errors  

The TLSServer class implements server-side functionality of the TLS protocol. In the TLS-disabled mode it works as a plain TCP server.

Syntax

TLSServer

Remarks

Use this component to accept TLS-encrypted or plain TCP connections in your application.

Follow the below steps to set up and run the server in your code:

• Create an instance of the server component and set up the license, if assumed by the edition you are using: var server = new Tlsserver(); server.RuntimeLicense = "5342..0000";
• Set up the listening port (make sure it is not in use): server.Port = 3456;
• Tell the component whether TLS connections should be enforced: server.UseTLS = false; // set to true to enable TLS
• (TLS-enabled servers only) Configure TLS parameters. The exact way of doing that may vary for different scenarios and security requirements. At the very least you need to set up the certificate chain that the server will use to authenticate itself to connecting clients. If you don"t, the component will generate a dummy certificate itself, however, that certificate is unlikely to pass any security requirements. It will let you accept test connections though.

  Below is an example of tuning up the TLS parameters of the server: // *** Switching TLS on and enabling the implicit mode *** server.UseTLS = true; server.TLSSettings.TLSMode = smImplicitTLS; // Loading the certificate chain var mgr = new Certificatemanager(); mgr.RuntimeLicense = "5342..0000"; // *** Setting up the host certificate *** // - it should be issued in the name that matches the hostname (such as domain.com) or its IP address (1.2.3.4), // - it must have an associated private key - so likely is provided in PFX or PEM format. mgr.ImportFromFile("CertTLSServer.pfx", "password"); server.ServerCertificates.Add(mgr.Certificate); // The CA certificate: this is to help connecting clients validate the chain. mgr.ImportFromFile("CertCA.cer", ""); server.ServerCertificates.Add(mgr.Certificate); // *** Adjusting finer-grained TLS settings *** // - session resumption (allows for faster handshakes for connections from the same origin) server.TLSSettings.UseSessionResumption = true; // - secure configuration server.TLSSettings.BaseConfiguration = stpcHighlySecure; // - disabling a cipher suite we dislike (just because we can): server.TLSSettings.Ciphersuites = "-DHE_RSA_AES128_SHA" // *** Configuring versions *** // The default version setting at the time of writing (May 2021) is TLS 1.2 and TLS 1.3, // but that may change in future versions. The following tune-up additionally activates TLS 1.1 and TLS 1.0, // which weakens security, but may be necessary to accept connections from older clients: server.TLSSettings.Versions = csbTLS1 | csbTLS11 | csbTLS12 | csbTLS13;

• Now that your server has been fully set up, activate it: server.Start();
• Once the Start call completes, your server can accept connections from clients. Each accepted connection runs in a separate thread, not interfering with each other or your own threads. The server communicates its ongoing activities to your application by throwing events:
  • Accept to notify you about a new incoming connection. This event lets you accept or reject it.
  • Connect to notify your code of an accepted connection. This event introduces a ConnectionID, a unique identifier that you can use to track the connection throughout its lifetime.
  • Disconnect to notify you that a connection has been closed.
  • TLSEstablished and TLSShutdown to let you know that a TLS layer has been activated/deactivated.
  • Data to notify you about a piece of data received from the remote side.
  • Error to report a protocol or other error.
  • CertificateValidate to communicate the client authentication event to your code. To access the certificate(s) provided by the authenticating client, pin the client and use the PinnedClientChain property to access its chain: server.PinClient(e.ConnectionID); e.Accept = CheckCert(server.PinnedClientChain);

  Note: every such event is thrown from the respective connection thread, so make sure you use some synchronization mechanism when dispatching the events to your UI thread - for example, by updating UI controls by sending a Window Message rather than accessing the controls directly.

  Use SendData and SendText to send data back to a client. When sending data, provide the ConnectionID that is associated with that client. Call DropClient to terminate a client connection.

• To stop the server, call Stop: server.Stop();

TLSServer and SSLLabs

Having said that, when assessing SecureBlackbox TLS-capable servers that are configured to use their default setup, you will often end up with a lower SSLLabs score than you could have. There is a simple reason for that. Being a vendor of a library used by thousands of customers, we have to find a delicate balance between security, compatibility, and keeping class contracts rolling from one product build to another. This makes the default configuration of the components not the strongest possible. To put it simple, we could easily make the default component setup bulletproof - but having done that, we would have likely ended up with hundreds of customers stuck with legacy environments (and there are a lot of them around) losing their connectivity.

If you are looking at achieving the best score at SSLLabs, please read on. The below guidance aims to help you tune up the server component in the way that should give you an A score.

First, switch your server to the highly secure base configuration: server.TLSSettings.BaseConfiguration = stpcHighlySecure; This should immediately give you an A, or a T if your server certificate does not chain up to a trusted anchor.

Some warnings will still be included in the report. One of those is related to the session resumption. It is normally shown in orange:

Session resumption (caching): No (IDs assigned but not accepted)

This literally means that the server is not configured to re-use older sessions, which may put extra computational burden on clients and itself. Use the following setting to enable session caching: server.TLSSettings.UseSessionResumption = true;

Besides, the report may show that there are some weak ciphersuites. All of those should be shown in orange (there should not be any reds; if there are - please let us know), which means they are only relatively weak. While switching them off may affect the interoperability level of the server, you may still want to do that. By using the below approach you can disable individual ciphersuites selectively. For example, if the report shows that TLS_DHE_RSA_WITH_AES128_CBC_SHA256 and TLS_DHE_RSA_WITH_AES256_CBC_SHA256 are weak (because of their CBC mode), you can disable them in the following way: server.TLSSettings.Ciphersuites = '-DHE_RSA_AES128_SHA256;-DHE_RSA_AES256_SHA256'; Note that SBB uses slightly different, simpler naming convention by dropping unnecessart WITH and CBC. Let us know if you have difficulties matching the cipher suite names.

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.

Active Property (TLSServer Class)

Indicates whether the server is active and is listening to new connections.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int secureblackbox_tlsserver_getactive(void* lpObj);

bool GetActive();

Default Value

FALSE

Remarks

This read-only property returns True if the server is listening to incoming connections.

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

Data Type

Boolean

BoundPort Property (TLSServer Class)

Indicates the bound listening port.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetBoundPort();

Unicode (Windows)
INT GetBoundPort();

int secureblackbox_tlsserver_getboundport(void* lpObj);

int GetBoundPort();

Default Value

0

Remarks

Check this property to find out the port that has been allocated to the server by the system. The bound port always equals Port if it is provided, or is allocated dynamically if configured to fall in the range between PortRangeFrom and PortRangeTo constraints.

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

Data Type

Integer

ExternalCrypto Property (TLSServer Class)

Provides access to external signing and DC parameters.

Syntax

• C++
• C
• Qt

SecureBlackboxExternalCrypto* GetExternalCrypto();

char* secureblackbox_tlsserver_getexternalcryptoasyncdocumentid(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptoasyncdocumentid(void* lpObj, const char* lpszExternalCryptoAsyncDocumentID);

char* secureblackbox_tlsserver_getexternalcryptocustomparams(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptocustomparams(void* lpObj, const char* lpszExternalCryptoCustomParams);

char* secureblackbox_tlsserver_getexternalcryptodata(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptodata(void* lpObj, const char* lpszExternalCryptoData);

int secureblackbox_tlsserver_getexternalcryptoexternalhashcalculation(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptoexternalhashcalculation(void* lpObj, int bExternalCryptoExternalHashCalculation);

char* secureblackbox_tlsserver_getexternalcryptohashalgorithm(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptohashalgorithm(void* lpObj, const char* lpszExternalCryptoHashAlgorithm);

char* secureblackbox_tlsserver_getexternalcryptokeyid(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptokeyid(void* lpObj, const char* lpszExternalCryptoKeyID);

char* secureblackbox_tlsserver_getexternalcryptokeysecret(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptokeysecret(void* lpObj, const char* lpszExternalCryptoKeySecret);

int secureblackbox_tlsserver_getexternalcryptomethod(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptomethod(void* lpObj, int iExternalCryptoMethod);

int secureblackbox_tlsserver_getexternalcryptomode(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptomode(void* lpObj, int iExternalCryptoMode);

char* secureblackbox_tlsserver_getexternalcryptopublickeyalgorithm(void* lpObj);
int secureblackbox_tlsserver_setexternalcryptopublickeyalgorithm(void* lpObj, const char* lpszExternalCryptoPublicKeyAlgorithm);

QString GetExternalCryptoAsyncDocumentID();
int SetExternalCryptoAsyncDocumentID(QString qsExternalCryptoAsyncDocumentID);

QString GetExternalCryptoCustomParams();
int SetExternalCryptoCustomParams(QString qsExternalCryptoCustomParams);

QString GetExternalCryptoData();
int SetExternalCryptoData(QString qsExternalCryptoData);

bool GetExternalCryptoExternalHashCalculation();
int SetExternalCryptoExternalHashCalculation(bool bExternalCryptoExternalHashCalculation);

QString GetExternalCryptoHashAlgorithm();
int SetExternalCryptoHashAlgorithm(QString qsExternalCryptoHashAlgorithm);

QString GetExternalCryptoKeyID();
int SetExternalCryptoKeyID(QString qsExternalCryptoKeyID);

QString GetExternalCryptoKeySecret();
int SetExternalCryptoKeySecret(QString qsExternalCryptoKeySecret);

int GetExternalCryptoMethod();
int SetExternalCryptoMethod(int iExternalCryptoMethod);

int GetExternalCryptoMode();
int SetExternalCryptoMode(int iExternalCryptoMode);

QString GetExternalCryptoPublicKeyAlgorithm();
int SetExternalCryptoPublicKeyAlgorithm(QString qsExternalCryptoPublicKeyAlgorithm);

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.

Data Type

SecureBlackboxExternalCrypto

FIPSMode Property (TLSServer Class)

Reserved.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFIPSMode();
int SetFIPSMode(int bFIPSMode);

Unicode (Windows)
BOOL GetFIPSMode();
INT SetFIPSMode(BOOL bFIPSMode);

int secureblackbox_tlsserver_getfipsmode(void* lpObj);
int secureblackbox_tlsserver_setfipsmode(void* lpObj, int bFIPSMode);

bool GetFIPSMode();
int SetFIPSMode(bool bFIPSMode);

Default Value

FALSE

Remarks

This property is reserved for future use.

Data Type

Boolean

HandshakeTimeout Property (TLSServer Class)

Specifies the handshake timeout in milliseconds.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetHandshakeTimeout();
int SetHandshakeTimeout(int iHandshakeTimeout);

Unicode (Windows)
INT GetHandshakeTimeout();
INT SetHandshakeTimeout(INT iHandshakeTimeout);

int secureblackbox_tlsserver_gethandshaketimeout(void* lpObj);
int secureblackbox_tlsserver_sethandshaketimeout(void* lpObj, int iHandshakeTimeout);

int GetHandshakeTimeout();
int SetHandshakeTimeout(int iHandshakeTimeout);

Default Value

20000

Remarks

Use this property to set the TLS handshake timeout.

Data Type

Integer

Host Property (TLSServer Class)

The host to bind the listening port to.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetHost();
int SetHost(const char* lpszHost);

Unicode (Windows)
LPWSTR GetHost();
INT SetHost(LPCWSTR lpszHost);

char* secureblackbox_tlsserver_gethost(void* lpObj);
int secureblackbox_tlsserver_sethost(void* lpObj, const char* lpszHost);

QString GetHost();
int SetHost(QString qsHost);

Default Value

""

Remarks

Use this property to specify the IP address on which to listen to incoming connections.

Data Type

String

PinnedClient Property (TLSServer Class)

Populates the pinned client details.

Syntax

• C++
• C
• Qt

SecureBlackboxTLSConnectionInfo* GetPinnedClient();

int secureblackbox_tlsserver_getpinnedclientaeadcipher(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientchainvalidationdetails(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientchainvalidationresult(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientciphersuite(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientclientauthenticated(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientclientauthrequested(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientconnectionestablished(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientconnectionid(void* lpObj, char** lpPinnedClientConnectionID, int* lenPinnedClientConnectionID);

char* secureblackbox_tlsserver_getpinnedclientdigestalgorithm(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientencryptionalgorithm(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientexportable(void* lpObj);

int64 secureblackbox_tlsserver_getpinnedclientid(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientkeyexchangealgorithm(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientkeyexchangekeybits(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientnamedeccurve(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientpfscipher(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientpresharedidentity(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientpresharedidentityhint(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientpublickeybits(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientremoteaddress(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientremoteport(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientresumedsession(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientsecureconnection(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientserverauthenticated(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientsignaturealgorithm(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientsymmetricblocksize(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientsymmetrickeybits(void* lpObj);

int64 secureblackbox_tlsserver_getpinnedclienttotalbytesreceived(void* lpObj);

int64 secureblackbox_tlsserver_getpinnedclienttotalbytessent(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientvalidationlog(void* lpObj);

char* secureblackbox_tlsserver_getpinnedclientversion(void* lpObj);

bool GetPinnedClientAEADCipher();

int GetPinnedClientChainValidationDetails();

int GetPinnedClientChainValidationResult();

QString GetPinnedClientCiphersuite();

bool GetPinnedClientClientAuthenticated();

bool GetPinnedClientClientAuthRequested();

bool GetPinnedClientConnectionEstablished();

QByteArray GetPinnedClientConnectionID();

QString GetPinnedClientDigestAlgorithm();

QString GetPinnedClientEncryptionAlgorithm();

bool GetPinnedClientExportable();

qint64 GetPinnedClientID();

QString GetPinnedClientKeyExchangeAlgorithm();

int GetPinnedClientKeyExchangeKeyBits();

QString GetPinnedClientNamedECCurve();

bool GetPinnedClientPFSCipher();

QString GetPinnedClientPreSharedIdentity();

QString GetPinnedClientPreSharedIdentityHint();

int GetPinnedClientPublicKeyBits();

QString GetPinnedClientRemoteAddress();

int GetPinnedClientRemotePort();

bool GetPinnedClientResumedSession();

bool GetPinnedClientSecureConnection();

bool GetPinnedClientServerAuthenticated();

QString GetPinnedClientSignatureAlgorithm();

int GetPinnedClientSymmetricBlockSize();

int GetPinnedClientSymmetricKeyBits();

qint64 GetPinnedClientTotalBytesReceived();

qint64 GetPinnedClientTotalBytesSent();

QString GetPinnedClientValidationLog();

QString GetPinnedClientVersion();

Remarks

Use this property to access the details of the client connection previously pinned with PinClient method.

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

Data Type

SecureBlackboxTLSConnectionInfo

PinnedClientChain Property (TLSServer Class)

Contains the certificate chain of the pinned client.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetPinnedClientChain();

int secureblackbox_tlsserver_getpinnedclientcertcount(void* lpObj);

int secureblackbox_tlsserver_getpinnedclientcertbytes(void* lpObj, int pinnedclientcertindex, char** lpPinnedClientCertBytes, int* lenPinnedClientCertBytes);

int secureblackbox_tlsserver_getpinnedclientcertcakeyid(void* lpObj, int pinnedclientcertindex, char** lpPinnedClientCertCAKeyID, int* lenPinnedClientCertCAKeyID);

char* secureblackbox_tlsserver_getpinnedclientcertfingerprint(void* lpObj, int pinnedclientcertindex);

int64 secureblackbox_tlsserver_getpinnedclientcerthandle(void* lpObj, int pinnedclientcertindex);

char* secureblackbox_tlsserver_getpinnedclientcertissuer(void* lpObj, int pinnedclientcertindex);

char* secureblackbox_tlsserver_getpinnedclientcertissuerrdn(void* lpObj, int pinnedclientcertindex);

char* secureblackbox_tlsserver_getpinnedclientcertkeyalgorithm(void* lpObj, int pinnedclientcertindex);

int secureblackbox_tlsserver_getpinnedclientcertkeybits(void* lpObj, int pinnedclientcertindex);

char* secureblackbox_tlsserver_getpinnedclientcertkeyfingerprint(void* lpObj, int pinnedclientcertindex);

int secureblackbox_tlsserver_getpinnedclientcertkeyusage(void* lpObj, int pinnedclientcertindex);

int secureblackbox_tlsserver_getpinnedclientcertpublickeybytes(void* lpObj, int pinnedclientcertindex, char** lpPinnedClientCertPublicKeyBytes, int* lenPinnedClientCertPublicKeyBytes);

int secureblackbox_tlsserver_getpinnedclientcertselfsigned(void* lpObj, int pinnedclientcertindex);

int secureblackbox_tlsserver_getpinnedclientcertserialnumber(void* lpObj, int pinnedclientcertindex, char** lpPinnedClientCertSerialNumber, int* lenPinnedClientCertSerialNumber);

char* secureblackbox_tlsserver_getpinnedclientcertsigalgorithm(void* lpObj, int pinnedclientcertindex);

char* secureblackbox_tlsserver_getpinnedclientcertsubject(void* lpObj, int pinnedclientcertindex);

int secureblackbox_tlsserver_getpinnedclientcertsubjectkeyid(void* lpObj, int pinnedclientcertindex, char** lpPinnedClientCertSubjectKeyID, int* lenPinnedClientCertSubjectKeyID);

char* secureblackbox_tlsserver_getpinnedclientcertsubjectrdn(void* lpObj, int pinnedclientcertindex);

char* secureblackbox_tlsserver_getpinnedclientcertvalidfrom(void* lpObj, int pinnedclientcertindex);

char* secureblackbox_tlsserver_getpinnedclientcertvalidto(void* lpObj, int pinnedclientcertindex);

int GetPinnedClientCertCount();

QByteArray GetPinnedClientCertBytes(int iPinnedClientCertIndex);

QByteArray GetPinnedClientCertCAKeyID(int iPinnedClientCertIndex);

QString GetPinnedClientCertFingerprint(int iPinnedClientCertIndex);

qint64 GetPinnedClientCertHandle(int iPinnedClientCertIndex);

QString GetPinnedClientCertIssuer(int iPinnedClientCertIndex);

QString GetPinnedClientCertIssuerRDN(int iPinnedClientCertIndex);

QString GetPinnedClientCertKeyAlgorithm(int iPinnedClientCertIndex);

int GetPinnedClientCertKeyBits(int iPinnedClientCertIndex);

QString GetPinnedClientCertKeyFingerprint(int iPinnedClientCertIndex);

int GetPinnedClientCertKeyUsage(int iPinnedClientCertIndex);

QByteArray GetPinnedClientCertPublicKeyBytes(int iPinnedClientCertIndex);

bool GetPinnedClientCertSelfSigned(int iPinnedClientCertIndex);

QByteArray GetPinnedClientCertSerialNumber(int iPinnedClientCertIndex);

QString GetPinnedClientCertSigAlgorithm(int iPinnedClientCertIndex);

QString GetPinnedClientCertSubject(int iPinnedClientCertIndex);

QByteArray GetPinnedClientCertSubjectKeyID(int iPinnedClientCertIndex);

QString GetPinnedClientCertSubjectRDN(int iPinnedClientCertIndex);

QString GetPinnedClientCertValidFrom(int iPinnedClientCertIndex);

QString GetPinnedClientCertValidTo(int iPinnedClientCertIndex);

Remarks

Use this property to access the certificate chain of the client connection pinned previously with a PinClient call.

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

Data Type

SecureBlackboxCertificate

Port Property (TLSServer Class)

Specifies the port number to listen for connections on.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPort();
int SetPort(int iPort);

Unicode (Windows)
INT GetPort();
INT SetPort(INT iPort);

int secureblackbox_tlsserver_getport(void* lpObj);
int secureblackbox_tlsserver_setport(void* lpObj, int iPort);

int GetPort();
int SetPort(int iPort);

Default Value

80

Remarks

Use this property to specify the port number to listen to connections on. Standard port numbers are 80 for an HTTP server, and 443 for an HTTPS server.

Alternatively, you may specify the acceptable range of listening ports via PortRangeFrom and PortRangeTo properties. In this case the port will be allocated within the requested range by the operating system, and reported in BoundPort.

Data Type

Integer

PortRangeFrom Property (TLSServer Class)

Specifies the lower limit of the listening port range for incoming connections.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPortRangeFrom();
int SetPortRangeFrom(int iPortRangeFrom);

Unicode (Windows)
INT GetPortRangeFrom();
INT SetPortRangeFrom(INT iPortRangeFrom);

int secureblackbox_tlsserver_getportrangefrom(void* lpObj);
int secureblackbox_tlsserver_setportrangefrom(void* lpObj, int iPortRangeFrom);

int GetPortRangeFrom();
int SetPortRangeFrom(int iPortRangeFrom);

Default Value

0

Remarks

Use this property to specify the lower limit of the port range to listen to connections on. When a port range is used to specify the listening port (as opposed to a fixed value provided via Port), the port will be allocated within the requested range by the operating system, and reported in BoundPort.

Note that this property is ignored if the Port property is set to a non-zero value, in which case the server always aims to listen on that fixed port.

Data Type

Integer

PortRangeTo Property (TLSServer Class)

Specifies the upper limit of the listening port range for incoming connections.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPortRangeTo();
int SetPortRangeTo(int iPortRangeTo);

Unicode (Windows)
INT GetPortRangeTo();
INT SetPortRangeTo(INT iPortRangeTo);

int secureblackbox_tlsserver_getportrangeto(void* lpObj);
int secureblackbox_tlsserver_setportrangeto(void* lpObj, int iPortRangeTo);

int GetPortRangeTo();
int SetPortRangeTo(int iPortRangeTo);

Default Value

0

Remarks

Use this property to specify the upper limit of the port range to listen to connections on. When a port range is used to specify the listening port (as opposed to a fixed value provided via Port), the port will be allocated within the requested range by the operating system, and reported in BoundPort.

Note that this property is ignored if the Port property is set to a non-zero value, in which case the server always aims to listen on that fixed port.

Data Type

Integer

SessionTimeout Property (TLSServer Class)

Specifies the default session timeout value in milliseconds.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSessionTimeout();
int SetSessionTimeout(int iSessionTimeout);

Unicode (Windows)
INT GetSessionTimeout();
INT SetSessionTimeout(INT iSessionTimeout);

int secureblackbox_tlsserver_getsessiontimeout(void* lpObj);
int secureblackbox_tlsserver_setsessiontimeout(void* lpObj, int iSessionTimeout);

int GetSessionTimeout();
int SetSessionTimeout(int iSessionTimeout);

Default Value

360000

Remarks

Specifies the period of inactivity (in milliseconds) after which the connection will be terminated by the server.

Data Type

Integer

SocketSettings Property (TLSServer Class)

Manages network connection settings.

Syntax

• C++
• C
• Qt

SecureBlackboxSocketSettings* GetSocketSettings();

int secureblackbox_tlsserver_getsocketincomingspeedlimit(void* lpObj);
int secureblackbox_tlsserver_setsocketincomingspeedlimit(void* lpObj, int iSocketIncomingSpeedLimit);

char* secureblackbox_tlsserver_getsocketlocaladdress(void* lpObj);
int secureblackbox_tlsserver_setsocketlocaladdress(void* lpObj, const char* lpszSocketLocalAddress);

int secureblackbox_tlsserver_getsocketlocalport(void* lpObj);
int secureblackbox_tlsserver_setsocketlocalport(void* lpObj, int iSocketLocalPort);

int secureblackbox_tlsserver_getsocketoutgoingspeedlimit(void* lpObj);
int secureblackbox_tlsserver_setsocketoutgoingspeedlimit(void* lpObj, int iSocketOutgoingSpeedLimit);

int secureblackbox_tlsserver_getsockettimeout(void* lpObj);
int secureblackbox_tlsserver_setsockettimeout(void* lpObj, int iSocketTimeout);

int secureblackbox_tlsserver_getsocketuseipv6(void* lpObj);
int secureblackbox_tlsserver_setsocketuseipv6(void* lpObj, int bSocketUseIPv6);

int GetSocketIncomingSpeedLimit();
int SetSocketIncomingSpeedLimit(int iSocketIncomingSpeedLimit);

QString GetSocketLocalAddress();
int SetSocketLocalAddress(QString qsSocketLocalAddress);

int GetSocketLocalPort();
int SetSocketLocalPort(int iSocketLocalPort);

int GetSocketOutgoingSpeedLimit();
int SetSocketOutgoingSpeedLimit(int iSocketOutgoingSpeedLimit);

int GetSocketTimeout();
int SetSocketTimeout(int iSocketTimeout);

bool GetSocketUseIPv6();
int SetSocketUseIPv6(bool bSocketUseIPv6);

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Data Type

SecureBlackboxSocketSettings

TLSServerChain Property (TLSServer Class)

The server's TLS certificates.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetTLSServerChain();
int SetTLSServerChain(SecureBlackboxList<SecureBlackboxCertificate>* val);

int secureblackbox_tlsserver_gettlsservercertcount(void* lpObj);
int secureblackbox_tlsserver_settlsservercertcount(void* lpObj, int iTLSServerCertCount);

int secureblackbox_tlsserver_gettlsservercertbytes(void* lpObj, int tlsservercertindex, char** lpTLSServerCertBytes, int* lenTLSServerCertBytes);

int64 secureblackbox_tlsserver_gettlsservercerthandle(void* lpObj, int tlsservercertindex);
int secureblackbox_tlsserver_settlsservercerthandle(void* lpObj, int tlsservercertindex, int64 lTLSServerCertHandle);

int GetTLSServerCertCount();
int SetTLSServerCertCount(int iTLSServerCertCount);

QByteArray GetTLSServerCertBytes(int iTLSServerCertIndex);

qint64 GetTLSServerCertHandle(int iTLSServerCertIndex);
int SetTLSServerCertHandle(int iTLSServerCertIndex, qint64 lTLSServerCertHandle);

Remarks

Use this property to provide a list of TLS certificates for the server endpoint.

A TLS endpoint needs a certificate to be able to accept TLS connections. At least one of the certificates in the collection - the endpoint certificate - must have a private key associated with it.

The collection may include more than one endpoint certificate, and more than one chain. A typical usage scenario is to include two chains (ECDSA and RSA), to cater for clients with different cipher suite preferences.

This property is not available at design time.

Data Type

SecureBlackboxCertificate

TLSSettings Property (TLSServer Class)

Manages TLS layer settings.

Syntax

• C++
• C
• Qt

SecureBlackboxTLSSettings* GetTLSSettings();

int secureblackbox_tlsserver_gettlsautovalidatecertificates(void* lpObj);
int secureblackbox_tlsserver_settlsautovalidatecertificates(void* lpObj, int bTLSAutoValidateCertificates);

int secureblackbox_tlsserver_gettlsbaseconfiguration(void* lpObj);
int secureblackbox_tlsserver_settlsbaseconfiguration(void* lpObj, int iTLSBaseConfiguration);

char* secureblackbox_tlsserver_gettlsciphersuites(void* lpObj);
int secureblackbox_tlsserver_settlsciphersuites(void* lpObj, const char* lpszTLSCiphersuites);

int secureblackbox_tlsserver_gettlsclientauth(void* lpObj);
int secureblackbox_tlsserver_settlsclientauth(void* lpObj, int iTLSClientAuth);

char* secureblackbox_tlsserver_gettlseccurves(void* lpObj);
int secureblackbox_tlsserver_settlseccurves(void* lpObj, const char* lpszTLSECCurves);

char* secureblackbox_tlsserver_gettlsextensions(void* lpObj);
int secureblackbox_tlsserver_settlsextensions(void* lpObj, const char* lpszTLSExtensions);

int secureblackbox_tlsserver_gettlsforceresumeifdestinationchanges(void* lpObj);
int secureblackbox_tlsserver_settlsforceresumeifdestinationchanges(void* lpObj, int bTLSForceResumeIfDestinationChanges);

char* secureblackbox_tlsserver_gettlspresharedidentity(void* lpObj);
int secureblackbox_tlsserver_settlspresharedidentity(void* lpObj, const char* lpszTLSPreSharedIdentity);

char* secureblackbox_tlsserver_gettlspresharedkey(void* lpObj);
int secureblackbox_tlsserver_settlspresharedkey(void* lpObj, const char* lpszTLSPreSharedKey);

char* secureblackbox_tlsserver_gettlspresharedkeyciphersuite(void* lpObj);
int secureblackbox_tlsserver_settlspresharedkeyciphersuite(void* lpObj, const char* lpszTLSPreSharedKeyCiphersuite);

int secureblackbox_tlsserver_gettlsrenegotiationattackpreventionmode(void* lpObj);
int secureblackbox_tlsserver_settlsrenegotiationattackpreventionmode(void* lpObj, int iTLSRenegotiationAttackPreventionMode);

int secureblackbox_tlsserver_gettlsrevocationcheck(void* lpObj);
int secureblackbox_tlsserver_settlsrevocationcheck(void* lpObj, int iTLSRevocationCheck);

int secureblackbox_tlsserver_gettlsssloptions(void* lpObj);
int secureblackbox_tlsserver_settlsssloptions(void* lpObj, int iTLSSSLOptions);

int secureblackbox_tlsserver_gettlstlsmode(void* lpObj);
int secureblackbox_tlsserver_settlstlsmode(void* lpObj, int iTLSTLSMode);

int secureblackbox_tlsserver_gettlsuseextendedmastersecret(void* lpObj);
int secureblackbox_tlsserver_settlsuseextendedmastersecret(void* lpObj, int bTLSUseExtendedMasterSecret);

int secureblackbox_tlsserver_gettlsusesessionresumption(void* lpObj);
int secureblackbox_tlsserver_settlsusesessionresumption(void* lpObj, int bTLSUseSessionResumption);

int secureblackbox_tlsserver_gettlsversions(void* lpObj);
int secureblackbox_tlsserver_settlsversions(void* lpObj, int iTLSVersions);

bool GetTLSAutoValidateCertificates();
int SetTLSAutoValidateCertificates(bool bTLSAutoValidateCertificates);

int GetTLSBaseConfiguration();
int SetTLSBaseConfiguration(int iTLSBaseConfiguration);

QString GetTLSCiphersuites();
int SetTLSCiphersuites(QString qsTLSCiphersuites);

int GetTLSClientAuth();
int SetTLSClientAuth(int iTLSClientAuth);

QString GetTLSECCurves();
int SetTLSECCurves(QString qsTLSECCurves);

QString GetTLSExtensions();
int SetTLSExtensions(QString qsTLSExtensions);

bool GetTLSForceResumeIfDestinationChanges();
int SetTLSForceResumeIfDestinationChanges(bool bTLSForceResumeIfDestinationChanges);

QString GetTLSPreSharedIdentity();
int SetTLSPreSharedIdentity(QString qsTLSPreSharedIdentity);

QString GetTLSPreSharedKey();
int SetTLSPreSharedKey(QString qsTLSPreSharedKey);

QString GetTLSPreSharedKeyCiphersuite();
int SetTLSPreSharedKeyCiphersuite(QString qsTLSPreSharedKeyCiphersuite);

int GetTLSRenegotiationAttackPreventionMode();
int SetTLSRenegotiationAttackPreventionMode(int iTLSRenegotiationAttackPreventionMode);

int GetTLSRevocationCheck();
int SetTLSRevocationCheck(int iTLSRevocationCheck);

int GetTLSSSLOptions();
int SetTLSSSLOptions(int iTLSSSLOptions);

int GetTLSTLSMode();
int SetTLSTLSMode(int iTLSTLSMode);

bool GetTLSUseExtendedMasterSecret();
int SetTLSUseExtendedMasterSecret(bool bTLSUseExtendedMasterSecret);

bool GetTLSUseSessionResumption();
int SetTLSUseSessionResumption(bool bTLSUseSessionResumption);

int GetTLSVersions();
int SetTLSVersions(int iTLSVersions);

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Data Type

SecureBlackboxTLSSettings

WebsiteName Property (TLSServer Class)

Specifies the web site name to use in the certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetWebsiteName();
int SetWebsiteName(const char* lpszWebsiteName);

Unicode (Windows)
LPWSTR GetWebsiteName();
INT SetWebsiteName(LPCWSTR lpszWebsiteName);

char* secureblackbox_tlsserver_getwebsitename(void* lpObj);
int secureblackbox_tlsserver_setwebsitename(void* lpObj, const char* lpszWebsiteName);

QString GetWebsiteName();
int SetWebsiteName(QString qsWebsiteName);

Default Value

"secureblackbox"

Remarks

If using an internally-generated certificate, use this property to specify the web site name to be included as a common name. A typical common name consists of the host name, such as '192.168.10.10' or 'domain.com'.

Data Type

String

BroadcastData Method (TLSServer Class)

Broadcasts data to all connections.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int BroadcastData(int64 lConnectionID, const char* lpData, int lenData);

Unicode (Windows)
INT BroadcastData(LONG64 lConnectionID, LPCSTR lpData, INT lenData);

int secureblackbox_tlsserver_broadcastdata(void* lpObj, int64 lConnectionID, const char* lpData, int lenData);

int BroadcastData(qint64 lConnectionID, QByteArray qbaData);

Remarks

Call this method to send Data to all active client connections except for ConnectionID. Set ConnectionID to -1 to broadcast to all connections without exceptions.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

BroadcastText Method (TLSServer Class)

Broadcasts a text string to all connections.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int BroadcastText(int64 lConnectionId, const char* lpszText);

Unicode (Windows)
INT BroadcastText(LONG64 lConnectionId, LPCWSTR lpszText);

int secureblackbox_tlsserver_broadcasttext(void* lpObj, int64 lConnectionId, const char* lpszText);

int BroadcastText(qint64 lConnectionId, const QString& qsText);

Remarks

Call this method to send Text to all active client connections except for ConnectionID. Set ConnectionID to -1 to broadcast to all connections without exceptions.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Cleanup Method (TLSServer Class)

Cleans up the server environment by purging expired sessions and cleaning caches.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Cleanup();

Unicode (Windows)
INT Cleanup();

int secureblackbox_tlsserver_cleanup(void* lpObj);

int Cleanup();

Remarks

Call this method while the server is active to clean up the environment allocated for the server by releasing unused resources and cleaning caches.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (TLSServer Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* secureblackbox_tlsserver_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DoAction Method (TLSServer Class)

Performs an additional action.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* DoAction(const char* lpszActionID, const char* lpszActionParams);

Unicode (Windows)
LPWSTR DoAction(LPCWSTR lpszActionID, LPCWSTR lpszActionParams);

char* secureblackbox_tlsserver_doaction(void* lpObj, const char* lpszActionID, const char* lpszActionParams);

QString DoAction(const QString& qsActionID, const QString& qsActionParams);

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;....

Common ActionIDs:

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DropClient Method (TLSServer Class)

Terminates a client connection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DropClient(int64 lConnectionId, int bForced);

Unicode (Windows)
INT DropClient(LONG64 lConnectionId, BOOL bForced);

int secureblackbox_tlsserver_dropclient(void* lpObj, int64 lConnectionId, int bForced);

int DropClient(qint64 lConnectionId, bool bForced);

Remarks

Call this method to shut down a connected client. Forced indicates whether the connection should be closed in a graceful manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ExportKeyMaterial Method (TLSServer Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportKeyMaterial(int64 lConnectionID, const char* lpszLbl, const char* lpContext, int lenContext, int iLen);

Unicode (Windows)
INT ExportKeyMaterial(LONG64 lConnectionID, LPCWSTR lpszLbl, LPCSTR lpContext, INT lenContext, INT iLen);

int secureblackbox_tlsserver_exportkeymaterial(void* lpObj, int64 lConnectionID, const char* lpszLbl, const char* lpContext, int lenContext, int iLen);

int ExportKeyMaterial(qint64 lConnectionID, const QString& qsLbl, QByteArray qbaContext, int iLen);

Remarks

Some protocols - for example, SRTP - use the TLS exporters scheme to derive their own session keys from the TLS master key. This method lets you employ exporters to obtain such keys, or to generate secure keys for your own needs from an active 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.

Use the ConnectionID parameter to specify the session that you would like to derive key material from.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ListClients Method (TLSServer Class)

Enumerates the connected clients.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* ListClients();

Unicode (Windows)
LPWSTR ListClients();

char* secureblackbox_tlsserver_listclients(void* lpObj);

QString ListClients();

Remarks

This method enumerates the connected clients. It returns a list of strings, with each string being of 'ConnectionID|Address|Port' format, and representing a single connection.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

PinClient Method (TLSServer Class)

Takes a snapshot of the connection's properties.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int PinClient(int64 lConnectionId);

Unicode (Windows)
INT PinClient(LONG64 lConnectionId);

int secureblackbox_tlsserver_pinclient(void* lpObj, int64 lConnectionId);

int PinClient(qint64 lConnectionId);

Remarks

Use this method to take a snapshot of a connected client. The captured properties are populated in PinnedClient and PinnedClientChain properties.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (TLSServer Class)

Resets the class settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int secureblackbox_tlsserver_reset(void* lpObj);

int Reset();

Remarks

Reset is a generic method available in every class.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SendData Method (TLSServer Class)

Sends a data buffer to a connection client.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SendData(int64 lConnectionID, const char* lpBuffer, int lenBuffer);

Unicode (Windows)
INT SendData(LONG64 lConnectionID, LPCSTR lpBuffer, INT lenBuffer);

int secureblackbox_tlsserver_senddata(void* lpObj, int64 lConnectionID, const char* lpBuffer, int lenBuffer);

int SendData(qint64 lConnectionID, QByteArray qbaBuffer);

Remarks

Use this method to send a data buffer to a connected client. Use ConnectionID to specify the client.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SendKeepAlive Method (TLSServer Class)

Sends a keep-alive packet.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SendKeepAlive(int64 lConnectionId);

Unicode (Windows)
INT SendKeepAlive(LONG64 lConnectionId);

int secureblackbox_tlsserver_sendkeepalive(void* lpObj, int64 lConnectionId);

int SendKeepAlive(qint64 lConnectionId);

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SendText Method (TLSServer Class)

Sends a text string to a client.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SendText(int64 lConnectionId, const char* lpszText);

Unicode (Windows)
INT SendText(LONG64 lConnectionId, LPCWSTR lpszText);

int secureblackbox_tlsserver_sendtext(void* lpObj, int64 lConnectionId, const char* lpszText);

int SendText(qint64 lConnectionId, const QString& qsText);

Remarks

Use this method to send a text string to a connected client.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Start Method (TLSServer Class)

Starts the TLS server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Start();

Unicode (Windows)
INT Start();

int secureblackbox_tlsserver_start(void* lpObj);

int Start();

Remarks

Use this method to start listening for incoming connections.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Stop Method (TLSServer Class)

Stops the TLS server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Stop();

Unicode (Windows)
INT Stop();

int secureblackbox_tlsserver_stop(void* lpObj);

int Stop();

Remarks

Call this method to stop listening for incoming connections.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Accept Event (TLSServer Class)

Reports an incoming connection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireAccept(TLSServerAcceptEventParams *e);

typedef struct {
  const char *RemoteAddress;
  int RemotePort;
  int Accept;
  int reserved;
} TLSServerAcceptEventParams;


Unicode (Windows)
virtual INT FireAccept(TLSServerAcceptEventParams *e);

typedef struct {
  LPCWSTR RemoteAddress;
  INT RemotePort;
  BOOL Accept;
  INT reserved;
} TLSServerAcceptEventParams;

#define EID_TLSSERVER_ACCEPT 1

virtual INT SECUREBLACKBOX_CALL FireAccept(LPSTR &lpszRemoteAddress, INT &iRemotePort, BOOL &bAccept);

class TLSServerAcceptEventParams {
public:
  const QString &RemoteAddress();

  int RemotePort();

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Accept(TLSServerAcceptEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireAccept(TLSServerAcceptEventParams *e) {...}

Remarks

This event is fired when a new connection from RemoteAddress:RemotePort is ready to be accepted. Use the Accept parameter to accept or decline it.

Subscribe to Connect event to be notified of every connection that has been set up.

Connect Event (TLSServer Class)

Reports an accepted connection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireConnect(TLSServerConnectEventParams *e);

typedef struct {
  int64 ConnectionID;
  const char *RemoteAddress;
  int RemotePort;
  int reserved;
} TLSServerConnectEventParams;


Unicode (Windows)
virtual INT FireConnect(TLSServerConnectEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  LPCWSTR RemoteAddress;
  INT RemotePort;
  INT reserved;
} TLSServerConnectEventParams;

#define EID_TLSSERVER_CONNECT 2

virtual INT SECUREBLACKBOX_CALL FireConnect(LONG64 &lConnectionID, LPSTR &lpszRemoteAddress, INT &iRemotePort);

class TLSServerConnectEventParams {
public:
  qint64 ConnectionID();

  const QString &RemoteAddress();

  int RemotePort();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Connect(TLSServerConnectEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireConnect(TLSServerConnectEventParams *e) {...}

Remarks

The class fires this event to report that a new connection has been established. ConnectionId indicates the unique ID assigned to this connection. The same ID will be supplied to any other events related to this connection, such as TLSHandshake or Data.

Data Event (TLSServer Class)

Supplies a data chunk received from a client.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireData(TLSServerDataEventParams *e);

typedef struct {
  int64 ConnectionID;
  const char *Buffer;
  int lenBuffer;
  int reserved;
} TLSServerDataEventParams;


Unicode (Windows)
virtual INT FireData(TLSServerDataEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  LPCSTR Buffer;
  INT lenBuffer;
  INT reserved;
} TLSServerDataEventParams;

#define EID_TLSSERVER_DATA 3

virtual INT SECUREBLACKBOX_CALL FireData(LONG64 &lConnectionID, LPSTR &lpBuffer, INT &lenBuffer);

class TLSServerDataEventParams {
public:
  qint64 ConnectionID();

  const QByteArray &Buffer();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Data(TLSServerDataEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireData(TLSServerDataEventParams *e) {...}

Remarks

This event is fired to supply another piece of data received from a client. This event may fire multiple times.

Disconnect Event (TLSServer Class)

Fires to report a disconnected client.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireDisconnect(TLSServerDisconnectEventParams *e);

typedef struct {
  int64 ConnectionID;
  int reserved;
} TLSServerDisconnectEventParams;


Unicode (Windows)
virtual INT FireDisconnect(TLSServerDisconnectEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  INT reserved;
} TLSServerDisconnectEventParams;

#define EID_TLSSERVER_DISCONNECT 4

virtual INT SECUREBLACKBOX_CALL FireDisconnect(LONG64 &lConnectionID);

class TLSServerDisconnectEventParams {
public:
  qint64 ConnectionID();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Disconnect(TLSServerDisconnectEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireDisconnect(TLSServerDisconnectEventParams *e) {...}

Remarks

The class fires this event when a connected client disconnects.

Error Event (TLSServer Class)

Information about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(TLSServerErrorEventParams *e);

typedef struct {
  int64 ConnectionID;
  int ErrorCode;
  int Fatal;
  int Remote;
  const char *Description;
  int reserved;
} TLSServerErrorEventParams;


Unicode (Windows)
virtual INT FireError(TLSServerErrorEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  INT ErrorCode;
  BOOL Fatal;
  BOOL Remote;
  LPCWSTR Description;
  INT reserved;
} TLSServerErrorEventParams;

#define EID_TLSSERVER_ERROR 5

virtual INT SECUREBLACKBOX_CALL FireError(LONG64 &lConnectionID, INT &iErrorCode, BOOL &bFatal, BOOL &bRemote, LPSTR &lpszDescription);

class TLSServerErrorEventParams {
public:
  qint64 ConnectionID();

  int ErrorCode();

  bool Fatal();

  bool Remote();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(TLSServerErrorEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireError(TLSServerErrorEventParams *e) {...}

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 (TLSServer Class)

Handles remote or external signing initiated by the server protocol.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireExternalSign(TLSServerExternalSignEventParams *e);

typedef struct {
  int64 ConnectionID;
  const char *OperationId;
  const char *HashAlgorithm;
  const char *Pars;
  const char *Data;
  char *SignedData;
  int reserved;
} TLSServerExternalSignEventParams;


Unicode (Windows)
virtual INT FireExternalSign(TLSServerExternalSignEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  LPCWSTR OperationId;
  LPCWSTR HashAlgorithm;
  LPCWSTR Pars;
  LPCWSTR Data;
  LPWSTR SignedData;
  INT reserved;
} TLSServerExternalSignEventParams;

#define EID_TLSSERVER_EXTERNALSIGN 6

virtual INT SECUREBLACKBOX_CALL FireExternalSign(LONG64 &lConnectionID, LPSTR &lpszOperationId, LPSTR &lpszHashAlgorithm, LPSTR &lpszPars, LPSTR &lpszData, LPSTR &lpszSignedData);

class TLSServerExternalSignEventParams {
public:
  qint64 ConnectionID();

  const QString &OperationId();

  const QString &HashAlgorithm();

  const QString &Pars();

  const QString &Data();

  const QString &SignedData();
  void SetSignedData(const QString &qsSignedData);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ExternalSign(TLSServerExternalSignEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireExternalSign(TLSServerExternalSignEventParams *e) {...}

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 (TLSServer Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotification(TLSServerNotificationEventParams *e);

typedef struct {
  const char *EventID;
  const char *EventParam;
  int reserved;
} TLSServerNotificationEventParams;


Unicode (Windows)
virtual INT FireNotification(TLSServerNotificationEventParams *e);

typedef struct {
  LPCWSTR EventID;
  LPCWSTR EventParam;
  INT reserved;
} TLSServerNotificationEventParams;

#define EID_TLSSERVER_NOTIFICATION 7

virtual INT SECUREBLACKBOX_CALL FireNotification(LPSTR &lpszEventID, LPSTR &lpszEventParam);

class TLSServerNotificationEventParams {
public:
  const QString &EventID();

  const QString &EventParam();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Notification(TLSServerNotificationEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireNotification(TLSServerNotificationEventParams *e) {...}

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.

This class can fire this event with the following EventID values:

TLSCertValidate Event (TLSServer Class)

Fires when a client certificate needs to be validated.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSCertValidate(TLSServerTLSCertValidateEventParams *e);

typedef struct {
  int64 ConnectionID;
  int Accept;
  int reserved;
} TLSServerTLSCertValidateEventParams;


Unicode (Windows)
virtual INT FireTLSCertValidate(TLSServerTLSCertValidateEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  BOOL Accept;
  INT reserved;
} TLSServerTLSCertValidateEventParams;

#define EID_TLSSERVER_TLSCERTVALIDATE 8

virtual INT SECUREBLACKBOX_CALL FireTLSCertValidate(LONG64 &lConnectionID, BOOL &bAccept);

class TLSServerTLSCertValidateEventParams {
public:
  qint64 ConnectionID();

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSCertValidate(TLSServerTLSCertValidateEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireTLSCertValidate(TLSServerTLSCertValidateEventParams *e) {...}

Remarks

The class fires this event to notify the application of an authenticating client. Use the event handler to validate the certificate and pass your decision back to the server component via the Accept parameter.

TLSEstablished Event (TLSServer Class)

Reports the setup of a TLS session.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSEstablished(TLSServerTLSEstablishedEventParams *e);

typedef struct {
  int64 ConnectionID;
  int reserved;
} TLSServerTLSEstablishedEventParams;


Unicode (Windows)
virtual INT FireTLSEstablished(TLSServerTLSEstablishedEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  INT reserved;
} TLSServerTLSEstablishedEventParams;

#define EID_TLSSERVER_TLSESTABLISHED 9

virtual INT SECUREBLACKBOX_CALL FireTLSEstablished(LONG64 &lConnectionID);

class TLSServerTLSEstablishedEventParams {
public:
  qint64 ConnectionID();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSEstablished(TLSServerTLSEstablishedEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireTLSEstablished(TLSServerTLSEstablishedEventParams *e) {...}

Remarks

Subscribe to this event to be notified about the setup of a TLS connection by a connected client.

TLSHandshake Event (TLSServer Class)

Fires when a newly established client connection initiates a TLS handshake.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSHandshake(TLSServerTLSHandshakeEventParams *e);

typedef struct {
  int64 ConnectionID;
  const char *ServerName;
  int Abort;
  int reserved;
} TLSServerTLSHandshakeEventParams;


Unicode (Windows)
virtual INT FireTLSHandshake(TLSServerTLSHandshakeEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  LPCWSTR ServerName;
  BOOL Abort;
  INT reserved;
} TLSServerTLSHandshakeEventParams;

#define EID_TLSSERVER_TLSHANDSHAKE 10

virtual INT SECUREBLACKBOX_CALL FireTLSHandshake(LONG64 &lConnectionID, LPSTR &lpszServerName, BOOL &bAbort);

class TLSServerTLSHandshakeEventParams {
public:
  qint64 ConnectionID();

  const QString &ServerName();

  bool Abort();
  void SetAbort(bool bAbort);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSHandshake(TLSServerTLSHandshakeEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireTLSHandshake(TLSServerTLSHandshakeEventParams *e) {...}

Remarks

Use this event to get notified about the initiation of the TLS handshake by the remote client. The ServerName parameter specifies the requested host from the client hello message.

TLSPSK Event (TLSServer Class)

Requests a pre-shared key for TLS-PSK.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSPSK(TLSServerTLSPSKEventParams *e);

typedef struct {
  int64 ConnectionID;
  const char *Identity;
  char *PSK;
  char *Ciphersuite;
  int reserved;
} TLSServerTLSPSKEventParams;


Unicode (Windows)
virtual INT FireTLSPSK(TLSServerTLSPSKEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  LPCWSTR Identity;
  LPWSTR PSK;
  LPWSTR Ciphersuite;
  INT reserved;
} TLSServerTLSPSKEventParams;

#define EID_TLSSERVER_TLSPSK 11

virtual INT SECUREBLACKBOX_CALL FireTLSPSK(LONG64 &lConnectionID, LPSTR &lpszIdentity, LPSTR &lpszPSK, LPSTR &lpszCiphersuite);

class TLSServerTLSPSKEventParams {
public:
  qint64 ConnectionID();

  const QString &Identity();

  const QString &PSK();
  void SetPSK(const QString &qsPSK);

  const QString &Ciphersuite();
  void SetCiphersuite(const QString &qsCiphersuite);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSPSK(TLSServerTLSPSKEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireTLSPSK(TLSServerTLSPSKEventParams *e) {...}

Remarks

The class fires this event to report that a client has requested a TLS-PSK negotiation. ConnectionId indicates the unique connection ID that requested the PSK handshake.

Use Identity to look up for the corresponding pre-shared key in the server's database, then assign the key to the PSK parameter. If TLS 1.3 PSK is used, you will also need to assign the Ciphersuite parameter with the cipher suite associated with that identity and their key.

TLSShutdown Event (TLSServer Class)

Reports closure of a TLS session.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSShutdown(TLSServerTLSShutdownEventParams *e);

typedef struct {
  int64 ConnectionID;
  int reserved;
} TLSServerTLSShutdownEventParams;


Unicode (Windows)
virtual INT FireTLSShutdown(TLSServerTLSShutdownEventParams *e);

typedef struct {
  LONG64 ConnectionID;
  INT reserved;
} TLSServerTLSShutdownEventParams;

#define EID_TLSSERVER_TLSSHUTDOWN 12

virtual INT SECUREBLACKBOX_CALL FireTLSShutdown(LONG64 &lConnectionID);

class TLSServerTLSShutdownEventParams {
public:
  qint64 ConnectionID();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSShutdown(TLSServerTLSShutdownEventParams *e);

// Or, subclass TLSServer and override this emitter function.
virtual int FireTLSShutdown(TLSServerTLSShutdownEventParams *e) {...}

Remarks

The class fires this event when a connected client closes their TLS session gracefully. This event is typically followed by a Disconnect, which marks the closure of the underlying TCP session.

Certificate Type

Encapsulates an individual X.509 certificate.

Syntax

SecureBlackboxCertificate (declared in secureblackbox.h)

Remarks

This type keeps and provides access to X.509 certificate details.

Fields

Constructors

Certificate()

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Syntax

SecureBlackboxExternalCrypto (declared in secureblackbox.h)

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

ExternalCrypto()

SocketSettings Type

A container for the socket settings.

Syntax

SecureBlackboxSocketSettings (declared in secureblackbox.h)

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

SocketSettings()

TLSConnectionInfo Type

Contains information about a network connection.

Syntax

SecureBlackboxTLSConnectionInfo (declared in secureblackbox.h)

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

TLSConnectionInfo()

TLSSettings Type

A container for TLS connection settings.

Syntax

SecureBlackboxTLSSettings (declared in secureblackbox.h)

Remarks

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

Fields

Constructors

TLSSettings()

SecureBlackboxList Type

Syntax

SecureBlackboxList<T> (declared in secureblackbox.h)

Remarks

SecureBlackboxList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the TLSServer class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

Config Settings (TLSServer Class)

TLSServer Config Settings

Base Config Settings