macula_tls (macula v10.23.0)
View SourceTLS certificate management and TLS options for Macula QUIC.
Client dials
quic_client_opts/0 decides what an outbound QUIC dial verifies. The QUIC NIF checks the server certificate against its built-in webpki root store and the host being dialed. It cannot load a CA file.
- No TLS mode configured, or production: [{verify, webpki}]. - Development set explicitly, through MACULA_TLS_MODE=development (or dev) or the tls_mode app env: [{verify, none}]. This skips verification, so use it only for local development against self-signed peers. - A CA file set through MACULA_TLS_CACERTFILE or the tls_cacertfile app env raises {tls_config_error, {cacertfile_not_supported, Path}}.
Listeners
quic_server_opts/0 follows get_tls_mode/0, which reports development when nothing is configured:
- Production: certificate and key from tls_certfile and tls_keyfile. - Development: a self-signed certificate, generated when missing.
Configuration (sys.config)
{macula, [ {tls_mode, production}, % or development {tls_certfile, "/path/to/server.crt"}, {tls_keyfile, "/path/to/server.key"} ]}
Environment Variables
- MACULA_TLS_MODE: production, prod, development or dev - MACULA_TLS_CERTFILE: path to the listener certificate - MACULA_TLS_KEYFILE: path to the listener private key
Summary
Functions
Derive Node ID from certificate public key.
Ensure TLS certificate exists, generate if missing.
Generate self-signed TLS certificate using OpenSSL.
Get default certificate paths from application environment.
Get the current TLS mode (production or development).
TLS verify_fun callback for hostname verification.
Check if running in production TLS mode.
Get QUIC client TLS options for an outbound dial.
Get QUIC client TLS options with overrides.
Get QUIC client TLS options for a dial to Hostname.
Get QUIC server TLS options based on current TLS mode.
Get QUIC server TLS options with overrides.
Functions
Derive Node ID from certificate public key.
Extracts the public key from the PEM-encoded certificate and computes SHA-256 hash to create a stable, cryptographically-derived Node ID.
-spec ensure_cert_exists(CertPath :: file:filename(), KeyPath :: file:filename()) -> {ok, file:filename(), file:filename(), binary()} | {error, term()}.
Ensure TLS certificate exists, generate if missing.
Checks if certificate and key files exist at the specified paths. If they don't exist, generates new self-signed certificate and saves to disk. Returns the paths and derived Node ID.
-spec generate_self_signed_cert(Opts :: map()) -> {ok, CertPEM :: binary(), KeyPEM :: binary()} | {error, term()}.
Generate self-signed TLS certificate using OpenSSL.
Creates a new RSA key pair and self-signed X.509 certificate with: - RSA 2048-bit key - 10-year validity period - Subject: CN=macula-node - Self-signed (issuer = subject)
-spec get_cert_paths() -> {file:filename(), file:filename()}.
Get default certificate paths from application environment.
-spec get_tls_mode() -> production | development.
Get the current TLS mode (production or development).
Checks in order: 1. MACULA_TLS_MODE environment variable 2. tls_mode application environment setting 3. Defaults to 'development'
-spec hostname_verify_fun(Cert :: term(), Event :: {bad_cert, term()} | {extension, term()} | valid | valid_peer, State :: map()) -> {valid, map()} | {fail, term()} | {unknown, map()}.
TLS verify_fun callback for hostname verification.
This function is called during TLS handshake to verify the peer certificate. When used with hostname verification, it checks that the server's certificate contains the expected hostname in either the Subject CN or Subject Alt Names.
Usage:
{verify_fun, {fun macula_tls:hostname_verify_fun/3, #{hostname => "example.com"}}}
-spec is_production_mode() -> boolean().
Check if running in production TLS mode.
-spec quic_client_opts() -> list().
Get QUIC client TLS options for an outbound dial.
Verification stays on unless development mode is set explicitly. See the module doc for the exact rules.
Get QUIC client TLS options with overrides.
Raises {tls_config_error, {cacertfile_not_supported, Path}} when a CA file is configured explicitly, because the QUIC NIF cannot use one.
Get QUIC client TLS options for a dial to Hostname.
Same as quic_client_opts/0. The QUIC NIF already checks the server certificate against the host being dialed, so a hostname adds no options of its own.
-spec quic_server_opts() -> list().
Get QUIC server TLS options based on current TLS mode.
Server always needs a certificate and key. In production mode: Also verifies client certificates if presented. In development mode: Auto-generates self-signed certificate if needed.
Get QUIC server TLS options with overrides.