Networking

Using client and CA certificates

Present client certificates and trust your own certificate authorities.

Overview

Relay checks every server's TLS certificate the way your Mac does. Two kinds of certificates let you work with servers that need more than that:

  • Client certificates: Some servers use mutual TLS and ask the client to prove its identity with a certificate. Relay presents the client certificate you add for the server's host.
  • CA certificates: Servers on a company network or a development machine often use certificates from a certificate authority your Mac doesn't trust. Add the authority's certificate, and Relay trusts the servers it signed, alongside the authorities macOS already trusts.

You add certificates to a workspace or to Globals, in the Certificates tab of the Workspaces window. Relay uses them for requests, WebSocket connections, requests from scripts and OAuth 2.0 token requests.

Add a client certificate

You need the certificate and its private key in a PKCS#12 file, with the extension .p12 or .pfx.

  1. In the sidebar, click the workspace menu and choose Edit Workspaces….
  2. Select the workspace, or select Globals to use the certificate in every workspace.
  3. Click Certs.
  4. Click Add Certificate, then choose Client Certificate….
  5. Next to PKCS#12 File, click Choose… and select the file.
  6. Enter the file's Passphrase.
  7. In Hosts, enter the hosts to present the certificate to, separated by commas, such as api.example.com, *.internal.example.com:8443. A client certificate needs at least one host.
  8. Optionally, enter a Name. If you leave it empty, Relay uses the certificate's subject.
  9. Click Add.

If the file can't be read or the passphrase is wrong, the sheet says so and the certificate isn't added.

A client certificate stays on your Mac. Relay never writes it, or its passphrase, to a workspace's files, so sharing a workspace folder doesn't share it. Each person who uses the workspace adds their own.

Add a CA certificate

  1. In the Workspaces window, select the workspace or Globals, then click Certs.
  2. Click Add Certificate, then choose CA Certificate….
  3. Select the certificate file, in PEM or DER format. A PEM file can hold several certificates, and Relay adds each one.

A new CA certificate is trusted for every host. To trust it only for some hosts, click Edit… in its row, enter the hosts in Hosts and click Save.

CA certificates aren't secret, so a workspace's CA certificates are saved in its files and shared with it.

Match certificates to hosts

Each host pattern in Hosts is one of these:

  • A host name, such as api.example.com, which matches that host only.
  • A wildcard, such as *.example.com, which matches the domain's subdomains but not example.com itself.
  • Either one with a port, such as api.example.com:8443, which matches only that port. Without a port, a pattern matches any port.

When several client certificates match a host, Relay presents the one with the most specific pattern: an exact host before a wildcard, and a pattern with a matching port before one without. A workspace's client certificate is used before a global one. Relay trusts every CA certificate that matches the host, from both the workspace and Globals.

Turn certificates off and remove them

Each certificate's row shows its name, the hosts it applies to, its subject and its expiry date. An expired certificate shows an Expired badge.

  • To stop using a certificate without removing it, deselect the checkbox at the start of its row.
  • To change a certificate's name, hosts or, for a client certificate, its file or passphrase, click Edit….
  • To remove a certificate, click the Remove button (the trash can) in its row.

You can undo each change with Edit > Undo.

Verify server certificates

Relay fails a request when the server's certificate isn't trusted. For a local server with a self-signed certificate, you can turn verification off instead of adding a CA certificate:

  • To change the default, choose Relay > Settings, click Network and turn off Verify Certificates.
  • To change it for a workspace, collection, folder or request, open its Settings tab and set Verify Certificates to Off in the Connection card.

When a request fails because the server's certificate isn't trusted, the response inspector shows "The server's certificate isn't trusted" with the reason. Click Turn Off Certificate Verification for This Request to turn verification off in the request's settings, then send it again. You can undo this change.

A response from a server whose certificate wasn't trusted, and that Relay accepted because verification was off, shows a Not Verified badge beside its status.

Important

With verification off, Relay can't tell whether it's talking to the server you meant. Turn it off only for servers you control.

Fix client certificate problems

When a server asks for a client certificate and Relay has none for its host, the server usually refuses the connection. The response inspector shows "The server asked for a client certificate". Click Open Certificates to open the workspace's Certificates tab, add a certificate for the host and send the request again.

If Relay can't load the client certificate that matches a request's host, it doesn't send the request, and the response inspector shows the reason, such as a wrong passphrase.

When Relay presents a client certificate, the response inspector's Headers tab names it under Request Headers.

See Also