Be more strict about public header files to install

.github/workflows/build-test.yaml

@@ -96,9 +96,11 @@ jobs:
         run: |
           ./check_symbols.py bsl_front bsl_dynamic --prefix bsl_
           ./check_symbols.py bsl_crypto --prefix bsl_ bslb_
-          ./check_symbols.py bsl_default_sc --prefix bslx_
+          ./check_symbols.py bsl_default_sc bsl_cose_sc --prefix bslx_
           ./check_symbols.py bsl_sample_pp --prefix bslp_
           ./check_symbols.py bsl_mock_bpa --prefix MockBPA_ bsl_eidpat_ bsl_mock_ mock_bpa_
+      - name: Trial build
+        run: ./build.sh check-install
       - name: Test
         run: ./build.sh check
       - name: Collect coverage

.github/workflows/packages.yaml

@@ -112,26 +112,8 @@ jobs:
           sparse-checkout: |
             mock-bpa-test
             lib-user-test
-      - name: Show pkg-config
-        env:
-          PKGS: bsl bsl-sample-pp
-        run: |
-          echo "Provides:"
-          pkg-config --print-provides ${PKGS}
-          echo "Requires:"
-          pkg-config --print-requires ${PKGS}
-          echo -n "CFlags: "
-          pkg-config --cflags ${PKGS}
-          echo -n "Libs: "
-          pkg-config --libs ${PKGS}
       - name: Trial build
-        env:
-          PKGS: bsl bsl-sample-pp
-        run: |
-          mkdir build
-          gcc -c $(pkg-config --cflags ${PKGS}) -o build/example.o lib-user-test/main.c
-          gcc $(pkg-config --libs ${PKGS}) -o build/example build/example.o
-          ./build/example
+        run: ./build.sh check-install
       - name: Mock BPA tests
         run: |
           pip3 install -r mock-bpa-test/requirements.txt

CMakeLists.txt

@@ -19,7 +19,7 @@ Institute of Technology, sponsored by the United States Government under
 the prime contract 80NM0018D0004 between the Caltech and NASA under
 subcontract 1700763.
 ]]
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.23)
 message(STATUS "Build mode ${CMAKE_BUILD_TYPE}")
 
 option(BUILD_LIB "Build the library itself" ON)

README.md

@@ -22,8 +22,6 @@ subcontract 1700763.
 
 # The NASA AMMOS BPSec Library (BSL)
 
-![example workflow](https://github.com/github/docs/actions/workflows/build-test.yml/badge.svg)
-
 The BPSec Library (BSL) is an implementation of *Bundle Protocol Security* as specified in [RFC 9172](https://datatracker.ietf.org/doc/rfc9172/) and [RFC 9173](https://datatracker.ietf.org/doc/rfc9173/), 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.
@@ -32,49 +30,54 @@ The BSL exposes an interface via C header files (under `src`), and contains an e
 
 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.
-
-```
+```sh
 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
+├── pkg/                 # Material for building RPMs and pkg-config
 ├── resources/           # Additional helper util scripts
 ├── src/                 # Source code, top level is header-only API
-├── src/backend          # Implementation of example dynamic backend
+├── src/front            # Implementation of BSL frontend
+├── src/dynamic          # Implementation of dynamic backend
+├── src/sample_pp        # Implementation of the example policy provider
+├── src/default_sc       # Implementation of Default Security Contexts (RFC 9173)
+├── src/cose_sc          # Implementation of COSE Context
+├── src/crypto           # Implementation of BSL crypto library and key store interface
 ├── 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
+├── test/                # Unit tests
+├── mock-bpa-test/       # Full BSL test/example using Mock BPA
+└── lib-user-test/       # Test an installation of the BSL for building
 ```
 
 ## 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.
+> [!NOTE]
+> BSL uses **Red Hat Enterprise Linux (RHEL 9)** as the target build environment.
+> Ubuntu is frequently used by developers, and for CI jobs, 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, Ruby, jansson-devel.
+ * CMake, GCC or Clang, OpenSSL (development), Ninja Build, Valgrind, Memcheck, Ruby, Jansson (development).
 
 _Optional: To Construct Docs, etc..._
- * Doxygen, gcovr (as Python package), graphviz, plantuml, texlive-bibtex, asciidoctor.
+ * Doxygen, gcovr (as Python package), pkg-config tool, graphviz, plantuml, texlive-bibtex, asciidoctor.
 
 ## 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
+The top `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 of the script:
+```sh
 ./build.sh help
 ```
 
 To clone submodules, build, and run the unit tests:
 
-```
+```sh
 # Clone dependencies
 git submodule update --init --recursive
 
@@ -93,14 +96,14 @@ git submodule update --init --recursive
 
 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
-```
+
+```sh
 ./build.sh coverage
 ```
+
 > [!NOTE]
 > The coverage target requires that the build prepare stage was run with the CLI flag `-DBUILD_COVERAGE=ON`:
 > ```
@@ -109,26 +112,43 @@ Code Coverage
 > For a full list of optional build flags, see [section 3.4.1 of the BSL product guide](https://nasa-ammos.github.io/BSL-docs/product-guide/html/index.html#sec-proc-build-devel-cmake).
 
 The output HTML can be opened in a browser using:
-```
+```sh
 xdg-open build/default/coverage-html/index.html
 ```
 
 Doxygen Documentation
-```
+```sh
 ./build.sh prep -DBUILD_DOCS_API=ON
 ./build.sh docs
 ```
 
 The output HTML can be opened in a browser using:
-```
+```sh
 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
-```
+```sh
 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'
 ```
 
+## Installing BSL
+
+After building, the BSL libraries, headers, and build support files (CMake and pkg-config) can be installed using:
+```sh
+./build.sh install
+```
+
+> [!NOTE]
+> The default install script uses environment `DESTDIR=testroot` and `PREFIX=/usr` which installs files under `./testroot/usr/...` paths.
+> This allows installing without special permissions on the host.
+> Alternatively, the install can be used with different environment such as `DESTDIR=/` to install to system paths.
+
+After install, a trial executable which simply links against the installed BSL using pkg-config discovery can be tested using:
+```sh
+./build.sh check-install
+```
+
 ## Testing with the Mock BPA
 
 The Mock BPA demonstrates how a BPA may interact with the BSL, it is found in `src/mock_bpa`.
@@ -138,33 +158,49 @@ 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:
-```
+```sh
 python3 -m venv venv
 source venv/bin/activate
 pip install -r mock-bpa-test/requirements.txt
 ```
 
 Then execute the test suite using:
-```
+```sh
 python3 -m pytest mock-bpa-test --log-cli-level=info
 ```
 
-### Running with Wireshark and Local Sockets
+### Running with Wireshark and Local UDP transport
 
-```
-wireshark -i lo -f 'port 4556 or port 24556' -k
+The Mock BPA uses local UDP datagram transport.
+This relies on the fact the the loopback device will have a large MTU to avoid the need for BP PDU segmentation.
+
+The UDP ports can be monitored using stock Wireshark with the following command line:
+```sh
+wireshark -i lo -k \
+    -f 'udp port 4556 or udp port 14556 or udp port 24556 or udp port 34556' \
+    -d 'udp.port==14556,bundle' -d 'udp.port==24556,bundle' -d 'udp.port==34556,bundle' \
+    -Y bpv7
 ```
 
 Start the mock BPA with local sockets:
-```
+```sh
 ./build.sh
 ./build.sh install
-./build.sh run bsl-mock-bpa -u localhost:4556 -r localhost:14556 -o localhost:24556 -a localhost:34556
+./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.
+```sh
+echo 9f88070000820282010282028202018202820201820018281a000f4240850b0200005856810101018202820201828201078203008181820158403bdc69b3a34a2b5d3a8554368bd1e808f606219d2a10a846eae3886ae4ecc83c4ee550fdfb1cc636b904e2f1a73e303dcd4b6ccece003e95e8164dcc89a156e185010100005823526561647920746f2067656e657261746520612033322d62797465207061796c6f6164ff | \
+    xxd -r -p | \
+    socat stdio udp-sendto:localhost:4556,pf=ip6,sourceport=14556 | \
+    xxd -p
 ```
-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.
+This example assumes that the `bsl-mock-bpa` resolves "localhost" to an IPv6 address (which is the default on RHEL-9), if not the socat can replace `pf=ip6` with `pf=ip4` to force IPv4 use.
 
+Alternatively for the overlayer app socket use `socat stdio udp-sendto:localhost:24556,pf=ip6,sourceport=34556` instead.
+
+> [!NOTE]
+> The output can be observed as CBOR extended diagnostic notation (EDN) using a CLI tool such as [cbor-diag](https://github.com/cabo/cbor-diag) by replacing `xxd -p` with `cbor2diag.rb`.
+> Similarly, the input can be provided in EDN by piping through `diag2cbor.rb` instead of hex piped through `xxd -r -p`.

build.sh

@@ -39,6 +39,7 @@ function usage {
     echo "  apply-format   - Apply format to all source code"
     echo "  apply-license  - Apply/update license preamble to files"
     echo "  check          - Run unit tests"
+    echo "  check-install  - Build a test executable linked to BSL"
     echo "  clean          - Clean build artifacts"
     echo "  deps           - Build dependend libraries"
     echo "  docs           - Build HTML and/or PDF doxygen"
@@ -56,18 +57,47 @@ function cmd_check_format {
 }
 
 function cmd_apply_format {
-    exec ./resources/apply_format.sh
+    shift
+    exec ./resources/apply_format.sh "$@"
 }
 
 function cmd_apply_license {
-    exec ./resources/apply_license.sh
+    shift
+    exec ./resources/apply_license.sh "$@"
 }
 
 function cmd_check {
     shift
     ctest --test-dir ${BUILDDIR} --output-on-failure "$@"
 }
 
+function cmd_check_install {
+    cd "${SELFDIR}"
+    if [[ -d testroot ]]
+    then
+        export PKG_CONFIG_PATH=$(find testroot/ -type d -name pkgconfig | tr '\n' ':')
+        PKG_PREFIX="--define-variable=prefix=testroot/usr"
+        echo "Using prefix: ${PKG_PREFIX}"
+    else
+        PKG_PREFIX=""
+    fi
+    PKGS="bsl bsl-sample-pp"
+
+    echo "Provides:"
+    pkg-config --print-provides ${PKGS}
+    echo "Requires:"
+    pkg-config --print-requires ${PKGS}
+    echo -n "CFlags: "
+    pkg-config ${PKG_PREFIX} --cflags ${PKGS}
+    echo -n "Libs: "
+    pkg-config ${PKG_PREFIX} --libs ${PKGS}
+
+    mkdir -p build
+    gcc -c -o build/example.o lib-user-test/main.c $(pkg-config ${PKG_PREFIX} --cflags ${PKGS})
+    gcc -o build/example build/example.o $(pkg-config ${PKG_PREFIX} --libs ${PKGS})
+    ./build/example
+}
+
 function cmd_clean {
     rm -rf build testroot deps/build
 }
@@ -184,14 +214,17 @@ case "$1" in
         cmd_check_format
         ;;
     apply-format)
-        cmd_apply_format
+        cmd_apply_format "$@"
         ;;
     apply-license)
-        cmd_apply_license
+        cmd_apply_license "$@"
         ;;
     check)
         cmd_check "$@"
         ;;
+    check-install)
+        cmd_check_install
+        ;;
     clean)
         cmd_clean
         ;;

lib-user-test/main.c

@@ -4,6 +4,10 @@
 
 #include <bsl/BPSecLib_Public.h>
 #include <bsl/BPSecLib_Private.h>
+#include <bsl/default_sc/DefaultSecContext.h>
+#include <bsl/cose_sc/CoseContext.h>
+#include <bsl/sample_pp/SamplePolicyProvider.h>
+#include <bsl/sample_pp/PolicyParser.h>
 
 int main(int argc, char *argv[])
 {

mock-bpa-test/README.md

@@ -23,11 +23,3 @@ subcontract 1700763.
 This directory contains a set of pytest-compatible test fixtures to exercise the Mock BPA.
 It will run using `./build.sh run` which will execute with a PATH environment preferring `./testroot/usr/bin` followed by system paths.
 This means it can test a local build as well as test the installed RPM packages.
-
-Tests can be logged using Wireshark similar to
-```sh
-wireshark -i lo -k \
-    -f 'udp port 4556 or udp port 14556 or udp port 24556 or udp port 34556' \
-    -d 'udp.port==14556,bundle' -d 'udp.port==24556,bundle' -d 'udp.port==34556,bundle' \
-    -Y bpv7
-```

pkg/bsl-cose-sc.pc.in

@@ -5,6 +5,6 @@ libdir=${prefix}/@CMAKE_INSTALL_LIBDIR@
 Name: bsl-cose-sc
 Description: BSL COSE Context provider
 Version: @PROJECT_VERSION@
-Requires: bsl
+Requires: bsl, m-lib
 Cflags: -I${includedir}
 Libs: -L${libdir} -lbsl_cose_sc