Security for Edge Java SDK Applications
A client application written using the ThingWorx Edge Java SDK can communicate with the ThingWorx Platform using the SSL/TLS protocol. The SDK supports the use of the Java Secure Socket Extension (JSSE) and certificates that are generated using the Java keytool utility. The JSSE supports SSL v.3.0, TLS versions 1.0, 1.1, 1.2, and 1.3, and DTLS versions 1.0 and 1.2.
The SSL and TLS protocols run above the TCP/IP layer and below the higher-level protocols such as HTTP and WebSocket. The SSL and TLS protocols use TCP/IP on behalf of the higher-level protocols, allowing an SSL/TLS-enabled server to authenticate itself to an SSL/TLS-enabled client..
These protocols provide encryption (confidentiality) and enables integrity and non-repudiation of communications. Further, they allow the client to authenticate itself to the server, and, if authentication is successful, they allow the client and server to establish an encrypted connection.
The features of the SSL and TLS protocols address typical issues concerning the security of data communicated over the Internet and other TCP/IP networks. These features include the following:
• Server Authentication — Allows the client such as a remote device to confirm the identity of a server such as ThingWorx Platform before sending data. The standard techniques of public-key cryptography are used to check that the certificate and identity of a ThingWorx Platform are valid and have been issued by a well-known certificate authority (CA) that is listed in the device’s list of trusted CAs.
• Encrypted Connection — Requires all information sent between a client and a server to be encrypted by the sending software and decrypted by the receiving software, thus providing a high degree of confidentiality. In addition to providing data confidentiality, the SSL and TLS protocols ensure integrity of transmitted data. That is, they provide a mechanism for determining whether the data has been altered in transit (message authentication).
• Client Authentication — Allows a server to confirm the identity of a client (device). Using the same techniques as those used for server authentication, the server software checks that the certificate and identity of the device are valid and have been issued by a well-known certificate authority (CA) that is listed in the server’s list of trusted CAs. Client authentication is an optional feature.
The SSL/TLS protocol supports the use of a variety of different encryption algorithms, or ciphers, for operations such as authenticating the server and client to each other, transmitting certificates, and establishing session keys. Clients and servers may support different cipher suites (sets of ciphers), depending on factors such as the version of SSL/TLS supported, company policies regarding acceptable encryption strength, and government restrictions on the export of SSL/TLS-enabled software.
 |
Java and OpenSSL provide different implementations of SSL/TLS. The concepts are the same, but the file extensions differ. What the files contain is the same. The ThingWorx Edge Java SDK and the ThingWorx Platform use Java TLS. You can use X.509 certificates and private keys for TLS communications between Java SDK client applications and the platform.
|
Types of Certificates and Contents of a Certificate File
Essentially, certificates are used for either of two purposes:
• Establishing Trust — Trusted Certificate Authority (CA) certificates verify other certificates. Typically, these files are found on a client that is attempting to establish an SSL/TLS connection with a server. For example, the installation of your Edge Java SDK application (the "client") should include valid certificates that belong to the issuers of the ThingWorx Platform certificates.
• Establishing Identity — Identity certificates with private keys provide a way of communicating the unique identity of an SSL/TLS peer. Identity certificates with private keys are typically used to show the identity of a server to a client. When a server requires client authentication, Identity certificates are also required on the client. In this latter case, the Trusted Certificate Authority certificate would be required on the server.
The requirements for products acting as clients or servers in SSL/TLS connections follow:
• A server must always have an Identity certificate. Optionally, if the product acting as a server supports and is configured to use client authentication, the server would need a Trusted Certificate Authority certificate.
• A client must always have a Trusted Certificate Authority (CA) certificate. An example of a Trusted CA certificate name is SSLCACert.pem. Optionally, if the product acting as a server supports and is configured to use client authentication, the client would also need an Identity certificate. An example of a client-side Identity certificate file name is SSLCert.pem, and an example of its private key name is SSLPrivKey.pem.
A keystore is a collection of keys, while a trust store is a collection of certificates or of keys.
Certificates Required
Note the following requirements for products acting as clients or servers in SSL/TLS connections. In each case, the "server" is the ThingWorx Platform and the client is the ThingWorx Edge Java SDK application running on a device/machine:
• A server must always have an Identity certificate (Identity.jks file). Optionally, if the server supports and is configured to use client authentication, the server would need a Trusted Certificate Authority (CA) certificate.
• A client must always have a Trusted Certificate Authority (CA) certificate. An example of a Trusted CA certificate is SSLCACert.pem. Optionally, if the server supports and is configured to use client authentication, the client would also need an Identity certificate. An example of a client-side Identity certificate file is SSLCert.pem, and an example of its private key is SSLPrivKey.pem.
Validation of SSL/TLS Certificates
An SSL/TLS-enabled client performs the following steps to authenticate a server:
1. The client checks the validity period of the server’s certificate. If the current date and time are outside of that period, the authentication process stops.
2. If step 1 passes, the client checks its list of trusted CA certificates to determine if the server's certificate Issuer is one of its trusted CAs. If the issuing CA is not on the list, the server is not authenticated unless the client can verify another certificate from the server's certificate chain against a CA that is on the list.
3. If step 2 passes, the client uses the public key from the CA’s certificate to validate the CA’s digital signature on the server certificate being presented. If the information in the server certificate does not correspond to the digital signature, the client will not authenticate the server’s identity. If the CA’s digital signature is validated, the client treats the server’s certificate as a valid “letter of introduction” from that CA and proceeds. At this point, the client has determined that the server certificate is valid.
4. If step 3 passes, the client can check various certificate fields against pre-configured values in order to validate them. This check confirms that the server's certificate is owned by the server with which the client intended to communicate, and not some other party. Although technically not part of the SSL/TLS protocol, this check provides the only protection against a form of security attack known as a Man-in-the-Middle attack. Clients should be configured to perform this check. You can specify Issuer and Subject fields for the connection through the ClientConfigurator of the ThingWorx Edge Java SDK. For example, set up the following in the ClientConfigurator:
config.setIssuerCN("Well_known_Issuer")
config.setIssuerO("Verisign")
config.setIssuerOU("Verisign IT")
config.setSubjectCN("thingworx.com")
config.setSubjectO("ThingWorx")
config.setSubjectOU("ThingWorx Team")
Optionally, an SSL/TLS-enabled server performs the following checks to authenticate a client:
1. The server checks the Validity period of the certificate. If the current date and time fall outside the period, the authentication process stops.
2. If step 1 passes, the server checks its list of trusted CA certificates to determine if the client's certificate Issuer matches the Subject of a CA on the server’s list. If the issuing CA is not on the list, the server does not authenticate the client unless it can verify another certificate from the client's certificate chain against a CA that is on the list. Administrators can control which certificates are trusted or not trusted within their organizations by controlling the lists of CA certificates maintained by clients and servers.
3. If step 2 passes, the server uses the public key from the CA’s certificate to validate the CA’s digital signature on the certificate being presented. If the information in the certificate does not correspond to the digital signature, the server does not authenticate the client’s identity. If the CA’s digital signature can be validated, the server treats the client's certificate as a valid “letter of introduction” from that CA and proceeds. At this point, the SSL/TLS protocol allows the server to consider the client authenticated and proceed with the connection.
4. Optionally, when step 3 passes, the server checks if the client’s certificate has been revoked by the Issuer. If you use this check, you can reject a client’s certificate even if it passes the tests in all the other steps. All servers that are set up to perform this check will then refuse to authenticate that certificate and will not establish a connection with the client.