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 - fetch_ds_records_for_domains
Skip to end of metadata
Go to start of metadata

Description

This function fetches a domain's Delegation of Signing (DS) record.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/fetch_ds_records_for_domains?api.version=1&domain=example.com
 Command Line
whmapi1 fetch_ds_records_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":"fetch_ds_records_for_domains",
      "version":1,
      "result":1,
      "reason":"OK"
   },
   "data":{
      "domains":[
         {
            "domain":"example.com",
            "ds_records":{
               "nsec_details":{
				  "nsec3_hash_algo_desc":"SHA-1",
				  "nsec3_hash_algo_num":"1",
				  "nsec3_iterations":"7",
				  "nsec3_narrow":"1",
				  "nsec3_opt_out":"0",
				  "nsec3_salt":"1a2b3c4d5e6f",
                  "nsec_version":"NSEC3"
               },
               "keys":{
                  "40481":{
                     "active":1,
                     "algo_desc":"RSA/SHA-256",
                     "algo_num":"8",
                     "algo_tag":"RSASHA256",
                     "bits":"2048",
                     "created":"1575395316",
                     "digests":[
                        {
                           "digest":"2808a14b89118256119d93d24b9e6b673dca092b",
                           "algo_num":"1",
                           "algo_desc":"SHA-1"
                        },
                        {
                           "algo_num":"2",
                           "digest":"02a57812deb952438382ed8dd20f00d4af844a55b5324d28bb",
                           "algo_desc":"SHA-256"
                        },
                        {
                           "algo_desc":"SHA-384",
                           "algo_num":"4",
                           "digest":"4569a6fcfe9e151ec6a163307e67eaa3a9547f16cd80751b0d46eb498bd96743bd4ff7c4f6fd5f76cc780aeb979cd08d",
                     "flags":"257",
                     "key_id":"1",
                     "key_tag":"40481",
                     "key_type":"KSK",
                        }
                     ]
                  }
               }
            }
         }
      ]
   }
}


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
domain

string

Required

The domain to fetch a DS record from.

Note:

To fetch records from 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

Returns

ReturnTypeDescriptionPossible valuesExample
domainshash of hashes

A hash of domains.

Each hash includes the domain and ds_records hashes.
                

domain

string

The domain name.

This function returns this value in the domains hash.

A valid domain.example.com

ds_records

hash of hashes

A hash of the domain's DS records.

Note:

If the domain does not have a DS record, this function returns an empty hash.

This function returns this value in the domains hash.

Each hash includes the nsec_details and keys hash.

nsec_details

hash

A hash of the domain's Next Secure Record (NSEC) information.

Note:

If the domain uses NSEC semantics, only the nsec_version return appears in this hash.

The function returns this value in the ds_records hash.

Each hash includes the nsec_hash_algo_descnsec_hash_algo_numnsec3_iterationsnsec3_narrownsec3_opt_outnsec3_salt, and nsec_version returns.

nsec3_hash_algo_desc

string

A description of the NSEC3 key's algorithm.

The function returns this value in the nsec_details hash.

A valid hashing algorithm.SHA-1

nsec_hash_algo_num

integer

The DNSSEC (Domain Name Security Extensions) Digest Algorithm Number.

The function returns this value in the nsec_details hash.

A positive integer.1

nsec3_iterations

integer

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

The function returns this value in the nsec_details hash.

A positive integer.7

nsec3_narrow

Boolean

Whether NSEC3 will operate in Narrow or Inclusive mode.

Note:

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

The function returns this value in the nsec_details hash.

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

nsec3_opt_out

Boolean

Whether NSEC3 will create records for all delegations or only for secure delegations.

The function returns this value in the nsec_details hash.

  • 1 — Create records for all delegations.
  • 0 — Create records only for secure delegations.
0

nsec3_salt

string

The salt value that PowerDNS uses in the hashes.

Note:

For more information about salt values, read RFC 5155.

The function returns this value in the nsec_details hash.

A hexadecimal string.1a2b3c4d5e6f

nsec_version

string

Whether the domain uses NSEC or NSEC3 (Next Secure Record version 3) DNSSEC semantics.

The function returns this value in the nsec_details hash.

  • NSEC
  • NSEC3
NSEC3

keys

hash of hashes

A hash of the DS keys on the requested domain.

The function returns this value in the ds_records hash.

Each hash includes the KEYNAME hash.

KEYNAME

hash

A hash of information related to the domain's DNSSEC record.

Note:

The return's name is the security key's integer value.

The function returns this value in the keys hash.

Each hash includes the activealgo_descalgo_numalgo_tagbitscreated, and key_tag returns and the digests array of hashes.40481

active

Boolean

Whether the DS key is active.

The function returns this value in the KEYNAME hash.

  • 1 — Active.
  • 0 — Inactive.
1

algo_desc

string

A description of the algorithm that the DS key uses.

The function returns this value in the KEYNAME hash.

A valid algorithm.RSA/SHA-256

algo_num

integer

The Internet Engineering Task Force (IETF)-recognized DNSSEC Digest Algorithm Number.

The function returns this value in the KEYNAME hash.

  • 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
8

algo_tag

string

The short-form reference to the algorithm.

The function returns this value in the KEYNAME hash.

A valid string.RSASHA256

bits

integer

The DS key's size, in bits.

The function returns this value in the KEYNAME hash.

A multiple of 64.2048

created

integer

The key's creation time, in Unix time format.

The function returns this value in the KEYNAME hash.

  • 0 — The creation time is unknown.
  • A valid timestamp, in Unix epoch time.
1575395316

digests

array of hashes

An array of information the registrar uses to populate DS records.

The function returns this value in the KEYNAME hash.

Each array includes the algo_descalgo_num, and digest returns.

algo_desc

string

A description of the algorithm that the DS record uses.

The function returns this value in the digests hash.

A valid string.SHA-1

algo_num

integer

The IETF-recognized DNSSEC Algorithm Number.

The function returns this value in the digests hash.

A positive integer.1

digest

string

The actual digest in the DS record.

The function returns this value in the digests hash.

A valid record.2808a14b89118256119d93d24b9e6b673dca092b

flags

integer

An integer that determines the key_type value.

The function returns this value in the KEYNAME hash.

  • 256 — A Zone Signing Key (ZSK).
  • 257 — A Combined Signing Key (CSK) or Key Signing Key (KSK).
257

key_id

string

PowerDNS's internal identifier.

The function returns this value in the KEYNAME hash.

A positive integer.1

key_tag

integer

The DS key's integer value.

The function returns this value in the KEYNAME hash.

A positive integer.40481

key_type

string

The DS key's signing type.

The function returns this value in the KEYNAME hash.

  • CSK — Combined Signing Key.
  • KSK — Key Signing Key.
  • ZSK   — Zone Signing Key.
KSK