feat(api): accept PKCS#12 and DER client certificates

Description

client_cert and client_key were only accepted as PEM, because the API transport loaded them with tls.LoadX509KeyPair. Corporate mTLS setups often hand out a PKCS#12 bundle (.p12/.pfx) or DER files, and those failed with tls: failed to find any PEM data.

The API transport now loads the key pair through one loader in internal/api/client_cert.go:

  • With client_key set, client_cert can be PEM or DER, and client_key can be PEM or DER in PKCS#8, PKCS#1 or EC (SEC 1) form. DER input is wrapped in PEM and passed to tls.X509KeyPair, so key parsing and the certificate/key match check stay in the standard library.
  • With client_key unset, client_cert is used when it is a PKCS#12 bundle, recognised by its outer PFX structure (a version, then PKCS#7 data or signed-data content). It is decrypted with client_cert_password using go-pkcs12 (already a direct dependency), and any CA certificates in the bundle are sent as the chain. Because the file is a PKCS#12 bundle, every decode failure is an error naming the file:
    • A wrong password: incorrect password for the PKCS#12 client certificate "<path>": set client_cert_password.
    • Anything else go-pkcs12 rejects, with its message kept: loading PKCS#12 client certificate "<path>": .... This covers an unsupported algorithm (NotImplementedError, for example MAC digest algorithm not supported), a bundle without a private key or with more than one, and decryption errors.
  • Any other client_cert without client_key (a PEM or DER certificate, an unknown format, or a file that can't be read) keeps today's behaviour: glab sends no client certificate and logs the reason with GLAB_DEBUG. Existing configs are unaffected, including CI auto-login, which can set CI_SERVER_TLS_CERT_FILE without CI_SERVER_TLS_KEY_FILE. The exception is a client_cert_password that would be ignored: with a password set, such a file is an error naming it (client_cert_password is set, but the client certificate "<path>" is not a PKCS#12 bundle, or ... cannot be read).
  • With client_key set, every error names the file and the format glab expected.

Please review this new config key. This MR adds the per-host key client_cert_password:

  • It's a KeySchema entry with Keyring: true, so with use_keyring: true it is stored in the OS keyring like token.
  • Its environment variable is GLAB_CLIENT_CERT_PASSWORD, with no unprefixed alias.
  • Like client_cert and client_key, its environment variable is not limited to trusted hosts (it is not in envCredentialKeys). The password only decrypts a local file and is never sent to a host.
  • It's read when client_cert, used without client_key, is a PKCS#12 bundle that needs a password. It's also read when that file is not a readable bundle, to report a password that would be ignored. A failed read there is ignored, so a broken keyring still can't fail a PEM or DER setup. PEM and DER pairs with client_key and unencrypted bundles never trigger a keyring lookup. A failed read for a bundle that needs the password is wrapped with the key and host.
  • glab auth logout does not clear it, because it doesn't clear client_cert or client_key either.

WithClientCertificate now takes the password as a third argument. Its only caller is NewClientFromConfig.

The descriptions of client_cert and client_key are updated, and make gen-docs regenerated docs/source/config/_index.md and docs/source/configuration.md. The hand-written mTLS section in docs/source/connection.md now covers DER and PKCS#12.

Stack note: the df-upstream-proxy-mtls MR (client_cert for an mTLS outbound proxy) loads the same settings with tls.LoadX509KeyPair. Whichever of the two merges second should switch the proxy path to loadClientCertificates and pass client_cert_password. If dfcmd needs the loader from outside internal/api, it must be exported or moved. This MR keeps it unexported because it has no other caller yet.

Related to #8635 (closed) Related to gitlab-org/gitlab#629431 Related to gitlab-org&24327

Part of the corporate-proxy stack. It is based on main and does not depend on the other stack MRs.

How has this been tested?

New tests:

  • internal/api/client_cert_test.go: TestNewClientFromConfig_ClientCertificateFormats builds an in-process TLS server that requires a client certificate signed by a test CA. It then checks that a client built with NewClientFromConfig presents the certificate for each format:
    • PEM certificate with a PKCS#8 key
    • DER certificate with a PKCS#8 key
    • DER certificate with a PKCS#1 RSA key
    • DER certificate with an EC key
    • PKCS#12 bundle with password changeit
  • TestNewClientFromConfig_ClientCertificateErrors checks that each error names the file and gives a clear message for:
    • a wrong PKCS#12 password
    • a certificate in an unknown format with a key set
    • a PKCS#12 bundle without a private key
    • client_cert_password set for a PEM certificate
    • client_cert_password set for a missing file
  • TestNewClientFromConfig_ClientCertificateWithoutKeyNotPKCS12IsNotSent checks that a client_cert without client_key that is not PKCS#12 builds a client with no error and sends no certificate to a server that requests one. It covers a PEM certificate, a DER certificate, an unknown format and a missing file.
  • TestNewClientFromConfig_ClientCertificateWithoutKeyIgnoresUnreadablePassword: a PEM client_cert without a key, with a failing keyring, builds a client that sends no certificate.
  • TestNewClientFromConfig_PKCS12PasswordReadErrorIsWrapped: a PKCS#12 bundle with a failing keyring returns failed to read client_cert_password for "<host>", wrapping the keyring error.
  • TestNewClientFromConfig_ClientCertificateFormats also covers a PKCS#12 bundle without a password.
  • internal/config/config_test.go:
    • client_cert_password is stored in the keyring and kept out of config.yml when use_keyring is true.
    • It round-trips through the config file.
    • GLAB_CLIENT_CERT_PASSWORD overrides the file value.
  • internal/config/known_keys_test.go: client_cert_password is a known (settable) key.

Before the fix, both original error cases failed and the DER and PKCS#12 cases failed the handshake. The PEM case passed. The config tests for keyring storage, the environment variable and the known key also failed. The three error cases added in review (a bundle without a private key, and a password set for a PEM certificate or a missing file) failed before 89309baaf: each built a client with no error.

With a built binary and OpenSSL-made files, each of these sent no certificate on 53d2f7915 and now fails with the errors above: a bundle exported with -nokeys, a bundle with a SHA-384 MAC (-macalg sha384), and a PEM certificate with GLAB_CLIENT_CERT_PASSWORD set. A lone PEM certificate without a password is still ignored.

Commands run:

  • go test ./internal/api/... ./internal/config/... ./internal/commands/config/... ./cmd/gen-docs/...: pass.
  • go test -race ./internal/api/... ./internal/config/...: pass.
  • golangci-lint run ./internal/api/... ./internal/config/...: 0 issues.
  • go run ./scripts/comment-overlap -threshold 1.0 -max-findings 0 on the changed Go files: 0 findings.
Edited by Arpit Gogia

Merge request reports

Loading
Loading