aiodnsprox package

Subpackages

aiodnsprox.coap module

DNS over CoAP serving side of the proxy.

class aiodnsprox.coap.DNSOverCoAPServerFactory(dns_upstream: DNSUpstream)[source]

Bases: BaseServerFactory

Factory to create DNS over CoAP servers

class ClosableContext(loop=None, serversite=None, loggername='coap', client_credentials=None, server_credentials=None)[source]

Bases: Context, BaseDNSServer

aiocoap.Context that also serves as an extension of dns_server.BaseDNSServer so it can be returned by DNSOverCoAPServerFactory.create_server()

async close()[source]

Closes the server.

class DNSQueryResource(factory)[source]

Bases: Resource

The DNS over CoAP resource of the DNS over CoAP server.

Parameters:

factory (DNSOverCoAPServerFactory) – The factory that created the DNS over CoAP server.

async render_fetch(request)[source]

aiocoap.resource.Resource method to serve a FETCH request

Parameters:

request – The FETCH request

Returns:

The response for the FETCH request.

async render_get(request)[source]

aiocoap.resource.Resource method to serve a GET request

Parameters:

request – The GET request

Returns:

The response for the GET request.

async render_post(request)[source]

aiocoap.resource.Resource method to serve a POST request

Parameters:

request – The POST request

Returns:

The response for the POST request.

async create_server(loop, *args, local_addr=None, **kwargs)[source]

Creates an aiocoap server context.

Parameters:

  • loop (asyncio.AbstractEventLoop) – the asyncio event loop the server should run in

  • local_addr (typing.Tuple[str, int]) – A tuple for the created server to bind to. The first element is the host part, the second element the port.

Returns:

An ClosableContext object representing an aiocoap server context.

Return type:

ClosableContext

exception aiodnsprox.coap.NotAcceptable(message=None)[source]

Bases: ConstructionRenderableError

Exception to represent a 4.06 Not Acceptable CoAP error response

code = <Response Code 134 "4.06 Not Acceptable">

Code assigned to messages built from it

aiodnsprox.config module

Proxy configuration

class aiodnsprox.config.Config(*args, **kwargs)[source]

Bases: object

Singleton Config mapping class to represent both config file and CLI argument congfiguration.

add_args_config(args) → NoReturn[source]

Adds configuration from CLI arguments

Parameters:

args (argparse.Namespace) – parsed CLI arguments.

add_config(config: Mapping) → NoReturn[source]

Adds configuration from a mapping

Parameters:

config (typing.Mapping.) – A mapping that contains the new configuration sections.

add_yaml_config(yaml_file) → NoReturn[source]

Adds configuration from a YAML file

Parameters:

yaml (A file-like object.) – A file-like object to a YAML file.

get(section: str, default=None) → Mapping[source]

Get configuration section.

Parameters:

  • key (str) – Name of the configuration section.

  • default – (Optional) default if section does not exist.

aiodnsprox.dns_server module

Base definitions for the serving side of the DNS proxy

class aiodnsprox.dns_server.BaseDNSServer[source]

Bases: ABC

An abstract DNS server.

abstract async close() → NoReturn[source]

Closes the server.

class aiodnsprox.dns_server.BaseServerFactory(dns_upstream: DNSUpstream)[source]

Bases: ABC

Abstract BaseDNSServer factory.

Parameters:

dns_upstream – The proxied DNS server for dns_upstream.DNSUpstreamServerMixin.

abstract async create_server(loop: AbstractEventLoop, *args, local_addr: Tuple[str, int] | None = None, **kwargs) → BaseDNSServer[source]

Creates a BaseDNSServer object.

Parameters:

  • loop (asyncio.AbstractEventLoop) – the asyncio event loop the server should run in

  • local_addr (typing.Tuple[str, int]) – A tuple for the created server to bind to. The first element is the host part, the second element the port. If local_addr is None or any of its elements are local_addr are None, a sensible default is selected by the implementation.

Returns:

An object based on the BaseDNSServer class.

Return type:

BaseDNSServer

aiodnsprox.dns_upstream module

Implementation of the proxying side of the DNS proxy.

class aiodnsprox.dns_upstream.DNSTransport(value)[source]

Bases: Enum

Type to identify the server proxied via DNSUpstream.

  • TCP for DNS over TCP

  • UDP for DNS over UDP

  • UDP_TCP_FALLBACK for DNS over UDP with a fallback to DNS over TCP in case the DNS over UDP response is truncated

TCP = 2
UDP = 0
UDP_TCP_FALLBACK = 1
class aiodnsprox.dns_upstream.DNSUpstream(host: str, port: int | None = None, transport: DNSTransport | None = DNSTransport.UDP)[source]

Bases: object

Implementation of the DNS client towards the proxied DNS server

Parameters:

  • host (str) – Host of the proxied DNS server

  • port (int) – (Optional) port of the proxied DNS server. If no port is provided, the default of the selected transport will be used (e.g. 53 for DNSTransport.TCP or DNSTransport.UDP).

  • transport (DNSTransport) – (Optional) transport used to communicate with the proxied DNS server. If no transport is provided, DNSTransport.UDP will be used.

DEFAULT_LIFETIME = 5.0
DEFAULT_TIMEOUT = 2.0
property port

Port of the proxied DNS server

Type:

int

async query(query: bytes, timeout: float | None = None) → bytes[source]

Query proxied DNS server.

Parameters:

  • query (bytes) – DNS query in the on-the-wire format

  • timeout (float) – (Optional) timeout for the DNS query operation. If not provided and the transport to the server is DNSTransport.UDP, DNSUpstream.DEFAULT_LIFETIME will be used.

class aiodnsprox.dns_upstream.DNSUpstreamServerMixin(dns_upstream: DNSUpstream, timeout: float | None = None)[source]

Bases: ABC

Mixin for the serving side of the proxy for easy access towards the proxied side.

Parameters:

  • dns_upstream (DNSUpstream) – The proxied DNS server.

  • timeout (float) – (Optional) timeout for queries towards dns_upstream.

dns_query_received(query: bytes, requester) → NoReturn[source]

The serving end of the proxy notifies that it received a DNS query and sends it to the proxied DNS server. When a response is received asynchronously, send_response_to_requester() is called to notify the serving end about the received response.

Parameters:

  • query (bytes) – The DNS query in on-the-wire format to send to the proxied DNS server.

  • requester – Identifier for the endpoint that originally requested the query.

logger = <Logger aiodnsprox.dns_upstream.aiodnsprox.dns_upstream (WARNING)>
abstract send_response_to_requester(response: bytes, requester) → NoReturn[source]

Called when proxied DNS server responded to a DNS query send by dns_query_received().

Parameters:

  • response – The DNS response in on-the-wire format received from the proxied DNS server.

  • requester – Identifier for the endpoint that originally requested the query. This will have the same value as the requester parameter of dns_query_received() for the query that response is the response to.

class aiodnsprox.dns_upstream.MockDNSUpstream(*args, IN=None, **kwargs)[source]

Bases: DNSUpstream

Mocks an upstream by statically responding with a preconfigured set of records.

Parameters:

IN (dict) – Records for the RDATA class IN. A mapping that maps the name of the record to its data. Currently supported are A and AAAA records.

async query(query: bytes, timeout: float | None = None) → bytes[source]

Query proxied DNS server.

Parameters:

  • query (bytes) – DNS query in the on-the-wire format

  • timeout (float) – (Optional) timeout for the DNS query operation. If not provided and the transport to the server is DNSTransport.UDP, DNSUpstream.DEFAULT_LIFETIME will be used.

aiodnsprox.dtls module

DNS over DTLS serving side of the proxy.

class aiodnsprox.dtls.BaseDTLSWrapper(transport: DatagramTransport)[source]

Bases: ABC

An abstract wrapper for a DTLS implementation

Parameters:

transport (asyncio.DatagramTransport) – The datagram transport the datagrams should be encrypted and decrypted for.

abstract close(addr: Any) → NoReturn[source]

Closes a session with addr.

Parameters:

addr – An (implementation-specific) remote endpoint

abstract connect(addr: Any) → NoReturn[source]

Establish a session with addr.

Parameters:

addr – An (implementation-specific) remote endpoint

abstract handle_message(msg: bytes, addr: Any) → Tuple[bytes, Any, bool][source]

Handles a DTLS message that came over the datagram transport.

Parameters:

  • msg (bytes) – An incoming DTLS message.

  • addr – The remote endpoint as served by the datagram transport.

Returns:

A 3-tuple, containing

  1. The unencrypted message,

  2. The (implementation-specific) remote endpoint the message was received from, an

  3. A boolean, indicating if the last message established a session with the remote endpoint.

If msg was a control message, the first and second elements will be None.

abstract is_connected(addr: Any) → bool[source]

Check if a session with addr was established.

Parameters:

addr – A remote endpoint (implementation-specific)

Returns:

True, when a session with addr is established, False if not.

abstract sessions() → Sequence[source]

Returns all currently established sessions.

Returns:

A sequence of (implementation-specific) remote endpoints with which a session is established.

abstract write(msg: bytes, addr: Any) → NoReturn[source]

Send a msg encrypted to addr

Parameters:

  • msg (bytes) – The message to encrypt via DTLS.

  • addr – An (implementation-specific) remote endpoint to send the encrypted message to.

class aiodnsprox.dtls.DNSOverDTLSServerFactory(dns_upstream: DNSUpstream)[source]

Bases: BaseServerFactory

Factory to create DNS over DLTS servers

class DNSOverDTLSServer(factory)[source]

Bases: BaseDNSServer, DNSUpstreamServerMixin

DNS over DTLS server implementation.

Parameters:

factory (DNSOverDTLSServerFactory) – The factory that created the DNS over DTLS server.

async close()[source]

Closes the server.

connection_lost(exc)[source]

See connection_lost()

connection_made(transport)[source]

See connection_made()

datagram_received(data, addr)[source]

See datagram_received()

error_received(exc)[source]

See error_received()

send_response_to_requester(response, requester)[source]

Called when proxied DNS server responded to a DNS query send by dns_query_received().

Parameters:

  • response – The DNS response in on-the-wire format received from the proxied DNS server.

  • requester – Identifier for the endpoint that originally requested the query. This will have the same value as the requester parameter of dns_query_received() for the query that response is the response to.

DODTLS_PORT = 853
async create_server(loop, *args, local_addr=None, **kwargs)[source]

Creates an DNSOverDTLSServer object.

Parameters:

  • loop (asyncio.AbstractEventLoop) – the asyncio event loop the server should run in

  • local_addr (typing.Tuple[str, int]) – A tuple for the created server to bind to. The first element is the host part, the second element the port.

Returns:

An DNSOverDTLSServer object representing an DNS over DTLS server.

Return type:

DNSOverDTLSServer

dtls_class

alias of TinyDTLSWrapper

class aiodnsprox.dtls.TinyDTLSWrapper(transport)[source]

Bases: BaseDTLSWrapper

A wrapper for tinydtls.

EVENT_CONNECTED = 478
LOG_LEVEL = {10: 6, 20: 5, 30: 3, 40: 2, 50: 0}
close(addr)[source]

Closes a session with addr.

Parameters:

addr – An (implementation-specific) remote endpoint

connect(addr)[source]

Establish a session with addr.

Parameters:

addr – An (implementation-specific) remote endpoint

handle_message(msg, addr)[source]

Handles a DTLS message that came over the datagram transport.

Parameters:

  • msg (bytes) – An incoming DTLS message.

  • addr – The remote endpoint as served by the datagram transport.

Returns:

A 3-tuple, containing

  1. The unencrypted message,

  2. The (implementation-specific) remote endpoint the message was received from, an

  3. A boolean, indicating if the last message established a session with the remote endpoint.

If msg was a control message, the first and second elements will be None.

is_connected(addr)[source]

Check if a session with addr was established.

Parameters:

addr – A remote endpoint (implementation-specific)

Returns:

True, when a session with addr is established, False if not.

sessions()[source]

Returns all currently established sessions.

Returns:

A sequence of (implementation-specific) remote endpoints with which a session is established.

write(msg, addr)[source]

Send a msg encrypted to addr

Parameters:

  • msg (bytes) – The message to encrypt via DTLS.

  • addr – An (implementation-specific) remote endpoint to send the encrypted message to.

aiodnsprox.udp module

DNS over UDP serving side of the proxy.

class aiodnsprox.udp.DNSOverUDPServerFactory(dns_upstream: DNSUpstream)[source]

Bases: BaseServerFactory

Factory to create DNS over UDP servers

class DNSOverUDPServer(factory)[source]

Bases: BaseDNSServer, DNSUpstreamServerMixin

DNS over UDP server implementation

Parameters:

factory (DNSOverUDPServerFactory) – The factory that created the DNS over DTLS server.

async close()[source]

Closes the server.

connection_lost(exc)[source]

See connection_lost()

connection_made(transport)[source]

See connection_made()

datagram_received(data, addr)[source]

See datagram_received()

error_received(exc)[source]

See error_received()

send_response_to_requester(response, requester)[source]

Called when proxied DNS server responded to a DNS query send by dns_query_received().

Parameters:

  • response – The DNS response in on-the-wire format received from the proxied DNS server.

  • requester – Identifier for the endpoint that originally requested the query. This will have the same value as the requester parameter of dns_query_received() for the query that response is the response to.

DNS_PORT = 53
async create_server(loop, *args, local_addr=None, **kwargs)[source]

Creates an DNSOverUDPServer object.

Parameters:

  • loop (asyncio.AbstractEventLoop) – the asyncio event loop the server should run in

  • local_addr (typing.Tuple[str, int]) – A tuple for the created server to bind to. The first element is the host part, the second element the port.

Returns:

An DNSOverUDPServer object representing an DNS over DTLS server.

Return type:

DNSOverUDPServer