|
| 1 | +@page bpa-integrators BPA Integrator Topics |
| 2 | +<!-- |
| 3 | +Copyright (c) 2025 The Johns Hopkins University Applied Physics |
| 4 | +Laboratory LLC. |
| 5 | +
|
| 6 | +This file is part of the Bundle Protocol Security Library (BSL). |
| 7 | +
|
| 8 | +Licensed under the Apache License, Version 2.0 (the "License"); |
| 9 | +you may not use this file except in compliance with the License. |
| 10 | +You may obtain a copy of the License at |
| 11 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | +Unless required by applicable law or agreed to in writing, software |
| 13 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 14 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 | +See the License for the specific language governing permissions and |
| 16 | +limitations under the License. |
| 17 | +
|
| 18 | +This work was performed for the Jet Propulsion Laboratory, California |
| 19 | +Institute of Technology, sponsored by the United States Government under |
| 20 | +the prime contract 80NM0018D0004 between the Caltech and NASA under |
| 21 | +subcontract 1700763. |
| 22 | +--> |
| 23 | + |
| 24 | +This page covers the using BSL from the perspective of a BPA developer integrating the BSL through its _service interface_. |
| 25 | + |
| 26 | +# BPA--BSL Interactions |
| 27 | + |
| 28 | +A BPA interacts with the BSL through two distinct interfaces: |
| 29 | + |
| 30 | + * A **[service interface](@ref bsl-service-api)** provided by the BSL, which is called by the BPA when security processing of a bundle is needed |
| 31 | + * A **[callback interface](@ref bpa-callback-api)** provided by the BPA |
| 32 | + |
| 33 | +@dot "BPA--BSL Interfaces" width=500pt |
| 34 | +digraph bpa_interfaces { |
| 35 | + rankdir=TB; |
| 36 | + node [shape=record, fontname=Helvetica, fontsize=12]; |
| 37 | + |
| 38 | + bpa [ label="BPA" ]; |
| 39 | + bsl [ label="BSL" ]; |
| 40 | + |
| 41 | + bpa -> bsl [ xlabel="BSL Service API" ]; |
| 42 | + bsl -> bpa [ xlabel="BPA Callback API" ]; |
| 43 | +} |
| 44 | +@enddot |
| 45 | + |
| 46 | +# BSL Service API {#bsl-service-api} |
| 47 | + |
| 48 | +Each runtime instance of the BSL is isolated for thread safety within a host-specific struct referenced by a [BSL_LibCtx_t](@ref BSL_LibCtx_s) pointer. |
| 49 | + |
| 50 | +The runtime instance is used by the BPA via the BSL _service interface_ to process bundles at each of the following four security interaction points within the BPA's bundle workflow. |
| 51 | +When invoked from the BPA, all BSL activities will occur within the context of a single bundle which is referenced by a ::BSL_BundleRef_t pointer. |
| 52 | + |
| 53 | +Details of how the BSL processing order relates to other BPA processing of bundles along the BPA's workflow are left to the BPA integration. |
| 54 | + |
| 55 | +* After bundle **transmission** from an application source, indicated by ::BSL_POLICYLOCATION_APPIN |
| 56 | +* Before bundle **delivery** to an application destination, indicated by ::BSL_POLICYLOCATION_APPOUT |
| 57 | +* After bundle **reception** via a CLA, indicated by ::BSL_POLICYLOCATION_CLIN |
| 58 | +* Before bundle **forwarding** via a CLA, indicated by ::BSL_POLICYLOCATION_CLOUT |
| 59 | + |
| 60 | +These are shown for a notional BPA in the diagram below, where each edge indicates one of the four interaction points listed above. |
| 61 | + |
| 62 | +@dot "BPA Interaction Points" width=500pt |
| 63 | +digraph bpa_interaction { |
| 64 | + rankdir=LR; |
| 65 | + node [shape=record, fontname=Helvetica, fontsize=12]; |
| 66 | + |
| 67 | + process [ label="Bundle Dispatch\nand Forwarding" ]; |
| 68 | + appin [ label="Application\nTransmission" ]; |
| 69 | + appout [ label="Application\nDelivery" ]; |
| 70 | + clin [ label="CLA\nReception" ]; |
| 71 | + clout [ label="CLA\nForwarding" ]; |
| 72 | + |
| 73 | + appin -> process [ label="BSL Call\n(APPIN)" ]; |
| 74 | + process -> appout [ label="BSL Call\n(APPOUT)" ]; |
| 75 | + clin -> process [ label="BSL Call\n(CLIN)" ]; |
| 76 | + process -> clout [ label="BSL Call\n(CLOUT)" ]; |
| 77 | +} |
| 78 | +@enddot |
| 79 | + |
| 80 | +# BPA Callback API {#bpa-callback-api} |
| 81 | + |
| 82 | +Separate from the API used to call into the BSL to initiate security processing, the BSL relies on specific functions provided by the BPA to do its normal processing. |
| 83 | +Some of these functions are for introspecting and manipulating specific bundle or block contents, others are for encoding and decoding EID and EID Pattern values. |
| 84 | + |
| 85 | +The BSL dynamic backend declares a set of functions which are delegated to the BPA, which are registered in the dynamic backend using the ::BSL_HostDescriptors_t struct and the BSL_HostDescriptors_Set() function. |
0 commit comments