pycsamt.iot.security#

Security configuration for IoT telemetry transports.

Field IoT reviewers expect a credible security story: TLS for transport encryption and a defined credential scheme (bearer token, basic auth, or API key). This module provides small, serialisable configuration objects that:

  • carry TLS material and credentials,

  • redact secrets from repr/as_dict so they never leak into logs, manifests, or notebooks, and

  • project into the **options accepted by build_telemetry_client().

The objects hold configuration only; they do not implement cryptography themselves — encryption is delegated to the underlying transport (TLS via the OS/OpenSSL, tokens via HTTP headers).

Functions

redact_secret(value)

Return a redaction placeholder when value is a non-empty secret.

Classes

AuthScheme(*values)

Supported authentication schemes.

Credential([scheme, token, username, ...])

Authentication credential with secret redaction.

SecurityConfig([tls, credential, ...])

Combined TLS + credential policy for telemetry transports.

TLSConfig([enabled, ca_cert, certfile, ...])

Transport-layer security material for a telemetry client.
class pycsamt.iot.security.AuthScheme(*values)[source]#

Bases: str, Enum

Supported authentication schemes.

NONE = 'none'#
BEARER = 'bearer'#
BASIC = 'basic'#
API_KEY = 'api_key'#
class pycsamt.iot.security.TLSConfig(enabled=False, ca_cert=None, certfile=None, keyfile=None, verify=True, min_version=None)[source]#

Bases: PyCSAMTObject

Transport-layer security material for a telemetry client.

Parameters:

  • enabled (bool)

  • ca_cert (str | None)

  • certfile (str | None)

  • keyfile (str | None)

  • verify (bool)

  • min_version (str | None)

enabled: bool = False#
ca_cert: str | None = None#
certfile: str | None = None#
keyfile: str | None = None#
verify: bool = True#
min_version: str | None = None#
validate()[source]#

Validate object state.

Subclasses can override this hook. The base implementation intentionally accepts all states.

Return type:

None

as_dict()[source]#

Return TLS configuration (paths are not secrets).

Return type:

dict[str, Any]

class pycsamt.iot.security.Credential(scheme=AuthScheme.NONE, token=None, username=None, password=None, api_key=None, api_key_header='X-API-Key')[source]#

Bases: PyCSAMTObject

Authentication credential with secret redaction.

Secrets (token, password, api_key) are never shown by repr or as_dict(); use reveal() explicitly when a real transport needs the raw values.

Parameters:
scheme: AuthScheme | str = 'none'#
token: str | None = None#
username: str | None = None#
password: str | None = None#
api_key: str | None = None#
api_key_header: str = 'X-API-Key'#
validate()[source]#

Validate object state.

Subclasses can override this hook. The base implementation intentionally accepts all states.

Return type:

None

headers()[source]#

Return HTTP headers implementing the configured scheme.

Return type:

dict[str, str]

reveal()[source]#

Return the raw credential values (handle with care).

Return type:

dict[str, Any]

as_dict()[source]#

Return a redacted, serialisable credential summary.

Return type:

dict[str, Any]

class pycsamt.iot.security.SecurityConfig(tls=<factory>, credential=<factory>, require_tls=False, allowed_protocols=None)[source]#

Bases: PyCSAMTObject

Combined TLS + credential policy for telemetry transports.

Parameters:
tls: TLSConfig#
credential: Credential#
require_tls: bool = False#
allowed_protocols: list[str] | None = None#
validate()[source]#

Validate object state.

Subclasses can override this hook. The base implementation intentionally accepts all states.

Return type:

None

allows(protocol)[source]#

Return whether protocol is permitted by policy.

Parameters:

protocol (str)

Return type:

bool

client_options()[source]#

Return options for build_telemetry_client().

Includes TLS flags, credential headers, and (for MQTT) username / password so a transport can authenticate. Raw secrets are included because this feeds the live client, not a log.

Return type:

dict[str, Any]

as_dict()[source]#

Return a redacted, serialisable security summary.

Return type:

dict[str, Any]

classmethod from_env(prefix='PYCSAMT_IOT_')[source]#

Build a security config from environment variables.

Recognised variables (with prefix): TOKEN, API_KEY, USERNAME, PASSWORD, TLS (truthy), CA_CERT, CERTFILE, KEYFILE.

Parameters:

prefix (str)

Return type:

SecurityConfig

pycsamt.iot.security.redact_secret(value)[source]#

Return a redaction placeholder when value is a non-empty secret.

Parameters:

value (Any)

Return type:

str | None