Bondy Connect

Appearance

Certificate Manager ​

The Certificate Manager provides WAMP procedures for managing TLS certificates at runtime without restarting Bondy.

Description ​

Bondy's certificate manager (bondy_cert_manager) centralises all TLS certificate operations:

  • CA trust store -- merges CA certificates from the certifi Mozilla bundle, a user-configured PEM file (cert_manager.cacertfile), and the OS trust store. Used for all outbound TLS connections (OIDC providers, HTTP Connector backends, etc.).
  • Server certificates -- manages per-listener TLS certificates (cert + key). Enables live certificate rotation via an sni_fun callback so new connections use updated certificates without listener restarts.
  • mTLS -- per-listener client CA pools, verify mode, and fail_if_no_peer_cert settings for mutual TLS authentication.

Live Certificate Rotation ​

When you rotate a server certificate, the change takes effect immediately for new TLS connections. Existing connections continue using the certificate that was active when the handshake occurred. This allows graceful rotation -- new connections get the new certificate, old connections finish naturally.

The typical workflow for certificate renewal:

  1. An external process (certbot, internal CA, cron job) writes new certificate files to disk.
  2. Call bondy.cert_manager.rotate_listener or bondy.cert_manager.rotate_all to reload them.
  3. New connections immediately use the updated certificates.

Authority ​

Master realm only

Every procedure on this page requires a session on the master realm (com.leapsight.bondy), and answers wamp.error.not_authorized anywhere else.

None of them takes a realm argument, because none of them is a per-realm decision: the CA trust store and a listener's certificate are node state, shared by every realm the node serves. A tenant reloading them would reach every other tenant on that node.

The ordinary wamp.call permission applies on top, so these procedures are grantable and revocable like any other — but a grant alone is not enough, and a realm with security disabled does not become an exception.

Procedures ​

NameURI
Reload CA certificatesbondy.cert_manager.reload_cacerts
Rotate listener certificatebondy.cert_manager.rotate_listener
Rotate all certificatesbondy.cert_manager.rotate_all
Get server certificate infobondy.cert_manager.get_server_cert_info
Set client authbondy.cert_manager.set_client_auth
Get client authbondy.cert_manager.get_client_auth

Reload CA certificates ​

bondy.cert_manager.reload_cacerts() -> result() ​

Re-reads CA certificates from all configured sources (certifi bundle, user PEM file, OS trust store), deduplicates them, and updates the in-memory trust store. New outbound TLS connections will use the updated CA certificates.

Call ​

Positional Args ​

None.

Keyword Args ​

None.

Result ​

Positional Results ​

None.

Keyword Results ​

None.

Rotate listener certificate ​

bondy.cert_manager.rotate_listener(listener) -> result() ​

Re-reads the certificate and key files from disk for the specified listener and updates the in-memory certificate store. New TLS handshakes on that listener will use the updated certificate.

Also calls ranch:set_transport_options/2 to update the static certificate for clients that do not send SNI (Server Name Indication).

Call ​

Positional Args ​
0stringREQUIRED

The listener name: the $name of a listeners.$name.* block in the node configuration.

Keyword Args ​

None.

Result ​

Positional Results ​

None.

Keyword Results ​

None.

Errors ​

  • wamp.error.invalid_argument -- the listener reference is not a known TLS listener.

Rotate all certificates ​

bondy.cert_manager.rotate_all() -> result() ​

Re-reads certificate files from disk for every listener whose listeners.$name.transport is tls, and updates the in-memory certificate store.

When Bondy cannot rotate the certificate of a listener, it logs a warning and continues with the next listener. The call does not return an error.

Call ​

Positional Args ​

None.

Keyword Args ​

None.

Result ​

Positional Results ​

None.

Keyword Results ​

None.

Get server certificate info ​

bondy.cert_manager.get_server_cert_info(listener) -> result(cert_info) ​

Returns metadata about the currently loaded server certificate for a listener. The private key is never exposed.

Call ​

Positional Args ​
0stringREQUIRED

The listener name: the $name of a listeners.$name.* block in the node configuration.

Keyword Args ​

None.

Result ​

Positional Results ​
0objectREQUIRED

Certificate metadata.

Keyword Results ​

None.

Errors ​

Set client auth ​

bondy.cert_manager.set_client_auth(listener, options) -> result() ​

Sets the client certificate verification configuration for a listener. This enables or disables mutual TLS (mTLS) at runtime.

Updates take effect for new connections. Existing connections are not affected.

The options replace the current mTLS configuration of the listener. They are not merged into it, so an option you omit is absent from the new configuration.

Call ​

Positional Args ​
0stringREQUIRED

The listener name: the $name of a listeners.$name.* block in the node configuration.

1objectREQUIRED

The mTLS configuration options.

Keyword Args ​

None.

Result ​

Positional Results ​

None.

Keyword Results ​

None.

Get client auth ​

bondy.cert_manager.get_client_auth(listener) -> result(mtls_config) ​

Returns the current mTLS configuration for a listener.

Call ​

Positional Args ​
0stringREQUIRED

The listener name: the $name of a listeners.$name.* block in the node configuration.

Keyword Args ​

None.

Result ​

Positional Results ​
0objectREQUIRED

The current mTLS configuration for the listener.

Keyword Results ​

None.

Errors ​