TechnitiumSoftware/DnsServer · warning · ArgumentException

DNS optional protocols TLS certificate password length canno

Error message

DNS optional protocols TLS certificate password length cannot exceed 255 characters.

What it means

Thrown by SetDnsTlsCertificate when the supplied certificate password is longer than 255 characters. The cap mirrors the server's config serialization budget; the password is optional (null is allowed), but if present it must be short.

Source

Thrown at DnsServerCore/Dns/DnsServer.cs:1646

            _doqSslServerAuthenticationOptions = null;
            _dohSslServerAuthenticationOptions = null;

            _dnsTlsCertificatePath = null;
            _dnsTlsCertificatePassword = null;

            StopTlsCertificateUpdateTimer();
        }

        public void SetDnsTlsCertificate(string dnsTlsCertificatePath, string dnsTlsCertificatePassword = null, bool throwException = false)
        {
            if (string.IsNullOrEmpty(dnsTlsCertificatePath))
                throw new ArgumentNullException(nameof(dnsTlsCertificatePath), "DNS optional protocols TLS certificate path cannot be null or empty.");

            if (dnsTlsCertificatePath.Length > 255)
                throw new ArgumentException("DNS optional protocols TLS certificate path length cannot exceed 255 characters.", nameof(dnsTlsCertificatePath));

            if (dnsTlsCertificatePassword?.Length > 255)
                throw new ArgumentException("DNS optional protocols TLS certificate password length cannot exceed 255 characters.", nameof(dnsTlsCertificatePassword));

            dnsTlsCertificatePath = ConvertToAbsolutePath(dnsTlsCertificatePath);

            if (throwException)
            {
                LoadDnsTlsCertificate(dnsTlsCertificatePath, dnsTlsCertificatePassword);
            }
            else
            {
                try
                {
                    LoadDnsTlsCertificate(dnsTlsCertificatePath, dnsTlsCertificatePassword);
                }
                catch (Exception ex)
                {
                    _log.Write("DNS Server encountered an error while loading DNS Server TLS certificate: " + dnsTlsCertificatePath, ex);
                }
            }

View on GitHub (pinned to d0484b6c1e)

Solutions

Use a shorter passphrase (<= 255 chars) when exporting the .pfx.
Double-check the field actually expects the PKCS12 password and not a key or token.
Re-export the .pfx with openssl using a concise password.
Validate password length in your config pipeline before submission.

Example fix

# before: openssl pkcs12 -export ... -password pass:$(cat giant-token.txt)

# after
export PFX_PASS='correct-horse-battery'  # <= 255 chars
openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.pfx -password pass:$PFX_PASS
server.SetDnsTlsCertificate("cert.pfx", PFX_PASS);

Defensive patterns

Strategy: validation

Validate before calling

void EnsureCertPass(string? p)
{
    if (p is not null && p.Length > 255)
        throw new ConfigurationException("TLS cert password must be <= 255 chars");
}

Type guard

static bool IsCertPasswordLengthOk(string? password) => password is null || password.Length <= 255;

Try / catch

try { server.SetDnsTlsCertificate(path, pass); }
catch (ArgumentException ex) when (ex.Message.Contains("password length cannot exceed")) { return BadRequest("Use a shorter PFX password"); }

Prevention

Use concise passphrases when exporting .pfx files.
Confirm the password field is not receiving a key or token.
Validate password length in CI config checks.

When it happens

Trigger: Passing an arbitrarily long string as dnsTlsCertificatePassword (e.g. a full PEM key pasted by mistake, a token, or a passphrase generated by a password manager without a length cap).

Common situations: Operator pastes the private key contents into the password field; an automation pipeline injects an OAuth token instead of the PKCS12 passphrase; password manager configured to generate 256+ char passwords.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

AI-assisted analysis of TechnitiumSoftware/DnsServer@d0484b6c1e (2026-08-13). Data as JSON: /api/errors/f09907f05cb57909. Report an issue: GitHub.