router-for-me/CLIProxyAPI · error

home ca fingerprint is required

Error message

home ca fingerprint is required

What it means

Thrown by verifyCACertificatePEM in internal/home/certificate.go when verifying the home CA certificate against an expected fingerprint. After computing the SHA-256 fingerprint of the PEM certificate, normalizeFingerprint(expectedFingerprint) trims/lowercases/strips colons; if the result is empty, the expected fingerprint was never supplied. The library refuses to trust a CA certificate without pinning it to a known fingerprint.

Source

Thrown at internal/home/certificate.go:191

	return nil
}

func verifyCACertificateFile(path string, expectedFingerprint string) error {
	raw, errRead := os.ReadFile(path)
	if errRead != nil {
		return errRead
	}
	return verifyCACertificatePEM(raw, expectedFingerprint)
}

func verifyCACertificatePEM(raw []byte, expectedFingerprint string) error {
	actual, errFingerprint := certificateFingerprintPEM(raw)
	if errFingerprint != nil {
		return errFingerprint
	}
	expected := normalizeFingerprint(expectedFingerprint)
	if expected == "" {
		return fmt.Errorf("home ca fingerprint is required")
	}
	if actual != expected {
		return fmt.Errorf("home ca fingerprint mismatch")
	}
	return nil
}

func certificateFingerprintPEM(raw []byte) (string, error) {
	block, _ := pem.Decode(raw)
	if block == nil || block.Type != "CERTIFICATE" {
		return "", fmt.Errorf("home ca certificate pem is invalid")
	}
	cert, errParse := x509.ParseCertificate(block.Bytes)
	if errParse != nil {
		return "", errParse
	}
	sum := sha256.Sum256(cert.Raw)
	return hex.EncodeToString(sum[:]), nil

View on GitHub (pinned to 78f0c4079e)

Solutions

1. Set the expected fingerprint in the home config (ca-fingerprint field) to the hex SHA-256 of the DER certificate: openssl x509 -in ca.pem -noout -fingerprint -sha256
2. Confirm the config file/env var actually loads (no typo in key name, .env present in working directory)
3. If fingerprints are managed out-of-band, ensure the enrollment flow stores the fingerprint before verification runs

Example fix

# before
home:
  ca-cert: /etc/cliproxy/ca.pem

# after
home:
  ca-cert: /etc/cliproxy/ca.pem
  ca-fingerprint: "a1b2c3d4..."  # sha256 of ca.pem

// before calling enrollment/verification, require a well-formed fingerprint
fp := strings.ToLower(strings.ReplaceAll(strings.TrimSpace(cfg.CAFingerprint), ":", ""))
if len(fp) != 64 { // sha256 hex
    return fmt.Errorf("home ca fingerprint missing or malformed: set it to sha256 hex of ca.pem")
}

When it happens

Trigger: Calling the certificate verification path (e.g. enroll/verify of the home CA) with an empty, whitespace-only, or colon-only expectedFingerprint value — typically because the config field that carries the fingerprint was left blank while ca-cert was set.

Common situations: Config yaml has home ca-cert path but no ca-fingerprint; operator copied the CA file but forgot to record its SHA-256; environment variable for the fingerprint unset in the deployment environment; fingerprint field renamed after a config schema change.

Related errors

• home ca fingerprint mismatch
• home ca certificate pem is invalid
• home tls: client certificate and key must be set together
• home tls: read ca-cert: %w
• home tls: ca-cert contains no PEM certificates

AI-assisted analysis of router-for-me/CLIProxyAPI@78f0c4079e (2026-08-15). Data as JSON: /api/errors/d1f8646ba4922d4d. Report an issue: GitHub.