:Integrate DoH into a HarmonyOS application

1. Introduction

On the HarmonyOS platform, we recommend that you connect by using the HarmonyOS SDK. For more information, see the HarmonyOS SDK Manual or . If you cannot import the SDK, you can connect by using DoH. The following network libraries and components are supported:

• Network Kit (httpRequest)

• Remote Communication Kit (RCP)

• ArkWeb (WebView)

2. Prerequisites

Before you connect by using DoH, make sure that you have configured the DoH service.

3. Connect to DoH using Network Kit (httpRequest)

To enable DoH for a single Network Kit request, set the options.dnsOverHttps: string parameter of http.request(options: <a href="https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-http#httprequestoptions" id="fa498210ee5q6">http.RequestOptions</a>) to your DoH endpoint. This does not modify the global session.

import http from '@ohos.net.http'; 
const httpRequest: http.HttpRequest = http.createHttp();
 // Replace this with your DoH URL
const DOH_ENDPOINT = 'https://xxxxx.aliyunhttpdns.com/dns-query';

const isDoHFailure = (err: ErrorDetails): boolean => {
  const code = String(err.code ?? '');
  const msg = String(err.message ?? '');
  return /(couldn'?t\s+resolve\s+host\s+name|resolve\s+host\s+name|dns|resolve|name\s*not\s*resolved|EAI_AGAIN)/i.test(msg) || /DNS/i.test(code);
};

httpRequest.request(this.urlInput, {
  method: http.RequestMethod.GET,
  connectTimeout: 3000,
  readTimeout: 3000,
  dnsOverHttps: DOH_ENDPOINT,
}).then((res: http.HttpResponse) => {
  console.log('DoH request success:', res);
}).catch((err: ErrorDetails) => {
  if (isDoHFailure(err)) {
    console.error('DoH request error, falling back to local DNS:', err);
    httpRequest.request(this.urlInput, {
      method: http.RequestMethod.GET,
      connectTimeout: 3000,
      readTimeout: 3000,
    }).then((fallbackRes: http.HttpResponse) => {
      console.log('Fallback request success:', fallbackRes);
    }).catch((fallbackErr: ErrorDetails) => {
      console.error('Fallback request error:', fallbackErr);
    });
  } else {
    console.error('Request error:', err);
  }
});

4. Connect to DoH using Remote Communication Kit (RCP)

RCP supports DoH at two levels of granularity: global Session and individual Request.

4.1 Connect to DoH at the session level

To enable DoH at the session level, specify your DoH endpoint in SessionConfiguration.requestConfiguration.dns.<a href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/remote-communication-rcp-V5#section13705867403" id="424c1e44d83tg">dnsOverHttps</a>. This does not modify the global session.

import { rcp } from '@kit.RemoteCommunicationKit';
import type { BusinessError } from '@ohos.base';
private isDoHFailure(err: BusinessError): boolean {
    const code: string = err.code ? String(err.code) : '';
    const msg: string =  String(err.data);
    return /(couldn'?t\s+resolve\s+host\s+name|resolve\s+host\s+name|dns|resolve|name\s*not\s*resolved|EAI_AGAIN)/i.test(msg) || /DNS/i.test(code);
  }
  
 async sendRequest() {
    try {
      const dohConfig: rcp.DnsOverHttpsConfiguration = {
        url: 'https://xxxxx.aliyunhttpdns.com/dns-query',
        skipCertificatesValidation: false,
      };

      const dohSession = rcp.createSession({
        requestConfiguration: {
          dns: { dnsOverHttps: dohConfig },
          transfer: { timeout: { connectMs: 3000, transferMs: 8000 } },
        },
      });

      const resp = await dohSession.get(this.urlInput);
      console.info('DoH request success, status=', resp.statusCode);
      console.info('Response:', JSON.stringify(resp));
    } catch (err) {
      if (this.isDoHFailure(err)) {
        console.error('DoH request error, falling back to local DNS:', err);
        try {
          const localSession = rcp.createSession({
            requestConfiguration: { transfer: { timeout: { connectMs: 3000, transferMs: 8000 } } },
          });
          const fb = await localSession.get(this.urlInput);
          console.info('Fallback (local DNS) success, status=', fb.statusCode);
          console.info('Fallback response:', JSON.stringify(fb));
        } catch (fallbackErr) {
          console.error('Fallback (local DNS) request error:', fallbackErr);
        }
      } else {
        console.error('Request error (non-DoH):', err);
      }
    }
  }

4.2 Connect to DoH at the request level

To enable DoH for a single RCP request, specify request.configuration.dns.<a href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/remote-communication-rcp-V5#section9677185417382" id="da462d45103k9">dnsOverHttps</a> as the DoH endpoint. This does not modify the global session.

import { rcp } from '@kit.RemoteCommunicationKit';
import type { BusinessError } from '@ohos.base';


  async sendRequest() {
    try {
      const dohConfig: rcp.DnsOverHttpsConfiguration = {
        url: 'https://xxxxx.aliyunhttpdns.com/dns-query',
        skipCertificatesValidation: false,
      };

      const session = rcp.createSession({
        requestConfiguration: {
          transfer: { timeout: { connectMs: 3000, transferMs: 8000 } },
        },
      });

      const perReq = new rcp.Request(this.urlInput, 'GET', undefined, undefined, undefined, undefined, {
        dns: { dnsOverHttps: dohConfig },
      });

      const resp = await session.fetch(perReq);
      console.info('DoH request success, status=', resp.statusCode);
      console.info('Response:', JSON.stringify(resp));
    } catch (err) {
      if (this.isDoHFailure(err)) {
        console.error('DoH request error, falling back to local DNS:', err);
        try {
          const localSession = rcp.createSession({
            requestConfiguration: { transfer: { timeout: { connectMs: 3000, transferMs: 8000 } } },
          });
          const fb = await localSession.get(this.urlInput);
          console.info('Fallback (local DNS) success, status=', fb.statusCode);
          console.info('Fallback response:', JSON.stringify(fb));
        } catch (fallbackErr) {
          console.error('Fallback (local DNS) request error:', fallbackErr);
        }
      } else {
        console.error('Request error (non-DoH):', err);
      }
    }
  }

5. DoH policy for WebView

Specify your DoH URL by using webview.WebviewController.setHttpDns.

import { webview } from '@kit.ArkWeb';
webview.WebviewController.setHttpDns(webview.SecureDnsMode.AUTO, 'https://xxxxx.aliyunhttpdns.com/dns-query');

6. Summary

Integrating DoH with the HarmonyOS network library improves the security and privacy of your application. After you complete the configuration, you can verify that DoH works correctly by setting the DNS server for your phone's Wi-Fi network to an invalid address and checking whether your application can still make requests.