ros_sugar.ui_node.security

Security of the UI node’s server.

Module Contents

Classes

Certificate	The certificate the UI serves, and where it came from
ApiKey	A third party’s API key as stored hash
ApiKeys	The API keys kept in a state directory.

Functions

state_dir	The UI’s state directory, created with owner-only access if missing
resolve_certificate	The certificate to serve, from the first source that provides one.
minted_certificate	Sugarcoat’s own certificate in directory, minted when missing, unusable or within RENEW_BEFORE of expiry
banner	UI print at startup about the certificate
uncovered_addresses	This machine’s IPv4 addresses the certificate does not cover
local_ipv4_addresses	IPv4 addresses of this machine’s network interfaces (Linux)
load_certificate	Read a certificate and check that its key belongs to it
session_key	The secret signing the browser front end’s cookies, created on first use

API

exception ros_sugar.ui_node.security.CertificateError

Bases: RuntimeError

A TLS certificate could not be found, read or minted

add_note()

with_traceback()

exception ros_sugar.ui_node.security.ApiKeyError

Bases: RuntimeError

API keys could not be read, created or revoked

add_note()

with_traceback()

class ros_sugar.ui_node.security.Certificate

The certificate the UI serves, and where it came from

ros_sugar.ui_node.security.state_dir() → pathlib.Path

The UI’s state directory, created with owner-only access if missing

ros_sugar.ui_node.security.resolve_certificate() → ros_sugar.ui_node.security.Certificate

The certificate to serve, from the first source that provides one.

1. SUGARCOAT_UI_TLS_CERT and SUGARCOAT_UI_TLS_KEY

2. Sugarcoat’s own, minted in the state directory and renewed near expiry

Raises:

CertificateError – If a configured certificate cannot be used, or none can be minted

ros_sugar.ui_node.security.minted_certificate(directory: pathlib.Path) → ros_sugar.ui_node.security.Certificate

Sugarcoat’s own certificate in directory, minted when missing, unusable or within RENEW_BEFORE of expiry

ros_sugar.ui_node.security.banner(certificate: ros_sugar.ui_node.security.Certificate) → List[str]

UI print at startup about the certificate

ros_sugar.ui_node.security.uncovered_addresses(certificate: ros_sugar.ui_node.security.Certificate) → List[str]

This machine’s IPv4 addresses the certificate does not cover

ros_sugar.ui_node.security.local_ipv4_addresses() → List[str]

IPv4 addresses of this machine’s network interfaces (Linux)

ros_sugar.ui_node.security.load_certificate(cert_path: pathlib.Path, key_path: pathlib.Path, source: str) → ros_sugar.ui_node.security.Certificate

Read a certificate and check that its key belongs to it

class ros_sugar.ui_node.security.ApiKey

A third party’s API key as stored hash

class ros_sugar.ui_node.security.ApiKeys(directory: pathlib.Path)

The API keys kept in a state directory.

The file is read on every use, so a key created or revoked takes effect in a running UI without a restart.

all() → List[ros_sugar.ui_node.security.ApiKey]

Every stored key, expired ones included

Raises:

ApiKeyError – If the file cannot be read

find(key: str) → Optional[ros_sugar.ui_node.security.ApiKey]

The unexpired stored key key is, if any

create(name: str, scopes: Sequence[str], expires_at: Optional[datetime.date] = None) → Tuple[ros_sugar.ui_node.security.ApiKey, str]

Create a key. The key itself is returned only here and never stored

Returns:

The stored key and the key to give its holder

Raises:

ApiKeyError – If the name, scopes or expiry are not valid

revoke(key_id: str) → ros_sugar.ui_node.security.ApiKey

Delete a key

Raises:

ApiKeyError – If there is no key with that id

ros_sugar.ui_node.security.session_key(directory: pathlib.Path) → str

The secret signing the browser front end’s cookies, created on first use