Secure Connections

The Interoperability Test Platform provides several ways to ensure that your test components are behaving in a secure way.

Encrypted Connections with mTLS

Normally, two components of a system may communicate via mutual TLS (mTLS), where both the client and the server authenticate themselves using public key cryptography. Since the test platform is a proxy in between these two components, we must now consider two connections instead of one:

1. The connection between a client and the proxy (acting on behalf of a server)
2. The connection between the proxy (acting as a client) and the server

In many cases where mTLS is used, these two connections may additionally operate in the reverse direction (i.e. the client may also act as a server, and vice versa).

Note that in the code samples below, openssl is used. Similar operations can be performed with any appropriate tool.

Proxy → Server

In this leg, ITP is acting as an application client, and your SUT is the application server. Although this is the second leg of the connection, it needs to be configured first, as part of the session creation wizard:

It is assumed that the application server is already configured with a server key and server certificate, signed by a private certificate authority (CA). In the code samples below, ca.crt refers the the public certificate of the private CA, and ca.key refers to its private key.

Firstly, the CA certificate (ca.crt) can be uploaded directly. This will be used by ITP to verify that your server is authenticating itself correctly with a valid server certificate.

To authenticate itself to your server, ITP also needs to present a client certificate signed by your private CA. In order to do this, a certificate signing request (CSR) can be generated as part of the session creation wizard. You can download this CSR (client.csr), and generate a client certificate (client.crt) using the CA credentials:

openssl x509 -req -days 365 \
    -in client.csr -out client.crt \
	-CA ca.crt -CAkey ca.key -CAcreateserial

You can now upload the client certificate to the platform and proceed to the next step of session creation.

Instead of uploading these certificates every time a new session is created, it is also possible to upload the certificates to a user group. By doing this, a dropdown will appear allowing you to select preconfigured certificates directly.

Debugging

It is possible to bypass this leg of the encrypted connection by disabling the "use encryption" setting for the component. When you do this, the URLs which are displayed will change to use the "insecure" version of the URL. However ITP will continue to present a secure mTLS server, so it will be possible for the Client → Proxy leg to continue to use the original secure url. A test failure will be logged on the test results, to indicate that an insecure connection was used when a secure one was expected.

Client → Proxy

In this direction, ITP is acting as an application server. ITP will present a server certificate (signed by its own private certificate authority), and will require that the client presents a client certificate signed by the same private certificate authority (CA). To establish an encrypted connection, therefore, you must obtain a signed client certificate when you create a session.

To do this, the client must first have a private key. If you do not already have a private key, one can be generated with:

openssl genrsa -out client.key 2048

Once you have a private key, you will need to generate a CSR (client.csr). This contains the information required for ITP to generate a signed certificate:

openssl req -new -key client.key -out client.csr

Within the test session, you can click the "Download Certificates" button to obtain this signed certificate. After uploading client.csr in the window that appears, you will be able to download a zip file containing two certificates.

One certificate will be called client.crt, which is the certificate your client should present when sending a request. The other certificate is called RootCA.crt, and your client should use this certificate as a CA certificate to validate the authenticity of ITP's server certificate.

These two certificates will remain constant across all sessions (as long as your client key does not change), so you should not need to reconfigure these certificates at any stage.

Debugging

It is possible to bypass the encrypted connection for this step by using the "insecure" version of the URL. When you use the insecure version of the URL, no mTLS checking is performed and a direct HTTP connection can be used. ITP will continue to use an mTLS connection when for the Proxy → Server leg, so the server will not need to be reconfigured. A test failure will be logged on the test results, to indicate that an insecure connection was used when a secure one was expected.

JSON Web Signatures (JWS)

Test cases can be defined with configuration to support JWS signatures. This configuration reads values from a session's environment. As a result, selecting a test case with a JWS configuration will add entries to a session's file environments:

Although the names of these variables may differ, there will generally always be two variables for each component which uses JWS signatures - a private key and a public key. As with all environment variables, it is possible to provide these through a user group environment instead of entering them separately for each new test session.

The public key should always be provided. ITP will use this to validate the JWS signature of the request when it is made. If the signature is malformed, a test failure will be logged.

The private key only needs to be provided if the component is being simulated by ITP. In this case, ITP needs to generate the signature itself, and it will use the given private key to do so. It is important that the private key matches the public key, otherwise the signature will be malformed when it is validated.

If you need to generate a new public/private key pair, you can do so using openssl or many other tools:

openssl genrsa -out private.key 2048
openssl rsa -in private.key -out public.key -pubout -outform PEM

If you already have a pair of keys, and you wish to verify that they correspond to one another, you can also do this with openssl. The output of the following two commands will be identical if the keys are a matching pair.

openssl rsa -in private.key -noout -modulus | openssl md5
openssl rsa -pubin -in public.key -noout -modulus | openssl md5