czds

README

ICANN CZDS client

A client library for the Internet Corporation for Assigned Names and Numbers (ICANN) Centralized Zone Data Service (CZDS). The client aims to streamline the process of querying the CZDS to retrieve zone files and to list the Top-Level Domains (TLDs) available on your account. It supports in-memory JWT storage and features a mechanism to refetch the token if it doesn't exist, is found to be invalid, or has expired.

Zone files obtained through this client contain a registry's list of registered and actively managed domain names, alongside various DNS records tailored to the registry's offered services. These files adhere to a specific format, initially defined in RFC 1035 and further refined by subsequent RFCs. However, the CZDS distributes these files in a format that conforms to a subset of these standards, as specified by the Zone File Access Advisory Group in their Strategy Proposal (Section 5.1.7, Page 9) and included in Specification 4 of the Registry Agreement. This ensures users receive comprehensively structured data, enabling effective analysis and application of the information contained within TLD zone files.

Features

• JWT Authentication: Manages JWT tokens with an in-memory store, automatically refetching tokens as needed. It is also possible to supply a custom JWT token store by implementing the TokenStore interface. The custom token store can be provided via TokenStoreOpt when initialising a new client.
• TLD Listing: Enables the listing of TLDs available to your account, including the approval status for each TLD.
• Zone File Queries: Allows for the retrieval of zone files from CZDS, presenting the data organized by domain name along with associated DNS records.

Prerequisites

Before using the client, you must obtain credentials from ICANN's Centralized Zone Data Service (CZDS). These credentials are necessary to authenticate and interact with the CZDS API.

Follow the steps below to obtain your ICANN CZDS credentials:

1. Register for an ICANN Account:
   • Visit the ICANN CZDS website.
   • Click on the "Sign Up" or "Register" option to create a new ICANN account.
   • Follow the registration process, providing the required personal and contact information.
   • Submit your registration. You may need to verify your email address as part of this process.
2. Apply for TLD zone file access:
   • Once your ICANN account is active, log in to the CZDS portal.
   • Navigate to the "Zone File Access" section.
   • Submit an application for zone file access. This will typically involve selecting the Top-Level Domains (TLDs) for which you're requesting access and agreeing to the terms and conditions.
   • Your application will be reviewed by the respective TLD operators. Approval times may vary depending on the operator.
3. Accessing the CZDS API:
   • To access the API, you will need to use your username (your email) and password when initialising a new client.

Remember, your access to zone files is governed by the terms and conditions you agreed to during the application process. Ensure your use of the data complies with these terms.

Usage

Import go-icann-czds-client into your Go project:

import "github.com/yourusername/go-icann-czds-client/czds"

Creating a Client

Initialise a new ICANN CZDS client with your credentials. By default, the client uses in-memory JWT storage:

client := czds.NewClient("email", "your_password")

If you prefer to use a custom token store, implement the TokenStore interface and pass it when creating the client:

client := icann.NewClient("email", "your_password", TokenStoreOpt(customTokenStore))

Querying Zone File Data

To obtain zone file data for a specific TLD:

zoneFile, err := client.GetZoneFileData("com")
if err != nil {
    log.Fatalf("failed to fetch zone file data: %v", err)
}
fmt.Println(zoneFile)

Listing TLDs

To list TLDs:

tlds, err := client.ListTLDs()
if err != nil {
    log.Fatalf("failed to list TLDs: %v", err)
}
fmt.Println(tlds)

Contributing

Feel free to contribute to the project by submitting pull requests or creating issues for bugs and feature requests.

License

This project is licensed under the MIT License. See LICENSE.md.

Disclaimer

This client library is not officially affiliated with ICANN or the CZDS. Its purpose is to streamline access to data provided by the CZDS.

Documentation

Overview

Package czds provides a Go client for interacting with the ICANN Centralized Zone Data Service (CZDS). It simplifies the process of querying CZDS to obtain zone files and lists the Top-Level Domains (TLDs). The client supports JWT authentication with an in-memory store by default and implements a refetching mechanism for the token if it doesn't exist, is invalid, or has expired. Users can provide a custom JWT token store by implementing the TokenStore interface. The client facilitates querying CZDS for zone file data, mapping the data by domain name and the associated DNS records. Additionally, it allows for listing TLDs available on the account and their status, providing a comprehensive tool for interacting with CZDS.

Index

• type Client
  • func NewClient(email, password string, opts ...ClientOption) *Client
  • func (c *Client) GetZoneFile(ctx context.Context, tld string) (map[string][]string, error)
  • func (c *Client) ListTLDs(ctx context.Context) ([]TLD, error)
• type ClientOption
  • func CZDSAPIBaseURL(baseURL string) ClientOption
  • func ICANNAccountsAPIBaseURL(baseURL string) ClientOption
  • func TokenStoreOpt(store TokenStore) ClientOption
• type InMemoryTokenStore
  • func (ts *InMemoryTokenStore) Get() string
  • func (ts *InMemoryTokenStore) Save(token string) error
• type Options
• type TLD
• type TokenStore

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a client for interacting with the ICANN Centralized Zone Data Service (CZDS).

func NewClient

func NewClient(email, password string, opts ...ClientOption) *Client

NewClient initialises and returns a new Client instance for interacting with the ICANN Centralized Zone Data Service (CZDS). It accepts email and password for authentication, enabling the client to obtain domain information from TLD zone files, list TLDs to allow to check their approval status for the account. If no TokenStore is provided, a new in-memory token store will be used by default, allowing for automatic management of JWT tokens.

func (*Client) GetZoneFile

func (c *Client) GetZoneFile(ctx context.Context, tld string) (map[string][]string, error)

GetZoneFile fetches and parses a zone file for a given TLD from the ICANN CZDS API. It requires a context for operation cancellation, a JWT for authorization, and the TLD name. The function returns a map of domain names to their records. An error is returned if the operation fails at any stage, including request creation, HTTP communication, decompression, or file parsing. It handles gzip-compressed zone files and expects authorized access to the requested zone file.

func (*Client) ListTLDs

func (c *Client) ListTLDs(ctx context.Context) ([]TLD, error)

type ClientOption

type ClientOption func(*Options)

func CZDSAPIBaseURL

func CZDSAPIBaseURL(baseURL string) ClientOption

func ICANNAccountsAPIBaseURL

func ICANNAccountsAPIBaseURL(baseURL string) ClientOption

func TokenStoreOpt

func TokenStoreOpt(store TokenStore) ClientOption

type InMemoryTokenStore

type InMemoryTokenStore struct {
	// contains filtered or unexported fields
}

InMemoryTokenStore implements TokenStore to provide an in-memory storage mechanism for JWT tokens.

func (*InMemoryTokenStore) Get

func (ts *InMemoryTokenStore) Get() string

Get retrieves the stored JWT token from the in-memory store.

func (*InMemoryTokenStore) Save

func (ts *InMemoryTokenStore) Save(token string) error

Save stores the given JWT token in the in-memory store.

type Options

type Options struct {
	// contains filtered or unexported fields
}

type TLD

type TLD struct {
	Name          string `json:"tld"`
	Ulable        string `json:"ulable"`
	CurrentStatus string `json:"currentStatus"`
	SFTP          bool   `json:"sftp"`
}

type TokenStore

type TokenStore interface {
	Save(token string) error
	Get() string
}

TokenStore defines an interface for JWT storage solutions. It allows clients to implement their own mechanism for storing JWT tokens, facilitating a flexible approach to token management. The Save method is designed to be called by the client when the provided JWT token has expired or does not exist in the storage. This design abstracts the complexities of token persistence away from the client, allowing the client to focus solely on how and where to store the JWT. Through this interface, clients can tailor their storage strategy to fit their application's needs, whether that involves in-memory caching, database storage, or any other persistent storage solution. The goal is to minimise token refetching by efficiently managing token expiration and renewal, streamlining the authentication process.