DocsCertificates

Capture

Certificates

To show you HTTPS traffic, Akev decrypts it. It answers each HTTPS connection with a certificate for the requested host, signed on the fly by its own certificate authority (CA). A client accepts those certificates only if it trusts the Akev CA.

Browsers, terminals and Electron apps that Akev launches from Connect trust it automatically, and nothing on your system changes. Everything else needs the CA installed once: the operating system, Firefox, Java, phones. Akev never changes your system's trust stores itself. It gives you the commands, and the commands to undo them.

Akev's CA

Every installation generates its own CA the first time it starts. It is created on your machine, and its private key never leaves it.

It lives in Akev's data directory, which the desktop app and the CLI share:

OS Data directory
Linux ~/.local/share/akev ($XDG_DATA_HOME/akev if that is set)
macOS ~/Library/Application Support/akev
Windows %LOCALAPPDATA%\akev
  • ca.pem: the CA certificate (PEM). This is the file clients trust.
  • ca.key: its private key (PKCS#8 PEM). On Linux and macOS it is readable only by you (mode 0600), and Akev tightens the permissions if they are looser. On Windows Akev gives it an access list that only your account can use, whenever it writes or loads it. Anyone with this key can intercept HTTPS traffic of every client that trusts your CA, so never share it.

--data-dir (or AKEV_DATA_DIR) points the CLI at another data directory, with its own CA. akev start --ephemeral without --data-dir uses a temporary directory, so it generates a new CA on every run.

What's in it

  • Key: ECDSA P-256.
  • Subject: O=Akev, OU=<id>, CN=Akev CA. The OU is a random 8-character id, so you can tell installations, and successive CAs, apart in a trust store.
  • Constraints: a CA that can't issue other CAs (path length 0), allowed to sign certificates.
  • Validity: from a day before it was created (to tolerate clock skew) for 10 years.

The certificates Akev makes for each host use ECDSA P-256 keys and are valid for at most 397 days, and never beyond the CA's own expiry. They name the host (or IP address) and, for names with three or more labels, a wildcard for the parent domain too (api.example.com also covers *.example.com). Akev caches the last 2,048.

Expiry

A CA lasts 10 years, and Akev never replaces one your devices trust on its own. When fewer than 60 days are left, the status bar, akev ca show, the akev start banner and the MCP akev_status tool warn you, with the date; once it has expired they say that HTTPS interception fails until you replace it. Regenerate it when it suits you, and trust the new one on your devices.

Akev does make a new CA by itself when it starts and ca.pem or ca.key is missing, can't be read as a certificate or key, the two don't match, or the certificate isn't valid yet (the clock was wrong when it was made). The previous files are kept as ca.pem.bak and ca.key.bak. Any other problem reading the files, such as a permission error, stops Akev with an error instead, so a passing problem never replaces a CA your devices trust.

In the app

Settings → Certificates (Ctrl/⌘ ,) shows the CA under Certificate authority:

Field What it is
Subject The CA's name, with your installation's id
SHA-256 The certificate's fingerprint, to compare with what a device shows
SPKI (base64) The SHA-256 of its public key, the pin Chromium-family browsers launched by Akev use
Android file name <hash>.0, the name of this CA in Android's system store (Akev uses it on rooted devices and emulators)
Valid First and last day of validity
File The path of ca.pem

Download PEM and Download DER (.crt) save a copy of the certificate. Regenerate… makes a new CA; see below.

Below it, Trust on this computer adds the CA to your operating system's certificate store in one click, and Trust by hand shows the commands to do it yourself; see trust the CA system-wide. When the main store doesn't trust the CA, the status bar says CA not trusted (it checks again when the window gets focus).

The akev ca command

bash
akev ca path                  # print the path of ca.pem
akev ca show [--json]         # subject, path, fingerprints, validity
akev ca export FILE           # write the certificate to FILE (PEM)
akev ca export FILE --der     # the same in DER (.crt / .cer, e.g. for Android or Windows)
akev ca regenerate            # make a new CA

akev ca show prints the subject, path, SHA-256 and SPKI fingerprints, the OpenSSL subject_hash_old (the Android file name) and the validity, in yellow when fewer than 60 days remain.

With Akev running, the commands use its data directory and its API. Without it, they work on the data directory directly, and create a CA if there is none yet.

Over the API: GET /api/ca, GET /api/ca/cert.pem, GET /api/ca/cert.der and POST /api/ca/regenerate. See Settings & certificate.

Regenerate the CA

Regenerate when the CA is about to expire, when its key may have leaked, or to start over with a fresh CA. In Settings → Certificates, click Regenerate… and confirm. Or run akev ca regenerate.

Akev creates the new key and certificate first, then replaces ca.pem and ca.key, keeping the old ones as ca.pem.bak and ca.key.bak (and putting them back if the new files can't be written), and restarts the proxy with the new CA on the same port and address.

Everything that trusted the old CA stops trusting Akev until you install the new one: system trust stores, Firefox profiles, Java trust stores, phones and other devices. Before you regenerate, remove the old CA where you installed it by hand. The removal commands below that take the certificate file only work with the file you trusted.

Clients Akev launches get the new CA when you launch them again. A browser that is still running with the old CA is restarted the next time you launch it from Connect. Quit Electron apps before you launch them again, and open new terminals.

Trust the CA system-wide

Clients that Akev launches trust its CA on their own. Clients that Akev doesn't launch, and apps that follow the system proxy, need the CA in your system's trust store.

In one click

Settings → Certificates → Trust on this computer lists the stores Akev can manage on this computer, with whether each one trusts the CA (Trusted, Not trusted or Unknown, checked for real, not remembered). Click Trust next to one; Akev asks you to confirm, then the operating system asks too:

OS Store What confirms it
macOS Your login keychain, as a trusted root for your account (Safari, Chrome, Edge, curl and apps that use the system's TLS) macOS's password dialog
Windows Your account's Trusted Root store (Edge, Chrome, .NET and most Windows apps) Windows's security warning
Linux The distribution's CA bundle, with p11-kit's trust anchor (Fedora, RHEL, Arch, openSUSE) or update-ca-certificates (Debian, Ubuntu), through pkexec Your desktop's password dialog (polkit)
Linux The NSS database Chrome, Chromium, Brave, Edge and Vivaldi read (~/.pki/nssdb) Akev's confirmation only; needs certutil (nss-tools on Fedora, libnss3-tools on Debian and Ubuntu)

Akev never does this on its own, and AI agents can't do it over MCP: installing a root certificate is always your click. Remove next to a trusted store takes the CA out again. Restart apps that were already open so they notice the change. Firefox keeps its own store; see Firefox.

When a store can't be managed from Akev (no pkexec, no certutil, or no supported tool), the row says why; use the commands below instead. Over the API: GET /api/ca/trust reports the stores, and POST or DELETE /api/ca/trust with {"store": "user" | "system" | "nss"} installs or removes the CA.

By hand

Settings → Certificates → Trust by hand shows the commands for your OS, with the path of your certificate filled in. The commands below use "$(akev ca path)" for that path.

Remove the CA again when you're done; see remove trust again.

Linux

Most Linux tools read the distribution's CA bundle.

Fedora, RHEL, Arch, openSUSE (p11-kit):

bash
sudo trust anchor --store "$(akev ca path)"
# remove:
sudo trust anchor --remove "$(akev ca path)"

Debian, Ubuntu:

bash
sudo cp "$(akev ca path)" /usr/local/share/ca-certificates/akev-ca.crt
sudo update-ca-certificates
# remove:
sudo rm /usr/local/share/ca-certificates/akev-ca.crt
sudo update-ca-certificates --fresh

Chrome and Chromium on Linux read their own NSS database (~/.pki/nssdb) for your user. This needs NSS certutil (the libnss3-tools package on Debian and Ubuntu). Browsers that Akev launches don't need it.

bash
certutil -d sql:$HOME/.pki/nssdb -A -t C,, -n 'Akev CA' -i "$(akev ca path)"
# remove:
certutil -d sql:$HOME/.pki/nssdb -D -n 'Akev CA'

Firefox keeps its own store: see Firefox. Java, Node.js and Python may ignore the system bundle: see Java and command-line tools.

macOS

Safari, Chrome, curl and apps using URLSession read the Keychain.

For your user only (asks for your password):

bash
security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db "$(akev ca path)"
# remove:
security remove-trusted-cert "$(akev ca path)"
security delete-certificate -Z <SHA-256> ~/Library/Keychains/login.keychain-db

For all users (System keychain):

bash
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "$(akev ca path)"
# remove:
sudo security remove-trusted-cert -d "$(akev ca path)"
sudo security delete-certificate -Z <SHA-256> /Library/Keychains/System.keychain

<SHA-256> is the certificate's SHA-256 fingerprint without the colons (akev ca show prints it with colons). Settings → Certificates fills it in for you.

Or use Keychain Access: open ca.pem with it and add it to the login keychain, double-click the Akev certificate → Trust → When using this certificate: Always Trust. To remove it, select the certificate in Keychain Access and delete it.

On a Mac you can also install the configuration profile from the setup page (iPhone / iPad / Mac), then install it in System Settings → Privacy & Security → Profiles and set the certificate to Always Trust.

Java, Node.js and Python ignore the Keychain: see Java and command-line tools.

Windows

Edge, Chrome, .NET and most native apps use the Windows certificate store.

For your user, in Command Prompt (Windows asks you to confirm):

certutil -user -addstore Root "%LOCALAPPDATA%\akev\ca.pem"

In PowerShell, use "$env:LOCALAPPDATA\akev\ca.pem" for the path. To remove it again, in PowerShell:

powershell
Get-ChildItem Cert:\CurrentUser\Root | Where-Object Subject -like "*CN=Akev CA*" | Remove-Item

This removes every Akev CA from your user's store, including those of earlier CAs.

Or use the certificate manager: double-click a .crt copy of the certificate (Download DER (.crt) in Settings → Certificates, or akev ca export akev-ca.crt --der) → Install Certificate… → Current User (or Local Machine for all users, which needs administrator rights) → Place all certificates in the following store: Trusted Root Certification Authorities → Finish. To remove it, run certmgr.msc → Trusted Root Certification Authorities → Certificates, and delete the Akev certificate.

Java, Node.js and Python ignore the Windows store: see Java and command-line tools.

Firefox

Firefox keeps its own certificate store.

Firefox launched from Akev needs nothing from you if NSS certutil is installed: Akev adds the CA to that profile's certificate database, and replaces an older Akev CA there. Akev finds certutil on PATH, and on macOS also in Homebrew's nss. On Debian and Ubuntu it is in libnss3-tools. Without certutil, the first tab asks you to trust the CA once per profile; see Firefox.

Your own Firefox profile:

  1. Settings → Privacy & Security → Certificates → View Certificates…
  2. Authorities → Import… → choose the PEM file (ca.pem, or a downloaded copy).
  3. Tick Trust this CA to identify websites → OK.

If that Firefox already uses Akev as its proxy, opening http://akev.cert/ca.crt shows the same trust dialog.

On Windows and macOS, Firefox can use the system store instead: set security.enterprise_roots.enabled to true in about:config, and trust the CA system-wide. Firefox profiles that Akev launches already have this setting.

To remove the CA, select it under Authorities and click Delete or Distrust….

Java

Java uses its own trust store (cacerts), not the Keychain or the Windows store, and on Linux it may ignore the system bundle too.

Terminals from Akev. When Akev finds keytool (in $JAVA_HOME/bin, or on PATH), it builds a trust store in the data directory, java/akev-truststore.p12: a copy of the JDK's default cacerts plus the Akev CA (PKCS#12, password changeit). New and existing terminals then set JAVA_TOOL_OPTIONS, which every JVM reads:

  • -Dhttp.proxyHost, -Dhttp.proxyPort, -Dhttps.proxyHost, -Dhttps.proxyPort and an empty -Dhttp.nonProxyHosts, so localhost is captured too;
  • an empty -Djdk.http.auth.tunneling.disabledSchemes, which allows Basic authentication through CONNECT tunnels;
  • -Djavax.net.ssl.trustStore, -Djavax.net.ssl.trustStorePassword=changeit and -Djavax.net.ssl.trustStoreType=PKCS12, once the trust store exists.

In an existing terminal, your own JAVA_TOOL_OPTIONS flags are kept. The trust store belongs to one CA: after you regenerate, Akev builds a new one the next time a terminal needs it. Without keytool, Java gets the proxy settings only.

By hand, build a trust store once and start the JVM with it:

bash
keytool -importcert -noprompt -alias akev-ca -file "$(akev ca path)" \
  -keystore akev-truststore.p12 -storetype PKCS12 -storepass changeit

java -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8000 \
     -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8000 -Dhttp.nonProxyHosts= \
     -Djavax.net.ssl.trustStore=akev-truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit \
     -jar app.jar

This trust store contains only the Akev CA, so the JVM trusts nothing else while it uses it. For Gradle, Maven or IDE runs, put the same -D flags in JAVA_TOOL_OPTIONS.

A JVM that is already running: attach to it instead. See Running JVMs (Pro).

Node, Python, curl and other tools

Terminals opened from Akev, the Existing Terminal command, Electron apps launched by Akev, and the env files for containers all set the same variables. The Anything card on the Connect page lists them with their values.

Trust. Variables that replace a tool's trusted roots point at a combined bundle, ca-bundle.pem in the data directory: your system's roots followed by the Akev CA. Requests that don't go through Akev keep working. NODE_EXTRA_CA_CERTS adds to Node's built-in roots, so it points at ca.pem alone.

Variable Points at Read by
SSL_CERT_FILE bundle OpenSSL, Ruby, Go (Linux only), httpx, uv, rustls-native-certs
REQUESTS_CA_BUNDLE bundle Python requests, Azure CLI, conda
CURL_CA_BUNDLE bundle curl, PHP
GIT_SSL_CAINFO bundle git
AWS_CA_BUNDLE bundle AWS CLI and SDKs
CARGO_HTTP_CAINFO bundle cargo
PIP_CERT bundle pip
BUNDLE_SSL_CA_CERT bundle Bundler
DENO_CERT bundle Deno
HEX_CACERTS_PATH bundle Elixir's Hex
PERL_LWP_SSL_CA_FILE bundle Perl LWP
CLOUDSDK_CORE_CUSTOM_CA_CERTS_FILE bundle gcloud
NODE_EXTRA_CA_CERTS ca.pem Node.js, npm, Bun, Electron's main process
JAVA_TOOL_OPTIONS trust store Java (above)

The system roots come from the bundle that SSL_CERT_FILE, REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE already pointed at (a company bundle, say). Otherwise Akev uses the distribution's bundle (/etc/ssl/certs/ca-certificates.crt, /etc/pki/tls/certs/ca-bundle.crt and similar; /etc/ssl/cert.pem on macOS), or Git for Windows' bundle on Windows. When the CA or the system bundle changes, Akev rewrites the bundle the next time it is needed.

Proxy. HTTP_PROXY and HTTPS_PROXY (in both cases), WS_PROXY, WSS_PROXY, GLOBAL_AGENT_HTTP_PROXY, CGI_HTTP_PROXY, npm_config_proxy, npm_config_https_proxy, YARN_HTTP_PROXY and YARN_HTTPS_PROXY point at the proxy. NODE_USE_ENV_PROXY=1 and ELECTRON_GET_USE_PROXY=1 turn on proxy support in Node.js and Electron's downloader, and NO_PROXY and no_proxy are emptied so localhost is captured too. AKEV_ACTIVE=1 and AKEV_PROXY mark the environment. ALL_PROXY is deliberately not set: many tools treat it as a SOCKS proxy or apply it to protocols other than HTTP, which breaks them.

Good to know:

  • Go reads SSL_CERT_FILE on Linux only. On macOS and Windows it uses the system store, so trust the CA system-wide. Go never sends requests for localhost or 127.0.0.1 through a proxy: use your machine's host name or network address.
  • Node.js 24 and later use the proxy variables for fetch and http(s) when NODE_USE_ENV_PROXY=1 is set. For older versions, use global-agent (node -r global-agent/bootstrap app.js) or an undici ProxyAgent.
  • Python: aiohttp only uses the proxy variables with ClientSession(trust_env=True).
  • Rust: reqwest uses the proxy variables, and trusts SSL_CERT_FILE with rustls-native-certs or native-tls. Builds that use webpki-roots need the CA added in code (add_root_certificate).
  • PowerShell's web cmdlets use the system store, except PowerShell 6 and later on Linux.

For a single command, pass the proxy and the CA directly:

bash
curl --proxy http://127.0.0.1:8000 --cacert "$(akev ca path)" https://example.com

Phones and tablets

  • iPhone and iPad: install the configuration profile from the setup page, then turn on full trust in Settings → General → About → Certificate Trust Settings. See iPhone and iPad.
  • Android: install the certificate as a user CA. Apps targeting Android 7 or later only trust it if they opt in. On rooted devices and emulators, Akev also trusts it as a system CA until the device restarts, which release apps trust too. See Android over ADB.
  • iOS Simulator (macOS): one click trusts the CA in booted simulators. See iOS Simulator.
  • Any device can download the certificate from the setup page, http://akev.cert/ through the proxy or http://<address>:<port>/ directly: as a configuration profile (/ca.mobileconfig), DER (/ca.crt, also /ca.cer and /ca.der) or PEM (/ca.pem). See other devices.

WireGuard mode sends a device's traffic through Akev without proxy settings, but the device still needs to trust the CA for HTTPS.

Bring your own CA

Akev has no import button, setting or API for your own CA. It does use whatever certificate and key it finds as ca.pem and ca.key in its data directory when it starts. So you can use your own CA, for example one your devices already trust, by replacing those two files:

  1. Quit Akev completely (quit the desktop app, or run akev stop).
  2. Back up the current ca.pem and ca.key if you might want them again.
  3. Save your CA certificate as ca.pem and its private key as ca.key in the data directory.
  4. Start Akev and check that Settings → Certificates (or akev ca show) shows your CA's subject.

What Akev accepts:

Supported
Files PEM only. Convert DER or PKCS#12 files to PEM first.
Key types ECDSA P-256 or P-384, RSA, Ed25519
Key formats PKCS#8 (BEGIN PRIVATE KEY), SEC1 (BEGIN EC PRIVATE KEY) or PKCS#1 (BEGIN RSA PRIVATE KEY), not encrypted. Decrypt an encrypted key first, e.g. openssl pkey -in ca.key -out ca-decrypted.key.
Certificate A CA certificate: basicConstraints with cA true, and a keyUsage (if it has one) that allows signing certificates (keyCertSign). It must match the key.
Validity Already valid (an expired CA is kept, with a warning, but you can't switch to one)
Subject No attribute type used twice (such as DC=example, DC=com) and no multi-valued RDNs, because Akev's certificates must reproduce the issuer name exactly

A certificate without basicConstraints is accepted, but strict clients may reject the certificates it signs.

Things to know before you rely on it:

  • If Akev can't use the pair, it doesn't stop. It moves your files to ca.pem.bak and ca.key.bak, generates its own CA and logs the reason. That's why step 4 matters.
  • Expiry: Akev keeps your CA until you replace it, and warns when fewer than 60 days are left.
  • Regenerating (Settings → Certificates, akev ca regenerate or the API) replaces your CA with a new Akev CA; your files are kept as ca.pem.bak and ca.key.bak only until the next regeneration. Keep a copy elsewhere.
  • Chains are kept. If ca.pem holds an intermediate CA followed by its chain, the first certificate signs, and the rest are sent after it in every TLS handshake.
  • Akev's host certificates still use ECDSA P-256 keys. Your CA signs them with its own key (RSA signatures use PKCS#1 v1.5 with SHA-256).
  • --ephemeral without --data-dir uses a temporary data directory, so it doesn't see your files.
  • The Windows removal command above looks for CN=Akev CA, so adapt it to your CA's name.

Remove trust again

Remove the CA when you're done debugging, and before you regenerate it.

Where How to remove it
Linux, macOS, Windows Remove in Settings → Certificates → Trust on this computer, or the removal commands under Trust the CA system-wide, also shown in Settings → Certificates → Trust by hand
Chrome or Chromium's NSS database (Linux) Remove under Trust on this computer, or certutil -d sql:$HOME/.pki/nssdb -D -n 'Akev CA'
Your own Firefox profile Settings → Privacy & Security → Certificates → View Certificates… → Authorities → Delete or Distrust…
iPhone and iPad Remove the profile in Settings → General → VPN & Device Management
Android Remove the user certificate in the device's security settings, and Download/akev-ca.crt if you like
A Java trust store you built Delete the .p12 file and stop passing it to the JVM

Nothing needs removing for clients Akev launched. Chromium-family browsers and Electron apps trust the CA only through a switch in that one process. Firefox profiles and Akev's Java trust store live in Akev's data directory. Terminals lose the variables when you close them or run akev-off. Containers you attached to lose the copied files when you click Detach.

Certificates for upstream servers

Settings → Certificates → Upstream servers is about the servers your clients talk to, not about Akev's CA:

  • Client certificates: present a certificate to servers that require mutual TLS. PKCS#12 (.p12, .pfx) or PEM files, per host (globs allowed), with an optional passphrase.
  • Trusted CA certificates: extra root certificates (PEM files) to trust for upstream servers, such as your company's internal CA, on top of the roots built into Akev (Mozilla's) and your system's.
  • Ignore certificate errors: hosts whose invalid, expired or self-signed certificates Akev accepts. Only list hosts you control: traffic to them could be intercepted by someone else without you noticing.

To see which certificates a server presented and why Akev trusted them, open an exchange's Connection tab: see certificates on the Connection tab.

Type to search guides, the CLI and the API.