The OpenDNS Network Devices API Developer Hub

Welcome to the OpenDNS Network Devices API developer hub. You'll find comprehensive guides and documentation to help you start working with OpenDNS Network Devices API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Identifying DNS traffic

After a successful registration, the device will receive a Device ID. This should be added to the DNS packet to create an EDNS0 packet. The format of EDNS0 packets is specified by RFC2671, with some specifics below.

Note that the only piece of information that is required on the device itself is the Device ID. If desired, the actual registration can be done by a separate configuration utility using the device’s details (model, MAC address, label, and serial number). The resulting Device ID can then be passed to the device for future use. If the device itself is doing the registration, then each device will also need the API key and API token. The API key can be set for all devices, but the API token will need to be obtained from the specific customer dashboard and transferred to each device in some way.

OPT RR description

Field
Type
Description

Name

Domain Name

Empty (root domain, 0)

Type

u_int16

OPT (41)

Class

u_int16

Sender’s UDP payload size (default 512; Umbrella supports up to 4096)

TTL

u_int32

Extended RCODE and flags (default 0)

RDLEN

u_int16

Combined size in bytes of RDATA options

RDATA

octet stream

One or two RDATA options, formatted in {attribute,value} pairs

RDATA description

Two RDATA options can be sent. The first (option code 0x6942) identifies the network device and is mandatory. The second (option code 0x4F44) identifies the local IP address originating the DNS query. RDATA option code 0x6942 can be sent without 0x4F44, but 0x4F44 should not be sent without 0x6942.
Policy can be applied to the network device RDATA, whereas the local IP address is for visibility and reporting only.

Field
Type
Description

OPTION-CODE

u_int16

Option Code (Umbrella accepts ‘0x6942’, or 26946 in decimal)

OPTION-LENGTH

u_int16

Size in octets of OPTION-DATA (15 bytes)

OPTION-DATA

Various

Data (“OpenDNS” + 8 octets of Device ID)

If the Device ID returned from the Register call is “0123456789abcdef”, RDATA would consist of the following array of bytes:

[ 0x69, 0x42, 0x00, 0x0F, 0x4F, 0x70, 0x65, 0x6E, 0x44, 0x4E, 0x53, 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF ]

Remote IP Address RDATA (optional)

Field
Type
Description

OPTION-CODE

u_int16

ODNS_AD (0x4F44)

OPTION-LENGTH

u_int16

Size in octets of OPTION-DATA

OPTION-DATA

Octet stream

As per below

Remote IP address OPTION-DATA:

Initial header (6B) is composed of a 4B "magic value", a 1B VERSION field and a 1B FLAGS field.

  • MAGIC is a value used to help distinguish an EDNS0 message using Umbrella’s OPTION-CODE from a message from another source that happens to use that same OPTION-CODE. The value of this field should always be 0x4F444E53 ("ODNS").
  • VERSION should be 0x00
  • FLAGS should be 0x00
    After the header each additional field will start with a 1B field type (bit values) followed by a fixed-length value.

Type Length Contents Comments/Restrictions
0x08 4 Organization ID Required.
0x10 4 Remote IPv4 The "internal" site address that's invisible to the DNS resolver
0x20 16 Remote IPv6 The "internal" site address that's usually invisible to the DNS resolver

Organization ID and remote IP are both to be given in network-endian byte order.

For example, if organization ID is 012345678, remote IPv4 is 192.168.1.55, and remote IPv6 is not sent, the OPTION-DATA would consist of the following array of bytes:


Registration API Endpoint < Identifying DNS Traffic

Identifying DNS traffic