cockroachdb/cockroach

Security

pkg/security/ centralizes the cryptographic and authentication primitives used by CockroachDB: certificate management, TLS configuration, password hashing (SCRAM), JWT and OIDC, LDAP, FIPS, OCSP, and the JOIN-token bootstrap flow. The pgwire layer and the RPC layer both consume what this package produces.

Purpose

Provide a single, well-tested set of authentication and key-management primitives. The package is the source of truth for which authenticators exist, how a client certificate maps to a SQL user, and how passwords are stored.

Directory layout

pkg/security/
├── cert.go                       // certificate types and pool helpers
├── certs.go                      // generate and load self-signed certs
├── certs_rotation_test.go        // hot-rotation tests
├── certificate_loader.go         // load PEM bundles from disk
├── certificate_manager.go        // mTLS material owned by a node
├── certnames/                    // CN/SAN policy for CRDB certs
├── auth.go                       // username extraction, audit hooks
├── tls.go                        // TLS config helpers
├── tls_ciphersuites.go           // explicit cipher suite policy
├── x509.go                       // X.509 helpers
├── pem.go                        // PEM helpers
├── password.go                   // SCRAM-SHA-256 + bcrypt fallback
├── password/                     // sub-package implementing the verifiers
├── pprompt/                      // password prompt
├── ocsp.go                       // OCSP stapling
├── join_token.go                 // bootstrap token for join
├── jwtauth/ and jwthelper/       // JWT verification
├── oidcauth/                     // OIDC interactive login flow
├── ldapauth/                     // LDAP bind + search
├── clientcert/                   // CN→user mapping
├── clientsecopts/                // client TLS option resolution
├── distinguishedname/            // X.500 DN parsing
├── dyncert/                      // dynamic certificate registration
├── fips/                         // FIPS-mode plumbing
├── provisioning/                 // automatic user provisioning
├── securityassets/               // embedded test assets
├── securitytest/                 // helpers for tests
├── sessionrevival/               // long-lived session revival
└── username/                     // SQL username type

Key types

Type	File	Description
`CertificateManager`	`pkg/security/certificate_manager.go`	Owns a node's TLS keypairs and CA pool. Hot-reloadable.
`CertificateLoader`	`pkg/security/certificate_loader.go`	Reads PEM files from a directory.
`JWTAuthenticator`	`pkg/security/jwtauth/`	Verifies JWTs against configured issuers/JWKS.
`OIDCAuthenticator`	`pkg/security/oidcauth/`	Browser-based OIDC login for the DB Console.
`LDAPAuthenticator`	`pkg/security/ldapauth/`	LDAP bind + search authenticator.
`Username`	`pkg/security/username/sql_username.go`	Normalized SQL username.
`JoinToken`	`pkg/security/join_token.go`	One-shot token to enroll a new node.

Authentication flow at a glance

graph LR
  Client["pgwire client"] --> Auth["pgwire/auth.go"]
  Auth -->|cert| CertMgr["CertificateManager"]
  Auth -->|password| Pwd["password.Verify"]
  Auth -->|JWT| JWT["jwtauth"]
  Auth -->|OIDC| OIDC["oidcauth"]
  Auth -->|LDAP| LDAP["ldapauth"]
  Auth --> User["security/username.SQLUsername"]
  User --> SQL["sql connExecutor"]

The actual dispatch is in pkg/sql/pgwire/auth.go (co-owned by sql-foundations and security teams). HBA-style configuration in pkg/sql/pgwire/hba/ selects which authenticator runs for a given connection based on database, user, source IP, and auth method.

Certificates

CockroachDB's certificate convention (pkg/security/certnames/):

ca.crt — cluster CA.
node.crt / node.key — server certificate for the node, with both node (in the SAN) and the node's hostnames.
client.<user>.crt — client cert for SQL user <user>.
client-tenant.<tid>.crt — client cert for tenant <tid> (multi-tenant).

The cockroach cert subcommands (pkg/cli/cert.go) generate these. CertificateManager watches the directory and reloads on change.

Passwords

pkg/security/password.go and pkg/security/password/:

Hashes are stored as PostgreSQL-compatible SCRAM-SHA-256$<iters>$<salt>:<storedKey>:<serverKey> strings.
For backwards compat, crdb-bcrypt$<cost>$<salt>$<hash> is also supported.
The cluster setting server.user_login.password_encryption selects the hashing scheme for new passwords.

The pwhash table in system.users carries the encoded hash.

JWT, OIDC, LDAP

JWT — pkg/security/jwtauth/: validates JWTs against a list of issuers, JWKS endpoints, and audiences. Used by the IAM-style integration with cloud auth providers.
OIDC — pkg/security/oidcauth/: implements the authorization-code flow for DB Console login. Cluster settings under server.oidc_authentication.* configure issuers and claim mapping.
LDAP — pkg/security/ldapauth/: bind + search-based authentication. Supports group-based role mapping.

The selected authenticator is chosen via hba.conf in system.settings.

OCSP

pkg/security/ocsp.go wires OCSP stapling for client certificates so the cluster can revoke compromised client certs without re-issuing them.

FIPS

pkg/security/fips/ and pkg/cli/debug_fips.go add a FIPS 140-2 build mode that:

Restricts cipher suites to the FIPS-approved list (tls_ciphersuites.go).
Uses BoringCrypto-backed Go for key operations.
Disables non-FIPS algorithms in JWT/OIDC.

New auth method: implement an authenticator under pkg/security/<name>auth/, register it in pkg/sql/pgwire/auth.go, expose cluster settings.
New cert kind: extend pkg/security/certnames/ and pkg/cli/cert.go.
Tighten TLS policy: edit pkg/security/tls_ciphersuites.go and the FIPS list, then run roachtests covering older clients.

RPC — consumes TLS material for inter-node calls.
SQL — pgwire chooses the authenticator.
Server — owns the HTTP authentication layer.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.