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
  • UAPI Functions - DNSSEC::fetch_ds_records
Skip to end of metadata
Go to start of metadata

Description

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

Important:

In cPanel & WHM version 76 and later, when you disable the DNS role, the system disables this function.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/DNSSEC/fetch_ds_records?domain=example.com


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.

// Fetch DS records.
$sa_settings = $cpanel->uapi(
    'DNSSEC', 'fetch_ds_records',
    array(
        'domain' => 'example.com',
    )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# Fetch DS records.
my $sa_settings = $cpliveapi->uapi(
    'DNSSEC', 'fetch_ds_records',
    {
        'domain' => 'example.com',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=username DNSSEC fetch_ds_records domain=example.com 


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
	"result": {
		"status": 1,
		"metadata": {},
		"messages": null,
		"data": {
			"example.com": {
				"keys": {
					"33930": {
						"flags": 256,
						"key_type": "ZSK",
						"key_tag": 33930,
						"algo_num": "8",
						"created": "1590002705",
						"privatekey": "Private-key-format: v1.2\nAlgorithm: 8 (RSASHA256)\nModulus: wcZl882v587qKmt3M7+y6u+kzSgCvfgyiSGQHE2EulDcAnfEmz/ryanXMveHGBsO4L/GynYYUUsGvD2jHK1ITh8CeISiqmbUmPolf9HLQgwcT5pVcvwJ0Wmzpw5Ukmx67N7TTX+yieI5OyflP23GnJYQ5EQUzBu/DhdxhL90hYU=\nPublicExponent: AQAB\nPrivateExponent: EnoBdKrTMA5Jw7u1hQitXbt2Al3jTQvifbLmk9xMYJufLtkOtSL2L6dzLpftmL3TwFho8xspnG7D+KUD7ZMURrwxnLlqTttaL2PeaYJdQ184ezuflExppkDkdTEOqcIUuSylfAbyIdeGkVFuWr0cdjM9OFKMAkoYaVeAUP0SYU0=\nPrime1: 4eslxBBwyvXzmFqKx5TTiHfU7EHIAxUru3ykOMqD2tVMHbRAq5AMKZL6ZhuTXk8mnGppEfC6qqNKnf3VT5jLxw==\nPrime2: 25OUAsWWAJrQ4uLytsXoSbjHsVyh61DgZ4S4n2Mv7RsSHt0Q/VcuyvHXuAKb8Y0XCYczZBtEW+ZoPte/HHnsUw==\nExponent1: Xkb4AqLtvvT2i8y0/2avA9MmCtXEtuydzGbOTVjNv4OlePvgxPee67aHQhcd34xeS4XohPEVpOHx4I6t9sKHvw==\nExponent2: ulZDBRcodNrs6Z4u22yX8/gbfyhdQJUh2reG9bv2sAB/wEJaaKPT0eXqav3L2PKfCjbyJcH+AP9G+A2e4UuWgQ==\nCoefficient: mynNLSgStpQMktIEdysefyOg5jpXE3VeDZF6fbEOUg+E2ZnLBkLu4KPrriCwfl+cLagwgzx2M6wV/1QWkm8vPQ==\n",
						"algo_tag": "RSASHA256",
						"algo_desc": "RSA/SHA-256",
						"active": 1,
						"bits": 1024,
						"key_id": 2
					},
					"51640": {
						"key_type": "KSK",
						"flags": 257,
						"privatekey": "Private-key-format: v1.2\nAlgorithm: 8 (RSASHA256)\nModulus: 4U681HsGhJDeP9XS8aTQpj9EZYkBIpWtelBIlDgRGwovoL9vackDXdMjjoQbgvDqbZB9+Ts2vOBFTmAAJpN7aea8yGgVF9QKWO/S2kqRacHAPpQxN2IJZH6vE0foFPsAoZ3nQHMCC7AcgE8QaGKx15tkPKkKIrpFFJekL9QeQ6MmkBBbHXmN2SGBdc6WSITJl2aLfyc3a0kSuE5ZA9VlPN9Iult3XUj14jLEm3LVjz8suPBlBDhLslpiaXPkA3F3nrK3uZC6Wdk6lXKlRJIeP2u1BVOc0kNk/Uk+rButi+4F5SPthYWmfoo4M0PBhO8NrO7uegBefOLTjf4SSiO/Lw==\nPublicExponent: AQAB\nPrivateExponent: AcqHc8T6m0kviyBfCe6+fePY3lnFeYnpFCTZPtxnPmjJUiTTdOrVLQTFrpdcRKE3q+FPLxEKcVvzERlwRt47R+8+pvU03big0G4vpe6b01Rn+9dfwMn1uyfKqoOS07/fFGnV8cw4QvGGeHqobbwDH+yrUlQhsX77l5tRAdRU3ULF9Qd/UDO6deRjz6XxkqVWmhlBIrI/929XFhBS4C1tXRaBGYWs7ACfhpjMgC3A/KcTDgZsqVVTColfhudd0OOS4K4L7DpFjE/Z126JzmrF6VAXWSvlHN2TELqpjVoTEyR0WKzp9MytA6bEpR4cglKDkdzaDxCCpmObfE6DRyisCQ==\nPrime1: 9DTyme6sXIEJ673sE1k7rJrohpmEn/XULLi09DNAwMjkkc+56V5fOjJAS5mZn4iBjzSx3o/AVnFaj63tsbWFpFGvFNLMIQiDO7LqdkoqXnKZzHYAeEZsXZaS7gRhU/ulWhh/admbmTCmSqTxxN8t3KjMyCBPA8KEtXWukA8K8+U=\nPrime2: 7DAk9OxydNjnFfH8cfBP3twiBOvVXh/PDZmviO3p36ejKRZRvFeU8Y9bk41FOr1/WyI6Qch/osX0fZc3OYyvx2IuFrpzJJP3FlTVNeEPokatOQOogA6yNe52TLeijghoXpdyk4k1Umzz/00Wtyb4xLs0Xmgna/mgg1ugyaPIHYM=\nExponent1: kauHz2S8sg1TEqleygfffc2FyMyIfTaRkv+3CTgNdzIejg/gMSHXIgrZqX79UVmHFxpyw3TyYV4KjExOzkOebW9AReacV1QRnCnUjC0faulnbrww+Y3glE7+ZDZ+rC8e6khUsJpao52OhFYx1aLfY5HZXcNP/skoimmhcFNY0DU=\nExponent2: SmjUi9EeMg/PpctJ8/94ukZx9UjzPKcazTcY5TPHFa4zqgP9xi91f3N9r1u3bs0anXSIFAd9pqNk5lhIjrny+wbEbGarNd/j3UY2sbXI/h/0HN05LbbzkCgjXwIPlV2yu/JMp4x3nxMyP8FioasGfrxXwFJh8ROA7UFlw4D0388=\nCoefficient: npSSANCvHSy0t/2NcOUNj96DOOHRDKQsoPQjI5aYCn7Ee3TnA8aIRE3X/0uyAUlX3zivr8ymadN3injYwWB7lSYjT02aBacjPl5Od792A5jB9ScK5LPxQFHAArv5nSHhNcnlYS/J5447cmN2W2hG1VW1JNaSjV5x5DMw4SketvM=\n",
						"digests": [{
								"digest": "cbb1b5f32dbaf69a147302fee126535e68b2255a",
								"algo_num": "1",
								"algo_desc": "SHA-1"
							},
							{
								"algo_desc": "SHA-256",
								"algo_num": "2",
								"digest": "942f1c53405ea8fd64ec51c3de73f970417d9fde7ab2db973132a3b57c76aa59"
							},
							{
								"algo_desc": "SHA-384",
								"algo_num": "4",
								"digest": "34ceaa687b68d0714cea6d07e34c8c9240b2d8069f4852e7212be3a62b814bf2b0d77d29b6487b3d00f479bd96848359"
							}
						],
						"key_tag": 51640,
						"active": 0,
						"algo_desc": "RSA/SHA-256",
						"algo_tag": "RSASHA256",
						"created": "1590002997",
						"key_id": 3,
						"algo_num": "8",
						"bits": 2048
					},
					"34519": {
						"key_id": 1,
						"bits": 2048,
						"active": 1,
						"algo_desc": "RSA/SHA-256",
						"algo_tag": "RSASHA256",
						"privatekey": "Private-key-format: v1.2\nAlgorithm: 8 (RSASHA256)\nModulus: 7WRqsuWY6H4iXz2cfxuhHF8N5uQgCrd4uRATApqvdR8yTqUx2g4yLckvu30N+kaOgA18MNvafjALd8YKO17xE/T5vFgQJxEFIGS0zV/pnHjmQI9BIIWEHX4m9FXrvTMdye+CyGeujudOFuU3ZWeBRpDQJ6SyJgTVn3zZuwH6WmEMluR7KpKZDD2SkB5jqkVQiwZRkkycvQuRlokjhHnOiyC5XNvsZUyib4Ac2RJZ5tDPiCkfMGk9Ya1xPr+XXPEw4TeolGWk9GczYxRTUHe+3DDrMI2a/f/chNu2fOhWZzqLQ21g+uOEF/zNzMFAU2mA9wI026WcrZzqupHKLNqdvQ==\nPublicExponent: AQAB\nPrivateExponent: AeFEswv8bQLqtMRhI+SNHxNlocl2s36rPhrxe5jMAOpxVIwcW/S20wP/28U+whei80KoFB75mPw6awVneVbkI9tRyvsLjbOlzb7ea63xxKp0cFhyFJbaF/2yw0aW6lWoS7wY1gt0J2+Pf8Dq8mOic3OcImQ8gO6S3oN3mfKHEAYm0stpgbVC8uB4D9CIECuZ2MozQA7eom/HMr1hf5QA45PlampUgFWkzwKsUsGVXi1EZvJYkURCChrhgmahIEHmTNe4CmfKWzamuglCDEGfj8BsPyi+0ami/V1ZOMo4ldq+mj01l7DxcfJZ/yfEiMUGhXmCVI6Z1p38RKkAgD0JhQ==\nPrime1: 98UnToyntwccdrlODbsYQjH0yMVQMuisUbuCtXbR+DfCTQ7dpI3arhZ9TW+elHAYs5ImqKAheiX9qQZCyKuUU4oZJuSz4GPEttlTyqqyXfw0JzlC9EWbd5opiCqyWJmKRqvxs57f/CgPUMfkVEBMC/hUq3KjanLcVB8EWu/WTos=\nPrime2: 9UcEjD/R5WeTFMstIM9HrvTqDdo+qU79RYTps/2vf7gZXtVFWcOksHLqed3oHl48gnPqCj0Bkbp+J0e1w+WiociPBs3dyQCZoyqPqPLhlXfrAlKMQ94l7BF/FhVSakhYvHYI1N52ZHojxkOfaxHaOwmDtMi79XOQTkYV/K8v1dc=\nExponent1: wBXgu0zgWUzyDDjtAkgiLm98Topp+o3XyiWM2Crs7XqM8CCuRHyVJJHa4sW+M2YUQGL2BZTfX0tEtF1eOSSMAZf2l+iGa1ftkbQ6+cwMLEDyTdZeyfGM7dRejmpLidS/FrsGzzJFAjfkZ8QQiCCw1DbZrXFar5QMrEq/naCCjLE=\nExponent2: BnHZQr4ii76O9Mrp4qTPo184Dyke4F/886isY1hVFiwGLqG38sXbO++pDY6xHKspN9xH2AEGW4fk7K9LrVwJS+rzJyCdpTxozQq/P5cyKjU+bY8xtE7P/EXxaukggz5nZnxLexxlRUCYVAtO0wdjDo4Pcd6cYbSppATfawZHYX0=\nCoefficient: CbIm0VYv1y3fSJ4jXCw7ynagC7YkHiT8CLiUAWKMSpht0m9KTyEp7VMwmSR+4Xtt6F6qP/w/cX/DsExZxjHgaFCfSz6efBn43x/RwwE0whSe3erW8c+kF5bUleE4ucEqdvwN3nNSaYo1rG4VvwDCjdPxINd5EHTt033DED7gme8=\n",
						"created": "1590002705",
						"algo_num": "8",
						"digests": [{
								"algo_num": "1",
								"digest": "62089f11d58f07f99d64e4d8da266563fed60896",
								"algo_desc": "SHA-1"
							},
							{
								"algo_num": "2",
								"digest": "4de3e58f1238fb7fc7caa84389ef6fa27d42572c35f1152c7f2ea3b899400019",
								"algo_desc": "SHA-256"
							},
							{
								"digest": "eff0ebcdb244bfe692a4192cc44e3845115d6ba49f21aecc97f0e75257563f41d074bd7ee645bcf6bd8b79e14a13b25e",
								"algo_num": "4",
								"algo_desc": "SHA-384"
							}
						],
						"key_tag": 34519,
						"key_type": "KSK",
						"flags": 257
					}
				},
				"nsec_details": {
					"nsec3_hash_algo_desc": "SHA-1",
					"nsec3_opt_out": "0",
					"nsec3_narrow": 1,
					"nsec3_iterations": "3",
					"nsec3_salt": "fa1ac2c1rd7fbab4",
					"nsec_version": "NSEC3",
					"nsec3_hash_algo_num": "1"
				}
			}
		},
		"errors": null,
		"warnings": null
	},
	"func": "fetch_ds_records",
	"apiversion": 3,
	"module": "DNSSEC"
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

Required.

The domain from which to fetch DS records.

Note:

To fetch DS records from multiple domains, increment the parameter name. For example: domain-0, domain-1, domain-2.

A valid domain.example.com

Returns

Return

TypeDescriptionPossible valuesExample

DOMAIN

hash of hashes


A hash of the domain's DS record information.

Note:

The return's name is the domain's name.

Each hash includes the nsec_details and keys hashes.


nsec_details

hash

A hash of the Next Secure Record (NSEC) information for the selected domain.

Note:

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

The function returns this hash in the domain hash.

Each hash includes the nsec_version, nsec3_hash, algo_desc, nsec3_hash_algo_num, nsec3_iterations, nsec3_narrow, nsec3_opt_out, and nsec3_salt returns.

nsec_version

string

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

The function returns this value in the nsec_details hash.

  • NSEC
  • NSEC3
NSEC

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

nsec3_hash_algo_num

integer

The DNSSEC 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.12

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.
1

nsec3_salt

string

The salt value that PowerDNS uses in the hashes.

Note:

For more information about the salt value, read RFC 5155.

The function returns this value in the nsec_details hash.

A hexadecimal string.fa1ac2c1rd7fbab4

keys

hash of hashes

A hash of the DS keys on the requested domain.

The function returns this hash in the domain 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 key_tag return's integer value.

The function returns this hash in the KEYNAME hash.

Each hash includes the activealgo_desc, algo_num, algo_tag, bits, created, flagskey_idkey_typekey_tag returns and the digests array of hashes.

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 algorithm the system generated for the security key.

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.

Note:

We added this return in cPanel & WHM version 86.

The function returns this value in the KEYNAME hash.

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

digests

array of hashes

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

The function returns this array in the KEYNAME hash.

Each array includes the algo_desc, algo_num, and digest returns.

algo_desc

string

A description of the algorithm that the DS key uses.

The function returns this value in the digests hash.

A valid algorithm. SHA-256

algo_num

integer

The IETF-recognized DNSSEC Algorithm Number.

The function returns this value in the digests hash.

A positive integer.2

digest

string

The actual digest in the DS record.

The function returns this value in the digests hash.

A valid string.

4de3e58f1238fb7fc7caa84389ef6fa27d42572c35f1152c7f2ea3b899400019

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

integer

PowerDNS's internal identifier.

The function returns this value in the KEYNAME hash.

A positive integer.1

key_tag

integer

The DS key's identification number.

The function returns this value in the KEYNAME hash.

A positive integer.

34519

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

privatekey

string

The DS key's private key.

Note:

We added this return in cPanel & WHM version 86.

The function returns this value in the KEYNAME hash.

A private key, in ISC format.
 Click to view...
Private-key-format: v1.2\nAlgorithm: 8 (RSASHA256)\nModulus: 7WRqsuWY6H4iXz2cfxuhHF8N5uQgCrd4uRATApqvdR8yTqUx2g4yLckvu30N+kaOgA18MNvafjALd8YKO17xE/T5vFgQJxEFIGS0zV/pnHjmQI9BIIWEHX4m9FXrvTMdye+CyGeujudOFuU3ZWeBRpDQJ6SyJgTVn3zZuwH6WmEMluR7KpKZDD2SkB5jqkVQiwZRkkycvQuRlokjhHnOiyC5XNvsZUyib4Ac2RJZ5tDPiCkfMGk9Ya1xPr+XXPEw4TeolGWk9GczYxRTUHe+3DDrMI2a/f/chNu2fOhWZzqLQ21g+uOEF/zNzMFAU2mA9wI026WcrZzqupHKLNqdvQ==\nPublicExponent: AQAB\nPrivateExponent: AeFEswv8bQLqtMRhI+SNHxNlocl2s36rPhrxe5jMAOpxVIwcW/S20wP/28U+whei80KoFB75mPw6awVneVbkI9tRyvsLjbOlzb7ea63xxKp0cFhyFJbaF/2yw0aW6lWoS7wY1gt0J2+Pf8Dq8mOic3OcImQ8gO6S3oN3mfKHEAYm0stpgbVC8uB4D9CIECuZ2MozQA7eom/HMr1hf5QA45PlampUgFWkzwKsUsGVXi1EZvJYkURCChrhgmahIEHmTNe4CmfKWzamuglCDEGfj8BsPyi+0ami/V1ZOMo4ldq+mj01l7DxcfJZ/yfEiMUGhXmCVI6Z1p38RKkAgD0JhQ==\nPrime1: 98UnToyntwccdrlODbsYQjH0yMVQMuisUbuCtXbR+DfCTQ7dpI3arhZ9TW+elHAYs5ImqKAheiX9qQZCyKuUU4oZJuSz4GPEttlTyqqyXfw0JzlC9EWbd5opiCqyWJmKRqvxs57f/CgPUMfkVEBMC/hUq3KjanLcVB8EWu/WTos=\nPrime2: 9UcEjD/R5WeTFMstIM9HrvTqDdo+qU79RYTps/2vf7gZXtVFWcOksHLqed3oHl48gnPqCj0Bkbp+J0e1w+WiociPBs3dyQCZoyqPqPLhlXfrAlKMQ94l7BF/FhVSakhYvHYI1N52ZHojxkOfaxHaOwmDtMi79XOQTkYV/K8v1dc=\nExponent1: wBXgu0zgWUzyDDjtAkgiLm98Topp+o3XyiWM2Crs7XqM8CCuRHyVJJHa4sW+M2YUQGL2BZTfX0tEtF1eOSSMAZf2l+iGa1ftkbQ6+cwMLEDyTdZeyfGM7dRejmpLidS/FrsGzzJFAjfkZ8QQiCCw1DbZrXFar5QMrEq/naCCjLE=\nExponent2: BnHZQr4ii76O9Mrp4qTPo184Dyke4F/886isY1hVFiwGLqG38sXbO++pDY6xHKspN9xH2AEGW4fk7K9LrVwJS+rzJyCdpTxozQq/P5cyKjU+bY8xtE7P/EXxaukggz5nZnxLexxlRUCYVAtO0wdjDo4Pcd6cYbSppATfawZHYX0=\nCoefficient: CbIm0VYv1y3fSJ4jXCw7ynagC7YkHiT8CLiUAWKMSpht0m9KTyEp7VMwmSR+4Xtt6F6qP/w/cX/DsExZxjHgaFCfSz6efBn43x/RwwE0whSe3erW8c+kF5bUleE4ucEqdvwN3nNSaYo1rG4VvwDCjdPxINd5EHTt033DED7gme8=\n