Caddy on demand tls ask over unix socket module

unixask is a Caddy TLS permission plugin that implements tls.permission.unixask.

It lets Caddy's on_demand_tls permission check call a local HTTP endpoint over a Unix domain socket.

Build with xcaddy

From this repository root:

xcaddy build --with https://github.com/moddengine/caddy-tls-unixask

Configure on_demand_tls to use this module

In JSON config, set the permission module inside apps.tls.automation.on_demand using this plugin's module name: tls.permission.unixask.

Example:

{
  "apps": {
    "tls": {
      "automation": {
        "on_demand": {
          "permission": {
            "module": "tls.permission.unixask",
            "socket_path": "/run/unixask/ask.sock",
            "request_path": "/allow"
          }
        }
      }
    },
    "http": {
      "servers": {
        "srv0": {
          "listen": [":443"],
          "routes": [
            {
              "match": [{ "host": ["{host}"] }],
              "handle": [{ "handler": "static_response", "body": "ok" }]
            }
          ]
        }
      }
    }
  }
}

Caddyfile example

This module also supports Caddyfile configuration for on_demand_tls.

{
	on_demand_tls {
		permission unixask {
			socket_path /run/unixask/ask.sock
			request_path /allow
		}
	}
}

:443 {
	respond "ok"
}

In Caddyfile, the permission module name is unixask (short name for tls.permission.unixask).

Field reference

• socket_path: Absolute path to the Unix socket your ask service listens on.
• request_path: HTTP path requested on that service (for example, /allow).

For each certificate request, the plugin sends:

GET http://localhost{request_path}?domain=<requested-domain>

The hostname is ignored (connection is over Unix socket).

Permission behavior

• 200 OK from your ask endpoint: certificate issuance is allowed.
• Any non-200 response: denied.
• Transport/request errors: denied (error returned to Caddy).

Minimal ask service contract

Your Unix-socket HTTP service should:

1. Accept GET requests on request_path
2. Read the domain query param
3. Return:
   • 200 to allow
   • non-200 to deny