Bundle Protocol (BP) Manifest Block

1.3. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

2.1. Well-known Metadata Items

The metadata items, and their keys, defined in this section apply only to the first map within the Manifest BTSD content. These items relate to the creation of the Manifest itself and not to any individual blocks covered by the Manifest.¶

$$metadata-item //= (
  0: int16
)

$$metadata-item //= (
  2: embed-eid-structure
)
; TODO: copied from [draft-ietf-dtn-eid-pattern] but should be reference
embed-eid-structure = bstr .cbor eid-structure

$$metadata-item //= (
  3: dtn-time
)

2.2. Common Block Items

The block data items, and their keys, defined in this section apply to all block types equivalently and can be present for any associated block type. These items relate to the BPv7 canonical block structure as defined in Section 4.3.2 of [RFC9171] without concern for the specific block type or content of the BTSD.¶

$$blockdata-item //= (
  1: block-id
)
block-id = [
  ; From the IANA Bundle Block Types registry
  block-type: uint,
  block-num: uint,
]

$$blockdata-item //= (
  2: block-control-flags
)

$$blockdata-item //= (
  5: btsd-len
)
btsd-len = uint

$$blockdata-item //= (
  ; One or more pair of hash outputs
  6: [+ btsd-hash]
)
btsd-hash = (
  ; From the IANA COSE Algorithms registry
  alg: tstr / int,
  value: bstr
)

3.1. Creation

The decision of when and why a Manifest is created and added to a Bundle is a local policy decision on a node.¶

The Reason item SHALL be present in all metadata maps. This metadata item is needed by other nodes to filter Manifest blocks and to interpret their semantics. The definition of a reason code can refine and require specific metadata or block data items to be present (see Section 4).¶

The selection of which blocks to cover by a Manifest is also a local policy decision and likely depends on the Reason code. Each covered block will correspond with a separate block data map.¶

The Block Identity item SHALL be present in each block data map. All of the other items in the block data map depend on its block number to create and verify, and some (specifically negative keys) depend on its block type.¶

3.2. Verification

The general Manifest verification procedure checks items in each block data map against the actual block data. Because blocks can be discarded after a Manifest has been created, one possible outcome for an individual block verification is that the block is missing; a missing covered block is a valid outcome and does not affect the verification of other blocks referenced by the same Manifest. It is a policy decision for how to act upon the outcome of verification, including cases of missing covered blocks.¶

The verification of a Manifest SHALL include checking whether the Manifest covers a minimum set of blocks, and if each block data map contains a minimum set of items. It is a matter of local policy on a verifier (within constraints for the associated Reason) to determine the minimum acceptable coverage for any particular Manifest.¶

The verification of a Manifest SHALL include verification of each item contained in each block data map based on the individual item definitions. It is an implementation matter to determine whether verification of a single block needs to stop on the first failure or continue to verify all items. The definition of a reason code can refine and require specific metadata or block data items to succeed in verification (see Section 4).¶

4.1. Preserve Extensions

When bundles are being forwarded through one or more transit networks on their path from source to destination, it is useful to be able to mark at ingress which extension blocks need to be preserved during the transit across those networks. This marking could be created by the edge nodes themselves or by a routing node on either side of the ingress hop.¶

The Manifest reason "Preserve Extensions" (code 2) SHALL be used to indicate that the Manifest block is intended to mark one or more blocks as needing to be kept in the Bundle until the Manifest itself is discarded.¶

When this reason is present, the block itself SHALL be marked with block processing control flags having bit 2 set, indicating "Delete bundle if block can't be processed."¶

When this reason is present in the metadata map, each block data map SHALL contain a Block Identity (key 1). When this reason is present in the metadata map, each block data map MAY contain a BTSD Length (key 5) and/or BTSD Hash (key 6).¶

When verifying for this reason, if any block is missing or has a mismatch with the Manifest the entire verification SHALL be considered to have failed.¶

4.2. Security AAD Hashing

The definition of external additional authenticated data (AAD) in the BPSec COSE context [I-D.ietf-dtn-bpsec-cose] allows an arbitrary number of other blocks (both canonical block metadata and BTSD) to be bound to a security operation on a single target block. Using external AAD coverage allows a security verifier or acceptor to assert that (a chosen subset of) the state of those other blocks at the time of verification matches their state at the time the operation was added to the Bundle. The use of direct BTSD-in-external-AAD is depicted in Figure 11.¶

A side effect of AAD directly covering the BTSD of other blocks is the need to serialize that BTSD as input to the COSE message processing, at the security source and for all verifiers and acceptors. For cases where the AAD covers large BTSD, including that of the payload block, this can impose a large data handling burden on the security processing entity (specifically its cryptographic element).¶

       Target BTSD
         +----------------+
         |                |
+--------+---+   +--------v---+ +------------+
|  Security  |   |   Target   | |  Other     |
|   Block    |   |   Block    | |  Blocks... |
+---^----+---+   +---^--------+ +---^----^---+
    |    |           |              |    |
    +----+-----------+--------------+----+
       AAD from any block header or BTSD

A common way to mitigate this need for cryptographic processing of large data is distill the data using a hash algorithm and then use the hash value as input to the cryptographic function. This preimage hashing is available for the target of a security operation using a COSE Hash Envelope [I-D.ietf-cose-hash-envelope] but is not available for its external AAD. A straightforward use of a Manifest block, defined later in this section, is to capture the hash values of other blocks for external AAD coverage and thus reduce the size of that external AAD needed as cryptographic input.¶

       Target BTSD
         +---------------------------------+
         |                                 |
+--------+---+   +------------+   +--------v---+ +------------+
|  Security  |   |  Manifest  |   |   Target   | |  Other     |
|   Block    |   |   Block    |   |   Block    | |  Blocks... |
+---^----+---+   +---^----^-+-+   +---^--------+ +---^----^---+
    |    |           |    |  \        |              |    |
    +----+-----------+----+   --------+--------------+----+
       AAD (header + BTSD)    Cover with header + BTSD Hash

Because some block types will necessarily have a small expected BTSD length, this use case involves a trade between using a hashing manifest, to guarantee external AAD size, and just using the other block BTSD in the AAD scope directly. For example, when using an overall security strength needing a SHA-384 hash a BTSD Hash item will contain a bstr value of 48 bytes. If the other block being included is a Hop Count type (Section 4.4.3 of [RFC9171]) it will never have a BTSD larger than 19 bytes (or more realistically, for hop limits below 64k, no larger than 7 bytes). It is an implementation matter by the manifest and security source to determine how and when to apply BTSD hashing for external AAD.¶

The Manifest reason "Security AAD Hashing" (code 1) SHALL be used to indicate that the Manifest block is intended to distill the BTSD of one or more blocks in the Bundle to be included in some security scope.¶

When this reason is present, the block itself SHALL be marked with block processing control flags having bit 2 set, indicating "Delete bundle if block can't be processed." TBD: is this adequate to handle middle-boxes that don't care about the Manifest (or any other) block content?¶

For this use case the Manifest Source will be identical to the Security Source of the security block using this Manifest in its AAD scope. When this reason is present in the metadata map, each block data map SHALL contain the following items:¶

• Block Identity (key 1)¶
• Block Flags (key 2)¶
• BTSD Hash (key 6)¶

When this reason is present in the metadata map, each block data map MAY contain a BTSD Length (key 5).¶

When verifying for this reason, if any block is missing or has a mismatch with the Manifest the entire verification SHALL be considered to have failed.¶

When a Manifest with this reason is included in the target or AAD scope of a security operation, the full verification of that operation SHALL include verifying the Manifest. This logic does not need to be implemented as part of BPSec processing, but can be done as part of larger security policy alongside BPSec proper. Although successful verification now requires both BPSec verification and Manifest verification, the order in which these two occur can be done in either order (or even concurrently). Choosing a desirable order allows an implementation to optimize further for expected success and failure modes.¶

4.3. Security Sourcing

When a BPSec security operation is created by a node, as its security source, the security target and its associated security results are embodied within the ASB structure of its parent security block. Because the ASB retains no history of security actions, later updates in the lifecycle of the security operation can cause the parent security block to be modified or even discarded (e.g., if the operation is accepted before the destination node). The reason defined in this section allows security sourcing to be recorded for downstream auditing [I-D.tian-dtn-sbam].¶

The Manifest reason "Security Sourcing" (code 3) SHALL be used to indicate that the Manifest block is intended to record the actions of a security source as defined by BPSec [RFC9172].¶

When this reason is present in the metadata map, each block data map SHALL contain the following items:¶

• Block Identity (key 1) having a covered block type of either 11 or 12 and having a Security Source field from the same node as the Manifest Source¶
• Security Targets (key -1)¶
• Security Context ID (key -2)¶
• Additional data about key identifiers?¶

Multiple block data maps MAY be present as needed to indicate all sourcing actions performed by the node across any security blocks in the Bundle.¶

Because this reason is meant to be used separately from the covered security blocks themselves, with a likely longer block lifecycle, the containing Manifest is not meant to be verified (in the sense of Section 3.2) by any node. This reason can be coupled with Security Acceptance manifest(s) to audit the lifecycles of those covered security blocks.¶

4.4. Security Acceptance

When a BPSec security operation is accepted by a node, the security target and its associated security results are removed from the ASB structure of its parent security block. Because the ASB retains no history of security actions, a removal due to acceptance is not visible downstream from the acceptor node any differently than malicious removal by an on-path attacker. The reason defined in this section allows security acceptance to be recorded for downstream auditing [I-D.tian-dtn-sbam].¶

The Manifest reason "Security Acceptance" (code 4) SHALL be used to indicate that the Manifest block is intended to record the actions of a security acceptor as defined by BPSec [RFC9172].¶

When this reason is present in the metadata map, each block data map SHALL contain the following items:¶

• Block Identity (key 1) having a covered block type of either 11 or 12¶
• Security Targets (key -1)¶
• Security Context ID (key -2)¶
• Additional data about key identifiers?¶

Multiple block data maps MAY be present as needed to indicate all acceptance actions performed by the node across any security blocks in the Bundle.¶

Because this reason is meant to be used when the referenced security operations (and their security targets) are removed from their parent security blocks, the containing Manifest is not meant to be verified (in the sense of Section 3.2) by any node. It is a recording of what was present before the security acceptance and meant to be coupled with either Security Sourcing manifest(s) or out-of-band information about expected security operations.¶

5.2. Threat: Weak Hash Algorithms

When used as defined in Section 4.2 the hashing function(s) become part of the overall security verification. A weak strength hash algorithm in a Manifest will lower the cryptographic binding to the associated BTSD down to the strength of that hashing.¶

When used as BPSec AAD, the choice of BTSD hash algorithm(s) in a Manifest SHALL be at least as strong as the overall security strength of the associated integrity or confidentiality algorithm(s).¶

5.3. Threat: Untrusted Manifest

The mere presence of a Manifest block in a Bundle does not grant any implied trust for the metadata or block data contained in the Manifest. A BPA can compare the block data within a Manifest with the actual blocks of a Bundle before any related security processing to catch mismatches early, but the results of any such comparison need to be treated as conditional on trust of the Manifest block itself.¶

Beyond the specific use in Section 4.2, each Manifest block SHOULD be the target or AAD of an associated BPSec integrity operation.¶

5.4. Threat: Manipulated Manifest

Any Manifest block which is kept in plaintext (i.e., is not the target of a BPSec confidentially operation) is vulnerable to on-path manipulation of its block content, either in-transit or at-rest.¶

The verification requirements in Section 3.2 ensure that entities processing a Manifest block verify not just the contents of the Manifest itself but also verify that the contained block data matches the actual Bundle contents.¶

6.1. BPv7 Block Type

IANA has registered, under the "Bundle Protocol" registry group [IANA-BUNDLE], an entry in the registry "Bundle Block Types" with the following information.¶

IANA NOTE: The TBA1 requested value is the lowest unassigned value (13).¶

6.2. Manifest Registries

EDITOR NOTE: registries to-be-created upon publication of this specification.¶

For all of the registries defined in this section, expert(s) are encouraged to be biased towards approving registrations unless they are abusive, frivolous, or actively harmful (not merely aesthetically displeasing, or architecturally dubious).¶

Specifications of new metadata items need to define the CBOR item structure of the map value as well as the interpretation of that value by entities processing the Manifest. Entities will ignore items with an unknown key, and that behavior needs to be considered by new items.¶

IANA has created, under the "Bundle Protocol" registry group [IANA-BUNDLE], a registry titled "Manifest Metadata Items" and initialize it with the contents of Table 2. For positive code points the registration procedure is Specification Required. Negative code points are reserved for use on private networks for functions not published to the IANA.¶

IANA has created, under the "Bundle Protocol" registry group [IANA-BUNDLE], a registry titled "Manifest Reason Codes" and initialize it with the contents of Table 3. For positive code points the registration procedure is Specification Required. Negative code points are reserved for use on private networks for functions not published to the IANA.¶

IANA has created, under the "Bundle Protocol" registry group [IANA-BUNDLE], a registry titled "Manifest Data Items" and initialize it with the contents of Table 4. For non-negative code points the registration procedure is Specification Required and the Block Type column is empty. For negative code points the registration procedure is Specification Required and the Block Type column references a type from the "Bundle Block Types" registry in the same group.¶