How to use the RFC2136 Plugin¶

This plugin works against any DNS provider that supports dynamic updates using the protocol specified in RFC 2136. Both unauthenticated and TSIG authenticated updates are supported.

Setup¶

It is beyond the scope of this guide to explain how to configure your DNS server to accept dynamic updates or generate a TSIG key to use for authentication. But if you're using BIND, the Dynamic Update Policies section of the official docs is a good place to start. There are also a variety of tutorials available with a quick web search.

The plugin does not currently support Kerberos (GSS-TSIG) based updates. You must either use unauthenticated updates with an IP allow list or TSIG authenticated updates using a key type supported by your DNS server and the nsupdate utility. As of this writing, the current stable version of BIND is 9.16.20 and supports key types using the following algorithms:

hmac-md5
hmac-sha1
hmac-sha224
hmac-sha256
hmac-sha384
hmac-sha512

When using a TSIG key, you will typically have 3 values; a key name, a key type from the list above, and a Base64 encoded key value. You will need to supply all three as plugin parameters.

Plugin Dependencies¶

Due to the inexplicable lack of good native DNS libraries within PowerShell/.NET, this plugin relies on the nsupdate utility which is part of the ISC BIND distribution. Most modern Linux distributions will have this installed by default, but double check to be sure. On Windows, you will need to download and install the utility. However, ISC has discontinued support for BIND (and its utilities) Windows since version 9.18. The last official build was 9.17.15 and is still available from their website here, https://downloads.isc.org/isc/bind9/9.17.15/BIND9.17.15.x64.zip. It may also be possible to use the Linux version from Windows via WSL (Windows Subsystem for Linux).

For the Windows version, you don't technically need to run the BIND installer. It is usually sufficient to simply unzip the archive and either add the folder to your PATH environment variable or specify the full path to nsupdate.exe in the plugin arguments. (Adding the folder to your PATH also gives you easy access to the dig utility which many DNS admins prefer over nslookup)

Note

Some users have reported needing to install Visual C++ Redistributable libraries in order for the unzip-and-run method to work. Many systems will already have these installed. But if not, among the files unzipped should be a vcredist_x64.exe installer you can use. You can test by running nsupdate -V to check the version.

Using the Plugin¶

When using unauthenticated updates, there are no required parameters as long as the nameserver in the domain's SOA record can directly accept the dynamic updates. You can optionally supply DDNSNameserver to override the value in returned in the SOA record. There is also a DDNSPort parameter if your nameserver is not listening on the standard port 53, but the parameter is ignored unless DDNSNameserver is also supplied.

When using TSIG authenticated updates, in addition to the previous parameters you must also supply DDNSKeyName, DDNSKeyType, and DDNSKeyValue which is a SecureString object.

Warning

The DDNSKeyValueInsecure parameter is deprecated and will be removed in the next major module version. If you are using it, please migrate to the Secure parameter set.

If the nsupdate utility is not in your PATH environment variable, you must also supply the full path to it using the DDNSExePath parameter.

There is an optional DDNSZone parameter which allows you to specify the zone(s) the records will be added to. But this shouldn't normally be necessary. See issue #307 for more info.

Here are a few examples using different combinations of parameters.

TSIG and explicit nsupdate path¶

$pArgs = @{
    DDNSKeyName = 'mykey'
    DDNSKeyType = 'hmac-sha256'
    DDNSKeyValue = (Read-Host 'TSIG Key Value' -AsSecureString)
    DDNSExePath = 'C:\BIND\nsupdate.exe'
}
New-PACertificate example.com -Plugin RFC2136 -PluginArgs $pArgs

Unauthenticated with nsupdate in PATH and alternate port¶

$pArgs = @{
    DDNSNameserver = 'ns.example.com'
    DDNSPort = 54
}
New-PACertificate example.com -Plugin RFC2136 -PluginArgs $pArgs