6.5.17 WatchGuard Firebox

CertKit provides three WatchGuard Firebox templates. Each one signs in to the Fireware CLI over SSH, imports the certificate by pasting it into the console, and reads the Firebox back before it reports success.

These templates are in beta. Lab testing so far has been on Fireware 12.12.2.

Requirements

• A locally managed Firebox. Cloud-managed Fireboxes and Fireboxes fully managed by WatchGuard Management Server are not supported. The template stops if the CLI prompt shows the Firebox is managed by Management Server.
• SSH access to the Fireware CLI from the agent host. The default port is 4118. If you use another port, add it to Firebox hostname or IP (optionally :port), for example firebox.example.com:4119.
• A Device Administrator account with read/write access. Create one in Fireware Web UI under System > Users and Roles. A read-only account is rejected.
• The Posh-SSH module on the agent host, installed for all users. The agent runs as Local System, so install it from an elevated PowerShell prompt:

Install-Module -Name Posh-SSH -Scope AllUsers -Repository PSGallery -Force

• The PEM (Cert + Key + Chain) certificate format, which the templates select for you. All three templates reject a password-protected key.

No FTP or TFTP server is needed. The agent pastes the certificate and key through the SSH session.

Template settings

What happens on each run

Every template starts the same way. It checks that the certificate thumbprint matches the leaf file and that the leaf is valid right now. The IKEv2 and Proxy Server templates also require the TLS Web Server Authentication extended key usage, a non-CA leaf with an RSA or EC key, and a chain file that forms one chain from the leaf. Then it connects over SSH and checks the prompt. A read-only account or a Firebox managed by Management Server stops the run before any change.

When a template needs to import, it sends the CA certificates first, from the root down, as General Use certificates. Fireware expects that order. A CA the Firebox already has is accepted as is.

Fireware lets one Device Administrator change the configuration at a time. If someone has the Web UI in Edit Mode, the template stops and asks you to have that administrator switch to View Mode.

Web Server certificate

1. Looks for the certificate among the General Use certificates by its SHA-1 fingerprint. If it’s already installed, the import is skipped.
2. Otherwise imports the chain, then the certificate and private key as General Use, and waits up to 30 seconds for Fireware to list the new certificate ID.
3. If the Web Server isn’t already using that ID, selects it with web-server-cert third-party <ID> in configuration mode.
4. Reads show web-server-cert back and fails unless it shows the new ID.
5. Runs cleanup if you turned it on.

WatchGuard’s documentation asks for a Web Server certificate with both the server and client authentication extended key usages. Public CAs no longer issue the client one. Fireware 12.12.2 imported and selected a server-only certificate in testing.

Mobile VPN with IKEv2 certificate

The template only replaces the certificate of a Mobile VPN with IKEv2 configuration that already exists, is enabled, and uses certificate authentication. It never creates, enables, or reconfigures the VPN. If show mvpn-ikev2 and the IKE policy list can’t confirm that configuration, the template stops before importing anything.

1. Reads the current IKEv2 certificate selection.
2. For an EC certificate, checks that the Firebox runs Fireware 12.5 or later.
3. Looks for the certificate by fingerprint, or imports the chain and then the certificate and key as General Use.
4. If IKEv2 isn’t already using it, reads the selection again to make sure nobody changed it, then runs mvpn-ikev2 certificate third-party <ID> and apply in policy mode.
5. Reads the selection back and fails unless it shows the new ID.
6. Runs cleanup if you turned it on.

The certificate must include the VPN address clients connect to as a DNS or IP name. The template doesn’t check this. Clients must also trust the CA that issued it. A renewal under the same root normally needs nothing new on the clients. If the root changes, distribute it to clients before you deploy.

Inbound HTTPS Proxy Server certificate

This template replaces the default Proxy Server certificate in place. Every HTTPS-Server proxy rule that uses the default serves the new certificate. Named Proxy Server certificates are not supported, and the Proxy Authority certificate for outbound inspection is never touched.

1. Reads the fingerprint of the default Proxy Server certificate. If it already matches, nothing changes.
2. Otherwise imports the chain as General Use, then the certificate and key with import certificate proxy-server, which overwrites the default.
3. Reads the default’s fingerprint back and fails unless it matches.

The template doesn’t inspect proxy actions or rules. Before the first deployment, check which inbound HTTPS proxy rules use the default certificate, because all of them change together. The certificate needs to cover the domain names those rules serve.

There is no cleanup for this template. The import overwrites the default, so no old certificate is left behind.

Restarts and disruption

None of the templates restart the Firebox or any service. CertKit hasn’t yet measured whether selecting a new certificate interrupts active SSL VPN, IKEv2, or portal sessions, so run the first deployment in a maintenance window.

WatchGuard documents that certificate imports synchronize between FireCluster members. CertKit hasn’t tested FireCluster yet.

Same-subject renewals

Fireware can refuse to import a renewal while an older certificate with the same subject is installed. The templates never delete a certificate that might be in use to make room. The run stops with an error that the certificate conflicts with one already on the Firebox.

To recover, follow WatchGuard’s renewal procedure for that service. Switch it to the default certificate, delete the old certificate under System > Certificates, then run the deployment again. CertKit imports the renewal and selects it.

Expired certificate cleanup

Set Clean up expired matching certificates to yes to remove old copies of the certificate after a successful deployment. Cleanup runs only after the new certificate is selected and verified. A certificate is removed only if all of these are true:

• It’s a General Use certificate with no name and no purpose set.
• It’s a leaf, not a CA. CA certificates are never removed.
• It has the same subject and the same SANs as the new certificate.
• It expired more than one day ago.
• It isn’t the Web Server or IKEv2 certificate.

The template rereads both selections and the certificate details right before each delete, and confirms the certificate is gone afterward. If anything changed, cleanup stops. A cleanup problem shows as a warning, and the deployment still counts as successful.

Fireware doesn’t list every feature that uses a certificate. An expired certificate that matches these rules could still be referenced by something the template doesn’t check, such as a Branch Office VPN. Leave cleanup off if other features use certificates with the same subject.

Common problems

• “The Posh-SSH PowerShell module is not installed on this machine”: install it for all users from an elevated prompt with the command above. A module installed for your own account isn’t visible to the agent.
• “SSH connection to … failed”: check SSH management access to port 4118 from the agent host, the username and password, and the Posh-SSH trusted host store on the agent host.
• “The SSH account has read-only access”: use a Device Administrator account, not a Device Monitor.
• “This Firebox is fully managed by WatchGuard Management Server”: these templates can’t change it. Make the change through Management Server.
• “Firebox configuration write access is locked by Device Administrator”: the named administrator has the Web UI in Edit Mode. Have them switch to View Mode or log out, then rerun.
• “console import is not available on this Fireware version” or “could not start”: this Fireware version doesn’t offer console certificate import. Contact CertKit support.
• “conflicts with a certificate already on the Firebox” or “conflicts with an existing certificate”: see Same-subject renewals.
• “Cannot confirm an existing certificate-based Mobile VPN with IKEv2 configuration” or “Cannot confirm an enabled Mobile VPN with IKEv2 policy”: set up Mobile VPN with IKEv2 with certificate authentication and enable it before using this template.
• “EC IKEv2 certificates require Fireware 12.5 or later”: upgrade Fireware or issue the certificate with an RSA key.
• “IKEv2 selection changed concurrently”: someone changed the IKEv2 settings during the run. Rerun the deployment.
• “did not list a general-use certificate with SHA-1 fingerprint” or “Import returned, but certificate fingerprint … was not found”: Fireware didn’t accept the certificate and key. Check the list with show certificate type common on the Firebox.
• “Import completed, but the default Proxy Server certificate is still”: Fireware didn’t replace the default. Check the certificate list under System > Certificates.
• “Multiple Firebox certificate IDs match”: the same certificate is installed more than once. Delete the extra copy by hand, then rerun.
• “chainPath does not form one unambiguous chain from the leaf”: the chain file has extra or unrelated certificates. Keep the certificate format the template selects and deploy again.
• “Leaf certificate is not currently valid” or “it expired at”: the certificate isn’t valid yet or has expired. Renew it in CertKit.
• “Certificate deployment succeeded, but expired-certificate cleanup stopped”: the new certificate is in place. The message after it explains why cleanup didn’t finish.

For a product overview, see certificate automation for WatchGuard Firebox.