We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • WHM API 1 Functions - enable_dnssec_for_domains
Skip to end of metadata
Go to start of metadata

Description

This function enables DNSSEC on the domain.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.


Note:

  • After you enable DNSSEC on the domain, you must add the Delegation of Signing (DS) records on your DNS server and with your registrar.
  • You cannot modify the DNSSEC security key. To make any changes, you must disable, delete, and re-create the DNSSEC security key.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/enable_dnssec_for_domains?api.version=1&domain=example.com
 Command Line
whmapi1 enable_dnssec_for_domains domain=example.com


Notes:

  • Unless otherwise noted, you must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{
   "metadata":{
      "command":"enable_dnssec_for_domains",
      "version":1,
      "result":1,
      "reason":"OK"
   },
   "data":{
      "domains":[
         {
            "enabled":1,
            "domain":"example.com",
            "nsec_version":"NSEC3",
            "new_key_id":"2"
         }
      ]
   }
}


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

Required

The domain for which to enable DNSSEC.

Note:

To enable DNSSEC on multiple domains, duplicate or increment the parameter name. For example, to check three domains, you could:

  • Use the domain parameter multiple times.
  • Use the domaindomain-1, and domain-2 parameters.
A valid domain.example.com
activeBoolean

Whether to activate the newly-created key.

This parameter defaults to 1.

  • 1 — Activate the key.
  • 0 — Do not activate the key.
1
algo_numinteger

The algorithm that the system uses to generate the security key.

This parameter defaults to 8.

  • 5  — RSA/SHA-1
  • 6  — DSA-NSEC3-SHA1
  • 7  — RSASHA1-NSEC3-SHA1
  • 8  — RSA/SHA-256
  • 10  — RSA/SHA-512
  • 13  — ECDSA Curve P-256 with SHA-256
  • 14  — ECDSA Curve P-384 with SHA-384

Note:

We recommend that you use an ECDSA Curve P-256 with SHA-256 (13) value if your registrar supports it.

8
key_setupstring

The manner in which the system creates the security key.

This parameter defaults to classic.

  • classic — Use separate keys for KSK and ZSK. Use this value when the algo_num parameter is equal to or less than 8.
  • simple — Use a single key for both KSK and ZSK. Use this value when the algo_num parameter is greater than 8.
2
use_nsec3Boolean

Whether the domain will use Next Secure Record (NSEC) or NSEC3 semantics.

This value defaults to 1.

  • 1 — Use NSEC3 semantics.
  • 0 — Use NSEC semantics.

    Note:

    If you use this value, the system ignores the other NSEC3 options.

1
nsec3_iterationsinteger

The number of times that the system rehashes the first resource record hash operation.

This value defaults to 7.

A positive integer less than 501.7
nsec3_narrowBoolean

Whether NSEC3 operates in Narrow or Inclusive mode.

Note:

For information about these modes, read  PowerDNS's DNSSEC documentation.

This value defaults to 1.

  • 1 — Narrow mode.
  • 0 — Inclusive mode.
1
nsec3_opt_outBoolean

Whether the system will create records for all delegations.

This value defaults to 0.

  • 1 — Create records for all delegations.

    Note:

    Only use this value if you must create records for all delegations.

  • 0 — Create records only for secure delegations.

1
nsec3_saltstring

A hexadecimal string that the system appends to the domain name before it applies the hash function to the name.

Note:

For information about salt values, read RFC 5155.

This value defaults to a random 64-bit value.

A hexadecimal string.1a2b3c4d5e6f

Returns

ReturnTypeDescriptionPossible valuesExample
domainsarray of hashesAn array of hashes that contains information about each domain.Each hash contains the domainenablederrornsec_version, and new_key_id returns.

domain

string

The domain for which the system enabled DNSSEC.

The function returns this value in the domains hash.

A valid domain.example.com

enabled

Boolean

Whether the system enabled DNSSEC.

The function returns this value in the domains hash.

  • 1 — Enabled.
  • 0 — The system failed to enable DNSSEC.

    Note:

    This function will not return the nsec_version and new_key_id returns if this return is a 0 value.

1

nsec_error

string

The domain has a NSEC3 configuration error.

Note:

The function only displays this return if there is a NSEC3 configuration error.

The function returns this value in the domains hash.

An error message.Error message.

nsec_version

string

The version of DNSSEC the system used.

The function returns this value in the domains hash.

  • NSEC3
  • NSEC

    Note:

    The function only displays this return if there is a NSEC3 configuration error. The system also returns the error in the nsec_error return.

NSEC3

new_key_id

string

The assigned security key ID.

The function returns this value in the domains hash.

A valid ID.2