The NASA AMMOS BPSec Library (BSL)

The BPSec Library (BSL) is an implementation of Bundle Protocol Security as specified in RFC 9172 and RFC 9173, with a flexible architecture enabling ready adaptability to flight or ground systems.

The BSL exposes an interface via C header files (under src), and contains an example backend implementing this interface in src/backend. The BSL also contains an implementation of the Default Security Context (RFC 9173) under src/security_context and a sample policy provider under src/policy_provider. Together these form a complete the set of functionality required to execute Bundle Protocol Security.

Project Organization

The following are the major parts of this project.

Note. The BSL API (both Public and Private) lives at the top level src directory. Example concrete modules implementations are found in subdirectories of it.

BSL/
├── build.sh             # Top-level build utility script
├── cmake/               # Additional CMake files
├── deps/                # Third-party dependencies
├── docs/                # Doxygen pages and templates
├── mock-bpa-test/       # Full BSL test/example using Mock BPA
├── pkg/                 # Material for building RPMs
├── resources/           # Additional helper util scripts
├── src/                 # Source code, top level is header-only API
├── src/backend          # Implementation of example dynamic backend
├── src/mock_bpa         # Implementation of example Mock BPA
├── src/policy_provider  # Implementation of the example policy provider
├── src/security_context # Implementation of RFC 9173 (Default Sec Context)
└── test/                # Unit tests

Development Requirements

Note! BSL uses Red Hat Enterprise Linux (RHEL 9) as the target build environment. Ubuntu is frequently used by developers, but not supported as an official target.

The following should be installable by the system package manager:

Required: Build and Run Unit Tests

• CMake, GCC or Clang, OpenSSL (Development), Ninja Build, Valgrind, Memcheck.

Optional: To Construct Docs, etc...

• Doxygen, Ruby, gcovr (as Python package).

Building BSL

Note. build.sh is the BSL general build script, that mostly serves as a wrapper for CMake commands. Most actions to configure, build, and deploy BSL work through this script.

# To view available subcommands
./build.sh help

To clone submodules, build, and run the unit tests:

# Clone dependencies
git submodule update --init --recursive

# Build dependencies
./build.sh deps

# Prepare build environment
./build.sh prep

# Build the software
./build.sh

# Run unit tests
./build.sh check

This will take about a minute to build and run the unit tests, there should be 100% success.

Note: On earlier versions of CMake (<3.20), ./build.sh check target may not run correctly.

Optional Additional Build Targets

Code Coverage

./build.sh coverage

The output HTML can be opened in a browser using:

xdg-open build/default/coverage-html/index.html

Doxygen Documentation

./build.sh prep -DBUILD_DOCS_API=ON
./build.sh docs

The output HTML can be opened in a browser using:

xdg-open build/default/docs/api/html/index.html

To check for misspelling in the Doxygen output use the following, substituting the word/phrase you are looking for in the grep command

xmlstarlet tr build/default/docs/api/xml/combine.xslt build/default/docs/api/xml/index.xml | xmlstarlet tr docs/api/spellcheck.xsl | cat -n | grep -E 'bsl'

Testing with the Mock BPA

The Mock BPA demonstrates how a BPA may interact with the BSL, it is found in src/mock_bpa.

Details of the Mock BPA are found in the Doxygen documentation.

Mock BPA System Test

To execute the Mock BPA tests of the BSL libraries as-built, first prepare a Pythong virtualenv using:

python3 -m venv venv
source venv/bin/activate
pip install -r mock-bpa-test/requirements.txt

Then execute the test suite using:

python3 -m pytest mock-bpa-test --log-cli-level=info

Running with Wireshark and Local Sockets

wireshark -i lo -f 'port 4556 or port 24556' -k

Start the mock BPA with local sockets:

./build.sh
./build.sh install
./build.sh run bsl-mock-bpa -u localhost:4556 -r localhost:14556 -o localhost:24556 -a localhost:34556

Send a trial bundle from the underlayer, which is taken from Appendix A.1.4 of RFC 9173.

echo 9f88070000820282010282028202018202820201820018281a000f4240850b0200005856810101018202820201828201078203008181820158403bdc69b3a34a2b5d3a8554368bd1e808f606219d2a10a846eae3886ae4ecc83c4ee550fdfb1cc636b904e2f1a73e303dcd4b6ccece003e95e8164dcc89a156e185010100005823526561647920746f2067656e657261746520612033322d62797465207061796c6f6164ff | xxd -r -p | socat stdio udp-sendto:localhost:4556,pf=ip6,sourceport=14556 | xxd -p

Alternatively for the overlayer app socket use socat stdio unix-sendto:/tmp/foo.sock instead.