grindsa · skcert · Feb 9, 2026
diff --git a/docs/eab.md b/docs/eab.md
@@ -12,7 +12,7 @@ To enable EAB, the Certificate Authority (CA) operator must provide both the ACM
 
 Key identifiers are included in reports generated by the [Housekeeping](housekeeping.md) class.
 
-By deafault `acme2certifier` validates, during each ACME transaction, whether the EAB credentials used to create the ACME account remain valid. If this check fails, `acme2certifier` stops processing the transaction. This check can be disabled by the configuration option `eabkid_check_disable` in `a<me_srv.cfg`.
+By default `acme2certifier` validates, during each ACME transaction, whether the EAB credentials used to create the ACME account remain valid. If this check fails, `acme2certifier` stops processing the transaction. This check can be disabled by the configuration option `eabkid_check_disable` in `acme_srv.cfg`.
 
 ```ini
 [EABhandler]
@@ -61,6 +61,112 @@ The `key_file` should contain key-value pairs in JSON format:
 }
 ```
 
+## SQL Handler
+
+The `sql_handler.py` script allows `kid` and `mac_key` (Base64 encoded) to be loaded from a database. SQL Handler supports PostgreSQL and SQL Server database systems.
+
+Using a database for storing EAB credentials is useful in use cases where many `acme2certifier` instances use the same credentials, for example in data centers using load balancing. Instead of maintaining multiple JSON files, credentials can be maintained using a single database instance.
+
+Using a database is beneficial also when rotating and managing `kid/mac_key` pairs in more complex scenarios, with the addition of an `account` table that can maintain information about the account related to each key.
+
+It is recommended to use the same [external database](external_database_support.md) for both `acme2certifier` and EAB.
+
+### Database Schema
+
+The database schema includes two tables, one for actual credentials used by `acme2certifier` and another for managing accounts and credentials. Any number of credentials can be related to a single account. Only the credentials table is actually used by `acme2certifier`.
+
+Schemas for the database systems differ in relation to fields that are used to maintain JSON data. SQL Server has `NVARCHAR` type for that, whereas PostgreSQL has `JSONB`. Schemas also have a status column to indicate if the credentials are active or not (value is 0 or 1).
+
+#### When Using PostgreSQL
+
+Create a database and then these two tables. See [Usage](#Usage) for entering some data in the tables. Then, [configure acme_srv.cfg](#Activate) with the database credentials that you have.
+
+```sql
+CREATE TABLE account (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(127) NOT NULL,
+    contact VARCHAR(127)
+);
+
+CREATE TABLE credentials (
+    id SERIAL PRIMARY KEY,
+	account_id INT NOT NULL REFERENCES account (id),
+	key_id VARCHAR(63) NOT NULL,
+	profile JSONB,
+	description VARCHAR(255),
+    status SMALLINT NOT NULL
+);
+```
+
+#### When Using SQL Server
+
+Create a database and then these two tables. See [Usage](#Usage) for entering some data in the tables. Then, [configure acme_srv.cfg](#Activate) with the database credentials that you have.
+
+```sql
+CREATE TABLE account (
+    id INT IDENTITY(1,1) PRIMARY KEY,
+    name NVARCHAR(127) NOT NULL,
+    contact NVARCHAR(127)
+);
+
+CREATE TABLE credentials (
+	id INT IDENTITY(1,1) PRIMARY KEY,
+	account_id INT NOT NULL REFERENCES account (id),
+	key_id NVARCHAR(63) NOT NULL,
+	profile NVARCHAR(MAX),
+	description NVARCHAR(255),
+    status TINYINT NOT NULL
+);
+```
+
+<a id="Usage"></a>
+
+### Usage
+
+In the simplest scenario, the database will have one account that all the keys are related to.
+
+```sql
+INSERT INTO account (name, contact)
+  VALUES ('myaccount', 'contact@myaccount.com');
+```
+
+The `profile` column in `credentials` table should contain JSON data in the same format as it is used in JSON Handler.
+
+Example:
+
+```sql
+INSERT INTO credentials (account_id, key_id, description, profile, status)
+  VALUES (
+    (SELECT id FROM account WHERE account.name = 'myaccount'),
+	'keyid_03',
+	'mykey',
+	'{
+    	"hmac": "YW5kX2ZpbmFsbHlfdGhlX2xhc3RfaG1hY19rZXlfd2hpY2hfaXNfbG9uZ2VyX3RoYW5fMjU2X2JpdHNfYW5kX3Nob3VsZF93b3Jr",
+    	"authorization": {
+      		"prevalidated_domainlist": ["www.example.com"]
+    	}
+  	}',
+    1
+  );
+```
+
+<a id="Activate"></a>
+
+### Activate Handler
+
+To activate this handler, configure the `EABhandler` section in `acme_srv.cfg` as follows. For `db_system`, enter either `mssql` or `postgres`.
+
+```ini
+[EABhandler]
+eab_profiling: True
+eab_handler_file: examples/eab_handler/sql_handler.py
+db_system: mssql, postgres
+db_host:
+db_name:
+db_user:
+db_password:
+```
+
 ## Keyfile Verification
 
 To check the consistency of the keyfile, use the `tools/eab_chk.py` utility:

diff --git a/docs/external_database_support.md b/docs/external_database_support.md
@@ -66,6 +66,35 @@ GRANT postgres TO acme2certifier;
 sudo apt-get install python3-django python3-psycopg2
 ```
 
+### When using SQL Server (Experimental)
+
+_SQL Server support is experimental, and is not tested in release regression like the other two databases._
+
+Note that this part of the guide is written for **Red Hat Enterprise Linux 9**.
+
+It is assumed that SQL Server is already installed and running.
+
+Open SQL Server Management Studio.
+
+- Create the acme2certifier database and database user:
+
+```SQL
+CREATE DATABASE acme2certifier;
+CREATE LOGIN acme2certifier WITH PASSWORD = 'a2c+passwd';
+CREATE USER acme2certifier FOR LOGIN acme2certifier;
+```
+
+- From Object Explorer, open acme2certifier, Security, Logins, acme2certifier Properties. Then, from User Mapping, map the user to the database and give necessary roles. From Server Roles, give public and sysadmin roles. In essence, grant all access to the database for the acme2certifier user.
+
+- Install missing python modules
+
+```bash
+pip install mssql-django pyodbc
+sudo dnf install unixODBC
+```
+
+- Follow [these instructions](https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server?view=sql-server-ver15&tabs=redhat18-install%2Credhat17-install%2Cdebian8-install%2Credhat7-13-install%2Crhel7-offline#17) to install Microsoft ODBC 17.
+
 ## Install and Configure acme2certifier
 
 - Download the [latest deb package](https://github.com/grindsa/acme2certifier/releases)
@@ -166,6 +195,28 @@ DATABASES = {
 }
 ```
 
+### Connecting to SQL Server
+
+- Modify `/var/www/acme2certifier/acme2certifier/settings.py` and configure your database connection as below:
+
+```python
+DATABASES = {
+    "default": {
+        "ENGINE": "mssql",
+        "NAME": "acme2certifier",
+        "USER": "acme2certifier",
+        "PASSWORD": "a2c+passwd",
+        "HOST": "sqlserverdbsrv,1433",
+        "PORT": "",
+        "OPTIONS": {
+            "driver": "ODBC Driver 17 for SQL Server"
+        },
+    }
+}
+```
+
+- You may also need to disable some SELinux settings for Apache, depending on your server configuration.
+
 ## Finalize acme2cerifier configuration
 
 - Create a Django migration set, apply the migrations, and load fixtures: Modify the [configuration file](acme_srv.md) `/var/www/acme2certifier/volume/acme_srv.cfg`according to your needs. If your CA handler needs runtime information (configuration files, keys, certificate bundles, etc.) to be shared between the nodes, ensure they are loaded from `/var/www/acme2certifier/volume`. Below is an example for the `[CAhandler]` section of the openssl-handler I use during my tests: