TLS certificates

wawa verifies the certificate of every HTTPS integration target before it sends any data. A server with a certificate from a public CA (such as Let's Encrypt, DigiCert or Sectigo) works out of the box. A server with an internal or self-signed certificate needs one extra step: an account admin adds a certificate in wawa and selects it on the integration.

You do this yourself, in Settings → Integrations → TLS certificates. Don't send certificates or private keys to wawa staff by email, chat or support ticket; nobody at wawa needs a copy.

Do you need one?

Your server's certificate	What to add	Type
Issued by a public CA	Nothing
Issued by your internal CA (for example Active Directory Certificate Services)	Your root CA certificate	CA root
Self-signed	The server's own certificate	CA root
The system authenticates wawa by certificate (mutual TLS)	The certificate and private key the vendor issued to wawa	Client certificate

To see how a server's certificate was issued, open its URL in a browser and view the certificate, or run this from a machine that can reach it:

openssl s_client -connect pacs.clinic.example:443 -showcerts </dev/null

Each certificate in the chain prints an s: (subject) and i: (issuer) line. If the first certificate's subject and issuer are the same, it is self-signed. Otherwise, follow the issuers up to the root.

Which integrations use them

An integration supports its own certificates when its Configuration tab has a TLS certificates switch. Every other integration trusts public CAs only: if one of its servers has an internal or self-signed certificate, contact us before you set it up.

Each integration trusts one CA root, in addition to the public CAs, and it applies to every server of that integration. If an integration connects to several servers that don't have public certificates, issue their certificates from one internal CA rather than self-signing each one.

Requirements

PEM format only

Every certificate and private key must be in PEM format: plain text that starts with -----BEGIN CERTIFICATE----- (or -----BEGIN PRIVATE KEY----- for a key). Binary DER files (often .cer or .crt), PKCS#7 bundles (.p7b) and PKCS#12 files (.pfx, .p12) are not accepted. Convert them to PEM first.

• One certificate per entry. Paste a single certificate, not a bundle or a chain. If you paste several, wawa uses only the first.
• The root, not an intermediate. With an internal CA, add the root certificate itself. Your server must present its own certificate and every intermediate during the TLS handshake; wawa holds only the root.
• No private key for a CA root. A server's private key never leaves the server. wawa rejects a CA root that comes with one.
• The certificate must name the server. wawa checks the hostname it connects to against the certificate's Subject Alternative Names. Over a Site-to-Site VPN, wawa reaches your server at an internal DNS name of its own, so set a DNS name or IPv4 address the certificate is issued for on the server's settings in wawa (see Add it to the integration).
• Client private keys must not be password-protected. wawa stores the key encrypted, but it must be pasted unencrypted.

Prepare the PEM file

Convert other formats with OpenSSL:

# DER (.cer, .crt) to PEM
openssl x509 -inform DER -in certificate.cer -out certificate.pem

# PKCS#7 bundle (.p7b), as exported by Windows: prints every certificate in it
openssl pkcs7 -inform DER -print_certs -in bundle.p7b -out bundle.pem

If OpenSSL cannot read a .p7b, it is already PEM-encoded: run the same command without -inform DER. The output lists each certificate after its subject= and issuer= lines. The root is the one whose subject and issuer are the same; copy that block, from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----, into its own file.

For a client certificate delivered as a .pfx or .p12, split it into the certificate and an unencrypted key:

openssl pkcs12 -in client.pfx -clcerts -nokeys -out client-certificate.pem
openssl pkcs12 -in client.pfx -nocerts -nodes -out client-key.pem

If OpenSSL 3 reports an unsupported algorithm, the file uses legacy encryption: add -legacy to both commands. Delete client-key.pem once you have added it to wawa.

Check a file before you add it. These print the certificate's subject, issuer and expiry, and fail if the file is not valid PEM:

openssl x509 -in certificate.pem -noout -subject -issuer -enddate

Add the certificate to wawa

You need to be an account admin.

1. Go to Settings → Integrations → TLS certificates and click Add Certificate.
2. Enter a Name you will recognise later, for example Main clinic PACS root.
3. Choose the Type: CA root for an internal root or a self-signed server certificate, Client certificate for a certificate wawa presents.
4. Paste the PEM text into Certificate. For a client certificate, also paste its Private key.
5. Save.

The list shows each certificate's type, common name, expiry date, and the integrations that use it. A client certificate's private key is stored encrypted and is never shown again.

Add it to the integration

1. Go to Settings → Integrations, open the integration and click Configure.
2. On the Configuration tab, turn on TLS certificates and save. This reveals the Certificates tab.
3. On the Certificates tab, choose your certificate under CA root, and under Client certificate if the tab has one, then save. Manage Account TLS certificates takes you to the certificate list and back.
4. If wawa reaches the server at an address the certificate doesn't name, edit the server in the integration, turn on Server answers to a different hostname and enter a DNS name or IPv4 address from the certificate under Hostname the server answers to. wawa still connects to the address in the URL, and presents this name for TLS and in the HTTP Host header.
5. Click Test next to the server.

Changes apply from the integration's next connection.

Renew or replace a certificate

The Expires column shows when each certificate runs out. Plan renewals before then.

• Internal CA. Renewing the server's certificate needs no change in wawa. Update the CA root only when the root itself changes.
• Self-signed. Every time the server's certificate is regenerated, edit its entry in wawa and paste the new certificate, at the same time as the server switches. Until both match, connections fail.
• Client certificate. Edit the entry and paste the new certificate and its private key. To keep the stored key, leave Private key blank.

Editing an entry updates every integration that uses it. To stop using a certificate, choose None on the integration's Certificates tab: turning off TLS certificates only hides the tab, it doesn't remove the selection. A certificate can be deleted only once no integration uses it.

Troubleshooting

When adding a certificate

Field	Message	What to do
Certificate	is not a valid PEM certificate	The text is not PEM, or is incomplete. Convert it and paste the whole block.
Certificate	must be a certificate authority (Basic Constraints CA:TRUE) or a self-signed certificate	You pasted the server's certificate or an intermediate. Paste the root instead.
Certificate	must be an end-entity certificate, not a certificate authority	A CA certificate was added as a Client certificate. Choose CA root, or paste the certificate issued to wawa.
Private key	must be blank for a CA root	Remove the key. A CA root never has one.
Private key	is required for a client certificate	Paste the private key that belongs to the certificate.
Private key	is not a valid PEM private key	The key is not PEM, or is password-protected. Export it unencrypted, as shown above.
Private key	must be the private key, not the public key	You pasted a PUBLIC KEY block. Paste the PRIVATE KEY block.
Private key	does not match the certificate	The key belongs to another certificate. Paste the pair issued together.

When testing the connection

Error contains	Cause
wrong version number	The URL starts with https://, but the port serves plain HTTP. Point it at the server's HTTPS port.
certificate verify failed	wawa doesn't trust the certificate: no CA root is selected on the integration, the wrong root is selected, a self-signed certificate has changed, or the server doesn't send its intermediates.
hostname mismatch or does not match the server certificate	The certificate doesn't name the hostname wawa presents. Set Hostname the server answers to to a name or IP address the certificate lists, as above.