DNSSEC

    Enable DNSSEC and manage cryptographic keys for your zones.

    Overview

    DNSSEC (Domain Name System Security Extensions) adds cryptographic signatures to DNS records, protecting against spoofing and cache poisoning attacks.

    Required scopes: dnssec:read, dnssec:write

    Endpoints

    MethodEndpointDescription
    GET/v1/zones/{zone_id}/dnssec/statusGet DNSSEC status
    PATCH/v1/zones/{zone_id}/dnssec/statusEnable/disable DNSSEC
    GET/v1/zones/{zone_id}/dnssec/cryptokeysList cryptographic keys
    POST/v1/zones/{zone_id}/dnssec/cryptokeysCreate a new key
    GET/v1/zones/{zone_id}/dnssec/cryptokeys/{key_id}Get key details
    PUT/v1/zones/{zone_id}/dnssec/cryptokeys/{key_id}Update a key
    DELETE/v1/zones/{zone_id}/dnssec/cryptokeys/{key_id}Delete a key
    GET/v1/zones/{zone_id}/dnssec/dsGet DS records

    Get DNSSEC Status

    Check if DNSSEC is enabled for a zone:

    curl https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/status \
  -H "Authorization: Bearer YOUR_API_KEY"

    Response:

    {
  "status": "success",
  "data": {
    "enabled": true,
    "nsec3": false,
    "keys": {
      "ksk": 1,
      "zsk": 1
    }
  }
}

    Enable DNSSEC

    Enable DNSSEC for a zone:

    curl -X PATCH https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

    Enabling DNSSEC automatically generates the necessary cryptographic keys (KSK and ZSK). The operation is asynchronous—poll the status endpoint to detect when keys are ready.

    Disable DNSSEC

    curl -X PATCH https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
    Disabling DNSSEC

    Before disabling DNSSEC, remove the DS records from your registrar to avoid validation failures.

    List Cryptographic Keys

    curl https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/cryptokeys \
  -H "Authorization: Bearer YOUR_API_KEY"

    Response:

    {
  "status": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "type": "ksk",
        "active": true,
        "algorithm": "ECDSAP256SHA256",
        "bits": 256,
        "dnskey": "257 3 13 base64...",
        "ds": [
          "12345 13 2 hex..."
        ],
        "created_at": "2025-01-15T10:30:00Z"
      },
      {
        "id": 2,
        "type": "zsk",
        "active": true,
        "algorithm": "ECDSAP256SHA256",
        "bits": 256,
        "dnskey": "256 3 13 base64...",
        "created_at": "2025-01-15T10:30:00Z"
      }
    ]
  }
}

    Get a Specific Key

    curl https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/cryptokeys/{key_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

    Create a New Key

    curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/cryptokeys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keytype": "ksk",
    "active": true,
    "algorithm": "ECDSAP256SHA256"
  }'

    Request Body:

    FieldTypeRequiredDescription
    keytypestringYesKey type: ksk or zsk
    activebooleanNoWhether key is active (default: true)
    algorithmstringNoAlgorithm (default: ECDSAP256SHA256)

    Supported Algorithms:

    AlgorithmDescription
    ECDSAP256SHA256ECDSA P-256 with SHA-256 (recommended)
    ECDSAP384SHA384ECDSA P-384 with SHA-384
    RSASHA256RSA with SHA-256
    ED25519Edwards-curve DSA

    Update a Key

    Activate or deactivate a key:

    curl -X PUT https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/cryptokeys/{key_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

    Delete a Key

    curl -X DELETE https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/cryptokeys/{key_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
    Key Deletion

    Deleting an active key may break DNSSEC validation. Ensure you have valid KSK and ZSK keys before removing any.

    Get DS Records

    Retrieve DS (Delegation Signer) records to submit to your domain registrar:

    curl https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/ds \
  -H "Authorization: Bearer YOUR_API_KEY"

    Response:

    {
  "status": "success",
  "data": {
    "zone": "example.com",
    "ds_records": [
      {
        "key_tag": 12345,
        "algorithm": 13,
        "digest_type": 2,
        "digest": "abc123def456...",
        "record": "example.com. IN DS 12345 13 2 abc123def456..."
      }
    ]
  }
}

    DNSSEC Setup Workflow

    1. Enable DNSSEC

    curl -X PATCH https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

    2. Wait for Key Generation

    Poll the status until keys are ready:

    curl https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/status \
  -H "Authorization: Bearer YOUR_API_KEY"

    3. Get DS Records

    curl https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/ds \
  -H "Authorization: Bearer YOUR_API_KEY"

    4. Add DS to Registrar

    Submit the DS records to your domain registrar. The process varies by registrar:

    • Cloudflare Registrar: Domain → DNS → DNSSEC → Enable
    • Namecheap: Domain List → Manage → Advanced DNS → DNSSEC
    • GoDaddy: My Products → DNS → DNSSEC → Add DS Record

    5. Verify DNSSEC

    Test your DNSSEC configuration:

    dig +dnssec example.com
 
# Or use online tools:
# - https://dnssec-analyzer.verisignlabs.com/
# - https://dnsviz.net/

    Key Rotation

    For enhanced security, rotate your ZSK periodically:

    # 1. Create new ZSK
curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/cryptokeys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keytype": "zsk", "active": true}'
 
# 2. Wait for propagation (24-48 hours)
 
# 3. Deactivate old ZSK
curl -X PUT https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/cryptokeys/{old_key_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'
 
# 4. Delete old ZSK after TTL expiry
curl -X DELETE https://api.dnscale.eu/v1/zones/{zone_id}/dnssec/cryptokeys/{old_key_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

    Related Documentation