3.1.4.6 R_DnssrvOperation2 (Opnum 5)

The R_DnssrvOperation2 method is used to invoke a set of server functions specified by the caller. The DNS server SHOULD implement R_DnssrvOperation2.

All parameters are as specified by the R_DnssrvOperation method (section 3.1.4.1) with the following exceptions:

 LONG R_DnssrvOperation2(
   [in]                               handle_t                    hBindingHandle,
   [in]                               DWORD                       dwClientVersion,
   [in]                               DWORD                       dwSettingFlags,
   [in, unique, string]               LPCWSTR                     pwszServerName,
   [in, unique, string]               LPCSTR                      pszZone,
   [in]                               DWORD                       dwContext,
   [in, unique, string]               LPCSTR                      pszOperation,
   [in]                               DWORD                       dwTypeId,
   [in, switch_is(dwTypeId)]          DNSSRV_RPC_UNION            pData
 );

dwClientVersion: The client version in DNS_RPC_CURRENT_CLIENT_VER (section 2.2.1.2.1) format.

dwSettingFlags: Reserved for future use. MUST be set to zero by clients and MUST be ignored by servers.

pszOperation: In addition to the operations specified in R_DnssrvOperation method, the following operations are specified.

Value

Meaning

SetEncryptionConfig

Specifies encryption configuration for DNS over HTTPS (DoH). The dwTypeId parameter MUST be set to DNSSRV_TYPEID_ENCRYPTION_CONFIG, and pData MUST point to a structure of type DNS_RPC_ENCRYPTION_CONFIG.<281>

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success or a nonzero Win32 error code value if an error occurred. See [MS-ERREF] section 2.2 or section 2.2.1.1.5. All error values MUST be treated the same.

When processing this call, the server MUST perform the same actions as for the R_DnssrvOperation method (section 3.1.4.1) except in the event the dwClientVersion is greater than the server version, in which case the server MUST return the highest version number known to the server.

If pszOperation is set to "SetEncryptionConfig", the server MUST do the following.

§ If dwTypeId is DNSSRV_TYPEID_ENCRYPTION_CONFIG and dwDnsEncryptionType parameter in DNS_RPC_ENCRYPTION_CONFIG contains a value other than specified in section 2.2.4.1.3, the server MUST fail the request with ERROR_INVALID_PARAMETER.

§ If dwTypeId is DNSSRV_TYPEID_ENCRYPTION_CONFIG, dwDnsEncryptionType is set to DnsEncryptionDoH and pwszUriTemplate parameter in DNS_RPC_ENCRYPTION_CONFIG does not conform with any of the following, the server MUST fail the request with ERROR_INVALID_PARAMETER.

§ pwszUriTemplate is NULL or empty string or if any individual URI template does not conform to [RFC8484].

§ pwszUriTemplate exceeds the maximum length specified in section 2.2.4.2.3.

§ pwszUriTemplate MUST contain between one and three non-empty URI template entries separated by the ‘|’ character. 

§ For each template the server MUST further verify,

§ The URI template does not contain URI Template variable expansion syntax as defined in [RFC6570].

§ The host name component of each URI template MUST NOT exceed 255 characters.

§ IPv4 addresses and bracketed IPv6 literal addresses MUST be accepted as the host component of the URI template.

§ Each URI template MUST use the “https” scheme.

§ If a port value is specified in the URI template, the port value MUST be a decimal integer in the range 1 through 65535.

§ Each URI template MUST NOT contain either a query or fragment component.

  • Duplicate URI template entries MUST be treated as a single entry. The presence of duplicate entries MUST NOT cause the operation to fail.

  • If dwTypeId is DNSSRV_TYPEID_ENCRYPTION_CONFIG, the server MUST ignore pszZone parameter.

  • If dwTypeId is DNSSRV_TYPEID_ENCRYPTION_CONFIG, the server MUST perform the following:

    • EnableEncryptedDNSFeatures MUST be set to dwDnsEncryptionType.

      • If dwDnsEncryptionType is set to DnsEncryptionDoH (0x00000001), DNS over HTTPS MUST be enabled on the server using the URI templates derived from pwszUriTemplate. DoHUrlTemplates MUST be set to pwszUriTemplate.

      • If pwszUriTemplate is NULL or an empty string, the server will use its own host name on port 443 with /dns-query as the default URI template. For example,

               https://<DNSServerName>:443/dns-query

      • If dwDnsEncryptionType is set to DnsEncryptionNone (0x00000000), the server MUST ignore pwszUriTemplate parameter. DNS over HTTPS MUST be disabled and DOHUrlTemplates MUST be set to empty.

  • Changes to the DNS encryption configuration are persisted immediately but do not take effect until the DNS Server is restarted.           

  • Last updated on