How UEFI Network Applications Resolve Domain Names

UEFI network applications resolve domain names by utilizing the standard Domain Name System (DNS) protocol implemented within the pre-boot firmware network stack. By leveraging modular drivers that expose dedicated DNS protocols—specifically EFI_DNS4_PROTOCOL and EFI_DNS6_PROTOCOL—UEFI applications such as HTTP Boot, PXE, and custom pre-boot utilities can translate human-readable hostnames into IPv4 or IPv6 addresses. This article explains how the UEFI network architecture integrates DNS services, the role of Service Binding Protocols, the asynchronous query resolution process, and how server configurations are managed.

The UEFI Network Stack Hierarchy

The UEFI network architecture is organized into layered, modular drivers built on top of the Simple Network Protocol (SNP). DNS resolution operates at the higher layer of this stack:

  1. Hardware & Link Layer: Simple Network Protocol (SNP) and Managed Network Protocol (MNP).
  2. Network Layer: EFI_IP4_PROTOCOL and EFI_IP6_PROTOCOL, supported by Address Resolution Protocol (ARP).
  3. Transport Layer: EFI_UDP4_PROTOCOL and EFI_UDP6_PROTOCOL handle the transport of DNS messages over standard UDP port 53.
  4. Application Layer: EFI_DNS4_PROTOCOL and EFI_DNS6_PROTOCOL provide high-level APIs for name resolution directly to UEFI applications.

Initializing the DNS Service

Before an application can query a domain name, it must obtain an instance of the DNS protocol. UEFI uses the Service Binding Protocol pattern to manage multiple instances of network drivers.

  1. Locating the Service Binding Protocol: The application calls the UEFI Boot Services function LocateHandleBuffer() or OpenProtocol() to find the EFI_DNS4_SERVICE_BINDING_PROTOCOL or EFI_DNS6_SERVICE_BINDING_PROTOCOL.
  2. Creating a Child Handle: The application invokes CreateChild() on the service binding interface. This creates a new controller handle and instantiates a private session with its own state and configuration.
  3. Opening the DNS Protocol: The application binds to the EFI_DNS4_PROTOCOL or EFI_DNS6_PROTOCOL interface installed on the newly generated child handle.

DNS Client Configuration

The DNS client instance must know which DNS servers to query and how to route traffic. The application configures the protocol using the Configure() function, passing an EFI_DNS4_CONFIG_DATA or EFI_DNS6_CONFIG_DATA structure. This configuration includes:

  • DNS Server Addresses: A list of one or more DNS server IP addresses. These addresses are typically obtained automatically during network boot initialization via DHCP (Option 6 for IPv4, Option 23 for IPv6) or hardcoded via static firmware configurations.
  • UseDefaultSetting Flag: Determines whether the DNS client pulls configuration parameters directly from the underlying IP configuration environment.
  • Protocol and Port Settings: Configures timeout values, retry counts, and local port binding settings.

The Resolution Process: HostNameToIp()

Once configured, the application initiates name resolution by calling the protocol's primary lookup function, HostNameToIp().

  1. Building the Request: The application passes the target hostname as a null-terminated string and provides an asynchronous event token (EFI_DNS4_COMPLETION_TOKEN or EFI_DNS6_COMPLETION_TOKEN).
  2. Asynchronous Execution: UEFI is fundamentally single-threaded and cooperative. The lookup function sets up an internal timer and sends standard RFC 1035 UDP queries via the underlying UDP protocol. It does not block execution; instead, it signals the completion token’s Event when a reply arrives or a timeout occurs.
  3. Event Polling: The calling application can either register a notification callback function on the event or use gBS->WaitForEvent() to halt execution until the DNS transaction completes.
  4. Parsing the Response: When the DNS server responds, the UEFI DNS driver validates the transaction ID, parses the resource records (Record Type A for IPv4, AAAA for IPv6), and copies the resolved IP addresses into the memory buffer referenced by the completion token.
  5. Return Status: If successful, the driver returns EFI_SUCCESS, and the application retrieves an array of matching IP addresses. Common error codes include EFI_TIMEOUT (server unresponsive) and EFI_DEVICE_ERROR (protocol or network failures).

Cleanup and Resource Destruction

After the IP addresses are obtained, the application cleans up its allocated network resources:

  1. Releasing the Interface: The application calls Configure(NULL) to reset and clear the internal state of the DNS session.
  2. Destroying the Child Instance: The application calls DestroyChild() on the original EFI_DNS4_SERVICE_BINDING_PROTOCOL interface to free the handle and underlying memory allocations, preventing resource leaks in the pre-boot environment.