Corporate proxies and custom CAs#

Run Lockpin on a network that sends outbound traffic through a company proxy, or that inspects TLS with a private root certificate. This page is for developers on a company network and for the IT and security admins who set those machines up.

What this covers#

Every connection Lockpin makes out of the machine goes through one shared transport that honours the proxy variables every other tool on the network already uses, and verifies TLS against the roots the machine trusts. That covers:

  • provider calls, including streamed ones and the signed Bedrock calls;

  • the -report on upload and the -capabilities-issuer heartbeat;

  • -prices-url and lockpin providers update;

  • alerts and the phone relay;

  • lockpin doctor -network.

Lockpin’s own connections to 127.0.0.1, ::1 and localhost are always direct, whatever NO_PROXY says.

Setting

What it does

HTTPS_PROXY=http://proxy.corp:3128

The proxy for https:// targets: every provider, the dashboard and the heartbeat. Lockpin opens a CONNECT tunnel through it, so the proxy sees host names, never request bodies.

HTTP_PROXY=http://proxy.corp:3128

The proxy for http:// targets, such as a self-hosted issuer or catalog over plain HTTP.

NO_PROXY=.corp.local,10.0.0.0/8

Hosts reached directly: names, .suffix domains, IP addresses, CIDR ranges, host:port, or *.

-ca-file corp-root.pem or LOCKPIN_CA_FILE=corp-root.pem

A PEM bundle of extra root certificates (the TLS-inspection root), trusted in addition to the system store. The flag wins over the variable.

The lower-case names (https_proxy, no_proxy) work too. The upper-case one wins when both are set.

Before you begin#

  • Lockpin is installed. To install behind a proxy, see The installers behind a proxy first.

  • You know the proxy’s address, and its credentials if it needs them.

  • If the network inspects TLS, you have its root certificate as a PEM file, or IT has installed it in the system store.

Set up the proxy#

  1. Set the proxy variables in the shell that starts Lockpin. Proxy credentials go in the URL (http://user:password@proxy.corp:3128) and are sent as basic authentication on the CONNECT.

    $env:HTTPS_PROXY = "http://proxy.corp:3128"
$env:NO_PROXY = ".corp.local,10.0.0.0/8"
lockpin

    export HTTPS_PROXY=http://proxy.corp:3128
export NO_PROXY=.corp.local,10.0.0.0/8
lockpin

  2. If the network inspects TLS with a private root the machine does not trust, give it to Lockpin:

    lockpin -ca-file corp-root.pem

    Or set it in lockpin.json, under "flags":

    {
  "flags": {
    "ca-file": "corp-root.pem"
  }
}

    Or store it in the background service’s definition:

    lockpin service install -args "-ca-file corp-root.pem"

    A file that is missing, holds no certificate, or does not parse stops Lockpin at start.

  3. Set NO_PROXY in your agents’ environment too:

    $env:NO_PROXY = "127.0.0.1,localhost,::1"

    export NO_PROXY=127.0.0.1,localhost,::1

Warning

Lockpin controls only its own connections. The hop from an agent to Lockpin is plain HTTP, and an HTTP library that does not exempt loopback on its own would send that call, prompt and key included, to the corporate proxy. lockpin doctor warns when HTTP_PROXY is set and NO_PROXY does not name both 127.0.0.1 and localhost.

Commands that make their own connections#

These subcommands have no -ca-file flag. They read LOCKPIN_CA_FILE only, not lockpin.json: enroll, phone pair, providers update, import, alerts test and digest. Set the variable before you run them:

$env:LOCKPIN_CA_FILE = "corp-root.pem"
lockpin providers update -dry-run

export LOCKPIN_CA_FILE=corp-root.pem
lockpin providers update -dry-run

Which roots Lockpin trusts#

Without -ca-file, Lockpin trusts what the operating system trusts:

System

Roots

Windows

The Windows certificate store. A root your IT pushed by policy is already there.

macOS

The macOS certificate store.

Linux

The distribution’s bundle, plus SSL_CERT_FILE and SSL_CERT_DIR.

A server the machine does not trust fails closed: the agent gets 502 upstream_error with the x509 reason, and nothing is charged.

For a fleet#

A company can set the root in its signed machine policy with ca_file. It is used instead of -ca-file from the next start. Point it at a file only administrators can change, since every outbound connection trusts what is in it. See Signed policy.

The installers behind a proxy#

The one-line installers fetch the script from lockpin.dev, and the latest release’s tag, the archive and SHA256SUMS from github.com, which redirects downloads to objects.githubusercontent.com and release-assets.githubusercontent.com. All of those hosts must be allowed through the proxy.

In Windows PowerShell 5.1, which irm ... | iex and lockpin upgrade run, the installer follows the Windows system proxy (Internet Options) and the Windows certificate store. It ignores HTTPS_PROXY, and sends no proxy credentials unless the system proxy settings hold them. In PowerShell 7 it also reads HTTPS_PROXY.

install.sh uses curl, which honours HTTPS_PROXY, https_proxy and NO_PROXY, and trusts the system bundle. For a private root, set the bundle before the one-liner:

export CURL_CA_BUNDLE=/path/corp-root.pem
curl --proto '=https' --tlsv1.2 -fsSL https://lockpin.dev/install.sh | sh

A variable set on the curl ... | sh line reaches only the outer curl, not the ones inside the script, so export it first. SSL_CERT_FILE works too. Either replaces curl’s bundle rather than adding to it, so the file must hold the public roots too, or the corporate root if the proxy re-signs everything. lockpin upgrade runs the same script with your environment.

Limits#

  • Verification is never turned off. There is no insecure flag and no variable for one.

  • Proxy authentication is basic credentials in the URL. For NTLM, Kerberos or a PAC file, run a local forwarder that speaks them, such as Cntlm or Px, and point HTTPS_PROXY at http://127.0.0.1:<its port>.

  • Proxies that need a client certificate are not supported, and a socks5:// value is refused as not a proxy URL.

  • A proxy that accepts the connection and never answers the CONNECT is bounded by the call’s own timeout: 10 minutes for a provider call, 20 seconds for the reporter.

  • A proxy outage never changes a cap decision. A call over its budget is refused as always with nothing dialled. A call within it fails like any unreachable provider (502, no charge).

  • The desktop overlay only talks to 127.0.0.1 and needs none of this.

Verify#

Run lockpin doctor with the same settings Lockpin uses, and read its egress line first:

lockpin doctor -ca-file corp-root.pem -network

[PASS] egress: https: via http://xxxxx@proxy.corp:3128 (HTTPS_PROXY); http: direct; NO_PROXY exempts .corp.local; Lockpin's own calls to 127.0.0.1 and localhost always direct; roots: the system store plus 1 certificate(s) from corp-root.pem

Doctor prints the whole user:password part of a proxy URL as xxxxx. A mistyped value is refused without being echoed anywhere.

Symptom

Fix

502 upstream_error with x509: certificate signed by unknown authority

The network inspects TLS with a root the machine does not trust. Give it to Lockpin with -ca-file or LOCKPIN_CA_FILE, or have IT install it in the system store. Never change the provider URL to plain HTTP to work around it.

502 upstream_error with proxyconnect or Proxy Authentication Required

HTTPS_PROXY points at a proxy that is down, or that wants credentials (http://user:password@proxy:3128).

Next steps#