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.
Option A (recommended): Let's Encrypt
Free, publicly trusted, and nothing to upload. You need a DNS name (a name and a port).
- Get a certificate for
home.example.netwith 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). - Use
fullchain.pemasserver.crtandprivkey.pemasserver.key, or pointserverCertandserverKeyinconfig.jsonat them. Use the full chain, not just the certificate. - 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:
- On the settings site, under Home client certificates, paste or choose
ca.crtand press Pin CA, so the skill trusts certificates from your CA. - Move
ca.keysomewhere 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 ./renewedThis writes a new
client.crtandclient.keyand 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.netto that command. It also writesserver.crtandserver.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 newca.crt(and, with mTLS, the newclient.crtandclient.key) on the settings site, give the home client the newca.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.
Make a CA and a relay client certificate with
certs.mjs(option B), even if your server certificate comes from Let's Encrypt.First, on the settings site under Home client certificates → Relay client certificate, paste or choose
client.crtandclient.keyand 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.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 asclientCA.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.