bp package

Subpackages

Submodules

Implementation of a symmetric BPv7 agent.

class bp.agent.Timestamper

Bases: object

Generate a unique Timestamp with sequence state.

class bp.agent.Agent(config, bus_kwargs=None)

Bases: Object

Overall agent behavior.

Parameters:

config (Config) – The agent configuration object.
bus_kwargs (dict or None) – Arguments to dbus.service.Object constructor. If not provided the default dbus configuration is used.

DBUS_IFACE = 'org.ietf.dtn.bp.Agent'

set_on_stop(func)

Set a callback to be run when this agent is stopped.

Parameters:: func – The callback, which takes no arguments.

shutdown()

Gracefully terminate all open sessions. Once the sessions are closed then the agent may stop.

Returns:: True if the agent is stopped immediately or False if a wait is needed.

stop(): Immediately stop the agent and disconnect any sessions.

exec_loop(): Run this agent in an event loop. The on_stop callback is replaced to quit the event loop.

add_tx_route(item)

get_cla(name)

Return type:: AbstractAdaptor

recv_bundle(ctr)

Perform agent handling of a received bundle.

Parameters:: ctr (BundleContainer) – The bundle container just recieved.

send_bundle(ctr)

Perform agent handling to send a bundle. Part of this is to update final CRCs on all blocks and assign block numbers.

Parameters:: ctr (BundleContainer) – The bundle container to send.

cl_attach(cltype, servname)

Listen to sessions and bundles from a CL agent.

Parameters:: servname (str) – The DBus service name to listen from.

ping(nodeid, datalen)

Ping with random data via the routing table.

Parameters:

nodeid (str) – The destination Node ID.
datalen (int) – The payload data length.

Convergence layer adaptors.

bp.cla.cl_type(name): Decorator to register a CL adaptor class.

class bp.cla.AbstractAdaptor(agent)

Bases: ABC

Interface for a CL.

Variables:: agent_obj – The bus proxy object when it is valid.

bind(bus_conn)

unbind()

peer_node_seen(node_id, tx_params)

Callback interface to a indicate when a peer is seen

Parameters:: node_id (str) – A potential route to use for this peer.

recv_bundle_finish(data, metadata)

Callback interface to a handle received bundles.

Parameters:

data (bytes) – The actual bundle recevied.
metadata (dict) – A dictionary of CL-defined supplemental data.

abstractmethod send_bundle_func(tx_params): Interface to get a function to send a bundle to be sent by the CL. :param kwargs: Arguments from the routing table.

class bp.cla.UdpclAdaptor(**kwargs)

Bases: AbstractAdaptor

UDP Convergence layer.

DBUS_IFACE = 'org.ietf.dtn.udpcl.Agent'

TAG_ENC = b'\xd9\xd9\xf7'

send_bundle_func(tx_params): Interface to get a function to send a bundle to be sent by the CL. :param kwargs: Arguments from the routing table.

class bp.cla.TcpclAdaptor(**kwargs)

Bases: AbstractAdaptor

TCP Convergence layer.

DBUS_IFACE = 'org.ietf.dtn.tcpcl.Agent'

connect(address, port): Initiate a connection preemptively.

send_bundle_func(tx_params): Get an active session or create one if needed.

class bp.cla.TcpclConnection

Bases: object

TCP Convergence layer session keeping.

Variables:: conn_obj – The bus proxy object when it is valid.

DBUS_IFACE = 'org.ietf.dtn.tcpcl.Contact'

send_bundle_data(data)

Command entry points.

bp.cmd.str2bool(val): Require an option value to be boolean text.

bp.cmd.uristr(val): Require an option value to be a URI.

bp.cmd.main(): Agent command entry point.

Agent configuration data.

class bp.config.RxRouteItem(eid_pattern, action, raw_config=<factory>)

Bases: object

Each item in the receive routing table.

eid_pattern: Pattern

action: str

raw_config: object

class bp.config.TxRouteItem(eid_pattern, next_nodeid, cl_type, mtu=None, raw_config=<factory>)

Bases: object

Each item in the transmit routing table.

eid_pattern: Pattern

next_nodeid: str

cl_type: str

mtu: Optional[int] = None

raw_config: object

class bp.config.Config(log_level=None, enable_test=<factory>, bus_addr=None, bus_service=None, node_id='', rx_route_table=<factory>, tx_route_table=<factory>, verify_ca_file=None, sign_cert_file=None, sign_key_file=None, encr_cert_file=None, encr_key_file=None, integrity_include_chain=True, accept_after_verify=False, cl_attach=<factory>, apps=<factory>)

Bases: object

Agent configuration.

log_level: Optional[str] = None

enable_test: Set[str]

bus_addr: Optional[str] = None

bus_service: Optional[str] = None

node_id: str = ''

rx_route_table: List[RxRouteItem]

tx_route_table: List[TxRouteItem]

verify_ca_file: Optional[str] = None

sign_cert_file: Optional[str] = None

sign_key_file: Optional[str] = None

encr_cert_file: Optional[str] = None

encr_key_file: Optional[str] = None

integrity_include_chain: bool = True: Include certificate chain in integrity parameters

accept_after_verify: bool = False: Are security operations accepted after successful verification

cl_attach: Dict[str, str]

apps: Dict[str, dict]

from_file(fileobj): Load configuration from a YAML file. :type fileobj: :param fileobj: The file to read from.

property bus_conn

bp.crypto.load_pem_key(infile): Read a private key from file.

bp.crypto.load_pem_chain(infile)

Read a certificate chain from file.

Return type:: List[Certificate]

bp.crypto.encode_der_cert(cert)

Encode a certificate as DER bytes.

Return type:: bytes

Prototype of Security Associations with Few Exchanges (SAFE) information and state machine.

class bp.safe_info.SimpleData(tx_items=<factory>, rx_items=<factory>)

Bases: object

Instances used with ActivityInfo.data

tx_items: Dict[int, object]: Items to be sent to a peer

rx_items: Dict[int, object]: Items received from a peer

bp.safe_info.SAFE_EAD_LABEL = 23: Allocated EAD label for embedded SAFE messages

bp.safe_info.SAFE_EXPORTER_LABEL = 32768: Allocated exporter label for SAFE primary SA

class bp.safe_info.ActivityType(*values)

Bases: IntEnum

INITIAL_AUTHN = 0

CAPABILITY_INDICATION = 1

SA_CREATION = 2

class bp.safe_info.ActCIKeys(*values)

Bases: IntEnum

Map keys for ActivityType.CAPABILITY_INDICATION

CAS = 1

ESS = 2

BCS = 3

class bp.safe_info.ActSCKeys(*values)

Bases: IntEnum

Map keys for ActivityType.SA_CREATION

LOCAL_SAI = 1

AKE = 2

ARN = 3

CTXID = 4

KUS = 5

TSI = 6

TSR = 7

NTI = 8

TBT = 9

class bp.safe_info.ActivityInfo(app, peer_state, act, data=<factory>)

Bases: ABC

Abstract base class for activity behaviors

app: SafeEntity

peer_state: PeerState

act: ActivityState

data: Optional[object]: Type-specific data populated by the derived class

is_finished()

Return type:: bool

get_tx_items()

Return type:: Optional[dict]

set_rx_items(items)

state_changed()

bp.safe_info.register_info(act_type): Register a class derived from ActivityInfo

class bp.safe_info.InitialAuthn(edhoc, **kwargs)

Bases: ActivityInfo

is_finished()

Return type:: bool

state_changed()

process_edhoc(step, seqdata)

Return type:: EadList

get_edhoc(step, ead)

Return type:: bytes

class bp.safe_info.CapabilityIndication(app, peer_state, act, data=<factory>)

Bases: ActivityInfo

is_finished()

Return type:: bool

get_tx_items()

Return type:: Optional[dict]

state_changed()

class bp.safe_info.SaCreation(app, peer_state, act, data=<factory>)

Bases: ActivityInfo

is_finished()

Return type:: bool

get_tx_items()

Return type:: Optional[dict]

set_rx_items(items)

state_changed()

class bp.safe_info.CoseCtxKusOptions(*values)

Bases: IntEnum

ALG = 1

class bp.safe_info.ActivityState(as_initiator, init_eid, act_idx, act_type, info=None, last_step_tx=-1, last_step_rx=-1, timer_retx=None, timer_remove=None, retx_count=0)

Bases: object

as_initiator: bool: True if this entity is the initiator side

init_eid: str: The activity initiator EID

act_idx: int: The initiator-defined index

act_type: ActivityType: Activity type enumeration

info: ActivityInfo = None: Activity-type specific descriptor

last_step_tx: int = -1: Step last transmitted (LTX)

last_step_rx: int = -1: Step last received (LRX)

timer_retx: Optional[object] = None: Retransmission timer handle from glib.timeout_add()

timer_remove: Optional[object] = None: Removal timer handle from glib.timeout_add()

retx_count: int = 0: LTX step retransmission count. This resets to zero upon the first TX of each step.

KeyType: alias of Tuple[str, int]

key()

Get a unique key for this activity

Return type:: Tuple[str, int]

property next_step: int: The next step to transmit.

need_tx()

Determine if a message needs to be sent

Return type:: bool

is_finished()

Determine if this activity is finished.

Return type:: bool
Returns:: True if the last step was sent or received already.

class bp.safe_info.PeerState(peer_eid, last_act_idx=0, edhoc=<factory>, own=<factory>, peer=<factory>, psa=None)

Bases: object

State of activities and messaging with a peer

peer_eid: str: The peer EID for this state

last_act_idx: int = 0: The last used activity index, which reserves the zero value.

edhoc: Dict[bytes, ActivityState]

own: Dict[int, ActivityState]

peer: Dict[int, ActivityState]

psa: Optional[PrimarySecAssn] = None: The latest SA for this peer

next_act_index()

Return type:: int

add_activity(act)

remove_activity(act)

all_normal()

Return type:: List[ActivityState]

class bp.safe_info.KeyUse(key, op_count=0, bytes_count=0)

Bases: object

Each derived symmetric key for an SA

key: SymmetricKey: Symmetric key including base-IV

op_count: int = 0

bytes_count: int = 0

increment(plain_size)

partial_iv()

Get a partial-iv byte string based on the op_count.

Return type:: bytes

class bp.safe_info.PrimarySecAssn(local_sai, peer_eid, peer_sai, edhoc, suite, safe_kdf, prk_sa1, tx_use, rx_use)

Bases: object

State of a security association from Section 3.3

local_sai: ConnectionId

peer_eid: str

peer_sai: ConnectionId

edhoc: Union[EdhocInitiator, EdhocResponder]

suite: CipherSuite

safe_kdf: AbstractKDF: The KDF function to use for PRK derivation

prk_sa1: bytes: PRK from which to derive secondary SA material

tx_use: KeyUse

rx_use: KeyUse

class bp.safe_info.SecondarySecAssn(psa, local_sai, peer_eid, peer_sai, tx_use, rx_use)

Bases: object

State of a security association from Section 3.3

psa: PrimarySecAssn: Parent of this SA

local_sai: ConnectionId

peer_eid: str

peer_sai: ConnectionId

tx_use: KeyUse

rx_use: KeyUse

class bp.safe_info.SafeEntity(send_pdu, method, suite, authn_priv_key=None, id_cred=None, cred_store=None, ke_priv_key=None, conn_id=None)

Bases: object

SAFE protocol entity.

Parameters:

method (Method) – The method to request and allow.
suite (CipherSuite) – The cipher suite to request and allow.
id_cred (Optional[dict]) – The local credential ID, which must be set here or before the first session start with any peer.
ke_priv_key (Optional[List[CoseKey]]) – A fixed list of key exchange private keys to use. This should be used for testing only.
conn_id (Optional[bytes]) – A specific EDHOC connection identifier to use. This should be used for testing only.

recv_pdu(pdu, peer_eid)

property own_eid: str

start_activity(peer_state, act_type): Start a new activity of a specific type.

get_primary_sas()

Return type:: List[PrimarySecAssn]

add_primary_sa(psa)

get_secondary_sas()

Return type:: List[SecondarySecAssn]

add_secondary_sa(ssa)

start(peer_eid): Start an Initial Authentication activity.

Utility helpers.

bp.util.BlockType

Identifier for block type as either a type code or a BTSD class

alias of int | Type[object]

class bp.util.BundleContainer(bundle=None)

Bases: object

A high-level representation of a bundle. This includes logical constraints not present in encoding.Bundle data handling class.

Variables:

bundle – The decoded bundle itself.
actions – Processing recorded on this bundle.
status_reason – The last status reason.
route – The transmit route (type TxRouteItem) chosen for this bundle.
sender – The transmit function to send this bundle.

block_num(num)

Look up a block by unique number.

Parameters:: num (int) – The block number to look up.
Return type:: CanonicalBlock
Returns:: The block with that number.
Raises:: KeyError – If the number is not present.

block_type(type_code)

Look up a block by type code or data class.

Parameters:: type_code (Union[int, Type[object]]) – The type code to look up.
Return type:: List[CanonicalBlock]
Returns:: A list of blocks of that type, which may be empty.

log_name()

Get a log-friendly name for this bundle.

Return type:: str

bundle_ident()

Get the bundle identity (source + timestamp) as a tuple.

Return type:: Tuple

add_block(blk)

Add an extension block. The block is added just before the payload. :type blk: CanonicalBlock :param blk: The existing block to remove (and reindex). This block will have its BTSD set if not already.

Return type:: None

remove_block(blk)

Remove an extension block. :type blk: CanonicalBlock :param blk: The existing block to remove (and reindex).

Return type:: None

reload()

Reload derived info from the bundle.

Return type:: None

get_block_num(): Get the next unused block number. :rtype: int :return: An unused number.

fix_block_num()

Assign unique block numbers where needed.

Return type:: None

sort_block_num()

Sort canonical blocks in reverse number order.

Return type:: None

record_action(action, reason=None): Mark an action on this bundle.

create_report()

Return type:: BundleContainer

class bp.util.ChainStep(order=0, name='unknown', action=None)

Bases: object

order: float = 0

name: str = 'unknown'

action: Callable[[BundleContainer], bool] = None