security/acme-client: Add custom DNS API script support

[NormB]

Summary

This PR adds support for custom acme.sh DNS API scripts in the ACME Client plugin, enabling users to integrate with DNS providers not already supported by the plugin.

Features:

• New "Custom DNS API Script" option in the DNS Service dropdown
• Configuration fields for specifying custom script name and up to 4 environment variables
• DnsCustom.php validation class to handle custom DNS script integration
• Example scripts in contrib/examples/ directory

Compliance

This PR follows OPNsense development guidelines:

• PHP code follows PSR-12 coding standard
• 2-Clause BSD license on all new files
• Code style matches existing ACME Client plugin patterns
• Based on latest master branch

Maintainer Commitment

I am committed to maintaining this feature and will respond to user feedback and QA issues.

Use Case

This feature is particularly useful for:

• Organizations using internal/private DNS servers
• DNS providers with custom APIs not yet supported by acme.sh
• Split-horizon DNS setups requiring custom automation
• Any custom DNS management scenario

---

Example Scripts Included

This PR includes ready-to-use example scripts in security/acme-client/contrib/examples/:

Script	Description
dns_myinternal.sh	SSH-based script for internal BIND DNS servers using nsupdate
dns_myapi.sh	Template for HTTP/REST-based DNS provider APIs
README.md	Installation and customization documentation

---

Installation & Usage

Step 1: Deploy an Example Script

Copy the example script to OPNsense:

scp dns_myinternal.sh root@opnsense:/usr/local/share/examples/acme.sh/dnsapi/
ssh root@opnsense "chmod 644 /usr/local/share/examples/acme.sh/dnsapi/dns_myinternal.sh"

Step 2: Configure the ACME Plugin

1. Navigate to Services > ACME Client > Challenge Types
2. Click Add to create a new challenge type
3. Configure:
   • Challenge Type: DNS-01
   • DNS Service: Custom DNS API Script
   • Script Name: dns_myinternal or myinternal
   • Environment Variables: Set required variables (e.g., DNS_SERVER_HOST, DNS_SERVER_USER)
4. Save the challenge type

Step 3: Create Certificate

1. Navigate to Services > ACME Client > Certificates
2. Click Add and select your custom challenge type
3. Save and issue the certificate

---

Creating Custom Scripts

Custom scripts must implement two functions:

dns_SCRIPTNAME_add() {
  fulldomain=$1    # e.g., _acme-challenge.example.com
  txtvalue=$2      # The ACME challenge token
  return 0         # Return 0 on success
}

dns_SCRIPTNAME_rm() {
  fulldomain=$1
  txtvalue=$2
  return 0
}

Scripts can use acme.sh helper functions: _info, _debug, _err for logging.

---

Test Plan

• DnsCustom.php validation class created
• Model fields added for script name and environment variables
• Form UI fields added
• Example scripts with BSD license headers
• PSR-12 coding standards applied
• Tested certificate issuance through plugin UI
• Review by maintainers

Files Changed

New files:

• security/acme-client/src/opnsense/mvc/app/library/OPNsense/AcmeClient/LeValidation/DnsCustom.php
• security/acme-client/contrib/examples/dns_myinternal.sh
• security/acme-client/contrib/examples/dns_myapi.sh
• security/acme-client/contrib/examples/README.md

Modified files:

• security/acme-client/src/opnsense/mvc/app/models/OPNsense/AcmeClient/AcmeClient.xml
• security/acme-client/src/opnsense/mvc/app/controllers/OPNsense/AcmeClient/forms/dialogValidation.xml
• security/acme-client/pkg-descr

---

🤖 Generated with Claude Code

[fraenki]

The ACME plugin only integrates DNS providers that are already supported by acme.sh. If you think that this "custom DNS API script" is useful, please submit a PR to acme.sh (and maybe specify some unsupported APIs that should work when using this script). If they add it, then we may include it in the ACME plugin.

That being said, I think this approach is flawed. The dns_myapi.sh script makes a lot assumptions about the DNS API, e.g. the URLs, request payload, etc. So in reality this is not a generic approach to add support for arbitrary DNS APIs, but will only work on a verify specific DNS API.

[NormB]

Thanks for taking a look at this contribution. For us, it solves the problem related to LetsEncrypt certificates and internal split-horizon DNS servers behind an Opnsense server.