ws-to-wss-proxy

What is this for?

The ws-to-wss-proxy can act as a bridge between WebSocket clients that don't support TLS and WebSocket servers that require TLS. HTTP Basic Authentication can optionally be used. TLS client certificates are also supported.

Building the Dockerfile

The Dockerfile can be built in the regular way, by running the following command in the project root folder:

docker build -t ws-to-wss-proxy .

Generating a TLS client certificate

Although most wss/https servers don't require a TLS client certificate, the NGINX configuration template is currently hard-coded to assume the existence of a TLS client certificate in the mounted directory /cert, and will therefore require one.

If the cert folder doesn't yet contain a certificate (clientcert.pem) and its corresponding private key (clientcertkey.pem), you can run the provided convenience script to create these, since the Docker container will look for the certificate and the key and will fail to start if it doesn't find them. Run the convenience script as follows:

./generate-client-cert.sh

Starting and accessing the proxy

To run the proxy in a Docker container, reachable on port 8080 on localhost, with the TLS client certificate you generated as instructed above, run the following Docker command:

docker run -p 8080:80 -e NGINX_PORT=80 -v $(pwd)/cert:/cert ws-to-wss-proxy

While the Docker container is running, you should be able to reach the WebSocket server through the proxy without TLS.

The proxy determines the target WSS server dynamically from the URL at which any client accesses the proxy. You need to take the WSS URL, without the wss:// prefix, and then suffix it behind the /wss endpoint in the ws:// URI.

For instance, if you started the Docker container through the example command above, and the TLS-requiring WebSocket server is reachable at wss://my-csms.com/ocpp, a WebSocket client should now be able to reach it through the proxy at ws://localhost:8080/wss/my-csms.com/ocpp, provided that the WebSocket client is running in the same environment in which the Docker container is deployed.

You may have to set up some routing and use something other than localhost for the WebSocket client to reach the proxy if they are running on different machines, but that shouldn't be too hard to figure out.

Note that if the wss/https server requires a TLS client certificate, you need to provide whomever maintains that server with a copy of the file cert/clientcert.pem (not clientcertkey.pem!), and ask them to configure it as the TLS client certificate that will identify the client that you will be trying to connect to that server through the proxy. If you don't take care of this beforehand, the connection will likely be rejected by the server, probably with an HTTP 401 response.