Certificates

The home client serves HTTPS, and the skill checks the client's certificate before it sends anything. The certificate must name the host in your endpoint URL, and be either:

  • publicly trusted, such as a free Let's Encrypt certificate (recommended: nothing to upload), or
  • issued by your own CA, which you then upload on the settings site so the skill trusts it.

Optionally, the client can also require a client certificate from every caller (mTLS), so only the skill (holding the certificate you uploaded) can talk to it. See Require client certificates.

Free, publicly trusted, and nothing to upload. You need a DNS name (a name and a port).

  1. Get a certificate for home.example.net with any ACME client: certbot, acme.sh, lego, or your router or NAS's built-in one. A DNS-01 challenge needs no inbound port 80. If your DNS is in Route 53, tools/acme/ has the scripts this project's own household uses: certbot in Docker, a twice-daily renewal, and an install step that swaps the certificate and restarts the client only when it changed (and puts the old one back if the client doesn't come up healthy).
  2. Use fullchain.pem as server.crt and privkey.pem as server.key, or point serverCert and serverKey in config.json at them. Use the full chain, not just the certificate.
  3. Let's Encrypt certificates last 90 days, so renewal must be automatic. After each renewal, copy the new files over the old ones and restart the client (an ACME client's "deploy hook" can do both).

Option B: your own CA

The client ships a certificate generator, certs.mjs. It makes a small certificate authority (CA) of your own and issues the certificates from it:

File What it is Mode
ca.key Your CA's private key. Anyone holding it can issue certificates your client trusts: keep it offline. 0600
ca.crt Your CA's certificate. You upload it on the settings site; with mTLS the client uses it too. 0644
server.key The home client's private key 0600
server.crt The home client's certificate, for the names given with --host 0644
client.key The relay client certificate's private key, for mTLS 0600
client.crt The relay client certificate, which the skill presents to your client when you turn on mTLS 0644

The file names match config.json's defaults, so put them next to it.

With Docker (nothing else needed on the host), from the folder that holds config.json:

docker run --rm --entrypoint node -v "$PWD:/out" registry.gitlab.com/jlaramie/alexa-chromecast:2.0.3 \
  /opt/acc/certs.mjs --host home.example.net --out /out

--entrypoint node is required: without it the image starts the client, which would receive these arguments.

With Node.js, using the client's files (direct install):

node /opt/alexa-chromecast/certs.mjs --host home.example.net --out .

Then:

  1. On the settings site, under Home client certificates, paste or choose ca.crt and press Pin CA, so the skill trusts certificates from your CA.
  2. Move ca.key somewhere safe and offline, such as a password manager's secure note. You need it only to issue new certificates.

Options

Option Meaning
--host <name> The name (or IP address) in your endpoint URL. Repeat it for more names; the first one becomes the certificate's name.
--out <dir> Where to write the files (default: the current folder).
--days <n> How long the server and client certificates last (default 825 days, a little over two years).
--force Overwrite existing files. Without it, certs.mjs writes nothing if any file it would write already exists.
--ca <dir> Issue new certificates from the existing CA in <dir> (its ca.crt and ca.key, which are only read) instead of making a new CA.

How long they last, and renewing

The server and client certificates last 825 days. A CA made by a client newer than 2.0.3 lasts 10 years, so you can renew certificates from it with --ca without touching anything else. Clients up to 2.0.3, including the 2.0.3 image, made a CA that lasts 825 days, exactly as long as its certificates, and have no --ca.

  • Renew only the relay client certificate, when it's about to expire or its key may have leaked:

    node certs.mjs --ca <folder with ca.crt and ca.key> --out ./renewed
    

    This writes a new client.crt and client.key and nothing else. Upload them on the settings site. The home client trusts the same CA, so it needs no change and no restart.

  • A new server certificate from the same CA: add --host home.example.net to that command. It also writes server.crt and server.key: copy them to the home client and restart it.

  • Everything, including the CA: run the first command again with --force. The CA changes, so upload the new ca.crt (and, with mTLS, the new client.crt and client.key) on the settings site, give the home client the new ca.crt, and restart it.

A certificate never outlives its CA: certs.mjs prints each certificate's end date and warns when it had to cut one short to end with the CA.

Require client certificates (mTLS)

Without mTLS, anyone on the internet can reach your client's port, although every command must still carry a valid signature made with your shared secret. With mTLS, a caller without your relay client certificate is refused before the client reads anything.

  1. Make a CA and a relay client certificate with certs.mjs (option B), even if your server certificate comes from Let's Encrypt.

  2. First, on the settings site under Home client certificates → Relay client certificate, paste or choose client.crt and client.key and press Upload certificate. The key is encrypted before it is stored and is never shown again. Do this first: once the client requires certificates, every command without one is refused.

  3. Then in config.json:

    {
      "https": true,
      "serverKey": "server.key",
      "serverCert": "server.crt",
      "clientCA": "ca.crt",
      "requireClientCert": true
    }
    

    With your own CA for the server certificate too, "serverCA": "ca.crt" does the same as clientCA.

  4. Give the client ca.crt (with Docker, mount it: -v "$C/ca.crt:/app/ca.crt:ro") and restart it.

Every request without a certificate from your CA now gets 403. The only exception is the health check from the client's own machine, so Docker's health check keeps working. Test it from another computer:

curl --cert client.crt --key client.key https://home.example.net:20846/health   # {"status":"ok"}
curl https://home.example.net:20846/health                                      # 403

(Add --cacert ca.crt when the server certificate comes from your own CA.)

Changing the CA later without an outage: put the old and new CA certificates together in ca.crt (one after the other), restart the client, upload the new relay certificate on the settings site, and only then remove the old CA from ca.crt.

Should the keys have passwords?

No. The client and the skill open their keys without anyone there to type a password, so a password would have to be stored right next to the key. Protect them instead by who can read them: server.key and config.json readable only by the account that runs the client (mode 0600), and ca.key kept offline. The relay client.key is encrypted when the settings site stores it.