cert verification updates (ocsp)

heskew · heskew · commit 4336b33f8bd1 · 2025-07-24T07:16:37.000-07:00
diff --git a/docs/deployments/configuration.md b/docs/deployments/configuration.md
@@ -130,7 +130,7 @@ http:
   timeout: 120000
 ```
 
-`mlts` - _Type_: boolean | object; _Default_: false
+`mtls` - _Type_: boolean | object; _Default_: false
 
 This can be configured to enable mTLS based authentication for incoming connections. If enabled with default options (by setting to `true`), the client certificate will be checked against the certificate authority specified with `tls.certificateAuthority`. And if the certificate can be properly verified, the connection will authenticate users where the user's id/username is specified by the `CN` (common name) from the client certificate's `subject`, by default.
 
@@ -142,20 +142,46 @@ This configures a specific username to authenticate as for mTLS connections. If
 
 `required` - _Type_: boolean; _Default_: false
 
-This can be enabled to require client certificates (mTLS) for all incoming MQTT connections. If enabled, any connection that doesn't provide an authorized certificate will be rejected/closed. By default, this is disabled, and authentication can take place with mTLS _or_ standard credential authentication.
+This can be enabled to require client certificates (mTLS) for all incoming connections. If enabled, any connection that doesn't provide an authorized certificate will be rejected/closed. By default, this is disabled, and authentication can take place with mTLS _or_ standard credential authentication.
+
+`certificateVerification` - _Type_: boolean | object; _Default_: true
+
+When mTLS is enabled, Harper verifies the revocation status of client certificates using OCSP (Online Certificate Status Protocol). This ensures that revoked certificates cannot be used for authentication.
+
+Set to `false` to disable certificate verification, or configure with an object:
+
+- `timeout` - _Type_: number; _Default_: 5000 - Maximum milliseconds to wait for OCSP response
+- `cacheTtl` - _Type_: number; _Default_: 3600000 - Milliseconds to cache verification results (default: 1 hour)
+- `failureMode` - _Type_: string; _Default_: 'fail-open' - Behavior when OCSP verification fails:
+  - `'fail-open'`: Allow connection on verification failure (logs warning)
+  - `'fail-closed'`: Reject connection on verification failure
+
+Example configurations:
 
 ```yaml
+# Basic mTLS with default certificate verification
 http:
   mtls: true
 ```
 
-or
-
 ```yaml
+# mTLS with certificate verification disabled (not recommended for production)
 http:
   mtls:
     required: true
     user: user-name
+    certificateVerification: false
+```
+
+```yaml
+# mTLS with custom verification settings for high-security environments
+http:
+  mtls:
+    required: true
+    certificateVerification:
+      timeout: 10000 # 10 seconds for OCSP response
+      cacheTtl: 7200000 # Cache results for 2 hours
+      failureMode: fail-closed # Reject if OCSP check fails
 ```
 
 ---
@@ -683,6 +709,7 @@ Harper's logger supports defining multiple logging configurations for different
 `logging.external`
 
 The `logging.external` section can be used to define logging for all external components that use the [`logger` API](../technical-details/reference/globals.md). For example:
+
 ```yaml
 logging:
   external:
@@ -693,15 +720,16 @@ logging:
 `http.logging`
 
 This section defines log configuration for HTTP logging. By default, HTTP requests are not logged, but defining this section will enable HTTP logging. Note that there can be substantive overhead to logging all HTTP requests. In addition to the standard logging configuration, the `http.logging` section also allows the following configuration properties to be set:
-* `timing` - This will log timing information
-* `headers` - This will log the headers in each request (which can be very verbose)
-* `id` - This will assign a unique id to each request and log it in the entry for each request. This is assigned as the `request.requestId` property and can be used to by other logging to track a request.
+- `timing` - This will log timing information
+- `headers` - This will log the headers in each request (which can be very verbose)
+- `id` - This will assign a unique id to each request and log it in the entry for each request. This is assigned as the `request.requestId` property and can be used to by other logging to track a request.
 Note that the `level` will determine which HTTP requests are logged:
-* `info` (or more verbose) - All HTTP requests
-* `warn` - HTTP requests with a status code of 400 or above
-* `error` - HTTP requests with a status code of 500
+- `info` (or more verbose) - All HTTP requests
+- `warn` - HTTP requests with a status code of 400 or above
+- `error` - HTTP requests with a status code of 500
 
 For example:
+
 ```yaml
 http:
   logging: 
@@ -739,7 +767,7 @@ This section defines log configuration for setting up and reading the database f
 
 This section defines log configuration for analytics. This takes the standard logging configuration options of `path` (or `root`), `level`, `tag`, and flag to enable/disable logging to `stdStreams`.
 
-***
+---
 
 ### `authentication`
 
@@ -1080,7 +1108,7 @@ This enables access to MQTT through WebSockets. This will handle WebSocket conne
 
 This indicates if authentication should be required for establishing an MQTT connection (whether through MQTT connection credentials or mTLS). Disabling this allows unauthenticated connections, which are then subject to authorization for publishing and subscribing (and by default tables/resources do not authorize such access, but that can be enabled at the resource level).
 
-`mlts` - _Type_: boolean | object; _Default_: false
+`mtls` - _Type_: boolean | object; _Default_: false
 
 This can be configured to enable mTLS based authentication for incoming connections. If enabled with default options (by setting to `true`), the client certificate will be checked against the certificate authority specified in the `tls` section. And if the certificate can be properly verified, the connection will authenticate users where the user's id/username is specified by the `CN` (common name) from the client certificate's `subject`, by default.
 
@@ -1098,6 +1126,18 @@ This can be enabled to require client certificates (mTLS) for all incoming MQTT
 
 This can define a specific path to use for the certificate authority. By default, certificate authorization checks against the CA specified at `tls.certificateAuthority`, but if you need a specific/distinct CA for MQTT, you can set this.
 
+`certificateVerification` - _Type_: boolean | object; _Default_: true
+
+When mTLS is enabled, Harper verifies the revocation status of client certificates using OCSP (Online Certificate Status Protocol). This ensures that revoked certificates cannot be used for authentication.
+
+Set to `false` to disable certificate verification, or configure with an object:
+
+- `timeout` - _Type_: number; _Default_: 5000 - Maximum milliseconds to wait for OCSP response
+- `cacheTtl` - _Type_: number; _Default_: 3600000 - Milliseconds to cache verification results (default: 1 hour)
+- `failureMode` - _Type_: string; _Default_: 'fail-open' - Behavior when OCSP verification fails:
+  - `'fail-open'`: Allow connection on verification failure (logs warning)
+  - `'fail-closed'`: Reject connection on verification failure
+
 For example, you could specify that mTLS is required and will authenticate as "user-name":
 
 ```yaml
diff --git a/docs/developers/clustering/certificate-management.md b/docs/developers/clustering/certificate-management.md
@@ -28,6 +28,18 @@ Once you generate new certificates, to make Harper start using them you can eith
 
 Since these new certificates can be issued with correct CNs, you should set `insecure` to `false` so that nodes will do full validation of the certificates of the other nodes.
 
+### Certificate Revocation Checking
+
+Harper automatically performs certificate revocation checking using OCSP (Online Certificate Status Protocol) for all cluster connections. This critical security feature ensures that:
+
+- Revoked certificates cannot be used for cluster communication
+- Compromised nodes can be quickly isolated by revoking their certificates
+- Certificate status is verified in real-time with the Certificate Authority
+
+Certificate verification is enabled by default for cluster connections and follows the same configuration as HTTP mTLS connections. The verification settings can be customized in the HTTP configuration section to balance security requirements with performance considerations.
+
+For production clusters, consider using `failureMode: fail-closed` to ensure maximum security by rejecting connections when OCSP verification cannot be completed.
+
 ### Certificate Requirements
 
 - Certificates must have an `Extended Key Usage` that defines both `TLS Web Server Authentication` and `TLS Web Client Authentication` as these certificates will be used to accept connections from other Harper nodes and to make requests to other Harper nodes. Example:
diff --git a/docs/developers/real-time.md b/docs/developers/real-time.md
@@ -36,7 +36,9 @@ mqtt:
   requireAuthentication: true
 ```
 
-Note that if you are using WebSockets for MQTT, the sub-protocol should be set to "mqtt" (this is required by the MQTT specification, and should be included by any conformant client): `Sec-WebSocket-Protocol: mqtt`. mTLS is also supported by enabling it in the configuration and using the certificate authority from the TLS section of the configuration. See the [configuration documentation for more information](../deployments/configuration.md).
+Note that if you are using WebSockets for MQTT, the sub-protocol should be set to "mqtt" (this is required by the MQTT specification, and should be included by any conformant client): `Sec-WebSocket-Protocol: mqtt`.
+
+mTLS is also supported by enabling it in the configuration and using the certificate authority from the TLS section of the configuration. When mTLS is enabled for MQTT, Harper automatically performs certificate revocation checking using OCSP (Online Certificate Status Protocol) to ensure that revoked certificates cannot be used for authentication. See the [configuration documentation for more information](../deployments/configuration.md).
 
 #### Capabilities
 
diff --git a/docs/developers/replication/README.md b/docs/developers/replication/README.md
@@ -73,6 +73,8 @@ replication:
 
 Harper supports the highest levels of security through public key infrastructure based security and authorization. Depending on your security configuration, you can configure Harper in several different ways to build a connected cluster.
 
+When using certificate-based authentication, Harper automatically performs OCSP (Online Certificate Status Protocol) verification to check if certificates have been revoked. This ensures that compromised certificates cannot be used for replication connections. Certificate verification settings follow the same configuration as HTTP mTLS connections (see [certificate verification configuration](../../deployments/configuration.md#http)).
+
 #### Provide your own certificates
 
 If you want to secure your Harper connections with your own signed certificates, you can easily do so. Whether you have certificates from a public authority (like Let's Encrypt or Digicert) or a corporate certificate authority, you can use them to authenticate nodes securely. You can then allow nodes to authorize each other by checking the certificate against the standard list of root certificate authorities by enabling the `enableRootCAs` option in the config:
diff --git a/docs/developers/security/README.md b/docs/developers/security/README.md
@@ -2,8 +2,14 @@
 
 Harper uses role-based, attribute-level security to ensure that users can only gain access to the data they’re supposed to be able to access. Our granular permissions allow for unparalleled flexibility and control, and can actually lower the total cost of ownership compared to other database solutions, since you no longer have to replicate subsets of your data to isolate use cases.
 
-- [JWT Authentication](jwt-auth.md)
-- [Basic Authentication](basic-auth.md)
-- [mTLS Authentication](mtls-auth.md)
-- [Configuration](configuration.md)
-- [Users and Roles](users-and-roles.md)
+## Authentication Methods
+
+- [JWT Authentication](jwt-auth.md) - JSON Web Token based authentication
+- [Basic Authentication](basic-auth.md) - Username/password authentication
+- [mTLS Authentication](mtls-auth.md) - Certificate-based mutual TLS authentication with automatic certificate revocation checking
+
+## Security Configuration
+
+- [Configuration](configuration.md) - Security-related configuration options
+- [Users and Roles](users-and-roles.md) - Managing users and role-based permissions
+- [Certificate Management](certificate-management.md) - Managing SSL/TLS certificates
diff --git a/docs/developers/security/mtls-auth.md b/docs/developers/security/mtls-auth.md
@@ -1,3 +1,29 @@
 # mTLS Authentication
 
-Harper supports mTLS authentication for incoming connections. When enabled in the [HTTP config settings](../../deployments/configuration.md#http) the client certificate will be checked against the certificate authority specified with `tls.certificateAuthority`. If the certificate can be properly verified, the connection will authenticate users where the user's id/username is specified by the `CN` (common name) from the client certificate's `subject`, by default. The [HTTP config settings](../../deployments/configuration.md#http) allow you to determine if mTLS is required for all connections or optional.
+Harper supports mTLS (mutual TLS) authentication for incoming connections, providing certificate-based authentication for enhanced security. When enabled in the [HTTP config settings](../../deployments/configuration.md#http), the client certificate will be checked against the certificate authority specified with `tls.certificateAuthority`. If the certificate can be properly verified, the connection will authenticate users where the user's id/username is specified by the `CN` (common name) from the client certificate's `subject`, by default. The [HTTP config settings](../../deployments/configuration.md#http) allow you to determine if mTLS is required for all connections or optional.
+
+## Certificate Verification
+
+When mTLS is enabled, Harper automatically performs certificate revocation checking using OCSP (Online Certificate Status Protocol). OCSP provides real-time verification that certificates have not been revoked by the Certificate Authority, ensuring that compromised or invalidated certificates cannot be used for authentication.
+
+### How It Works
+
+When a client presents a certificate:
+
+1. Harper validates the certificate against the configured Certificate Authority
+2. If validation succeeds, Harper queries the CA's OCSP responder to check revocation status
+3. The verification result is cached to minimize performance impact on subsequent connections
+4. Based on the configuration, the connection is either allowed or rejected
+
+### Key Features
+
+- **Enabled by default** when mTLS is configured
+- **Real-time verification** with the Certificate Authority's OCSP responder
+- **Intelligent caching** of verification results (default: 1 hour)
+- **Configurable timeout** for OCSP responses (default: 5 seconds)
+- **Flexible failure handling** with fail-open or fail-closed modes
+- **Unified across all protocols** - HTTP, MQTT, and replication connections
+
+### Configuration
+
+Certificate verification can be disabled or customized through the `certificateVerification` setting. See the [HTTP configuration](../../deployments/configuration.md#http) and [MQTT configuration](../../deployments/configuration.md#mqtt) sections for detailed options.
