aiocoap.oscore module

This module contains the tools to send OSCORE secured messages.

It only deals with the algorithmic parts, the security context and protection and unprotection of messages. It does not touch on the integration of OSCORE in the larger aiocoap stack of having a context or requests; that’s what aiocoap.transports.osore is for.`

exception aiocoap.oscore.NotAProtectedMessage(message, plain_message)

Bases: ValueError

Raised when verification is attempted on a non-OSCORE message

exception aiocoap.oscore.ProtectionInvalid

Bases: ValueError

Raised when verification of an OSCORE message fails

exception aiocoap.oscore.DecodeError

Bases: aiocoap.oscore.ProtectionInvalid

Raised when verification of an OSCORE message fails because CBOR or compressed data were erroneous

exception aiocoap.oscore.ReplayError

Bases: aiocoap.oscore.ProtectionInvalid

Raised when verification of an OSCORE message fails because the sequence numbers was already used

class aiocoap.oscore.Algorithm

Bases: object

encrypt(plaintext, aad, key, iv)

Return (ciphertext, tag) for given input data

decrypt(ciphertext, tag, aad, key, iv)

Reverse encryption. Must raise ProtectionInvalid on any error stemming from untrusted data.

class aiocoap.oscore.AES_CCM

Bases: aiocoap.oscore.Algorithm

AES-CCM implemented using the Python cryptography library

classmethod encrypt(plaintext, aad, key, iv)

Return (ciphertext, tag) for given input data

classmethod decrypt(ciphertext, tag, aad, key, iv)

Reverse encryption. Must raise ProtectionInvalid on any error stemming from untrusted data.

class aiocoap.oscore.AES_CCM_64_64_128

Bases: aiocoap.oscore.AES_CCM

value = 12
key_bytes = 16
iv_bytes = 7
tag_bytes = 8
class aiocoap.oscore.AES_CCM_16_64_128

Bases: aiocoap.oscore.AES_CCM

value = 10
key_bytes = 16
iv_bytes = 13
tag_bytes = 8
class aiocoap.oscore.SecurityContext

Bases: object

protect(message, request_data=None, *, can_reuse_partiv=True)
unprotect(protected_message, request_data=None)
new_sequence_number()
class aiocoap.oscore.ReplayWindow

Bases: object

class aiocoap.oscore.SimpleReplayWindow(seen=None)

Bases: aiocoap.oscore.ReplayWindow

A ReplayWindow that keeps its seen sequence numbers in a sorted list; all entries of the list and all numbers smaller than the first entry are considered seen.

This is not very efficient, but easy to understand and to serialize.

>>> w = SimpleReplayWindow()
>>> w.strike_out(5)
>>> w.is_valid(3)
True
>>> w.is_valid(5)
False
>>> w.strike_out(0)
>>> print(w.seen)
[0, 5]
>>> w.strike_out(1)
>>> w.strike_out(2)
>>> print(w.seen)
[2, 5]
>>> w.is_valid(1)
False
window_count = 64
is_valid(number)
strike_out(number)
class aiocoap.oscore.FilesystemSecurityContext(basedir, role)

Bases: aiocoap.oscore.SecurityContext

Security context stored in a directory as distinct files containing containing

  • Master secret, master salt, the sender IDs of the participants, and optionally algorithm, the KDF hash function, and replay window size (settings.json and secrets.json, where the latter is typically readable only for the user)
  • sequence numbers and replay windows (sequence.json, the only file the process needs write access to)

The static parameters can all either be placed in settings.json or secrets.json, but must not be present in both; the presence of either file is sufficient.

The static files are phrased in a way that allows using the same files for server and client; only by passing “client” or “server” as role parameter at load time, the IDs are are assigned to the context as sender or recipient ID. (The sequence number file is set up in a similar way in preparation for multicast operation; but is not yet usable from a directory shared between server and client; when multicast is actually explored, the sequence file might be renamed to contain the sender ID for shared use of a directory).

Note that the sequence number file is updated in an atomic fashion which requires file creation privileges in the directory. If privilege separation between settings/key changes and sequence number changes is desired, one way to achieve that on Linux is giving the aiocoap process’s user group write permissions on the directory and setting the sticky bit on the directory, thus forbidding the user to remove the settings/secret files not owned by him.

exception LoadError

Bases: ValueError

Exception raised with a descriptive message when trying to load a faulty security context

classmethod generate(basedir)

Create a security context directory from default parameters and a random key; it is an error if that directory already exists.

No SecurityContext object is returned immediately, as it is expected that the generated context can’t be used immediately but first needs to be copied to another party and then can be opened in either the sender or the recipient role.

aiocoap.oscore.verify_start(message)

Extract a CID from a message for the verifier to then pick a security context to actually verify the message.

Call this only requests; for responses, you’ll have to know the security context anyway, and there is usually no information to be gained (and things would even fail completely in compressed messages).