Using HTTPDNS in iOS native scenarios

1. Introduction

In mobile network environments, issues such as DNS hijacking and local DNS cache pollution often prevent domain names from resolving correctly, which leads to network request failures. For these scenarios, Alibaba Cloud HTTPDNS provides a reliable recursive domain name resolution service. This service helps mobile apps bypass the potential risks of local DNS and improves the success rate and stability of network requests.

However, using HTTPDNS on the iOS platform requires you to replace the original domain name in a request with the resolved IP address before you initiate the request. This can cause additional issues, especially in complex scenarios such as HTTPS and Server Name Indication (SNI). Therefore, before you integrate HTTPDNS, you must have a comprehensive understanding of the potential issues and viable solutions. This ensures that you can use HTTPDNS safely and correctly in your business.

This topic describes the main issues that you may encounter when using HTTPDNS on iOS. It also provides integration solutions for different scenarios, along with their pros and cons, to help developers quickly complete HTTPDNS integration.

2. Issues when using HTTPDNS on iOS

In mobile applications, if you replace the domain name in the original URL, such as example.com, with the IP address resolved by HTTPDNS, you often encounter the following issues. These problems are closely related to how the HTTPS protocol uses the Host field at different layers: the TLS/SSL layer and the HTTP layer.

• TLS/SSL layer: In an HTTPS scenario, the client first performs a TLS/SSL handshake. The client uses the Host from the URL to complete the following tasks:

  1. Certificate verification: Verifies that the domain name of the server certificate (Common Name or Subject Alternative Name) matches the requested Host.

  2. SNI: When establishing a TLS connection, the client sends the requested domain name information (the Host in the URL) to the server. This allows the server to return the corresponding certificate.

• HTTP layer: After the TLS handshake is complete, the client includes the Host field in the HTTP request header. This tells the server the specific site or resource for the request. If you replace the domain name in the URL with an IP address and do not manually set the Host in the HTTP header, the server may not be able to identify the actual domain name being accessed. This can cause the request to fail or return abnormal content.

Based on the role of the Host at various layers of the HTTPS protocol stack, replacing the domain name in the URL with the IP address resolved by HTTPDNS causes the following technical issues:

1. Domain name and certificate mismatch For an HTTPS request, if you directly use the IP address resolved by HTTPDNS as the Host in the URL, the TLS layer cannot match the correct certificate domain name (Common Name or SAN additional domain name). This causes the SSL handshake to fail.

2. SNI issues In an SNI scenario, a single server IP address may correspond to certificates for multiple domain names. If the client does not pass the correct domain name information during the SSL handshake phase and sends only the IP address, the server cannot return a certificate that matches the domain name. This causes the SSL handshake to fail. Because high-level network APIs in iOS, such as NSURLSession, do not expose an interface to directly configure SNI, SNI issues are often difficult to solve with simple methods.

3. Host header and service addressing If you replace the domain name in the URL with an IP address but forget to explicitly set the Host in the HTTP request header to the original domain name, the server-side may not be able to identify the specific site or resource at the HTTP layer. For example, in a CDN scenario, the server relies on the Host field to distribute the correct content. If the Host is an IP address, the service becomes abnormal.

4. Choice of underlying network library The built-in high-level APIs in iOS, such as NSURLSession, have limited extensibility for customizing SNI or manual certificate verification. If a developer wants to handle SNI or modify the TLS handshake logic, they need to use lower-level interfaces, such as CFNetwork or libcurl. However, this increases development and maintenance costs.

In summary, directly replacing the domain name in a URL with the IP address resolved by HTTPDNS affects certificate verification and SNI transmission at the TLS layer in HTTPS scenarios. It may also cause Host header information to be abnormal at the HTTP layer. Therefore, when you integrate HTTPDNS on iOS, you must solve these issues in a targeted manner to ensure the reliability and security of network requests.

3. Recommended solution: Integrate with EMASCurl

In real-world iOS applications, HTTPS is standard, and scenarios involving CDNs, single IPs for multiple domains, and SNI are common. To address these challenges, the Alibaba Cloud EMAS team provides EMASCurl, an iOS network library built on libcurl. It works directly with HTTPDNS and is the recommended solution for implementing a direct IP connection on iOS. The code is open-source and available on GitHub.

This section describes the use cases, integration approach, and usage notes for the EMASCurl solution. For specific installation instructions, interception configurations, and API usage, see the README file on GitHub.

1. Installation and interception

   • It can be used in two main ways:

     1) Intercept requests from an NSURLSession created with a specific NSURLSessionConfiguration.

     2) Intercept requests from the system's global [NSURLSession sharedSession].

2. Integration with HTTPDNS

   • Implement the EMASCurlProtocolDNSResolver protocol to pass the HTTPDNS resolution results to EMASCurl.

   • In the resolveDomain: method, call [HttpDnsService resolveHostSyncNonBlocking:] to get the IP address. Then, return it to EMASCurl to handle the SNI setup and send the request.

3. Certificate verification

   • EMASCurl relies on the certificate verification mechanism of libcurl. You can also extend or customize certificate verification through the provided interfaces to meet your service requirements.

4. HTTP/3 support

   • EMASCurl provides EMASCurl/HTTP3, an encapsulated version based on a QUIC-enabled libcurl. You can integrate it as needed to use HTTP/3 capabilities without extra adaptation.

The following example shows the basic method for integrating EMASCurl with HTTPDNS:

@interface MyDNSResolver : NSObject <EMASCurlProtocolDNSResolver>
@end

@implementation MyDNSResolver

+ (nullable NSString *)resolveDomain:(nonnull NSString *)domain {
    HttpDnsService *httpdns = [HttpDnsService sharedInstance];
    HttpdnsResult *result = [httpdns resolveHostSyncNonBlocking:domain
                                                      byIpType:HttpdnsQueryIPTypeBoth];
    if (!result || (!result.hasIpv4Address && !result.hasIpv6Address)) {
        return nil;
    }

    NSMutableArray<NSString *> *allIPs = [NSMutableArray array];
    if (result.hasIpv4Address) {
        [allIPs addObjectsFromArray:result.ips];
    }
    if (result.hasIpv6Address) {
        [allIPs addObjectsFromArray:result.ipv6s];
    }
    return [allIPs componentsJoinedByString:@","];
}

@end

- (void)setupEMASCurl {
    EMASCurlConfiguration *config = [EMASCurlConfiguration defaultConfiguration];

    // Configure the HTTPDNS resolver
    config.dnsResolver = [MyDNSResolver class];

    NSURLSessionConfiguration *sessionConfig = [NSURLSessionConfiguration defaultSessionConfiguration];

    // Install EMASCurl
    [EMASCurlProtocol installIntoSessionConfiguration:sessionConfig
                                    withConfiguration:config];

    // Create a specific session
    self.session = [NSURLSession sessionWithConfiguration:sessionConfig];
    
    // Use this session for subsequent requests
}

4. Integration solutions for simplified scenarios

For plain HTTP or HTTPS without SNI scenarios, you can typically continue to use the system's built-in NSURLSession and regular network request logic to integrate HTTPDNS with simple adjustments. These solutions are simpler to implement, suitable for specific scenarios, and have limited applicability.

Note that plain HTTP scenarios do not involve a TLS handshake or certificate verification. However, HTTPS without SNI scenarios still require you to handle certificate verification, which you can do by hooking the verification process in NSURLSession.

5. Other solutions for HTTPS + SNI scenarios

For HTTPS + SNI scenarios, besides EMASCurl, you can also implement HTTPDNS integration by using lower-level capabilities. These solutions typically offer greater flexibility but come with higher development and maintenance costs. They are better suited for scenarios with existing custom network stacks, a need for stronger low-level control, or cross-platform unification requirements. If you do not have special requirements, we recommend using the EMASCurl solution.

CURL *curl_handle = curl_easy_init();
if (curl_handle) {
    // For example, get IP = 1.2.3.4 from HTTPDNS, target domain = example.com, and port = 443
    struct curl_slist *dnsResolve = NULL;
    dnsResolve = curl_slist_append(dnsResolve, "example.com:443:1.2.3.4");
    // Set the domain-to-IP mapping
    curl_easy_setopt(curl_handle, CURLOPT_RESOLVE, dnsResolve);

    // Continue to use the original domain as the URL
    curl_easy_setopt(curl_handle, CURLOPT_URL, "https://example.com");

    // Enable SSL verification
    curl_easy_setopt(curl_handle, CURLOPT_SSL_VERIFYPEER, 1L);
    curl_easy_setopt(curl_handle, CURLOPT_SSL_VERIFYHOST, 2L);

    // Initiate the request
    CURLcode res = curl_easy_perform(curl_handle);

    // Check the result
    if (res != CURLE_OK) {
        fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
    }

    // Clean up
    curl_easy_cleanup(curl_handle);
    curl_slist_free_all(dnsResolve);
}

6. Summary

You can choose a solution based on your business needs, such as whether you need to support SNI, multiple domain names, and certificate verification. The following table compares the different solutions:

You can evaluate these solutions based on your business's multi-domain needs, network security requirements, compatibility, maintenance costs, and acceptance of third-party libraries. You must choose the most suitable integration solution and thoroughly test the availability and security of network requests before the solution is published.