Require Clients to Provide Certificates to the Gateway
Typically, TLS/SSL is used to validate the Gateway's identity to the client and encrypt data. However you can also use TLS/SSL to have the Gateway validate a client's identity. When TLS/SSL is used to verify both the Gateway and clients, it is sometimes referred to as mutual verification.
Note: You instruct the Gateway to verify the Kaazing WebSocket Gateway client's identity by including the ssl.verify-client element in the Gateway configuration. The Gateway will not establish a TLS/SSL connection (HTTPS or WSS) with the client until the identity of client has been verified.With client-side certificates, after the Kaazing WebSocket Gateway client has validated the certificate from the Gateway, the Gateway responds with a challenge to the client. This challenge includes all the public keys included in the truststore of the Gateway. The client then attempts to find a matching private key in its keystore (or keystore equivalent based on the client operating system or web browser) and respond with that key.
To prepare your clients for this client-side verification, you must create a new certificate for the client, put the public key of the certificate in the Gateway's truststore, put the private key in the client's keystore.
Important: Do not use the same certificate for both the client and Gateway. Doing so would put the connection at risk of TLS/SSL replay attacks.This procedure describes how to implement a mutual verification pattern where, in addition to the Gateway presenting a certificate to the client, the client must present a certificate to the Gateway so that the Gateway can verify the client's identity.
Before You Begin
This procedure is part of Checklist: Secure Network Traffic with the Gateway, that includes the following steps:
- Secure the Gateway Using Trusted Certificates
- Secure the Gateway Using Self-Signed Certificates (Optional)
- Secure Clients and Web Browsers with a Self-Signed Certificate (Optional)
- Require Clients to Provide Certificates to the Gateway (Optional)
- Implement Certificate Revocation Using OCSP (Optional)
To Configure Clients to Provide TLS/SSL Certificates
- On the Kaazing WebSocket Gateway client, create a new self-signed certificate. The public key in this self-signed certificate will be imported into the truststore on the Gateway later. Each operating system has a different method for creating client certificates.
Export the public key certificate from the client. If you are using the Java keytool utility, the command is:
keytool -export -alias name -file client_certificate.cer -keystore client-keystore.jks
Import the public key into the Gateway's truststore using the Java keytool utility:
keytool -importcert -keystore GATEWAY_HOME\conf\truststore.db -storepass changeit -trustcacerts -alias name -file client_certificate.cer
Add the ssl.verify-client option in your Gateway configuration (GATEWAY_HOME/conf/gateway-config.xml).
The following example shows a snippet of a simple Gateway configuration that accepts on a secure URI (wss://) and includes the ssl.verify-client option (shown in line 8) to require that all clients connecting to the Gateway on that URI provide a digital certificate verifying their identity.
<service> <accept>wss://example.com:443</accept> <connect>tcp://server1.corp.example.com:5050</connect> <type>proxy</type> <accept-options> <ssl.verify-client>required</ssl.verify-client> </accept-options> </service>
- Start the Gateway.
- Connect to the Gateway from the client using the HTTPS/WSS URI. The Gateway will provide the client with a certificate. Once the client has verified that certificate, the Gateway will request a client certificate from the client. Once the Gateway has verified the client certificate, the secure connection is established.
- To use ssl.verify-client as an accept-option on a service, the service must be accepting on a secure URI (wss://, https://, ssl://). You cannot use ssl.verify-client on a unsecured URI (ws://, http://, tcp://, udp://).
- For more examples, including how to require clients to provide certificates in an Enterprise Shield™ topology, see Configure Enterprise Shield™ and the ssl.verify-client accept-option.
Next Step
To troubleshoot TLS/SSL errors and exceptions, see Troubleshooting Kaazing WebSocket Gateway Security.
Notes
- This procedure is recommended for added security in an Enterprise Shield™ topology. See About Enterprise Shield™ for more topics and information.
- Consider configuring the socks.ssl.verify-client connect-option for end-to-end security in an Enterprise Shield™ topology.
- A best practice is to use mutual verification between gateways that are located at different sites. Each gateway can require that the other gateway provide a certificate, thereby ensuring that the connection is secure.
- To support DSA certificates, you must add ADH to the ssl.ciphers element as follows: <ssl.ciphers>HIGH, MEDIUM, ADH</ssl.ciphers>. Do not use ADH with DEFAULT. DSA certificates are not recommended. See Diffie-Hellman key exchange for more information. If you omit the -keyalg switch when you create a certificate using keytool, keytool generates a DSA certificate. You should always include -keyalg RSA when creating a certificate using keytool.