docs: add definitions

This commit is contained in:
Maël Gangloff
2025-11-20 12:21:45 +01:00
parent 8f248eba8e
commit 17c74b094e
12 changed files with 551 additions and 1 deletions

View File

@@ -58,7 +58,8 @@ export default defineConfig({
],
},
{label: 'Legal', autogenerate: {directory: 'legal'}, collapsed: true},
{slug: 'acknowledgment'}
{slug: 'acknowledgment'},
{label: 'Definitions', autogenerate: {directory: 'definitions'}, collapsed: true},
],
locales: {
en: {

View File

@@ -0,0 +1,74 @@
---
title: DNS Protocol
description: What is DNS? Understand the Domain Name System, how it translates domain names into IP addresses, and its role in modern internet navigation.
---
import {LinkCard} from "@astrojs/starlight/components";
**DNS (Domain Name System)** is the decentralized naming system for computers, services, or any resources connected to the internet or a private network.
It acts as the "phonebook of the internet", translating human-readable domain names into machine-readable infos.
## The Hierarchical Architecture
The DNS architecture is a distributed, hierarchical database resembling an inverted tree. This structure, known as the **Domain Name Space**, is processed from right to left:
* **Root Level**: The top of the hierarchy, represented by a silent single dot (`.`) at the end of a fully qualified domain name.
* **Top-Level Domains (TLDs)**: The highest visible level (e.g., `.com`, `.org`, `.fr`).
* **Second-Level Domains (SLDs)**: The specific name registered by an entity (e.g., `example` in `example.com`).
* **Subdomains**: Further subdivisions for specific services or organizational structures (e.g., `www`, `blog`, or `api`).
## Authoritative Servers
Authoritative DNS servers hold the definitive resource records for a specific domain zone. Unlike recursive resolvers that cache answers, authoritative servers provide the original data.
When a client requests a domain, the resolution chain queries:
1. **Root Servers**: Directs to the TLD servers.
2. **TLD Servers**: Directs to the domain's authoritative nameservers.
3. **Authoritative Server**: Returns the final IP address (or other record).
<LinkCard
title="Top Level Domain"
description="An overview of Top-Level Domains (TLDs), their classification (gTLD, ccTLD, etc.), and the structure of the DNS root zone."
href="/en/definitions/top-level-domain"/>
## GLUE Records
A GLUE record is an A (or AAAA) record **provided by the parent zone** to prevent circular dependencies. Normally, the parent zone only delegates, but here it must provide data.
They are strictly necessary when a domain's nameserver is a subdomain of the domain itself (e.g., `example.com` uses `ns1.example.com` as its nameserver). Without the GLUE record in the `.com` zone pointing to `ns1`'s IP, the resolver would be stuck in a loop trying to resolve the nameserver's name.
### Example: `ns.icann.org`
In this example, `icann.org` uses `ns.icann.org` as one of its nameservers.
To resolve `icann.org`, you must query `ns.icann.org`, but you cannot find `ns.icann.org` without first resolving `icann.org`.
When querying the `.org` TLD server (`A0.ORG.AFILIAS-NST.INFO`), the server returns the Nameserver (NS) records in the **Authority Section**, but crucially, it also provides the IP addresses in the **Additional Section**. These are the GLUE records.
```text title="DNS query of ns.icann.org using the dig command" {17-18}
; <<>> DiG 9.20.15 <<>> ns.icann.org @A0.ORG.AFILIAS-NST.INFO
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 52458
;; flags: qr rd; QUERY: 1, ANSWER: 0, AUTHORITY: 4, ADDITIONAL: 3
;; QUESTION SECTION:
;ns.icann.org. IN A
;; AUTHORITY SECTION:
icann.org. 3600 IN NS ns.icann.org.
icann.org. 3600 IN NS a.icann-servers.net.
icann.org. 3600 IN NS c.icann-servers.net.
icann.org. 3600 IN NS b.icann-servers.net.
;; ADDITIONAL SECTION:
ns.icann.org. 3600 IN A 199.4.138.53
ns.icann.org. 3600 IN AAAA 2001:500:89::53
;; Query time: 241 msec
;; SERVER: 199.19.56.1#53(A0.ORG.AFILIAS-NST.INFO) (UDP)
```
## See also
- [Domain Name System](https://en.wikipedia.org/wiki/Domain_Name_System) on Wikipedia

View File

@@ -0,0 +1,52 @@
---
title: DNSSEC
description: Secure your domain resolution. Learn about DNSSEC (Domain Name System Security Extensions) and how it protects users from forged DNS data.
---
import {LinkCard} from "@astrojs/starlight/components";
**DNSSEC (Domain Name System Security Extensions)** adds a layer of cryptographic security to the DNS protocol. It defends against specific attacks, such as **DNS cache poisoning** and **man-in-the-middle attacks**, by ensuring that the DNS data received is identical to what the zone owner published.
## What DNSSEC does
DNSSEC employs public-key cryptography to establish a **Chain of Trust**.
* **Origin Authentication**: Verifies that the data comes from the correct authoritative server.
* **Data Integrity**: Ensures the data has not been modified in transit.
* **Authenticated Denial of Existence**: Proves securely that a domain or record does *not* exist (using NSEC/NSEC3).
New resource records enable this validation:
* `RRSIG`: The digital signature associated with a record set.
* `DNSKEY`: The public key used to verify the RRSIG.
* `DS` (Delegation Signer): A hash of the child zone's key, stored in the parent zone to link the trust chain.
## What DNSSEC does not do
* **No Encryption**: DNS queries and responses remain in plain text (unlike DoH or DoT).
* **No Identity Validation**: It does not validate the legitimacy of the domain owner (e.g., it doesn't prevent phishing domains, it just proves the phishing domain's IP is correct).
## Configure DNSSEC on your Domain Name
Implementing DNSSEC involves two main stages:
1. **Signing the Zone**: The authoritative nameserver generates keys (`ZSK` and `KSK`) and signs the zone data, creating `RRSIG` and `DNSKEY` records.
2. **Establishing Trust**: The domain owner must send the `DS` record (hash of the KSK) to the Registrar. The Registrar forwards this to the Registry for publication in the parent TLD zone.
<LinkCard
title="Domain name"
description="An explanation of what a domain name is and its structure."
href="/en/definitions/domain-name"/>
## The Adoption of DNSSEC
Adoption is a top-down process starting from the Root Zone. While the Root and most TLDs are signed, adoption at the end-user level (Second-Level Domains) relies on registrar support and registrant awareness.
<LinkCard
title="Top Level Domain"
description="An overview of Top-Level Domains (TLDs) and their classification (gTLD, ccTLD, etc.)."
href="/en/definitions/top-level-domain"/>
## See also
- [DNSSEC World Map](https://stats.labs.apnic.net/dnssec) of the APNIC Labs

View File

@@ -0,0 +1,44 @@
---
title: Domain Lifecycle
description: Explore the domain lifecycle, from registration and renewal to expiration and redemption. Know the critical phases for managing your domain name.
---
import {LinkCard} from "@astrojs/starlight/components";
The **Domain Lifecycle** defines the statuses a domain name traverses from its creation to its deletion.
Understanding these phases is critical to prevent unintentional loss of a domain.
## The Generic Life Cycle
![Generic Domain Name Life Cycle](https://www.icann.org/en/registrars/gtld-lifecycle.jpg)
For most Generic Top-Level Domains (gTLDs) regulated by ICANN, the cycle follows this path:
1. **Available**: The domain is open for registration.
2. **Registered (Active)**: The domain is owned and functional. It can be updated, transferred, or renewed (typically 110 years).
3. **Auto-Renew Grace Period**: (045 days) The domain expires. The owner can usually renew it at the standard rate. The domain may stop resolving (ServerHold).
4. **Redemption Grace Period**: (30 days) The domain is deleted from the registrar but held by the registry. Recovery is possible but requires a higher **restoration fee**.
5. **Pending Delete**: (5 days) The domain is scheduled for permanent deletion. It cannot be recovered or renewed.
6. **Released**: The domain becomes **Available** again for public registration.
<LinkCard
title="Domain name"
description="An explanation of what a domain name is and its structure."
href="/en/definitions/domain-name"/>
## Special Cases of some ccTLDs
Country Code Top-Level Domains (ccTLDs) operate under local regulations, leading to diverse lifecycles:
* **No Grace Periods**: Some ccTLDs enter "Pending Delete" immediately upon expiration.
* **Pre-Expiration Renewal**: Some registries require renewal fees to be paid weeks before the actual expiration date.
* **Manual Processes**: Restoration in some ccTLDs may require manual intervention and paperwork.
<LinkCard
title="Top Level Domain"
description="An overview of Top-Level Domains (TLDs) and their classification (gTLD, ccTLD, etc.)."
href="/en/definitions/top-level-domain"/>
## See also
- [Life Cycle of a Typical gTLD Domain Name](https://www.icann.org/en/contracted-parties/accredited-registrars/resources/gtld-lifecycle) on the ICANN website

View File

@@ -0,0 +1,53 @@
---
title: Domain name
description: Define your identity online. An explanation of what a domain name is and its structure.
---
A **Domain Name** is a human-readable identification string used to locate resources on the Internet. It maps complex numerical IP addresses to memorable names.
## The Structure of a Domain Name
A domain name is read hierarchically from right to left:
1. **Top-Level Domain (TLD)**: The suffix (e.g., `.com`, `.fr`).
2. **Second-Level Domain (SLD)**: The unique name chosen by the registrant (e.g., `example`).
3. **Subdomain**: prefixes for specific services (e.g., `www`, `api`).
A **Fully Qualified Domain Name (FQDN)** includes all labels up to the root (e.g., `www.example.com.`).
## The EPP Statuses
The Extensible Provisioning Protocol (EPP) assigns status codes to domains to indicate their state or restrictions. These are visible in WHOIS/RDAP lookups.
### Server Statuses (Set by Registry)
The registry can apply EPP codes to modify the state of a domain name. These are all codes except those beginning with `client`, which are reserved for registrars.
Generic codes are listed in the ICANN documentation.
Some registries have developed additional codes to describe non-standard cases.
For example, AFNIC added the code `server trade prohibited` to describe the prohibition of the `trade` operation on a domain name.
This operation is part of AFNIC's EPP extension and is not a standard operation for a domain name.
### Client Statuses (Set by Registrar)
Registrars can also apply EPP codes to a domain name. These codes always begin with `client` to distinguish them from the codes applied by the registry.
Some codes have the same effect as those applied by the registry.
For example, the `client hold` and `server hold` codes block the resolution of a domain name's DNS zone.
This means that the top-level domain name's DNS zone no longer contains the `NS` records necessary for delegating the domain name's zone.
This results in the complete shutdown of services for the domain name.
This code is often used by the registrar to strongly encourage the registrant to pay renewal fees (when the domain name is not in its redemption period).
## Internationalized Domain Name (IDN)
An IDN is a domain name that contains characters other than the standard ASCII format (a-z, 0-9, and hyphens). This includes characters with diacritics (accents) or characters from non-Latin scripts (Arabic, Chinese, Cyrillic, etc.).
To function in the legacy DNS system, IDNs are converted into an ASCII-compatible format called **Punycode**, which always begins with `xn--`.
| Display | Punycode |
|:-----------------:|:------------------------:|
| `maëlgangloff.fr` | `xn--malgangloff-0bb.fr` |
## See also
- [EPP Status Codes](https://icann.org/epp) on the ICANN website

View File

@@ -0,0 +1,44 @@
---
title: EPP Protocol
description: What is a Domain Name Registrar? Learn their role in managing the registration and transfer of domain names for the public.
---
import {LinkCard} from "@astrojs/starlight/components";
The **Extensible Provisioning Protocol (EPP)** is the standard application-layer protocol for allocating objects within registries over the Internet. While primarily used for domain names, it can also manage contacts and host objects.
## The Actors
### Client (Registrar)
The Registrar acts as the EPP Client. They send XML commands to create, update, renew, or delete domain names based on customer requests.
<LinkCard
title="Registrar"
description="What is a Domain Name Registrar?"
href="/en/definitions/registrar"/>
### Server (Registry)
The Registry acts as the EPP Server. It processes the commands, validates logic (e.g., "is this domain available?"), updates the central database, and returns success or error responses.
<LinkCard
title="Registry"
description="What is a Domain Name Registry?"
href="/en/definitions/registry"/>
## The Protocol Mechanism
EPP uses **XML** messages transported over **TCP**, secured by **TLS**. It is a stateful protocol, meaning a session is established (Login) before commands are executed.
Common EPP commands include:
* `<check>`: Verify availability.
* `<create>`: Register a new object.
* `<info>`: Retrieve object details.
* `<transfer>`: Initiate a registrar transfer.
* `<poll>`: Retrieve asynchronous notifications from the Registry.
## See also
- [RFC 5730 - Extensible Provisioning Protocol (EPP)](https://datatracker.ietf.org/doc/html/rfc5730)

View File

@@ -0,0 +1,37 @@
---
title: ICANN
description: Learn about ICANN (Internet Corporation for Assigned Names and Numbers), the non-profit organization coordinating the global internet's unique identifiers.
---
import {LinkCard} from "@astrojs/starlight/components";
**ICANN (Internet Corporation for Assigned Names and Numbers)** is the non-profit organization responsible for coordinating the maintenance and security of the global Internet's unique identifiers.
ICANN acts as the primary governance body for the technical infrastructure of the DNS. Its responsibilities include:
* **IANA Functions**: Managing the allocation of IP address space and the Root Zone of the DNS.
* **Policy Development**: Facilitating the creation of global policies for the domain name system via a multi-stakeholder model.
## Managing Top-Level Domains
ICANN decides which new Top-Level Domains (TLDs) are added to the Root Zone.
* It oversees the **New gTLD Program**, which expanded the internet from a few dozen extensions (like `.com`) to over 1,000 (like `.app`, `.shop`).
* It delegates **ccTLDs** (like `.uk`, `.fr`) to specific country managers, although it has less direct control over their local policies.
<LinkCard
title="Top Level Domain"
description="An overview of Top-Level Domains (TLDs) and their classification (gTLD, ccTLD, etc.)."
href="/en/definitions/top-level-domain"/>
## Accrediting Registrars
ICANN manages the accreditation system for Registrars wishing to sell generic TLDs. Accreditation ensures that companies handling domain registrations adhere to security, stability, and data retention standards.
<LinkCard
title="Registrar"
description="What is a Domain Name Registrar?"
href="/en/definitions/registrar"/>
## See also
- [Official website](https://www.icann.org/)

View File

@@ -0,0 +1,29 @@
---
title: RDAP Protocol
description: The modern data access protocol. Understand RDAP (Registration Data Access Protocol) for reliable and structured access to domain registration and ownership data.
---
import {LinkCard} from "@astrojs/starlight/components";
The **Registration Data Access Protocol (RDAP)** is the modern standard for accessing registration data. It was designed to replace the legacy WHOIS protocol by addressing its lack of standardization and security.
## Key Improvements over WHOIS
* **Structured Data (JSON)**: Unlike WHOIS, which returns unstructured free text, RDAP returns data in JSON format. This allows for easy automated parsing and consistent display by clients.
* **Standardized Queries**: RDAP uses RESTful web services (HTTP/HTTPS).
* **Internationalization**: Native support for non-Latin characters (IDNs).
* **Differentiated Access**: RDAP supports authentication, allowing registries to show limited data to the public (GDPR compliance) while providing full data to accredited authorities.
<LinkCard
title="WHOIS Protocol"
description="Get an overview of the WHOIS Protocol."
href="/en/definitions/whois"/>
## Deployment Status
ICANN mandates RDAP implementation for all accredited Registrars and gTLD Registries.
While WHOIS is still widely used by legacy systems, RDAP is the authoritative source for gTLD registration data. Adoption among ccTLDs is voluntary and ongoing.
## See also
- [RDAP Deployment Dashboard](https://deployment.rdap.org)

View File

@@ -0,0 +1,36 @@
---
title: Registrar
description: What is a Domain Name Registrar? Learn their role in managing the registration and transfer of domain names for the public.
---
import {LinkCard} from "@astrojs/starlight/components";
A **Registrar** is an accredited commercial entity that sells domain name registrations to the public. They act as the intermediary between the Registrant (the domain owner) and the Registry (the database operator).
<LinkCard
title="Registry"
description="What is a Domain Name Registry?"
href="/en/definitions/registry"/>
## Core Responsibilities
### Administrative Management
* **Registration & Renewal**: Handling the purchase and periodic renewal of domains.
* **Lifecycle Management**: Managing grace periods, redemption fees, and transfers.
* **Data Accuracy**: Collecting and maintaining accurate contact information for WHOIS/RDAP directories.
### Technical Services
* **EPP Interface**: Translating user actions into EPP commands sent to the Registry.
* **DNS Hosting**: Most registrars provide default nameservers, allowing users to manage their DNS records (A, MX, CNAME) via a user-friendly dashboard.
* **DNSSEC**: Facilitating the rotation and publication of DS records.
<LinkCard
title="DNS Protocol"
description="What is DNS? Understand the Domain Name System."
href="/en/definitions/dns"/>
## See also
- [Domain name registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) on Wikipedia

View File

@@ -0,0 +1,33 @@
---
title: Registry
description: Understand the Domain Name Registry? Learn how these organizations manage the central database for all domain names under a specific TLD.
---
import {LinkCard} from "@astrojs/starlight/components";
A **Registry** (or Registry Operator) is the organization responsible for maintaining the master database of all domain names registered under a specific Top-Level Domain (TLD).
## Technical Roles
The Registry is the authoritative source for its TLD. Its duties include:
* **Zone File Generation**: Publishing the zone file that directs global DNS traffic to the correct nameservers for every domain in the extension.
* **IDN & DNSSEC Management**: Enforcing policies for special characters and managing the cryptographic signing of the TLD zone.
* **WHOIS/RDAP Server**: Operating the directory service that provides public information about registered domains.
## Operational Roles
Registries generally do not sell directly to the public. Instead, they:
* Define the **Acceptable Use Policies** for the TLD.
* Set the wholesale price for domains.
* Accredit and connect with **Registrars** via EPP.
<LinkCard
title="Registrar"
description="What is a Domain Name Registrar?"
href="/en/definitions/registrar"/>
## See also
- [Domain name registry](https://en.wikipedia.org/wiki/Domain_name_registry) on Wikipedia

View File

@@ -0,0 +1,50 @@
---
title: Top-Level Domain (TLD)
description: An overview of Top-Level Domains (TLDs), their classification (gTLD, ccTLD, etc.), and the structure of the DNS root zone.
---
A **Top-Level Domain (TLD)** is the rightmost segment of a domain name (after the last dot). TLDs are the highest level of the DNS hierarchy below the root.
## TLD Classifications
### Generic TLD (gTLD)
Originally intended for specific use cases, most gTLDs are now open to everyone.
* **Legacy**: `.com` (commercial), `.net` (network), `.org` (organization).
* **New gTLDs**: Thousands of niche extensions like `.app`, `.blog`, `.guru`.
* **Restricted**: Domains like `.bank` or `.pharmacy` require verification of eligibility.
* **Brand**: Closed TLDs for corporations, e.g., `.google` or `.bmw`.
### Country Code TLD (ccTLD)
Reserved for countries and territories (two letters, based on ISO 3166).
* **Examples**: `.uk` (United Kingdom), `.de` (Germany), `.io` (British Indian Ocean Territory).
* **Rules**: Policies vary strictly by country. Some require local residency (e.g., `.no`, `.ca`), while others are marketed globally (e.g., `.tv`, `.ai`).
### Sponsored TLD (sTLD)
Managed by private organizations representing a specific community.
* `.gov` (US Government)
* `.edu` (Accredited US institutions)
* `.aero` (Aviation industry)
### Infrastructure TLD
* `.arpa`: Managed by IANA, used exclusively for technical infrastructure (e.g., reverse DNS lookups).
## Reserved TLDs
Per [RFC 2606](https://tools.ietf.org/html/rfc2606), four TLDs are permanently reserved for testing and documentation to avoid confusion in production environments:
* `.test`
* `.example`
* `.invalid`
* `.localhost`
## See also
- [Top-level domain (Wikipedia)](https://en.wikipedia.org/wiki/Top-level_domain)
- [IANA Root Zone Database](https://www.iana.org/domains/root/db)

View File

@@ -0,0 +1,97 @@
---
title: WHOIS Protocol
description: Get an overview of WHOIS. Learn how this protocol is used to query databases for information about the registered user or assignees of a domain name.
---
import {LinkCard} from "@astrojs/starlight/components";
WHOIS is a text-based query/response protocol (listening on **TCP Port 43**) widely used for querying databases that store the registered users or assignees of an Internet resource, such as a domain name or an IP address block.
## Core Use Cases
* **Availability Check**: Verifying if a specific domain name is available for registration.
* **Ownership Identification**: Identifying the Registrant or the Registrar managing the domain.
* **Technical Troubleshooting**: Finding the authoritative nameservers or the technical contacts to resolve network issues.
* **Legal & Abuse**: Providing a record for law enforcement, intellectual property protection, and abuse reporting.
## Thick vs. Thin Registries
Understanding WHOIS responses requires understanding how the TLD Registry stores data.
### Thin Registry (e.g., .com, .net)
The Registry only stores technical data (DNSSEC, Nameservers) and a pointer to the Registrar.
To get the full contact details, a second WHOIS query must be sent to the **Registrar's WHOIS server**.
### Thick Registry (e.g., .org, .info, most ccTLDs)
The Registry stores *all* information, including the Registrant's contact details and administrative data.
A single query to the Registry provides the full record.
## Example: Recursive WHOIS Query
The standard `whois` command line tool often handles the "Thin Registry" redirect automatically.
However, seeing the raw steps helps understand the protocol.
In the example below for a **Thin TLD** (`.com`), we first query the Registry, which points us to the Registrar.
### Request to the Registry (Verisign)
Note the `Registrar WHOIS Server` field in the response.
```text title="WHOIS query to the Registry"
$ whois --verbose example.com -h whois.verisign-grs.com.
Using server whois.verisign-grs.com..
Query string: "example.com"
Domain Name: EXAMPLE.COM
Registry Domain ID: 2336799_DOMAIN_COM-VRSN
Registrar WHOIS Server: whois.iana.org
Registrar URL: http://res-dom.iana.org
Updated Date: 2025-08-14T07:01:39Z
Creation Date: 1995-08-14T04:00:00Z
Registry Expiry Date: 2026-08-13T04:00:00Z
Registrar: RESERVED-Internet Assigned Numbers Authority
Domain Status: clientDeleteProhibited https://icann.org/epp#clientDeleteProhibited
Domain Status: clientTransferProhibited https://icann.org/epp#clientTransferProhibited
Name Server: A.IANA-SERVERS.NET
Name Server: B.IANA-SERVERS.NET
DNSSEC: signedDelegation
>>> Last update of whois database: 2025-11-20T08:05:54Z <<<
```
### Request to the Registrar (IANA)
Following the referral, we query the specific Registrar to get the ownership details.
```text title="WHOIS query to the Registrar"
$ whois --verbose example.com -h whois.iana.org
Using server whois.iana.org..
Query string: "example.com"
% IANA WHOIS server
% for more information on IANA, visit http://www.iana.org
% This query returned 1 object
domain: EXAMPLE.COM
organisation: Internet Assigned Numbers Authority
created: 1992-01-01
source: IANA
```
## Privacy Considerations
Since the implementation of the **GDPR** (General Data Protection Regulation) and similar global privacy laws, the WHOIS output has changed significantly.
* **Data Redaction**: Most personal fields (Name, Email, Phone) are now replaced with placeholders like `DATA REDACTED` or `Redacted for Privacy`.
* **Privacy Proxies**: Registrars often provide services that replace the registrant's details with the registrar's generic contact information to prevent spam and harassment.
* **Tiered Access**: Full, unredacted data is often no longer publicly available anonymously and requires a legitimate legal request or accreditation.
<LinkCard title="RDAP Protocol" href="/en/definitions/rdap"
description="Learn about the successor to WHOIS designed to handle structured data and privacy access."/>
## See also
* [RFC 3912 - WHOIS Protocol Specification](https://datatracker.ietf.org/doc/html/rfc3912)