From 8fe7fa0d50795db1c532a53590a971347c3a6894 Mon Sep 17 00:00:00 2001 From: Brian Sipos Date: Thu, 16 Jul 2026 10:35:20 -0400 Subject: [PATCH 1/5] Add more explanation and diagram for options --- user-guide/manual.adoc | 33 +++++++++++++++++++++++++++++---- user-guide/static/classes.puml | 4 +++- 2 files changed, 32 insertions(+), 5 deletions(-) diff --git a/user-guide/manual.adoc b/user-guide/manual.adoc index 8e374f4..5782e9c 100644 --- a/user-guide/manual.adoc +++ b/user-guide/manual.adoc @@ -455,15 +455,40 @@ plantuml::static/bsl-breakdown.puml[format=svg,scale=60] 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. +The data-use relationships of security operations between PP and SC are depicted in <>. [#fig-secop-assoctaions] .Security Operation Associations plantuml::static/secop-associations.puml[format=svg,scale=60] +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, as depicted in <>. +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. +A key distinction from the point of view of the SC is that options are internal to the BSL and implicitly trusted, while Parameters and Results (when used as verifier or acceptor role) are untrusted input coming from outside the BPA. + +Options are also used to define how operations behave for the source role, but are also used to constrain acceptable behaviors for verifier or acceptor role. +For example, an option can restrict that verification _must_ use a specific security algorithm/strength and if the received operation uses a different algorithm/strength it will be treated as a failure during execution. + +[#fig-secop-in-out] +.Logical Relationship between Options and Parameters +[graphviz,format=svg,width=80mm] +---- +digraph figure { + node [shape=rectangle]; + + sc [label="Security Context\n(execute)"] + policy [label="Policy Provider"] + asbin [label="ASB (input)"] + asbout [label="ASB (output)"] + + { rank=same; policy; sc; } + + policy -> sc [label="Options"] + asbin -> sc [label="Parameters\n and Results", style=dashed] + sc -> asbout [label="Parameters\n and Results", style=dashed] +} +---- + [#sec-api-secondary] === Secondary Interactions diff --git a/user-guide/static/classes.puml b/user-guide/static/classes.puml index c870a56..23b1b68 100644 --- a/user-guide/static/classes.puml +++ b/user-guide/static/classes.puml @@ -30,7 +30,9 @@ class "Security Operation" as SecOp { + role : BPSec Role + target : uint64 + context ID : int16 - + options : Option[0..*] + + options : Map + + parameters : Map + + results : Map + conclusion : bool [0..1] } From ddebf37a54d78a527579b581b3bd53768fec29f6 Mon Sep 17 00:00:00 2001 From: Brian Sipos Date: Fri, 17 Jul 2026 14:26:43 -0400 Subject: [PATCH 2/5] Updates for new crypto key store --- user-guide/manual.adoc | 48 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 9 deletions(-) diff --git a/user-guide/manual.adoc b/user-guide/manual.adoc index 5782e9c..a65123a 100644 --- a/user-guide/manual.adoc +++ b/user-guide/manual.adoc @@ -489,6 +489,24 @@ digraph figure { } ---- +The internal representation of Options, Parameters, and Results within the BSL takes the form of a _variant_ capable of holding a value with one of the following types: + +Int64:: +Used to convey signed and unsigned integer values. +This is limited to 63-bits of magnitude, but currently there are no code points or flags that require all 64 bits of unsigned integer. + +Byte String:: +Used to convey byte string values from configuration or from ASB content. +For example, authentication tags of default security contexts or COSE messages of the COSE context. + +Text String:: +Used to convey text string values from configuration. +There are currently no security contexts which use text strings as a parameter or result. + +Raw:: +Used to convey other context-specific byte-string-encoded values. +For example, the AAD Scope option and parameter for the COSE context as a CBOR-encoded map. + [#sec-api-secondary] === Secondary Interactions @@ -538,13 +556,21 @@ Security Contexts must validate Security Operations for consistency, and process The BSL includes its own context implementations, as explained in <> and <>, which are also used by the Mock BPA for BSL testing (see <>). -[#sec-api-sc-crypto] -==== Cryptographic Processing +[#sec-api-crypto] +=== Cryptographic Processing -Both of the default contexts use the BSL frontend for abstracting cryptographic processing. -It is expected that alternative and/or future contexts will also use the BSL frontend for abstracting such processing, and that that frontend API will evolve as those needs change. +Both of the default contexts and the COSE context use a BSL "crypto" library for abstracting cryptographic processing. +It is expected that alternative and/or future contexts will also use this library for abstracting such processing, and that that frontend API of that library will evolve as those needs change. -The BSL backend cryptographic interface utilizes OpenSSL to perform HMAC-signing, encryption, and decryption operations through its "EVP" primitives APIs <>. +The BSL backend cryptographic interface utilizes OpenSSL to perform AES key wrap/unwrap, HKDF derivation, HMAC integrity, and AES-GCM encryption operations through its "EVP" primitives APIs <>. + +[#sec-api-crypto-keystore] +==== Key Store Interface + +Part of the software-only cryptographic API is the need for an in-memory symmetric key store to provide key material to OpenSSL APIs. + +The crypto library reads key material and updates telemetry counters in the key store. +The implementation of the key store is delegated to the host BPA through callbacks (registered during startup <>). [#sec-api-preprocessor] === Preprocessor Define Directives @@ -563,11 +589,16 @@ A simple BPA that utilizes the example policy provider, default security context The following steps are not thread safe and must be performed before any BSL context instances are initialized (in <>). -. *Set & Initialize Host Descriptors*: +. *Set 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. +. *Set Key Store Descriptors*: +The BSL crypto interface relies on a host-specific cryptographic key store to access key material needed by security contexts. +The function-pointer fields of a `BSL_KeyStore_Descriptors_t` struct should be set with host-implemented functions and initialized with `BSL_KeyStore_Init()` for successful BSL operation. + + [#sec-workflow-bslctx] === Initialization of a BSL Context @@ -585,9 +616,8 @@ 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 two Default Security Contexts ("BIB-HMAC-SHA2" and "BCB-AES-GCM") with the Library Context. +. *Register Default Security Contexts with the Library Context*: +Register the needed Default Security Contexts (BIB-HMAC-SHA2, BCB-AES-GCM, and COSE) with the Library Context. [#sec-workflow-bundle] === Single-Bundle Workflow From 49a3453dd7f9436b5b38bcc2c3edfb8d4062f714 Mon Sep 17 00:00:00 2001 From: Brian Sipos Date: Thu, 13 Aug 2026 14:57:55 -0400 Subject: [PATCH 3/5] spelling --- user-guide/dictionary.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/user-guide/dictionary.txt b/user-guide/dictionary.txt index 1d9a0f1..a12acb9 100644 --- a/user-guide/dictionary.txt +++ b/user-guide/dictionary.txt @@ -93,6 +93,7 @@ TBD toc UDP UML +untrusted UTF verifier Verifier From 1a945836abfc290fcc42e4810cb3ba362bde10dd Mon Sep 17 00:00:00 2001 From: Brian Sipos Date: Thu, 13 Aug 2026 15:08:44 -0400 Subject: [PATCH 4/5] Add specific terms --- user-guide/dictionary.txt | 1 + user-guide/manual.adoc | 2 ++ 2 files changed, 3 insertions(+) diff --git a/user-guide/dictionary.txt b/user-guide/dictionary.txt index a12acb9..64648fa 100644 --- a/user-guide/dictionary.txt +++ b/user-guide/dictionary.txt @@ -46,6 +46,7 @@ executables frontend Frontend GCM +HKDF HMAC IANA IEC diff --git a/user-guide/manual.adoc b/user-guide/manual.adoc index a65123a..4a62a07 100644 --- a/user-guide/manual.adoc +++ b/user-guide/manual.adoc @@ -89,6 +89,7 @@ The following are cryptographic terms (used within security context options and Key Derivation Function (KDF):: A cryptographic function used to derive symmetric key material from input key material, an entropy-adding "salt" value, and opaque context information data. +One variety of of this type of function is a hash-based KDF (HKDF). Key Derivation Key (KDK):: A key used as an input to a key-derivation function to derive additional keying material. Key Encryption Key (KEK):: @@ -103,6 +104,7 @@ Additional Authenticated Data (AAD):: The input data to the authenticated encryption function that is authenticated but not encrypted. Message Authentication Code (MAC):: A symmetric key algorithm used to provide integrity over some plaintext, which can itself be composed of a payload along with additional authenticated data. +One variety of of this type of function is a hash-based MAC (HMAC). [#list-terms-bpsec] The following are BP- and BPSec-related terms: From 595e3c0416b5bb2fca6ac660c788e6ea80ce9803 Mon Sep 17 00:00:00 2001 From: Brian Sipos Date: Tue, 18 Aug 2026 14:18:03 -0400 Subject: [PATCH 5/5] Fixing typos --- user-guide/manual.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/user-guide/manual.adoc b/user-guide/manual.adoc index 4a62a07..9ccf83b 100644 --- a/user-guide/manual.adoc +++ b/user-guide/manual.adoc @@ -89,7 +89,7 @@ The following are cryptographic terms (used within security context options and Key Derivation Function (KDF):: A cryptographic function used to derive symmetric key material from input key material, an entropy-adding "salt" value, and opaque context information data. -One variety of of this type of function is a hash-based KDF (HKDF). +One variety of this type of function is a hash-based KDF (HKDF). Key Derivation Key (KDK):: A key used as an input to a key-derivation function to derive additional keying material. Key Encryption Key (KEK):: @@ -104,7 +104,7 @@ Additional Authenticated Data (AAD):: The input data to the authenticated encryption function that is authenticated but not encrypted. Message Authentication Code (MAC):: A symmetric key algorithm used to provide integrity over some plaintext, which can itself be composed of a payload along with additional authenticated data. -One variety of of this type of function is a hash-based MAC (HMAC). +One variety of this type of function is a hash-based MAC (HMAC). [#list-terms-bpsec] The following are BP- and BPSec-related terms: @@ -562,7 +562,7 @@ The BSL includes its own context implementations, as explained in <>.