Subdomain Gateway Specification

2.1.1 Host (request header)

Defines the root that should be prepended to the path before IPFS content path resolution is performed.

The value in Host header must be a valid FQDN with at least three DNS labels: a case-insensitive content root identifier followed by ipfs or ipns namespace, and finally the domain name used by the gateway.

Converting Host into a content path depends on the nature of requested resource:

• For content at /ipfs/{cid}:
  • Host: {cid-mbase32}.ipfs.example.net
    • Example: Host: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.dweb.link
• For content at /ipns/{libp2p-key}:
  • Host: {libp2p-key-mbase36}.ipns.example.net
    • Example: Host: k2k4r8jl0yz8qjgqbmc2cdu5hkqek5rj6flgnlkyywynci20j0iuyfuj.ipns.dweb.link
    • Note: Base36 must be used to ensure CIDv1 with ED25519 fits in a single DNS label (63 characters).
• For content at /ipns/{dnslink-name}:
  • Host: {inlined-dnslink-name}.ipns.example.net
    • DNSLink names include . which means they MUST be inlined into a single DNS label to provide unique origin and work with wildcard TLS certificates.
      • DNSLink label encoding:
        • Every - is replaced with --
        • Every . is replaced with -
      • DNSLink label decoding
        • Every standalone - is replaced with .
        • Every remaining -- is replaced with -
      • Example:
        • example.net/ipns/en.wikipedia-on-ipfs.org → Host: en-wikipedia--on--ipfs-org.ipns.example.net
• If Host header does not include any subdomain, but the requested path is a valid content path, gateway MUST attempt to migrate from Path to Subdomain Gateway.
• Finally, if it is impossible to construct a content path from Host, return HTTP Error 400 Bad Request, as seen in [path-gateway].

2.1.2 X-Forwarded-Proto (request header)

Optional. Allows http:// gateway implementation to be deployed behind reverse proxies that provide TLS (https://) termination.

Setting X-Forwarded-Proto: https on reverse proxy informs gateway implementation that it MUST:

1. set all absolute redirect URLs to https:// (not http://)
2. inline DNSLink names to fit in a single DNS label, making it compatible with a single wildcard TLS certificate:

Example (GET with X-Forwarded-Proto: https):

• GET http://dweb.link/ipfs/{cid} → HTTP 301 with Location: https://{cid}.ipfs.dweb.link
• GET http://dweb.link/ipns/your-dnslink.site.example.com → HTTP 301 with Location: https://your--dnslink-site-example-com.ipfs.dweb.link

2.1.3 X-Forwarded-Host (request header)

Optional. Enables Path Gateway requests to be redirected to a Subdomain Gateway on a different domain name.

See also: migrating from Path to Subdomain Gateway.

Example (GET with X-Forwarded-Host: example.com):

• GET https://dweb.link/ipfs/{cid} → HTTP 301 with Location: https://{cid}.ipfs.example.com

2.2.1 uri (request query parameter)

Optional. When present, passed address should override regular path routing.

See URI router section for usage and implementation details.

3.1.1 Location (response header)

Below MUST be implemented in addition to Location requirements defined in [path-gateway].

4.3.1 Wildcard TLS certificates

Wildcard TLS certificates SHOULD be set for *.ipfs.example.net and *.ipns.example.net if a subdomain gateway is to be exposed on the public internet.

If TLS termination takes place outside of gateway implementation, then setting X-Forwarded-Proto at a reverse HTTP proxy is RECOMMENDED for preserving https protocol.

4.3.2 Public Suffix List and eTLD enforcement

Subdomain gateways assign each content root a unique origin, yet these origins share the gateway’s parent domain. Without proper isolation, all subdomains under the same effective Top-Level Domain (eTLD) face risks: a single problematic CID could trigger widespread blocking of the entire gateway by software like Safe Browsing (incident example).

To mitigate this and align with the web’s Same-origin security model, operators SHOULD register a wildcard entry like *.example.net with the Public Suffix List (PSL).

This will make ipfs.example.net and ipns.example.net eTLDs, treating each identifier (e.g., cid.ipfs.example.net) as a distinct top-level Origin. The public good gateway, listed as *.dweb.link and *.inbrowser.link on the PSL, exemplifies this approach.

Browsers supporting IPFS natively SHOULD detect URI patterns such as https://{content-root-id}.ip[f|n]s.example.net and dynamically update their internal PSL, bolstering security and compatibility without relying solely on operator action.