Certificates and SDK trust

When an SDK refuses the interception certificate, and how to fix it.

certificate verify failed inside your test container means an SDK refused the certificate the proxy presents. Clients that read the container’s trust store are unaffected. An SDK that ships its own certificate bundle never looks there.

The certificate flags are listed in veris.

Symptoms


SSLError: certificate verify failed: unable to get local issuer certificate

stripe-python and stripe-ruby report the same failure as APIConnectionError.

The run reports it when every handshake to a host was rejected:


api.stripe.com: 4 TLS handshake(s) rejected (unknown_ca) after the
certificate was minted; 0 requests completed -- the client refused the
interception CA. Next: re-run with --patch-bundled-cas

Fixes

Patch bundled CAs


veris run --image <image> --patch-bundled-cas -- pytest -q

Adds the Veris certificate to the bundled certificate files it finds in your image, without changing the image itself. One log line per patched file. Resolves most cases.

The patch acts on files inside a container image, so the run has to be containerised: pass --image here, or record proxy.image in .veris/twin.yaml and the flag stands on its own.

Mount the bundle

For a bundle in a non-standard location, append /veris-share/veris-ca.pem to the file your SDK reads and mount it over the original path.

Append, do not replace. A file containing only the Veris certificate breaks trust for every untwinned host.

Java truststore

The JVM requires a JKS and ignores the usual environment variables. One is built for you when a JDK is found and passed through JAVA_TOOL_OPTIONS, which Gradle and Maven test forks inherit.

An application loading its own keystore needs the certificate added:


keytool -importcert -noprompt -trustcacerts -alias veris-local-ca \
  -file ~/.veris/ca/veris-ca.pem -keystore your-keystore.p12

Affected SDKs

stripe-python, stripe-ruby, older botocore, httplib2, and anything that vendors certifi and passes it explicitly.

Certificate pinning

A client pinning a specific certificate or public key cannot be satisfied by adding a root: OkHttp CertificatePinner, curl --pinnedpubkey, aiohttp with fingerprint=.

Disable pinning in the test build, or test that call path another way.

An SDK errors but the receipt shows traffic

When some calls to a host fail TLS and others succeed, the receipt shows traffic and the diagnostic above is not printed. Read the paths in the request trace to identify which client succeeded.