TLS/SSL¶
KX Sensors can use Secure Sockets Layer (SSL)/Transport Layer Security (TLS) to encrypt connections using the OpenSSL libraries.
When TLS is configured, it applies to all connections:
- Outgoing Gateway (GW) connections
- Incoming Response Process (RP) connections
- Message Queue (MQ) connections
- ETCD connections (Discovery)
Keys/Certificates¶
To enable TLS connections for SAPI; set the flag UseTLS through the SAPI config object to true.
SAPI offers two ways to configure the certificate and keys; hardcoded strings or file locations. It does not support a mixture of hardcoded strings/file paths.
The exact naming differs between the interface languages.
TLS gets configured through the SAPITLS struct.
typedef struct
{
char *CA; // TLS CA certificate
char *CAFile; // File location of TLS CA certificate. If provided, will override the value for `tlsCA`
char *cert; // TLS certificate
char *certFile; // File location of TLS certificate. If provided, will override the value for `tlsCert`
char *key; // Certificate key
char *keyFile; // File location of Certificate key. If provided, will override the value for `tlsKey`
bool verifyClient; // Verify that the certificate provided to incoming is valid
bool verifyServer; // Verify that the certificate provided to outgoing connections is valid
} SAPITLS;Configuring TLS using hardcoded strings
SAPIConfig *config = calloc(1, sizeof(SAPIConfig));
SAPITLS* tls = calloc(1, sizeof(SAPITLS));
tls->CA = "-----BEGIN CERTIFICATE-----\n"
"MIIDhzCCAm+gAwIBAgIUIXAoIbivJCxFbj5UXoAE3JBNl3QwDQYJKoZIhvcNAQEL\n"
"...\n"
"-----END CERTIFICATE-----\n";
tls->cert = "-----BEGIN CERTIFICATE-----\n"
"MIIDdDCCAlygAwIBAgIUaRcc63KyIcgtYQPrvBWVc7ewGd8wDQYJKoZIhvcNAQEL\n"
"...\n"
"-----END CERTIFICATE-----\n";
tls->key = "-----BEGIN PRIVATE KEY-----\n"
"MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCT1S1b0zR9Wdyw\n"
"...\n"
"-----END PRIVATE KEY-----\n";
tls->verifyClient = true;
tls->verifyServer = true;
config->tls = tls;
config->useTLS = true;Configuring TLS using file-based certificates
SAPIConfig *config = calloc(1, sizeof(SAPIConfig));
SAPITLS* tls = calloc(1, sizeof(SAPITLS));
tls->CAFile = "certs/ca-cert.pem";
tls->certFile = "certs/client-cert.pem";
tls->keyFile = "certs/client-private-key.pem";
tls->verifyClient = true;
tls->verifyServer = true;
config->tls = tls;
config->useTLS = true;The TLS struct offers flag for validation of client and server certificates:
VerifyClient: Verify that the certificate provided to incoming connections is validVerifyServer: Verify that the certificate provided to outgoing connections is valid
TLS gets configured through the SapiTls class.
namespace Kx.Sapi
{
public class SapiTls
{
/// <summary>
/// TLS CA certificate
/// </summary>
public string CA { get; set; } = null;
/// <summary>
/// File location of TLS CA certificate. If provided, will override the value for `tlsCA`
/// </summary>
public string CAFile { get; set; } = null;
/// <summary>
/// TLS certificate
/// </summary>
public string Cert { get; set; } = null;
/// <summary>
/// File location of TLS certificate. If provided, will override the value for `tlsCert`
/// </summary>
public string CertFile { get; set; } = null;
/// <summary>
/// Certificate key
/// </summary>
public string Key { get; set; } = null;
/// <summary>
/// File location of Certificate key. If provided, will override the value for `tlsKey`
/// </summary>
public string KeyFile { get; set; } = null;
/// <summary>
/// Verify that the certificate provided to incoming is valid
/// </summary>
public bool VerifyClient { get; set; } = false;
/// <summary>
/// Verify that the certificate provided to outgoing connections is valid
/// </summary>
public bool VerifyServer { get; set; } = false;
}
}
Configuring TLS using hardcoded strings
SapiConfig config = new()
{
Tls = new()
{
CA = """
-----BEGIN CERTIFICATE-----
MIIDhzCCAm+gAwIBAgIUIXAoIbivJCxFbj5UXoAE3JBNl3QwDQYJKoZIhvcNAQEL
BQAwUzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQHDAlTb21ld2hl
...
-----END CERTIFICATE-----
""",
Cert = """
-----BEGIN CERTIFICATE-----
MIIDdDCCAlygAwIBAgIUaRcc63KyIcgtYQPrvBWVc7ewGd8wDQYJKoZIhvcNAQEL
...
-----END CERTIFICATE-----
""",
Key = """
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCT1S1b0zR9Wdyw
...
-----END PRIVATE KEY-----
""",
VerifyClient = true,
VerifyServer = true
}
};
config.UseTLS = true;Configuring TLS using file-based certificates
SapiConfig config = new();
config.Tls = new()
{
CAFile = "certs/ca-cert.pem",
CertFile = "certs/client-cert.pem",
KeyFile = "certs/client-private-key.pem",
};
config.UseTLS = true;The TLS class offers flag for validation of client and server certificates:
VerifyClient: Verify that the certificate provided to incoming connections is validVerifyServer: Verify that the certificate provided to outgoing connections is valid
TLS gets configured through the SapiTLS class.
public class SapiTLS {
private String CA; // TLS CA certificate
private String CAFile; // File location of TLS CA certificate. If provided, will override the value for `tlsCA`
private String cert; // TLS certificate
private String certFile; // File location of TLS certificate. If provided, will override the value for `tlsCert`
private String key; // Certificate key
private String keyFile; // File location of Certificate key. If provided, will override the value for `tlsKey`
private Boolean verifyClient; // Verify that the certificate provided to incoming is valid
private Boolean verifyServer; // Verify that the certificate provided to outgoing connections is valid
/**
* @return TLS CA certificate
*/
public String getCA() {
return CA;
}
/**
* @param CA TLS CA certificate
*/
public void setCA(String CA) {
this.CA = CA;
}
/**
* @return File location of TLS CA certificate. If provided, will override the value for `tlsCA`
*/
public String getCAFile() {
return CAFile;
}
/**
* @param CAFile File location of TLS CA certificate. If provided, will override the value for `tlsCA`
*/
public void setCAFile(String CAFile) {
this.CAFile = CAFile;
}
/**
* @return TLS certificate
*/
public String getCert() {
return cert;
}
/**
* @param cert TLS certificate
*/
public void setCert(String cert) {
this.cert = cert;
}
/**
* @return File location of TLS certificate. If provided, will override the value for `tlsCert`
*/
public String getCertFile() {
return certFile;
}
/**
* @param certFile File location of TLS certificate. If provided, will override the value for `tlsCert`
*/
public void setCertFile(String certFile) {
this.certFile = certFile;
}
/**
* @return Certificate key
*/
public String getKey() {
return key;
}
/**
* @param key Certificate key
*/
public void setKey(String key) {
this.key = key;
}
/**
* @return File location of Certificate key. If provided, will override the value for `tlsKey`
*/
public String getKeyFile() {
return keyFile;
}
/**
* @param keyFile File location of Certificate key. If provided, will override the value for `tlsKey`
*/
public void setKeyFile(String keyFile) {
this.keyFile = keyFile;
}
/**
* @return Verify that the certificate provided to incoming is valid
*/
public Boolean getVerifyClient() {
return verifyClient;
}
/**
* @param verifyClient Verify that the certificate provided to incoming is valid
*/
public void setVerifyClient(Boolean verifyClient) {
this.verifyClient = verifyClient;
}
/**
* @return Verify that the certificate provided to outgoing connections is valid
*/
public Boolean getVerifyServer() {
return verifyServer;
}
/**
* @param verifyServer Verify that the certificate provided to outgoing connections is valid
*/
public void setVerifyServer(Boolean verifyServer) {
this.verifyServer = verifyServer;
}
@Override
public String toString() {
return "SapiTls [CA=" + CA + ", CAFile=" + CAFile
+ ", cert=" + cert + ", certFile=" + certFile
+ ", key=" + key + ", keyFile=" + keyFile
+ ", verifyClient=" + verifyClient + ", verifyServer=" + verifyServer + "]";
}
}
Configuring TLS using hardcoded strings
SapiConfig config = new SapiConfig();
SapiTLS tls = new SapiTLS();
tls.setCA("-----BEGIN CERTIFICATE-----\n" +
"MIIDhzCCAm+gAwIBAgIUIXAoIbivJCxFbj5UXoAE3JBNl3QwDQYJKoZIhvcNAQEL\n" +
"...\n" +
"-----END CERTIFICATE-----\n");
tls.setCert("-----BEGIN CERTIFICATE-----\n" +
"MIIDdDCCAlygAwIBAgIUaRcc63KyIcgtYQPrvBWVc7ewGd8wDQYJKoZIhvcNAQEL\n" +
"...\n" +
"-----END CERTIFICATE-----\n");
tls.setKey("-----BEGIN PRIVATE KEY-----\n" +
"MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCT1S1b0zR9Wdyw\n" +
"...\n" +
"-----END PRIVATE KEY-----\n");
tls.setVerifyClient(true);
tls.setVerifyServer(true);
config.setTLS(tls);
config.setUseTLS(true);Configuring TLS using file-based certificates
SapiConfig config = new SapiConfig();
SapiTLS tls = new SapiTLS();
tls.setCAFile("certs/ca-cert.pem");
tls.setCertFile("certs/client-cert.pem");
tls.setKeyFile("certs/client-private-key.pem");
tls.setVerifyClient(true);
tls.setVerifyServer(true);
config.setTLS(tls);
config.setUseTLS(true);The TLS class offers flag for validation of client and server certificates:
VerifyClient: Verify that the certificate provided to incoming connections is validVerifyServer: Verify that the certificate provided to outgoing connections is valid
TLS gets configured through the SAPITLS class.
class SAPITLS:
"""TLS settings used for SAPI connections."""
CA: Optional[str] = None
CAFile: Optional[str] = None
cert: Optional[str] = None
certFile: Optional[str] = None
key: Optional[str] = None
keyFile: Optional[str] = None
verifyClient: bool = False
verifyServer: bool = FalseConfiguring TLS using hardcoded strings
config = SAPIConfig()
tls = SapiTLS()
tls.CA = """-----BEGIN CERTIFICATE-----
MIIDhzCCAm+gAwIBAgIUIXAoIbivJCxFbj5UXoAE3JBNl3QwDQYJKoZIhvcNAQEL
...
-----END CERTIFICATE-----"""
tls.cert = """-----BEGIN CERTIFICATE-----
MIIDdDCCAlygAwIBAgIUaRcc63KyIcgtYQPrvBWVc7ewGd8wDQYJKoZIhvcNAQEL
...
-----END CERTIFICATE-----"""
tls.key = """-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCT1S1b0zR9Wdyw
...
-----END PRIVATE KEY-----"""
tls.verifyClient = True
tls.verifyServer = True
config.tls = tls
config.useTLS = TrueConfiguring TLS using file-based certificates
config = SAPIConfig()
tls = SAPITLS(
CAFile="certs/ca-cert.pem",
keyFile="certs/client-private-key.pem",
certFile="certs/client-cert.pem"
)
tls.verifyClient = True
tls.verifyServer = True
config.tls = tls
config.useTLS = TrueThe TLS class offers flag for validation of client and server certificates:
verifyClient: Verify that the certificate provided to incoming connections is validverifyServer: Verify that the certificate provided to outgoing connections is valid