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_keyset,client_certcan be PEM or DER, andclient_keycan be PEM or DER in PKCS#8, PKCS#1 or EC (SEC 1) form. DER input is wrapped in PEM and passed totls.X509KeyPair, so key parsing and the certificate/key match check stay in the standard library. - With
client_keyunset,client_certis 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 withclient_cert_passwordusinggo-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 exampleMAC digest algorithm not supported), a bundle without a private key or with more than one, and decryption errors.
- A wrong password:
- Any other
client_certwithoutclient_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 withGLAB_DEBUG. Existing configs are unaffected, including CI auto-login, which can setCI_SERVER_TLS_CERT_FILEwithoutCI_SERVER_TLS_KEY_FILE. The exception is aclient_cert_passwordthat 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_keyset, 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
KeySchemaentry withKeyring: true, so withuse_keyring: trueit is stored in the OS keyring liketoken. - Its environment variable is
GLAB_CLIENT_CERT_PASSWORD, with no unprefixed alias. - Like
client_certandclient_key, its environment variable is not limited to trusted hosts (it is not inenvCredentialKeys). The password only decrypts a local file and is never sent to a host. - It's read when
client_cert, used withoutclient_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 withclient_keyand 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 logoutdoes not clear it, because it doesn't clearclient_certorclient_keyeither.
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 Issues
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_ClientCertificateFormatsbuilds an in-process TLS server that requires a client certificate signed by a test CA. It then checks that a client built withNewClientFromConfigpresents 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_ClientCertificateErrorschecks 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_passwordset for a PEM certificateclient_cert_passwordset for a missing file
TestNewClientFromConfig_ClientCertificateWithoutKeyNotPKCS12IsNotSentchecks that aclient_certwithoutclient_keythat 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 PEMclient_certwithout a key, with a failing keyring, builds a client that sends no certificate.TestNewClientFromConfig_PKCS12PasswordReadErrorIsWrapped: a PKCS#12 bundle with a failing keyring returnsfailed to read client_cert_password for "<host>", wrapping the keyring error.TestNewClientFromConfig_ClientCertificateFormatsalso covers a PKCS#12 bundle without a password.internal/config/config_test.go:client_cert_passwordis stored in the keyring and kept out ofconfig.ymlwhenuse_keyringis true.- It round-trips through the config file.
GLAB_CLIENT_CERT_PASSWORDoverrides the file value.
internal/config/known_keys_test.go:client_cert_passwordis 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 0on the changed Go files: 0 findings.