Bundle Protocol Security Library (BSL) User Guide

DOC-005922, Prepared by The Johns Hopkins University Applied Physics Laboratory

JHU/APL

License

This document is part of the Bundle Protocol Security Library (BSL).

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This work was performed for the Jet Propulsion Laboratory, California Institute of Technology, sponsored by the United States Government under the prime contract 80NM0018D0004 between the Caltech and NASA under subcontract 1700763.

Revision History
Revision Initial	21 August 2025
Initial issue of document for BSL v1.0.0

Table of Contents

Introduction
1. Application Programming Interface Overview
2. Workflows
3. Product Support
- 3.1. Troubleshooting
- 3.2. Contacting or Contributing
Index

List of Figures

1.1. Interaction Points from the BPA into BSL
2.1. Visual Representation of Per-Bundle Workflow

List of Tables

1. Applicable JPL Rules Documents
2. Applicable MGSS Documents
3. Applicable Other Documents

Introduction

This User Guide provides an overview of the application programming interface (API) and high-level workflows of the Bundle Protocol Security Library (BSL), which is part of the NASA Advanced Multi-Mission Operations System (AMMOS) suite of tools.

1. Identification

Property	Value
Configuration ID (CI)	681.4
Element	Mission Control System (MCS)
Program Set	Bundle Protocol Security Library (BSL)
Version	1.0

2. Scope

This document describes and explains the API and workflows of the BSL. For technical details about the BSL architecture, installation, upgrade, monitoring, and maintenance see the BSL Product Guide. Details about specific API structures and cross-relationships is provided in the online BSL API Docs.

Terminology

Bundle Protocol (BP): The overlay network protocol used to transport BPSec blocks and target blocks between nodes.
Bundle Protocol Security (BPSec): The mandatory-to-implement security mechanism to protect blocks of a BP bundle. This is the principal scope of behavior implemented in the BSL.
BP Agent (BPA): The instantiation of a BP node with a unique administrative Endpoint ID.
BP Endpoint: The source or destination of a BP bundle, identified by a BP Endpoint ID (EID).
BP Endpoint ID (EID): The identifier of a BP Endpoint; names the source and destination for a BP bundle.
Bundle (per BPv7): The protocol data unit of Bundle Protocol, which uses a CBOR-encoding of its data.
Block (per BPv7): Each sub-element of a bundle. All bundles contain a mandatory primary block, any number of extension blocks, and a mandatory payload block. Each extension block has an explicit block type identifier.
Block-Type-Specific Data (BTSD): The arbitrary-length binary data containing the contents of a block which is block-type-specific.
Block Integrity Block (BIB): A well-known block type used for integrity operations in BPSec.
Block Confidentiality Block (BCB): A well-known block type used for integrity operations in BPSec.
Abstract Security Block (ASB): A the block-type-specific data for one of the security block types: BIB or BCB, which contains an encoded CBOR sequence.
Concise Binary Object Representation (CBOR): A binary encoding defined in [RFC8949] which follows a superset of the JSON data model (see below) and enables both small encoded size as well as efficient encoding and decoding. The BSL itself uses CBOR to encode the contents of BPSec ASBs.
JavaScript Object Notation (JSON): A text encoding defined in [RFC8259] which allows a limited data model to be encoded in a human-readable form. The BSL does not use JSON directly, but the example Policy Provider uses JSON for policy configuration and key material configuration.
BSL Context: An container of state and memory allocation for each instance of the BSL. Each BSL context is not thread safe, it must be used within a single thread exclusively.
Policy Provider (PP): An abstract interface (and a C callback descriptor struct) for providing security policy to a BSL Context. The BSL dynamic backend contains a run-time-variable PP registry.
Security Context (SC): An abstract interface (and a C callback descriptor struct) for providing BPSec security context processing to a BSL Context. The BSL dynamic backend contains a run-time-variable SC registry.

3. References

Table 1. Applicable JPL Rules Documents

Title	Document Number
Software Development	57653 rev 10

Table 2. Applicable MGSS Documents

Title	Document Number
MGSS Implementation and Maintenance Task Requirements (MIMTaR)	DOC-001455 rev G
BSL Software Requirements Document (SRD)	DOC-005735
BSL Software Interface Specification (SIS)	DOC-005835
BSL Product Guide	DOC-005921

Table 3. Applicable Other Documents

Title	Reference
BSL Source	GitHub project BSL
BSL Documentation Source	GitHub project BSL-docs
BSL API Documentation — Main Branch	GitHub Pages for BSL
Programming Languages — C	ISO/IEC 9899:1999
IEEE Standard for Information Technology - Portable Operating System Interface (POSIX®)	IEEE Std 1003.1-2008
OpenSSL Library	https://openssl-library.org/
Jansson Library	GitHub project for Jansson
Unity Test Library	GitHub project Unity
NASA Interplanetary Overlay Networking (ION) software	GitHub project for ION-DTN
Wireshark Project	https://www.wireshark.org/
The JavaScript Object Notation (JSON) Data Interchange Format	IETF RFC 8259
Concise Binary Object Representation (CBOR)	IETF RFC 8949
Bundle Protocol Version 7	IETF RFC 9171
Bundle Protocol Security (BPSec)	IETF RFC 9172
Default Security Contexts for Bundle Protocol Security (BPSec)	IETF RFC 9173

Chapter 1. Application Programming Interface Overview

The following section provides an overview of the BSL API and references to specific sections of the online API documentation.

1.1. Architecture

The BSL as a whole is separated into two primary layers of implementation: an API-centric abstract Frontend library and a host-binding concrete Backend library.

The Frontend library provides the service API for the BSL to be called by its associated BPA as needed and for stable public APIs used by Policy Provider implementations and Security Context implementations. The Backend library implements forward-declared structs and functions from the Frontend using specific concrete data containers, algorithms, etc.

Most interactions with the BSL/frontend API occur within the context of a single bundle. There are four points along bundle traversal where BSL interaction from the BPA is necessary:

After bundle transmission from an application source (APPIN).
Before bundle delivery to an application destination (APPOUT).
After bundle reception via a CLA (CLIN).
Before bundle forwarding via a CLA (CLOUT).

Figure 1.1. Interaction Points from the BPA into BSL

1.2. Policy Providers

Policy Providers need to be registered with a library context via the dynamic backend before they can be used. Policy Providers must implement the function headers of the frontend PolicyProvider.h header file.

Policy Providers must inspect each bundle to produce an Action Set, containing Security Operations. Policy Providers also must finalize over a bundle after each Security Operation has been executed by the security context.

The BSL includes a simple rule-based example PP that may be utilized.

1.3. Security Contexts

Security Contexts need to be registered with a library context via the dynamic backend before they can be used. Security Contexts must implement the function headers of the frontend SecurityContext.h header file.

The BSL includes two Default Security Context implementations (specified in RFC9173), BIB-HMAC-SHA2 (Bundle Integrity) and BCB-AES-GCM (Bundle Confidentiality) that may be utilized. The BSL backend cryptographic interface utilizes OpenSSL to perform HMAC-signing, encryption, and decryption operations.

Security Contexts operate in the context of a single Security Operation over a bundle. Security Contexts must validate Security Operations for consistency, and process Security Operations on bundles to produce security outcomes.

1.4. Mock BPA

An executable used to provide a test fixture and example BPA integration. However, the Mock BPA does not provide any of the normal processing required of a real BPA by [RFC9171], it is limited to decoding and encoding BPv7 protocol data unit (PDU) byte strings, processing specific BPv7 primary block fields, providing BSL-required integration callbacks, and calling into the BSL for each bundle being processed at each interaction point. Users may reference the Mock BPA for an example of library and bundle workflow.

Chapter 2. Workflows

A simple BPA that utilizes the example policy provider, default security contexts, and dynamic backend could operate with the following workflow:

2.1. Initialization of BPA Callbacks

The following steps are not thread safe and must be performed before any BSL context instances are initialized (in Section 2.2).

Set & Initialize Host Descriptors: The BSL backend relies on host-specific information from the BPA, such as EID registering and encoding information. The function-pointer fields of a BSL_HostDescriptors_t struct should be set with host-implemented functions and initialized with BSL_HostDescriptors_Set() for successful BSL operation. See the Mock BPA for a simple example of implementing host descriptors.

2.2. Initialization of a BSL Context

The following steps contain BSL initialization instructions to be performed once (per-thread). The correct operation relies on the host BPA configuration from Section 2.1 to be in-place.

Initialize the Library Context: Each runtime instance of the BSL is isolated for thread safety within a host-specific struct referenced by a BSL_LibCtx_t pointer. Each instance should be initialized using BSL_LibCtx_Init().
Initialize EIDs: BPAs can register one or more nodes, each of which has a unique endpoint ID (EID). Each EID must be registered with the host using BSL_HostEID_Init().
Register Example Policy Provider with the Library Context: Register the example Policy Provider with the Library Context.
Initialize Cryptographic State & Register Default Security Contexts with the Library Context: Initialize the backend cryptographic interface with BSL_CryptoInit(). Then, register the BIB-HMAC-SHA2 and BCB-AES-GCM Default Security Contexts with the Library Context.

2.3. Single-Bundle Workflow

The following steps should be performed for each bundle being processed, their entity relationships are depicted in Figure 2.1. All of these actions operate within a BSL library context, initialized in Section 2.2.

Initialize Bundle Context for each Bundle: For each bundle being processed by BPA at one of the four points of interaction (APPIN, APPOUT, CLIN, CLOUT), initialize a bundle context. The bundle context will keep track of a bundle’s state throughout its interaction with the BSL. The context must utilize the host-specific struct BSL_BundleCtx_t.
Inspect Bundles with Policy Providers: Utilize the example Policy Provider’s inspection function to produce an Action Set that contains Security Operations (Security Operations) to perform on the current bundle context.
Validate Security Operations with Security Contexts: For each Security Operation contained within the Action Set, utilize the validate function from the relevant Default Security Context to ensure validity and feasibility of the operation.
Execute Security Operations with Security Contexts: For each Security Operation contained within the Action Set, utilize the execute function from the relevant Default Security Context to perform the operations on the bundle context. The Security Context will produce Security Outcomes which will be returned to the BPA.
Finalize Bundles with Policy Providers: Utilize the example Policy Provider’s finalize function to verify successful security operations, handle unsuccessful operations, and verify bundle consistency.
Free Bundle Context: The bundle has now completed the required BSL interactions, and the bundle context resources can be released. The bundle can now be forwarded within the BPA.

Figure 2.1. Visual Representation of Per-Bundle Workflow

2.4. De-initialization of a BSL Context

Before joining or termination of an associated work thread, each BSL_LibCtx_t instance should be de-initialized with BSL_LibCtx_Deinit() to free its resources.

Each BSL Context is independent of all others, so there is no need to coordinate activities of one with any other.

Chapter 3. Product Support

There are two levels of support for the BSL: troubleshooting by a system administrator, which is detailed in Section 3.1, and upstream support via the BSL public GitHub project, accessible as described in Section 3.2. Attempts to troubleshoot should be made before submitting issue tickets to the upstream project.

3.1. Troubleshooting

TBD

3.2. Contacting or Contributing

The BSL is hosted on a GitHub repository [bsl-source] with submodule references to several other repositories. There is a CONTRIBUTING.md document in the BSL repository which describes detailed procedures for submitting tickets to identify defects and suggest enhancements.

Separate from the source for the BSL proper, the BSL Product Guide and User Guide are hosted on a GitHub repository [bsl-docs], with its own CONTRIBUTING.md document for submitting tickets about either the Product Guide or User Guide.

While the GitHub repositories are the primary means by which users should submit detailed tickets, other inquiries can be made directly via email to the the support address dtnma-support@jhuapl.edu.