HTTPS Certificate Verification Issues

When RustMailer calls a webhook endpoint over HTTPS, it uses Rust's reqwest crate to perform the HTTP request. By default, reqwest validates the server's TLS certificate to ensure secure communication.

If the certificate cannot be verified, you may encounter errors like:

reqwest::Error {
  kind: Request,
  url: "https://example.com/webhook",
  source: hyper_util::client::legacy::Error(
    Connect,
    Ssl(
      Error {
        code: ErrorCode(1),
        cause: Some(
          Ssl(
            ErrorStack([
              Error {
                code: 167772294,
                library: "SSL routines",
                function: "tls_post_process_server_certificate",
                reason: "certificate verify failed",
                file: "ssl/statem/statem_clnt.c",
                line: 2123,
              },
            ]),
          ),
        ),
      },
      X509VerifyResult { code: 20, error: "unable to get local issuer certificate" },
    ),
  ),
}

---

Why This Happens

This error occurs before the request reaches the target server. Key reasons include:

1. Missing or incomplete certificate chain

   • The webhook target may be using a self-signed certificate or an internal CA.
   • The certificate chain might lack intermediate certificates, so RustMailer cannot find a trusted root.

2. Outdated or missing CA certificates in the container

   • RustMailer runs inside a Docker container, and if the base image does not include the ca-certificates package, TLS verification will fail.
   • For example, a minimal Ubuntu image may not have root certificates installed.

3. Network interception (less common)

   • Some corporate proxies or firewalls perform TLS interception, replacing the certificate with their own.

---

How to Resolve

Step 1: Ensure CA Certificates Are Installed

Depending on your environment:

• Docker container:

  # Install ca-certificates to ensure HTTPS certificate verification works correctly
  RUN apt update && apt install -y ca-certificates && rm -rf /var/lib/apt/lists/*

• Ubuntu / Debian host:

  sudo apt update
  sudo apt install -y ca-certificates
  sudo update-ca-certificates

• Other OS: Ensure the system’s CA bundle is present and up-to-date.

This allows RustMailer’s reqwest client to validate public HTTPS endpoints like Cloud Run or Let’s Encrypt certificates.

---

Step 2: Verify the Webhook Endpoint

Test the target HTTPS endpoint from the client environment:

curl -v https://your-webhook-url

• A successful TLS handshake will show Verify return code: 0 (ok) at the end.
• If this fails, the endpoint’s certificate may be incomplete, self-signed, or otherwise untrusted.

---

Step 3: Use Trusted Certificates

• For internal services, provide a certificate signed by a trusted CA.
• For public endpoints, ensure the client environment has up-to-date root certificates so verification passes automatically.

---

Summary

• certificate verify failed and unable to get local issuer certificate indicate RustMailer cannot trust the HTTPS certificate.

• Common causes: missing or outdated CA certificates in the client environment, or self-signed/internal certificates on the webhook target.

• Solutions:

  1. Install and update CA certificates in the environment.
  2. Ensure the webhook endpoint uses a valid, trusted certificate.
  3. (Optional, testing only) Temporarily disable TLS verification in RustMailer.

---