HTTPDNS:Use HTTPDNS in native iOS scenarios

3.1 Plain HTTP scenarios

For plain HTTP requests, the network path does not involve a TLS/SSL handshake or certificate validation. The core operation for integrating HTTPDNS is performed only at the HTTP layer:

1. Replace the Host in the request URL with the IP address resolved by HTTPDNS.

   • For example, if the original request URL is http://example.com/api and HTTPDNS resolves it to the IP address 1.2.3.4, change the URL to http://1.2.3.4/api.

2. Explicitly set the Host in the HTTP header to the original domain name.

   • If you use NSMutableURLRequest, add request.allHTTPHeaderFields[@"Host"] = @"example.com"; to the request header. This ensures that the server can identify the correct domain name at the application layer.

3.2 HTTPS non-SNI scenarios

For HTTPS sites that do not use SNI or that use a certificate covering only a few fixed domain names, you can integrate HTTPDNS and perform certificate validation at the NSURLSession layer as follows:

1. Replace the Host in the request URL with the IP address resolved by HTTPDNS.

   • For example, if the original request URL is https://example.com/api and HTTPDNS resolves it to the IP address 1.2.3.4, change the URL to https://1.2.3.4/api.

2. Explicitly set the Host in the HTTP header to the original domain name.

   • Similarly, you can set request.allHTTPHeaderFields[@"Host"] = @"example.com"; in NSMutableURLRequest.

3. Hook the certificate validation process.

   • Because this is an HTTPS request, certificate validation is required during the TLS handshake. At this point, if you directly use the IP address as the Host for the check, a domain name and certificate mismatch problem occurs.

   • In the NSURLSessionDelegate callback method URLSession:didReceiveChallenge:completionHandler:, when you validate the serverTrust object, replace the IP address with the original domain name, such as example.com. This allows the request to pass certificate validation.

   • Code example:

     - (void)URLSession:(NSURLSession *)session
                   task:(NSURLSessionTask *)task
     didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge
       completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition,
                                   NSURLCredential *credential))completionHandler {
         if ([challenge.protectionSpace.authenticationMethod isEqualToString:NSURLAuthenticationMethodServerTrust]) {
             NSString *originalHost = [self getOriginalHostFromRequest:task.originalRequest];
             SecTrustRef serverTrust = challenge.protectionSpace.serverTrust;
             if ([self evaluateServerTrust:serverTrust forDomain:originalHost]) {
                 // The certificate is verified.
                 NSURLCredential *credential = [NSURLCredential credentialForTrust:serverTrust];
                 completionHandler(NSURLSessionAuthChallengeUseCredential, credential);
             } else {
                 // Certificate validation failed. Use the default handler.
                 completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
             }
         } else {
             completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
         }
     }
     
     - (BOOL)evaluateServerTrust:(SecTrustRef)serverTrust forDomain:(NSString *)domain {
         // Create a certificate validation policy.
         NSMutableArray *policies = [NSMutableArray array];
         if (domain) {
             [policies addObject:(__bridge_transfer id) SecPolicyCreateSSL(true, (__bridge CFStringRef) domain)];
         } else {
             [policies addObject:(__bridge_transfer id) SecPolicyCreateBasicX509()];
         }
     
         // Bind the validation policy to the server certificate.
         SecTrustSetPolicies(serverTrust, (__bridge CFArrayRef) policies);
         // Evaluate whether the current serverTrust is trusted. Apple recommends that serverTrust can be verified if the result is kSecTrustResultUnspecified or kSecTrustResultProceed. For more information, see https://developer.apple.com/library/ios/technotes/tn2232/_index.html.
         // For more information about SecTrustResultType, see SecTrust.h.
         SecTrustResultType result;
         SecTrustEvaluate(serverTrust, &result);
         return (result == kSecTrustResultUnspecified || result == kSecTrustResultProceed);
     }

4.1 Implement a custom NSURLProtocol

iOS allows developers to intercept network requests initiated by the system by inheriting from NSURLProtocol. You can then implement the HTTP/HTTPS request logic at a lower level. You can use interfaces such as CFNetwork or NSInputStream/NSOutputStream to manually handle all network operations:

1. Intercept requests

   • In the canInitWithRequest: method, determine whether to intercept the current request.

   • In the startLoading method, replace the domain name in the original request URL with the IP address. Retain the original domain name for subsequent certificate validation and SNI settings.

2. Set SNI

   • Use CFStream-related APIs or the SecureTransport interface to specify kCFStreamSSLPeerName as the original domain name. This ensures that the underlying layer will include the correct domain name information during the SSL handshake.

3. Certificate validation

   • Manually perform the certificate validation process to ensure that the domain name in the certificate matches the original domain name.

For a reference example, Alibaba Cloud provides the HttpDnsNSURLProtocolImpl.m sample implementation in the httpdns_ios_demo. You can modify or reuse it as needed.

4.2 Implement network requests using libcurl

libcurl is a cross-platform network library implemented in C. It supports manually setting the SNI field to pass the correct domain name information during the SSL handshake. This allows for successful certificate validation in scenarios where multiple domain names share the same IP address. The general process is as follows:

1. Resolve the domain name to retrieve the corresponding IP address.

   • For example, use an API provided by HTTPDNS, such as resolveHostSyncNonBlocking:, to retrieve the IP address of the target domain name.

2. Set the SNI and IP mapping.

   • Use CURLOPT_RESOLVE or another API to write the "domain:port:resolved IP" mapping to the internal DNS cache of curl.

   • Continue to use the original domain name as the access target for CURLOPT_URL. This ensures that the correct domain name information is included during the TLS handshake.

3. Certificate validation

   • libcurl enables certificate validation by default. You can also use corresponding callbacks for more fine-grained checks on the certificate as needed.

The following core code snippet (pseudocode) shows how to use the result of an HTTPDNS resolution to complete a request through libcurl in iOS:

CURL *curl_handle = curl_easy_init();
if (curl_handle) {
    // For example, get IP = 1.2.3.4 from HTTPDNS, target domain = example.com, 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 name 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);
}

4.3 Use EMASCurl

To lower the barrier to entry for using libcurl directly on iOS, the Alibaba Cloud EMAS team provides the EMASCurl library. It wraps libcurl and supports direct integration with HTTPDNS.

1. Installation and interception

   • Provides two main ways to use it: 1) Intercept NSURLSession created from a specified NSURLSessionConfiguration. 2) Intercept the system's global [NSURLSession sharedSession].

   • For API information, see the README file on GitHub.

2. Integration with HTTPDNS

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

   • In the resolveDomain: method, call [HttpDnsService resolveHostSyncNonBlocking:] to retrieve the IP address. Then, return it to EMASCurl to complete the subsequent SNI settings and request sending.

3. Certificate validation

   • EMASCurl relies on the certificate validation mechanism of libcurl. You can also extend or customize certificate validation through corresponding interfaces to meet your service needs.