HTTPDNS:Using HTTPDNS in iOS native scenarios

3.1 Plain HTTP scenarios

For plain HTTP requests, there is no TLS/SSL handshake or certificate verification in the network link. Therefore, 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, you can 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, you can 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 the SNI mechanism or contain only a few fixed domain names (the certificate covers only these domains), you can integrate HTTPDNS and perform certificate verification 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, you can 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. Hooking the certificate verification process

   • Because this is an HTTPS request, certificate verification 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 issue occurs.

   • In the NSURLSessionDelegate callback method URLSession:didReceiveChallenge:completionHandler:, when you verify the serverTrust obtained from the system, you can replace the IP address with the original domain name (example.com). This allows the certificate verification to pass.

   • 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 verification failed. Use the default handler.
                 completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
             }
         } else {
             completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
         }
     }
     
     - (BOOL)evaluateServerTrust:(SecTrustRef)serverTrust forDomain:(NSString *)domain {
         // Create a certificate verification 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 verification policy to the server certificate.
         SecTrustSetPolicies(serverTrust, (__bridge CFArrayRef) policies);
         // Evaluate whether the current serverTrust is trusted. Apple recommends that the 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 Custom NSURLProtocol implementation

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

1. Intercept requests

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

   • In the startLoading method, you can replace the domain name in the original request URL with the IP address. You must retain the original domain name for subsequent certificate verification and SNI settings.

2. Set SNI

   • Using CFStream-related APIs or the SecureTransport interface, you can specify kCFStreamSSLPeerName as the original domain name. This ensures that the underlying layer includes the correct domain name information during the SSL handshake phase.

3. Verify certificates

   • You can manually execute the certificate verification process to ensure that the domain name included in the certificate matches the original domain name.

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

4.2 Using libcurl for network requests

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 completes certificate verification in scenarios where multiple domain names share the same IP address. The general process is as follows:

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

   • For example, you can use an HTTPDNS API operation such as resolveHostSyncNonBlocking: to obtain the IP address of the target domain name.

2. Configure the SNI and IP mapping.

   • Use CURLOPT_RESOLVE or other APIs to add the "domain:port:resolved_IP" mapping to curl's internal DNS cache.

   • Continue to use the original domain name for CURLOPT_URL. This ensures that the correct domain name is included in the TLS handshake.

3. Verify certificates.

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

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

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

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

1. Installation and interception

   • It provides two main usage methods: 1) Intercept an NSURLSession created with a specific NSURLSessionConfiguration. 2) Intercept the system's global [NSURLSession sharedSession].

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

2. Integration with HTTPDNS

   • You can implement the EMASCurlProtocolDNSResolver protocol to pass the HTTPDNS resolution result to EMASCurl.

   • In the resolveDomain: method, you can call [HttpDnsService resolveHostSyncNonBlocking:] to obtain the IP address. Then, you can return the IP address to EMASCurl to complete the subsequent SNI setting and request sending.

3. Certificate verification

   • EMASCurl relies on the certificate verification mechanism of libcurl. Developers can also extend or customize certificate verification through corresponding interfaces to meet business requirements.

4. HTTP/3 support

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