The "factory default" BSL is configured to operate with a "dynamic backend" which uses dynamic heap allocation and variable-sized data containers (arrays, lists, maps, etc.). An alternative backend could be developed for specific BPA needs, but that is outside the scope of the BSL project.

The factory default BSL also builds example Policy Providers and example Security Contexts in order to be able to fully exercise the BSL behaviors. Alternative Policy Providers are expected to be developed for each deployment. Alternative Security Context implementations are expected to be developed for future contexts, and to adapt to deployment-specific needs such as for key management or specialized cryptographic interfaces.

The BSL project is based on a single source tree but is subdivided into separate libraries, each with their own cross-dependencies (for compiling and linking). The dependencies between areas are shown in Figure 1.1, where the single "BSL" block is meant to represent both the frontend and backend libraries for simplicity.

Figure 1.1. Logical Structure and Dependencies

The BSL is internally separated into two 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:

This is depicted in Figure 1.2, where each of the edges in that diagram indicates a call from the BPA into the BSL to process security on that single bundle at the specific location. A more detailed view of the BSL processing sequence at each of those interaction points is described later in Section 3.2.

Figure 1.2. Interaction Points from the BPA into BSL

Separate from the structural aspects of the BSL and its external APIs, there are different directions that calls are being made for different interactions between the same entities. For the factory configuration, using the dynamic backend, these interactions take two forms:

The initiating calls are directed from the BPA into the BSL, and then into PPs (to inform what security operations need to be done) and SCs (to actually execute the security operations). This is depicted in Figure 1.3, where the BPA initiates the sequence using the frontend API and the BSL calls into each PP and necessary SC based on callbacks injected into the BPA at their times of registration.

Figure 1.3. Calls Directed From the BPA

As part of normal PP and SC processing, they will need to obtain data from the bundle, access its various blocks, and obtain some data from the BPA itself. Some of these calls will originate from the BSL itself and some will originate from the PP and SC instances, passing through the BSL based on its own frontend API. This is depicted in Figure 1.4, which elides the ultimate source of each of these calls (which is always the BPA).

Figure 1.4. Calls Directed To the BPA

All of the discussion in this subsection is at the level of logical entities and information models. It does not map one-for-one with the actual APIs of the BSL, but is useful for explaining terminology and framing explanations at a higher level than the C-language details discussed in the BSL API Docs.

The BSL proper is embodied as a "BSL Context" state, for which a single process can have any number of instances. One BPA option is to have a single BSL Context for all of its security processing, which will save on memory use but will act as a bottleneck if the BPA performs its own bundle processing concurrently at each of the interaction points. Another BPA option is to use a separate BSL Context for each interaction point and operate them independently and possibly concurrently.

Because the function of the BSL is perform security processing on individual bundles, all of the processing of the BSL Context operates on a single "Bundle Context" at a time. The purpose of a Bundle Context is to both relate back to some form of BPA-specific handle used to identify the bundle within the BPA, as well as keeping BSL-specific state derived from the BPA-supplied bundle data such as an efficient look-up table for block types or block numbers.

Figure 2.1. BPA and Bundle Context Associations

Each BSL Context instance is associated with one or more Policy Provider instances and one or more Security Context instances, as depicted in Figure 2.2. The Policy Providers are used to control what the BSL needs to do for a specific bundle, as discussed in more detail in Section 2.2. The Security Contexts are used to validate and actually execute each security operation, as discussed in more detail in Section 2.3.

Figure 2.2. BSL Structure Breakdown

In addition to the externally-visible information about security operations and their target, parameters, and results the BSL adds the notion of a security Action which is an ordered sequence of specific operations. This is necessary because some policies require, for example, some operations to be accepted before others are sourced which would refer to the same target block.

Another internal information item is the security Option, which is used to communicate configuration of individual security operations between a Policy Provider and an associated Security Context. Some options are converted by the SC into Parameters or Results that get encoded into the ASB when acting as the Source role. Some options, like key identifiers for the default security contexts, do not have representation in the ASB but are necessary for correct processing of the security operation.

Figure 2.3. Security Operation Associations

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.

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, both specified in [RFC9173]:

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.

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.

The following are preprocessor define directives that limit certain capabilities within the BSL.

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

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

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

Figure 3.1. Visual Representation of Per-Bundle Workflow

The BSL Frontend API consists of two primary functions for per-bundle operation:

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.

The following provides troubleshooting guidance for the BSL from the perspective of a normal or administrative user. Each situation consists of an observed state followed by a recommended troubleshooting activity.

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.