]> ApertoDNS

Italy support@apertodns.com

Operations and Management DNS Operations dynamic dns ddns dns update REST API ACME DNS-01 This document specifies the ApertoDNS Protocol, a modern RESTful protocol for dynamic DNS (DDNS) updates. It provides a secure, provider-agnostic alternative to legacy protocols, with native support for IPv4, IPv6, bulk updates, automatic IP detection, TXT record management for ACME DNS-01 challenges, and standardized authentication mechanisms. The protocol uses well-known URIs (RFC 8615), JSON payloads (RFC 8259), and bearer token authentication (RFC 6750) to enable interoperable dynamic DNS services across different providers.

Introduction Dynamic DNS (DDNS) services allow users with dynamically assigned IP addresses to maintain a consistent hostname that automatically updates when their IP address changes. This capability is essential for home users, small businesses, and IoT devices that need to be reachable despite lacking static IP addresses. While RFC 2136 defines DNS UPDATE for programmatic DNS modifications, most consumer-facing DDNS services use simpler HTTP-based protocols. The de facto standard for consumer DDNS emerged organically without formal specification. This lack of standardization has led to:

• Inconsistent implementations across providers
• Security vulnerabilities from ad-hoc designs
• Limited feature sets (e.g., no native IPv6 support)
• Vendor lock-in due to proprietary extensions
• No formal capability negotiation

This document specifies the ApertoDNS Protocol as a modern, secure, and fully interoperable alternative designed for the current Internet landscape.

Protocol Versioning The protocol version specified in discovery responses (e.g., "1.3.0") refers to the semantic version of the protocol specification itself. This document represents the first IETF standardization of a protocol that has been in production use since 2024. The version number in the discovery endpoint reflects the feature set available, while the Internet-Draft version (e.g., "-02") tracks the IETF document revision process separately.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Goals The ApertoDNS Protocol is designed with the following goals:

• Provider-agnostic: Any DDNS provider can implement this protocol using their own domain and branding
• Secure by default: HTTPS required, bearer token authentication
• Modern: JSON responses, proper HTTP semantics, native IPv6
• Discoverable: Self-describing via discovery endpoint
• Extensible: Capability negotiation allows future enhancements
• Backward compatible: Optional legacy endpoint for existing clients

Terminology This document uses the following terms:

DDNS:

Dynamic DNS. A service that automatically updates DNS records when a client's IP address changes.

Provider:

An organization or service implementing this protocol to offer DDNS services to users.

Hostname:

A fully qualified domain name (FQDN) managed by the provider and associated with a user account.

Token:

An authentication credential issued by the provider, used to authorize API requests.

Auto-detection:

Server-side determination of the client's IP address from the incoming HTTP request, used when the client specifies "auto" as the IP value.

Client:

Software or device that makes requests to a DDNS provider to update DNS records.

A-label:

The ASCII-Compatible Encoding (ACE) form of an Internationalized Domain Name label, as defined in .

TXT Record:

A DNS resource record type used to store arbitrary text data, commonly used for domain verification and ACME DNS-01 challenges.

ACME DNS-01:

A challenge type defined in where domain ownership is proven by provisioning a DNS TXT record.

Protocol Overview The ApertoDNS Protocol is a RESTful API using JSON over HTTPS. All protocol endpoints are located under the well-known URI path /.well-known/apertodns/v1/.

Base URL Conforming implementations MUST serve all endpoints under: The use of well-known URIs ensures consistent endpoint discovery across providers.

Content Type All request and response bodies MUST use the application/json media type unless otherwise specified.

Response Format All responses MUST include a boolean success field at the top level: Or for errors:

Conformance Requirements This section defines the requirements for conforming implementations.

Conformance Levels This protocol defines two conformance levels:

Core Conformance:

A conforming implementation MUST implement the following endpoints: /info, /health, and /update. A conforming implementation MUST support bearer token authentication. A conforming implementation MUST serve all endpoints over HTTPS.

Full Conformance:

In addition to core conformance requirements, a fully conforming implementation MUST implement: /bulk-update, /status/{hostname}, and /domains endpoints.

Capability Advertisement Implementations MUST accurately advertise their capabilities in the /info endpoint response. Implementations MUST NOT advertise capabilities they do not support.

Interoperability Implementations SHOULD accept requests from any conforming client. Implementations MUST NOT require proprietary extensions for basic DDNS functionality.

Authentication

Supported Methods Protected endpoints require authentication via one of the following methods:

1. Bearer Token (RECOMMENDED) : Authorization: Bearer {token}
2. API Key Header: X-API-Key: {token}
3. HTTP Basic (legacy only): Authorization: Basic {credentials}

Implementations MUST support bearer token authentication. Implementations MAY support additional methods.

Token Format Tokens SHOULD follow the format: Where:

• {provider}: Provider identifier (e.g., "apertodns", "example")
• {environment}: Token environment ("live", "test", "sandbox")
• {random}: Cryptographically secure random string (minimum 32 characters recommended)

Example: apertodns_live_Kj8mP2xL9nQ4wR7vY1zA3bC6dE0fG5hI This format enables:

• Easy identification of token source during debugging
• Environment separation (production vs. testing)
• Consistent token handling across providers

Token Transmission Tokens MUST be transmitted only in HTTP headers. Tokens MUST NOT appear in URLs, query parameters, or request bodies where they might be logged.

Authorization Scopes Servers MAY implement scope-based authorization to limit token permissions. When supported, the /info endpoint SHOULD include a scopes_supported array in the authentication object. The following scopes are defined:

Scope	Description
dns:update	Permission to update DNS A/AAAA records
domains:read	Permission to list user's domains
txt:read	Permission to read TXT records
txt:write	Permission to create/update TXT records
txt:delete	Permission to delete TXT records

Tokens with insufficient scope MUST receive a 403 Forbidden response when attempting operations outside their permitted scope.

Endpoints

Discovery Endpoint (/info) The discovery endpoint returns provider information, capabilities, and configuration. This endpoint MUST NOT require authentication.

Response Fields

Field	Type	Required	Description
protocol	string	YES	MUST be "apertodns"
protocol_version	string	YES	Semantic version (e.g., "1.3.0")
provider	object	YES	Provider information
capabilities	object	YES	Supported features
authentication	object	YES	Supported auth methods
endpoints	object	YES	Available endpoint paths
rate_limits	object	NO	Rate limiting configuration
server_time	string	NO	Current server time (ISO 8601)

Capability Fields The capabilities object MUST include the following fields:

Field	Type	Description
ipv4	boolean	IPv4 address updates supported
ipv6	boolean	IPv6 address updates supported
auto_ip_detection	boolean	Automatic IP detection supported
bulk_update	boolean	Bulk update endpoint available
max_bulk_size	integer	Maximum hostnames per bulk request

The capabilities object MAY include the following OPTIONAL fields:

Field	Type	Description
webhooks	boolean	Provider-specific webhook support available
txt_records	boolean	TXT record management supported
txt_max_records	integer	Max TXT records per hostname (5)

When webhooks is true, the provider offers webhook notifications for DNS update events such as IP address changes. The webhook API is implementation-specific and not standardized by this protocol version. Providers offering webhooks SHOULD document their webhook API separately. When txt_records is true, the provider supports TXT record management via the /txt endpoint. This capability enables ACME DNS-01 challenges for automated certificate issuance. The capabilities object MAY include additional fields for future extensions. Unknown capability fields SHOULD be ignored by clients.

Example Response

Health Endpoint (/health) Returns service health status. This endpoint MUST NOT require authentication and SHOULD be used for monitoring.

Example Response The status field MUST be one of: "healthy", "degraded", or "unhealthy".

Update Endpoint (/update) Updates DNS records for a single hostname. This endpoint MUST require authentication.

Request Fields

Field	Type	Required	Description
hostname	string	YES	Fully qualified domain name
ipv4	string	NO	IPv4 address or "auto"
ipv6	string	NO	IPv6 address or "auto"
ttl	integer	NO	Time to live in seconds (60-86400)

At least one of ipv4 or ipv6 SHOULD be provided. If neither is provided, implementations SHOULD use auto-detection for IPv4. The special value "auto" instructs the server to detect the client's IP address from the incoming request.

Auto-Detection Limitations Auto-detection is constrained by HTTP connection semantics: the server can only detect the address family used by the client's TCP connection. This is a fundamental characteristic of HTTP-based protocols, not a limitation specific to this specification. The following constraints apply:

• If the client connects via IPv4: only IPv4 can be auto-detected
• If the client connects via IPv6: only IPv6 can be auto-detected
• Cross-family detection is not possible (e.g., detecting IPv4 address when connected via IPv6)

When a client requests auto-detection for an address family that does not match the connection's address family, the server MUST return an error with the appropriate error code (ipv4_auto_failed or ipv6_auto_failed). Clients requiring dual-stack updates (both IPv4 and IPv6) SHOULD use one of the following approaches:

1. Provide explicit IP addresses for both fields
2. Make separate update requests over each address family
3. Use auto-detection for the matching address family and provide an explicit address for the other

Example Request

Example Response The changed field indicates whether the IP address was actually modified (false if the new IP matches the existing record).

Backward Compatibility For backward compatibility during the transition from legacy field names, servers MAY also include the following deprecated fields in the response:

• ipv4_previous: Alias for previous_ipv4 (deprecated)
• ipv6_previous: Alias for previous_ipv6 (deprecated)

Clients SHOULD use previous_ipv4 and previous_ipv6. The deprecated field names will be removed in a future protocol version.

Auto-Detection Failure Response When auto-detection fails due to address family mismatch:

Record Deletion via Null Values Clients MAY delete specific DNS record types by setting the corresponding field to null in the update request. This enables selective removal of A or AAAA records without affecting other record types. The following semantics apply:

Field Value	Server Action
"203.0.113.1"	Create or update the record
"auto"	Auto-detect and update
null	Delete the record
(field omitted)	No change to existing record

Servers MUST distinguish between an explicit null value (delete request) and an omitted field (no change requested).

Example: Delete IPv6 Record Request to delete the AAAA record while preserving the A record: Response:

Example: Delete IPv4 Record Request to delete the A record: Response: When a record is deleted, the corresponding field in the response MUST be null, and the previous_* field MUST contain the value that was deleted.

Bulk Update Endpoint (/bulk-update) Updates multiple hostnames in a single request. Providers advertising bulk_update: true in capabilities MUST implement this endpoint.

Example Request

Example Response

Status Endpoint (/status/{hostname}) Returns current DNS record status for a hostname.

Example Response

Domains Endpoint (/domains) Returns list of hostnames available to the authenticated user, with their current DNS record status. The response is a flat array of hostname objects containing full details for each entry.

Example Response

TXT Record Endpoint (/txt) The TXT record endpoint enables management of DNS TXT records, primarily for ACME DNS-01 challenges used in automated certificate issuance. Providers advertising txt_records: true in capabilities MUST implement this endpoint.

Design Rationale TXT record management is designed to support wildcard certificate issuance, which requires multiple simultaneous TXT records during the ACME validation process. The protocol supports:

• Accumulation: Multiple TXT values can coexist for the same hostname prefix (e.g., _acme-challenge.example.com)
• Selective deletion: Individual TXT values can be removed without affecting others
• Automatic cleanup: Providers MAY implement TTL-based expiration for TXT records

Set TXT Record (POST) Creates or adds a TXT record value for the specified hostname. Multiple calls with different values MUST accumulate (not replace) TXT records for the same hostname, up to the provider's limit.

Request Fields

Field	Type	Required	Description
hostname	string	YES	FQDN for the TXT record
value	string	YES	TXT record value (max 255 chars)
ttl	integer	NO	Time to live in seconds (default: 60)

Example Request

Example Response The record_count field indicates the total number of TXT values currently stored for this hostname after the operation.

Delete TXT Record (DELETE) Removes a specific TXT record value. If value is omitted, ALL TXT records for the hostname are removed.

Request Fields

Field	Type	Required	Description
hostname	string	YES	FQDN of the TXT record
value	string	NO	Specific value to delete (omit to delete all)

Example Request (selective deletion)

Example Response

Get TXT Records (GET) Returns all TXT record values for a hostname.

Example Response

Error Handling

HTTP Status Codes Implementations MUST use appropriate HTTP status codes as defined in :

Status	Usage
200	Successful request
400	Invalid request (bad hostname, invalid IP)
401	Missing or invalid authentication
403	Not authorized for requested resource
404	Resource not found
429	Rate limit exceeded
500	Server error

Error Response Format

Standard Error Codes

Code	HTTP Status	Description
unauthorized	401	Missing authentication
invalid_token	401	Invalid or expired token
forbidden	403	Not authorized for resource
not_found	404	Hostname not found
rate_limited	429	Too many requests
invalid_hostname	400	Invalid hostname format
invalid_ip	400	Invalid IP address format
hostname_not_owned	403	User does not own hostname
ipv4_auto_failed	400	Cannot detect IPv4 from IPv6 connection
ipv6_auto_failed	400	Cannot detect IPv6 from IPv4 connection
validation_error	400	Request validation failed
invalid_ttl	400	TTL value out of acceptable range
txt_not_supported	400	Provider does not support TXT records
txt_limit_exceeded	400	Maximum TXT records per hostname exceeded
txt_invalid_name	400	TXT hostname must use allowed prefix
txt_value_too_long	400	TXT value exceeds 255 characters

Rate Limiting Headers When rate limiting is applied, responses SHOULD include:

• Retry-After: Seconds until rate limit resets
• X-RateLimit-Limit: Maximum requests per window
• X-RateLimit-Remaining: Remaining requests in window
• X-RateLimit-Reset: Unix timestamp when window resets

Legacy Compatibility For backward compatibility with existing DDNS clients, providers MAY implement:

Legacy Response Codes Responses MUST be plain text (not JSON):

Response	Meaning
good {ip}	Update successful
nochg {ip}	No change needed
badauth	Authentication failed
notfqdn	Invalid hostname
nohost	Hostname not found
abuse	Account blocked

This endpoint is provided for compatibility only. New implementations SHOULD use the modern JSON endpoints.

Comparison with RFC 2136 RFC 2136 defines DNS UPDATE, a protocol for dynamic updates to DNS zones. The ApertoDNS Protocol differs in several key aspects:

Aspect	RFC 2136	ApertoDNS Protocol
Transport	DNS (UDP/TCP)	HTTPS
Format	DNS wire format	JSON
Auth	TSIG/SIG(0)	Bearer tokens
Discovery	None	/info endpoint
IPv6	Supported	Native support
Bulk ops	Per-message	Dedicated endpoint

The ApertoDNS Protocol is designed for consumer DDNS services where simplicity and HTTP integration are priorities, while RFC 2136 is suited for direct DNS zone manipulation.

Concurrency Model This section describes the behavior when multiple clients attempt to update the same hostname concurrently.

Last-Write-Wins Semantics The protocol uses a last-write-wins model for concurrent updates. When multiple clients update the same hostname:

• The most recent update takes precedence
• No conflict detection or resolution is performed
• The previous_* fields reflect the value immediately before the current update, regardless of which client set it

Implications for Clients Clients operating in environments where multiple devices may update the same hostname SHOULD be aware of the following:

1. Update intervals: Clients SHOULD implement appropriate update intervals to minimize conflicts
2. Change detection: Clients MAY compare previous_* values with expected values to detect concurrent modifications
3. Idempotent updates: When the new IP matches the existing record, changed will be false regardless of which client originally set the value

Example Scenario Consider two clients (A and B) updating the same hostname:

1. Initial state: ipv4 = "203.0.113.10"
2. Client A sends update with ipv4 = "203.0.113.20" (succeeds, previous_ipv4 = "203.0.113.10")
3. Client B sends update with ipv4 = "203.0.113.30" (succeeds, previous_ipv4 = "203.0.113.20")
4. Final state: ipv4 = "203.0.113.30"

Client A's update was overwritten by Client B. Neither client receives an error, as this is expected behavior under last-write-wins semantics.

Recommendations for Conflict-Sensitive Applications Applications requiring stronger consistency guarantees SHOULD:

• Use separate hostnames for each client/device
• Implement application-level coordination outside this protocol
• Consider using RFC 2136 which supports prerequisite conditions for updates

Security Considerations

Transport Security All endpoints MUST be served over HTTPS using TLS 1.2 or higher. Implementations MUST NOT support plaintext HTTP for any protocol endpoint. Implementations SHOULD support TLS 1.3 and SHOULD disable older cipher suites known to be weak.

Token Security

• Tokens MUST be generated using cryptographically secure random number generators (CSPRNG)
• Tokens SHOULD have configurable expiration
• Providers SHOULD support token revocation
• Tokens MUST NOT be logged in server access logs
• Tokens MUST NOT appear in URLs or error messages

Hostname Validation Before processing any update request, implementations MUST verify that the authenticated user owns or has permission to modify the requested hostname. Failure to validate ownership could allow unauthorized DNS modifications.

Rate Limiting Providers SHOULD implement rate limiting to prevent:

• Brute-force token guessing
• Denial of service attacks
• Excessive DNS propagation load

Rate limits SHOULD be advertised in the discovery endpoint and communicated via response headers.

IP Address Validation Implementations MUST reject IP addresses that are not globally routable. This prevents DNS rebinding attacks and ensures that dynamic DNS records point to legitimate public addresses.

Rejected IPv4 Addresses The following IPv4 address ranges MUST be rejected per :

Address Block	Attribute	Reference
0.0.0.0/8	"This network"
10.0.0.0/8	Private-Use
100.64.0.0/10	Shared Address Space (CGNAT)
127.0.0.0/8	Loopback
169.254.0.0/16	Link-Local
172.16.0.0/12	Private-Use
192.0.0.0/24	IETF Protocol Assignments
192.0.2.0/24	Documentation (TEST-NET-1)
192.168.0.0/16	Private-Use
198.18.0.0/15	Benchmarking
198.51.100.0/24	Documentation (TEST-NET-2)
203.0.113.0/24	Documentation (TEST-NET-3)
224.0.0.0/4	Multicast
240.0.0.0/4	Reserved
255.255.255.255/32	Limited Broadcast

Rejected IPv6 Addresses The following IPv6 address ranges MUST be rejected per :

Address Block	Attribute	Reference
::/128	Unspecified
::1/128	Loopback
::ffff:0:0/96	IPv4-mapped
64:ff9b::/96	IPv4-IPv6 Translation
100::/64	Discard-Only
2001:db8::/32	Documentation
fc00::/7	Unique Local (ULA)
fe80::/10	Link-Local
ff00::/8	Multicast

Implementation Notes Implementations SHOULD return the invalid_ip error code when rejecting addresses from these ranges. Implementations MAY log rejected addresses for security monitoring purposes. Note: The documentation ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 for IPv4 and 2001:db8::/32 for IPv6) are used in examples throughout this specification but MUST be rejected in production deployments. Implementations MAY provide configuration options to allow specific private ranges for internal deployments, but such configurations MUST be explicitly enabled and SHOULD generate warnings.

Input Validation All user input MUST be validated:

• Hostnames MUST conform to DNS naming rules
• IP addresses MUST be valid IPv4 or IPv6 format
• TTL values MUST be within acceptable ranges
• TXT values MUST NOT exceed 255 characters

TXT Record Abuse Prevention TXT records can potentially be abused for:

• DNS tunneling: Encoding data in TXT records for covert communication
• Data exfiltration: Using DNS queries to leak sensitive data
• Resource exhaustion: Creating excessive TXT records

Implementations MUST implement safeguards:

• Limit TXT value length to 255 characters (DNS standard)
• Limit number of TXT records per hostname (default: 5)
• Restrict TXT hostnames to approved prefixes (e.g., _acme-challenge.)
• Implement rate limiting on TXT operations
• Consider automatic expiration of TXT records (recommended: 24 hours)

Internationalized Domain Names When handling Internationalized Domain Names (IDNs), the following requirements apply as specified in :

• Clients SHOULD convert IDN hostnames to their A-label (ASCII Compatible Encoding) form before sending requests
• Servers MUST accept hostnames in A-label form
• Servers MAY accept hostnames in U-label (Unicode) form and convert them to A-labels internally
• Servers MUST store and return hostnames in a consistent form

For example, a client wishing to update an internationalized hostname SHOULD send the request with the A-label form (e.g., "xn--r8jz45g.example.com" for a Japanese hostname). Implementations that accept U-label input MUST perform IDNA2008 validation as specified in before processing the request.

Privacy Considerations This section addresses privacy considerations as recommended by .

Data Minimization Providers SHOULD minimize the collection and retention of personal data. Specifically:

• IP address history SHOULD have configurable retention periods
• Update timestamps MAY be retained for operational purposes
• Providers SHOULD document their data retention policies

User Control Users SHOULD have mechanisms to:

• View their stored data
• Delete their accounts and associated data
• Export their data in a portable format

Traffic Analysis DDNS updates inherently reveal:

• That a user's IP address has changed
• The timing of IP address changes
• The association between a hostname and IP address

Providers should be aware that this information could be used to track user behavior or network changes.

Encryption All communications MUST be encrypted via HTTPS, preventing passive observation of update requests and tokens.

IANA Considerations

Well-Known URI Registration This document requests registration of the following well-known URI suffix:

URI Suffix:

apertodns

Change Controller:

IETF

Specification Document:

This document

Status:

provisional

Related Information:

None

The well-known URI /.well-known/apertodns/ is used as the base path for all protocol endpoints.

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This document is the revised protocol definition for Internationalized Domain Names (IDNs). The rationale for changes, the relationship to the older specification, and important terminology are provided in other documents. This document specifies the protocol mechanism, called Internationalized Domain Names in Applications (IDNA), for registering and looking up IDNs in a way that does not require changes to the DNS itself. IDNA is only meant for processing domain names, not free text. [STANDARDS-TRACK] Public Key Infrastructure using X.509 (PKIX) certificates are used for a number of purposes, the most significant of which is the authentication of domain names. Thus, certification authorities (CAs) in the Web PKI are trusted to verify that an applicant for a certificate legitimately represents the domain name(s) in the certificate. As of this writing, this verification is done through a collection of ad hoc mechanisms. This document describes a protocol that a CA and an applicant can use to automate the process of verification and certificate issuance. The protocol also provides facilities for other certificate management functions, such as certificate revocation. This memo reiterates the assignment of an IPv4 address block (192.0.0.0/24) to IANA. It also instructs IANA to restructure its IPv4 and IPv6 Special-Purpose Address Registries. Upon restructuring, the aforementioned registries will record all special-purpose address blocks, maintaining a common set of information regarding each address block. This document requests the allocation of an IPv4 /10 address block to be used as Shared Address Space to accommodate the needs of Carrier- Grade NAT (CGN) devices. It is anticipated that Service Providers will use this Shared Address Space to number the interfaces that connect CGN devices to Customer Premises Equipment (CPE). Shared Address Space is distinct from RFC 1918 private address space because it is intended for use on Service Provider networks. However, it may be used in a manner similar to RFC 1918 private address space on routing equipment that is able to do address translation across router interfaces when the addresses are identical on two different interfaces. Details are provided in the text of this document. This document details the allocation of an additional special-use IPv4 address block and updates RFC 5735. This memo documents an Internet Best Current Practice. This RFC is an official specification for the Internet community. It incorporates by reference, amends, corrects, and supplements the primary protocol standards documents relating to hosts. [STANDARDS-TRACK] To participate in wide-area IP networking, a host needs to be configured with IP addresses for its interfaces, either manually by the user or automatically from a source on the network such as a Dynamic Host Configuration Protocol (DHCP) server. Unfortunately, such address configuration information may not always be available. It is therefore beneficial for a host to be able to depend on a useful subset of IP networking functions even when no address configuration is available. This document describes how a host may automatically configure an interface with an IPv4 address within the 169.254/16 prefix that is valid for communication with other devices connected to the same physical (or logical) link. IPv4 Link-Local addresses are not suitable for communication with devices not directly connected to the same physical (or logical) link, and are only used where stable, routable addresses are not available (such as on ad hoc or isolated networks). This document does not recommend that IPv4 Link-Local addresses and routable addresses be configured simultaneously on the same interface. [STANDARDS-TRACK] This document provides guidance for the Internet Assigned Numbers Authority (IANA) in assigning IPv4 multicast addresses. It obsoletes RFC 3171 and RFC 3138 and updates RFC 2780. This memo documents an Internet Best Current Practice. This memo specifies the extensions required of a host implementation of the Internet Protocol (IP) to support multicasting. Recommended procedure for IP multicasting in the Internet. This RFC obsoletes RFCs 998 and 1054. [STANDARDS-TRACK] This RFC proposes simple rules for broadcasting Internet datagrams on local networks that support broadcast, for addressing broadcasts, and for how gateways should handle them. This RFC suggests a proposed protocol for the ARPA-Internet community, and requests discussion and suggestions for improvements. This document discusses the algorithmic translation of an IPv6 address to a corresponding IPv4 address, and vice versa, using only statically configured information. It defines a well-known prefix for use in algorithmic translations, while allowing organizations to also use network-specific prefixes when appropriate. Algorithmic translation is used in IPv4/IPv6 translators, as well as other types of proxies and gateways (e.g., for DNS) used in IPv4/IPv6 scenarios. [STANDARDS-TRACK] This document defines an IPv6 unicast address format that is globally unique and is intended for local communications, usually inside of a site. These addresses are not expected to be routable on the global Internet. [STANDARDS-TRACK] Informative References Using this specification of the UPDATE opcode, it is possible to add or delete RRs or RRsets from a specified zone. Prerequisites are specified separately from update operations, and can specify a dependency upon either the previous existence or nonexistence of an RRset, or the existence of a single RR. [STANDARDS-TRACK] This document offers guidance for developing privacy considerations for inclusion in protocol specifications. It aims to make designers, implementers, and users of Internet protocols aware of privacy-related design choices. It suggests that whether any individual RFC warrants a specific privacy considerations section will depend on the document's content. This document describes address allocation for private internets. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This specification defines the addressing architecture of the IP Version 6 (IPv6) protocol. The document includes the IPv6 addressing model, text representations of IPv6 addresses, definition of IPv6 unicast addresses, anycast addresses, and multicast addresses, and an IPv6 node's required addresses. This document obsoletes RFC 3513, "IP Version 6 Addressing Architecture". [STANDARDS-TRACK] Three IPv4 unicast address blocks are reserved for use in examples in specifications and other documents. This document describes the use of these blocks. This document is not an Internet Standards Track specification; it is published for informational purposes. To reduce the likelihood of conflict and confusion when relating documented examples to deployed systems, an IPv6 unicast address prefix is reserved for use in examples in RFCs, books, documentation, and the like. Since site-local and link-local unicast addresses have special meaning in IPv6, these addresses cannot be used in many example situations. The document describes the use of the IPv6 address prefix 2001:DB8::/32 as a reserved prefix for use in documentation. This memo provides information for the Internet community. This document is a republication of RFC 1944 correcting the values for the IP addresses which were assigned to be used as the default addresses for networking test equipment. This memo provides information for the Internet community. Remote triggered black hole filtering describes a method of mitigating the effects of denial-of-service attacks by selectively discarding traffic based on source or destination address. Remote triggered black hole routing describes a method of selectively re- routing traffic into a sinkhole router (for further analysis) based on destination address. This document updates the "IPv6 Special Purpose Address Registry" by explaining why a unique IPv6 prefix should be formally assigned by IANA for the purpose of facilitating IPv6 remote triggered black hole filtering and routing. This document is not an Internet Standards Track specification; it is published for informational purposes.

Acknowledgments Thanks to the dynamic DNS community for decades of service enabling home users and small businesses to maintain stable hostnames with dynamic IP addresses. Thanks to the IETF DNSOP working group participants for their review and feedback on this specification.

Implementation Status Note to RFC Editor: Please remove this appendix before publication. This section records the status of known implementations of the protocol defined by this specification.

ApertoDNS

Organization:

ApertoDNS

Implementation:

Reference implementation

Description:

Full protocol support including all endpoints, bulk updates, webhooks, and legacy compatibility

Level of Maturity:

Production

Coverage:

Complete

Licensing:

Proprietary service, open protocol

Contact:

support@apertodns.com

URL:

https://apertodns.com

OpenAPI Specification A complete OpenAPI 3.0.3 specification for this protocol is available at: https://github.com/apertodns/apertodns-protocol/blob/main/openapi.yaml This specification can be used to:

• Generate client libraries in various programming languages
• Create interactive API documentation
• Validate implementations for conformance

Example Update Flow The following illustrates a typical update flow:

1. Client discovers provider capabilities: ~~~ GET /.well-known/apertodns/v1/info ~~~
2. Client authenticates and requests update: ~~~ POST /.well-known/apertodns/v1/update Authorization: Bearer example_live_abc123 Content-Type: application/json {"hostname": "home.example.com", "ipv4": "auto"} ~~~
3. Provider validates token and hostname ownership
4. Provider updates DNS record
5. Provider returns result: ~~~json { "success": true, "data": { "hostname": "home.example.com", "ipv4": "203.0.113.50", "changed": true } } ~~~
6. DNS propagates the new record

Changes from Legacy DDNS Protocols For implementers familiar with legacy HTTP-based DDNS protocols (commonly referred to as "dyndns2" in client implementations such as ddclient), key differences include:

• JSON responses instead of plain text
• Bearer token authentication instead of HTTP Basic
• Explicit capability negotiation via /info endpoint
• Dedicated endpoints for different operations
• Standardized error codes and response formats
• Native IPv6 support with separate fields
• Bulk update support for multiple hostnames
• Well-known URI path for consistent discovery

Changes from -00 This section summarizes changes from draft-ferro-dnsop-apertodns-protocol-00:

Version 1.2.3 Changes

• Added ipv4_auto_failed and ipv6_auto_failed error codes to Section 8.3 (Standard Error Codes)
• Added "Auto-Detection Limitations" subsection to Section 7.3 (Update Endpoint) documenting HTTP connection semantics constraints
• Added validation_error and invalid_ttl error codes
• Added example response for auto-detection failure
• Updated protocol version in examples from "1.2.0" to "1.3.0"
• Added acknowledgment of IETF DNSOP working group

Version 1.3.0 Changes (TXT Records)

• Added TXT record management endpoint (/txt) for ACME DNS-01 challenges
• Added txt_records and txt_max_records capability fields
• Added TXT-related error codes: txt_not_supported, txt_limit_exceeded, txt_invalid_name, txt_value_too_long
• Added "TXT Record Abuse Prevention" section to Security Considerations
• Added RFC 8555 (ACME) to normative references
• Added TXT Record and ACME DNS-01 terminology definitions
• Updated protocol version to 1.3.0

Changes from -01 This section summarizes changes from draft-ferro-dnsop-apertodns-protocol-01:

Version 1.3.2 Changes (Response Consistency)

• Standardized timestamp field naming across all endpoints:
  • Renamed timestamp to updated_at in /update response
  • Renamed last_updated to updated_at in /status response
  • This provides consistent naming for timestamp fields across the protocol
• Changed /domains response structure from grouped domains to flat array:
  • Previous: data.domains[].hostnames[] (grouped by parent domain)
  • New: data[] (flat array of hostname objects with full details)
  • Each hostname object now includes: hostname, ipv4, ipv6, ttl, updated_at, created_at
  • This reduces API calls needed to retrieve hostname information
• Clarified that timestamp field remains unchanged for /health and /txt endpoints
• Clarified that server_time field remains unchanged for /info endpoint

Version 1.3.2 Changes (Enhancements)

• Added "Backward Compatibility" subsection to /update endpoint documenting deprecated field aliases (ipv4_previous, ipv6_previous) for transition from legacy field names
• Added "Authorization Scopes" section documenting optional scope-based authorization with defined scopes: dns:update, domains:read, txt:read, txt:write, txt:delete
• Updated example timestamps to 2026

Version 1.4.0 Changes (Record Deletion and Concurrency)

• Added "Record Deletion via Null Values" subsection to /update endpoint documenting the ability to delete A or AAAA records by setting the corresponding field to null in the update request
• Defined tri-state semantics for ipv4/ipv6 fields: string value (update), null (delete), omitted (no change)
• Added examples for IPv4 and IPv6 record deletion
• Added "Concurrency Model" section documenting last-write-wins semantics for concurrent updates to the same hostname
• Added recommendations for conflict-sensitive applications
• Expanded "IP Address Validation" section with explicit lists of rejected IPv4 (15 ranges) and IPv6 (9 ranges) address blocks per RFC 6890
• Added RFC 6890 to normative references
• Updated protocol version to 1.4.0

Changes from -02 This section summarizes changes from draft-ferro-dnsop-apertodns-protocol-02:

• Added Status: provisional to the IANA Well-Known URI registration as required by RFC 8615 Section 3.1