aiocoap.credentials module

This module describes how security credentials are expressed in aiocoap, how security protocols (TLS, DTLS, OSCOAP) can store and access their key material, and for which URIs they are used.

For consistency, mappings between accessible resources and their credentials are always centered around URIs. This is slightly atypical, because a client will typically use a particular set of credentials for all operations on one server, while a server first loads all available credentials and then filters out whether the client may actually access a resource per-path, but it works with full URIs (or patterns thereof) just as well. That approach allows using more similar structures both on the server and the client, and works smoothly for virtual hosting, firewalling and clients accessing resources with varying credentials.

Still, client and server credentials are kept apart, lest a server open up (and potentially reveal) to a PSK set it is only configured to use as a client. While client credentials already have their place in aiocoap.protocol.Context.client_credentials, server credentials are not in use at a standardized location yet because there is only code in the OSCORE plug tests that can use it so far.

Library developer notes

This whole module currently relies on a mixture of introspection and manual parsing of the JSON-ish tree. A preferred expression of the same would rely on the credentials.cddl description and build an object tree from that, but the author is unaware of any existing CDDL Python implementation. That might also ease porting to platforms that don’t support inspect like micropython does.

exception aiocoap.credentials.CredentialsLoadError

Bases: ValueError

Raised by functions that create a CredentialsMap or its parts from simple data structures

exception aiocoap.credentials.CredentialsMissingError

Bases: RuntimeError

Raised when no suiting credentials can be found for a message, or credentials are found but inapplicable to a transport’s security mechanisms.

class aiocoap.credentials.CredentialReference(target, map)

Bases: object

as_dtls_psk()

class aiocoap.credentials.AnyOf

Bases: aiocoap.credentials._Listish

class aiocoap.credentials.AllOf

Bases: aiocoap.credentials._Listish

class aiocoap.credentials.DTLS(psk: bytes, client_identity: bytes)

Bases: aiocoap.credentials._Objectish

as_dtls_psk()

class aiocoap.credentials.TLSCert(certfile: str)

Bases: aiocoap.credentials._Objectish

Indicates that a client can use the given certificate file to authenticate the server.

Can only be used with ‘coaps+tcp://HOSTINFO/’ and ‘coaps+tcp://’ forms.

as_ssl_params()

Generate parameters suitable for passing via ** to ssl.create_default_context when purpose is alreay set

aiocoap.credentials.construct_oscore(contextfile: str)

class aiocoap.credentials.CredentialsMap

Bases: dict

FIXME: outdated, rewrite when usable

A CredentialsMap, for any URI template and operation, which security contexts are sufficient to to perform the operation on a matching URI.

The same context can be used both by the server and the client, where the client uses the information on allowed client credentials to decide which credentials to present, and the information on allowed server credentials to decide whether the server can be trusted.

Conversely, the server typically loads all available server credentials at startup, and then uses the client credentials list to decide whether to serve the request.

load_from_dict(d)

Populate the map from a dictionary, which would typically have been loaded from a JSON/YAML file and needs to match the CDDL in credentials.cddl.

Running this multiple times will overwriter individual entries in the map.

credentials_from_request(msg)

Return the most specific match to a request message. Matching is currently based on wildcards, but not yet very well thought out.

ssl_client_context(scheme, hostinfo)

Return an SSL client context as configured for the given request scheme and hostinfo (no full message is to be processed here, as connections are used across requests to the same origin).

If no credentials are configured, this returns the default SSL client context.

find_oscore(unprotected)

find_dtls_psk(identity)