What causes "missing KeyUsage keyCertSign" in gravitational/teleport?

Re-issue the CA certificate with KeyUsage including keyCertSign (and cRLSign).

missing KeyUsage keyCertSign

Error message

missing KeyUsage keyCertSign

What it means

validateOverrideCertificate requires the override certificate's KeyUsage to include keyCertSign (x509.KeyUsageCertSign). Without this key usage the certificate is not permitted to verify/sign other certificates, so it cannot serve as a CA override.

Source

Thrown at lib/subca/parsed.go:353

	}
	if certClusterName != clusterName {
		return fmt.Errorf(
			"incorrect cluster name %q (expected %q)",
			certClusterName,
			clusterName,
		)
	}

	// Verify certificate constraints.
	switch {
	case !cert.IsCA:
		return errors.New("not a CA certificate (IsCA=false)")
	case !cert.BasicConstraintsValid:
		return errors.New("basic constraints not valid (BasicConstraintsValid=false)")
	case cert.KeyUsage&x509.KeyUsageCertSign == 0:
		// Usage names per Go 1.26.1.
		// https://cs.opensource.google/go/go/+/refs/tags/go1.26.1:src/crypto/x509/x509_string.go;l=23
		return errors.New("missing KeyUsage keyCertSign")
	case cert.KeyUsage&x509.KeyUsageCRLSign == 0:
		return errors.New("missing KeyUsage cRLSign")
	case cert.NotBefore.After(cert.NotAfter):
		return errors.New("NotBefore > NotAfter")
	}

	return nil
}

View on GitHub (pinned to 1283425b60)

Solutions

Re-issue the CA certificate with KeyUsage including keyCertSign (and cRLSign).
Inspect with 'openssl x509 -in cert.pem -text' that 'Certificate Sign' appears under Key Usage.
In Go generation code, add x509.KeyUsageCertSign to template.KeyUsage.

Example fix

// before
KeyUsage: x509.KeyUsageDigitalSignature
// after
KeyUsage: x509.KeyUsageDigitalSignature |
          x509.KeyUsageCertSign |
          x509.KeyUsageCRLSign

Defensive patterns

Strategy: validation

Validate before calling

if cert.KeyUsage&x509.KeyUsageCertSign == 0 {
    return errors.New("override cert lacks keyCertSign key usage")
}

Prevention

Always provision CA certs with KeyUsageCertSign (plus CRLSign).
Check key usage via 'openssl x509 -text | grep -A1 "Key Usage"'.
Never reuse TLS server certs as CA overrides.

When it happens

Trigger: Supplying a certificate where KeyUsage is set but does not contain the keyCertSign bit (e.g. only digitalSignature/keyEncipherment) when calling ValidateAndParseCAOverride.

Common situations: Reusing a TLS server certificate as an override CA; CA certs issued by tooling that forgot the keyUsage extension; certificates converted between formats dropping extensions.

Related errors

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/5dd5a9e1f678ac8f. Report an issue: GitHub.