idnits 2.17.1 draft-ietf-dtn-bpsec-default-sc-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 15, 2021) is 1158 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'AES-GCM' == Outdated reference: A later version (-27) exists of draft-ietf-dtn-bpsec-26 ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 4634 (Obsoleted by RFC 6234) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Delay-Tolerant Networking E. Birrane 3 Internet-Draft JHU/APL 4 Intended status: Standards Track February 15, 2021 5 Expires: August 19, 2021 7 BPSec Default Security Contexts 8 draft-ietf-dtn-bpsec-default-sc-01 10 Abstract 12 This document defines default integrity and confidentiality security 13 contexts that may be used with the Bundle Protocol Security Protocol 14 (BPSec) implementations. These security contexts may be used for 15 both testing the interoperability of BPSec implementations and for 16 providing basic security operations when no other security contexts 17 are defined or otherwise required for a network. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on August 19, 2021. 36 Copyright Notice 38 Copyright (c) 2021 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 55 3. Integrity Security Context BIB-HMAC-SHA2 . . . . . . . . . . 3 56 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.3. Parameters . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.3.1. SHA Variant . . . . . . . . . . . . . . . . . . . . . 5 60 3.3.2. Encapsulated Key . . . . . . . . . . . . . . . . . . 6 61 3.3.3. Integrity Scope Flags . . . . . . . . . . . . . . . . 6 62 3.3.4. Enumerations . . . . . . . . . . . . . . . . . . . . 7 63 3.4. Results . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 3.5. Key Considerations . . . . . . . . . . . . . . . . . . . 7 65 3.6. Canonicalization Algorithms . . . . . . . . . . . . . . . 8 66 3.7. Processing . . . . . . . . . . . . . . . . . . . . . . . 9 67 3.7.1. Keyed Hash Generation . . . . . . . . . . . . . . . . 9 68 3.7.2. Keyed Hash Verification . . . . . . . . . . . . . . . 10 69 4. Security Context BCB-AES-GCM . . . . . . . . . . . . . . . . 11 70 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 11 71 4.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 4.3. Parameters . . . . . . . . . . . . . . . . . . . . . . . 13 73 4.3.1. Initialization Vector (IV) . . . . . . . . . . . . . 13 74 4.3.2. AES Variant . . . . . . . . . . . . . . . . . . . . . 13 75 4.3.3. Encapsulated Key . . . . . . . . . . . . . . . . . . 14 76 4.3.4. AAD Scope Flags . . . . . . . . . . . . . . . . . . . 14 77 4.3.5. Enumerations . . . . . . . . . . . . . . . . . . . . 15 78 4.4. Results . . . . . . . . . . . . . . . . . . . . . . . . . 15 79 4.4.1. Authentication Tag . . . . . . . . . . . . . . . . . 16 80 4.4.2. Enumerations . . . . . . . . . . . . . . . . . . . . 16 81 4.5. Key Considerations . . . . . . . . . . . . . . . . . . . 16 82 4.6. Canonicalization Algorithms . . . . . . . . . . . . . . . 17 83 4.6.1. Cipher text related calculations . . . . . . . . . . 17 84 4.6.2. Additional Authenticated Data . . . . . . . . . . . . 18 85 4.7. Processing . . . . . . . . . . . . . . . . . . . . . . . 19 86 4.7.1. Encryption . . . . . . . . . . . . . . . . . . . . . 19 87 4.7.2. Decryption . . . . . . . . . . . . . . . . . . . . . 20 88 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 89 5.1. Security Context Identifiers . . . . . . . . . . . . . . 22 90 6. Normative References . . . . . . . . . . . . . . . . . . . . 22 91 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 23 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23 94 1. Introduction 96 The Bundle Protocol Security Protocol (BPSec) [I-D.ietf-dtn-bpsec] 97 specification provides inter-bundle integrity and confidentiality 98 operations for networks deploying the Bundle Protocol (BP) 99 [I-D.ietf-dtn-bpbis]. BPSec defines BP extension blocks to carry 100 security information produced under the auspices of some security 101 context. 103 This document defines two security contexts (one for an integrity 104 service and one for a confidentiality service) for populating BPSec 105 Block Integrity Blocks (BIBs) and Block Confidentiality Blocks 106 (BCBs). 108 These contexts generate information that MUST be encoded using the 109 CBOR specification documented in [RFC8949]. 111 2. Requirements Language 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 115 "OPTIONAL" in this document are to be interpreted as described in BCP 116 14 [RFC2119] [RFC8174] when, and only when, they appear in all 117 capitals, as shown here. 119 3. Integrity Security Context BIB-HMAC-SHA2 121 3.1. Overview 123 The BIB-HMAC-SHA2 security context provides a keyed hash over a set 124 of plain text information. This context uses the Secure Hash 125 Algorithm 2 (SHA-2) discussed in [RFC4634] combined with the HMAC 126 keyed hash discussed in [RFC2104]. 128 BIB-HMAC-SHA2 supports three variants of HMAC-SHA, based on the 129 supported length of the SHA-2 hash value. These variants correspond 130 to HMAC256-SHA256, HMAC384-SHA384, and HMAC512-SHA512 as defined in 131 [RFC8152] Table 7: HMAC Algorithm Values. The selection of which 132 variant is used by this context is provided as a security context 133 parameter. 135 The output of the HMAC shall be equal to the size of the SHA2 hashing 136 function: 256 bits for SHA-256, 384 bits for SHA-384, and 512 bits 137 for SHA-512. 139 The BIB-HMAC-SHA2 security context shall have the Security Context ID 140 specified in Section 5.1. 142 3.2. Scope 144 The scope of BIB-HMAC-SHA2 refers to the set of information used to 145 produce the plain text over which a keyed hash is calculated. This 146 plain text is termed the "Integrity Protected Plain Text" (IPPT). 147 The contents of the IPPT is constructed as the concatenation of 148 information whose integrity is being preserved from the BIB-HMAC-SHA2 149 security source to its security acceptor. There are four types of 150 information that can be used in the generation of the IPPT, based on 151 how broadly the concept of integrity is being applied. These four 152 types of information, whether they are required, and why they are 153 important for integrity, are discussed as follows. 155 Security target contents 156 The contents of the block-type-specific data field of the 157 security target MUST be included in the IPPT. Including this 158 information protects the security target data and is considered 159 the minimal, required set of information for an integrity service 160 on the security target. 162 Primary block 163 The primary block identifies a bundle and, once created, the 164 contents of this block are immutable. Changes to the primary 165 block associated with the security target indicate that the 166 security target (and BIB) may no longer be in the correct bundle. 168 For example, if a security target and associated BIB are copied 169 from one bundle to another bundle, the BIB may still contain a 170 verifiable signature for the security target unless information 171 associated with the bundle primary block is included in the keyed 172 hash carried by the BIB. 174 Including this information in the IPPT protects the integrity of 175 the association of the security target with a specific bundle. 177 Security target other fields 178 The other fields of the security target include block 179 identification and processing information. Changing this 180 information changes how the security target is treated by nodes 181 in the network even when the "user data" of the security target 182 are otherwise unchanged. 184 For example, if the block processing control flags of a security 185 target are different at a security verifier than they were 186 originally set at the security source then the policy for 187 handling the security target has been modified. 189 Including this information in the IPPT protects the integrity of 190 the policy and identification of the security target data. 192 BIB other fields 193 The other fields of the BIB carrying the security result for this 194 security context security block include block identification and 195 processing information. Changing this information changes how 196 the BIB is treated by nodes in the network, even when other 197 aspects of the BIB are unchanged. 199 For example, if the block processing control flags of the BIB are 200 different at a security verifier than they were originally set at 201 the security source, then the policy for handling the BIB has 202 been modified. 204 Including this information in the IPPT protects the integrity of 205 the policy and identification of the security service in the 206 bundle. 208 NOTE: The security context identifier and security context 209 parameters of the security block are not included in the IPPT 210 because these parameters, by definition, are required to verify 211 or accept the security service. Successful verification at 212 security verifiers and security acceptors implies that these 213 parameters were unchanged since being specified at the security 214 source. 216 The scope of the BIB-HMAC-SHA2 security context is configured using 217 an optional security context parameter. 219 3.3. Parameters 221 BIB-HMAC-SHA2 can be parameterized to select SHA-2 variants, 222 communicate key information, and define the scope of the IPPT. 224 3.3.1. SHA Variant 226 This optional parameter identifies which variant of the SHA-2 227 algorithm is to be used in the generation of the authentication code. 229 This value MUST be encoded as a CBOR unsigned integer. 231 Valid values for this parameter are as follows. 233 SHA Variant Parameter Values 235 +-------+-----------------------------------------------------------+ 236 | Value | Description | 237 +-------+-----------------------------------------------------------+ 238 | 5 | HMAC256/SHA256 as defined in [RFC8152] Table 7: HMAC | 239 | | Algorithm Values | 240 | 6 | HMAC384/SHA384 as defined in [RFC8152] Table 7: HMAC | 241 | | Algorithm Values | 242 | 7 | HMAC512/SHA512 as defined in [RFC8152] Table 7: HMAC | 243 | | Algorithm Values | 244 +-------+-----------------------------------------------------------+ 246 Table 1 248 When not provided, implementations SHOULD assume a value of 6 249 (indicating use of HMAC384/SHA384), unless an alternate default is 250 established by security policy at the security source, verifier, or 251 acceptor of this integrity service. 253 3.3.2. Encapsulated Key 255 This optional parameter contains the output of a Key Encapsulation 256 Mechanism (KEM) run at the security source of this security context. 258 This value MUST be encoded as a CBOR byte string. 260 If provided, this information is used to retrieve the symmetric HMAC 261 key used in the generation of security results for this security 262 context. If not provided, security verifiers and acceptors MUST 263 determine the proper key as a function of their local BPSec policy 264 and configuration, as discussed in Section 3.5. 266 3.3.3. Integrity Scope Flags 268 This optional parameter contains a series of flags that describe what 269 information is to be included with the block-type-specific data when 270 constructing the IPPT value. 272 This value MUST be represented as a CBOR unsigned integer, the value 273 of which MUST be processed as a bit field containing no more than 16 274 bits. 276 Bits in this field represent additional information to be included 277 when generating an integrity signature over the security target. 278 These bits are defined as follows. 280 - Bit 0 (the low-order bit, 0x1): Primary Block Flag. 282 - Bit 1 (0x02): Target Header Flag. 284 - Bit 2 (0x03): Security Header Flag. 286 - Bits 3-7 are reserved. 288 - Bits 8-15 are unassigned. 290 3.3.4. Enumerations 292 BIB-HMAC-SHA2 defines the following security context parameters. 294 BIB-HMAC-SHA2 Security Parameters 296 +----+-----------------------+--------------------+---------------+ 297 | Id | Name | CBOR Encoding Type | Default Value | 298 +----+-----------------------+--------------------+---------------+ 299 | 1 | SHA Variant | UINT | 256 | 300 | 2 | Encapsulated Key | Byte String | NONE | 301 | 3 | Integrity Scope Flags | UINT | 0x7 | 302 +----+-----------------------+--------------------+---------------+ 304 Table 2 306 3.4. Results 308 BIB-HMAC-SHA2 defines the following security results. 310 BIB-HMAC-SHA2 Security Results 312 +--------+----------+-------------+---------------------------------+ 313 | Result | Result | CBOR | Description | 314 | Id | Name | Encoding | | 315 | | | Type | | 316 +--------+----------+-------------+---------------------------------+ 317 | 1 | Expected | byte string | The output of the HMAC | 318 | | HMAC | | calculation at the security | 319 | | | | source. | 320 +--------+----------+-------------+---------------------------------+ 322 Table 3 324 3.5. Key Considerations 326 BIB-HMAC-SHA2 does not define or otherwise mandate any method for key 327 exchange, encryption, or encapsulation. The derivation of an 328 appropriate key for use in the integrity service is considered 329 separate from the application of the integrity service for this 330 context. 332 HMAC keys used with this context MUST be symmetric and MUST have a 333 key length equal to the output of the HMAC. 335 It is assumed that any security verifier or security acceptor 336 performing an integrity verification can determine the proper HMAC 337 key to be used. Potential sources of the HMAC key include (but are 338 not limited to) the following: 340 Pre-placed keys selected based on local policy. 342 Keys extracted from encapsulated key material carried in the BIB. 344 Session keys negotiated via a mechanism external to the BIB. 346 NOTE: When keys are extracted from key material carried in the BIB 347 itself, the encapsulated key SHOULD be protected by an approved 348 algorithm such as NIST SP-800-38F. The determination to use approved 349 algorithms increases interoperability and can be specified as part of 350 local security policy. 352 BIB-HMAC-SHA2 provides no explicit requirements on the configuration, 353 storage, or exchange of HMAC keys. 355 3.6. Canonicalization Algorithms 357 This section defines the canonicalization algorithm used to prepare 358 the IPPT input to the BIB-HMAC-SHA2 integrity mechanism. The 359 construction of the IPPT depends on the settings of the Integrity 360 Scope Flags that may be provided as part of customizing the behavior 361 of this security context. 363 In all cases, the canonical form of any portion of an extension block 364 MUST be performed as described in [I-D.ietf-dtn-bpsec]. The 365 canonicalization algorithms defined in [I-D.ietf-dtn-bpsec] adhere to 366 the canonical forms for extension blocks defined in 367 [I-D.ietf-dtn-bpbis] but resolve ambiguities related to how values 368 are represented in CBOR. 370 The IPPT is constructed using the following process. 372 1. The canonical form of the IPPT starts as the empty set with 373 length 0. 375 2. If the Integrity Scope parameter is present and the Primary Block 376 Flag is set to 1, then a canonical form of the bundle's primary 377 block MUST be calculated and the result appended to the IPPT. 379 3. If the Integrity Scope parameter is present and the Security 380 Header flag is set to 1, then the canonical form of the Block 381 Type Code, Block Number, and Block Processing Control Flags 382 associated with the BIB MUST be calculated and, in that order, 383 appended to the IPPT. 385 4. If the Integrity Scope parameter is present and the Target Header 386 flag is set to 1, then the canonical form of the Block Type Code, 387 Block Number, and Block Processing Control Flags associated with 388 the security target MUST be calculated and, in that order, 389 appended to the IPPT. 391 5. The canonical form of the security target block-type-specific 392 data MUST be calculated and appended to the IPPT. 394 3.7. Processing 396 3.7.1. Keyed Hash Generation 398 During keyed hash generation, two inputs are prepared for the the 399 appropriate HMAC/SHA2 algorithm: the HMAC key and the IPPT. These 400 data items MUST be generated as follows. 402 The HMAC key MUST have the appropriate length as required by local 403 security policy. The key may be generated specifically for this 404 integrity service, given as part of local security policy, or 405 through some other key management mechanism as discussed in 406 Section 3.5. 408 Prior to the generation of the IPPT, if a CRC value is present for 409 the target block of the BIB, then that CRC value MUST be removed 410 from the target block. This involves both removing the CRC value 411 from the target block and setting the CRC Type field of the target 412 block to "no CRC is present." 414 Once CRC information is removed, the IPPT MUST be generated as 415 discussed in Section 3.6. 417 Upon successful hash generation the following actions MUST occur. 419 The keyed hash produced by the HMAC/SHA2 variant MUST be added as 420 a security result for the BIB representing the security operation 421 on this security target, as discussed in Section 3.4). 423 Finally, the BIB containing information about this security operation 424 MUST be updated as follows. These operations may occur in any order. 426 The security context ID for the BIB MUST be set to the context 427 identifier for BIB-HMAC-SHA2. 429 Any local flags used to generate the IPPT SHOULD be placed in the 430 Integrity Scope flags security parameter for the BIB unless these 431 flags are expected to be correctly configured at security 432 verifiers and acceptors in the network. 434 The HMAC key MAY be encapsulated using some key encapsulation 435 mechanism (to include encrypting with a key encryption key) and 436 the results of the encapsulation added as the Encapsulated Key 437 security parameter for the BIB. 439 The SHA Variant used by this security context SHOULD be added as 440 the SHA Variant security parameter for the BIB if it differs from 441 the default key length. Otherwise, this parameter MAY be omitted 442 if doing so provides a useful reduction in message sizes. 444 Problems encountered in the keyed hash generation MUST be processed 445 in accordance with local BPSec security policy. 447 3.7.2. Keyed Hash Verification 449 During keyed hash verification, the input of the security target and 450 a HMAC key are provided to the appropriate HMAC/SHA2 algorithm. 452 During keyed hash verification, two inputs are prepared for the the 453 appropriate HMAC/SHA2 algorithm: the HMAC key and the IPPT. These 454 data items MUST be generated as follows. 456 The HMAC key MUST be derived using the Encapsulated Key security 457 parameter if such a parameter is included in the security context 458 parameters of the BIB. Otherwise, this key MUST be derived in 459 accordance with security policy at the verifying node as discussed 460 in Section 3.5. 462 The IPPT MUST be generated as discussed in Section 3.6 with the 463 value of Integrity Scope flags being taken from the Integrity 464 Scope flags security context parameter. If the Integrity Scope 465 flags parameter is not included in the security context parameters 466 then these flags MAY be derived from local security policy. 468 The calculated HMAC output MUST be compared to the expected HMAC 469 output encoded in the security results of the BIB for the security 470 target. If the calculated HMAC and expected HMAC are identical, the 471 verification MUST be considered a success. Otherwise, the 472 verification MUST be considered a failure. 474 If the verification fails or if any needed parameters are missing 475 then the verification MUST be treated as failed and processed in 476 accordance with local security policy. 478 This security service is removed from the bundle at the security 479 acceptor as required by the BPSec specification. If the security 480 acceptor is not the bundle destination and if no other integrity 481 service is being applied to the target block, then a CRC MUST be 482 included for the target block. The CRC type, as determined by 483 policy, is set in the target block's CRC type field and the 484 corresponding CRC value is added as the CRC field for that block. 486 4. Security Context BCB-AES-GCM 488 4.1. Overview 490 The BCB-AES-GCM security context replaces the block-type-specific 491 data field of its security target with cipher text generated using 492 the Advanced Encryption Standard (AES) cipher operating in Galois/ 493 Counter Mode (GCM) [AES-GCM]. 495 Additionally, the BCB-AES-GCM security context generates an 496 authentication tag based on the plain text value of the block-type- 497 specific data and other additional authenticated data that may be 498 specified via parameters to this security context. 500 This security context supports two variants of AES-GCM, based on the 501 supported length of the symmetric key. These variants correspond to 502 A128GCM and A256GCM as defined in [RFC8152] Table 9: Algorithm Value 503 for AES-GCM. 505 The BCB-AES-GCM security context shall have the Security Context ID 506 specified in Section 5.1. 508 4.2. Scope 510 There are two scopes associated with BCB-AES-GCM: the scope of the 511 confidentiality service and the scope of the authentication service. 512 The first defines the set of information provided to the AES-GCM 513 cipher for the purpose of producing cipher text. The second defines 514 the set of information used to generate an authentication tag. 516 The scope of the confidentiality service defines the set of 517 information provided to the AES-GCM cipher for the purpose of 518 producing cipher text. This MUST be the full set of plain text 519 contained in the block-type-specific data field of the security 520 target. 522 The scope of the authentication service defines the set of 523 information used to generate an authentication tag carried with the 524 security block. This information MUST include the plain text of the 525 block-type-specific data field of the security target. This 526 information MAY include other information (additional authenticated 527 data), as follows. 529 Primary block 530 The primary block identifies a bundle and, once created, the 531 contents of this block are immutable. Changes to the primary 532 block associated with the security target indicate that the 533 security target (and BCB) may no longer be in the correct bundle. 535 For example, if a security target and associated BCB are copied 536 from one bundle to another bundle, the BCB may still be able to 537 decrypt the security target even though these blocks were never 538 intended to exist in the copied-to bundle. 540 Including this information as part of additional authenticated 541 data ensures that security target (and security block) appear in 542 the same bundle at the time of decryption as at the time of 543 encryption. 545 Security target other fields 546 The other fields of the security target include block 547 identification and processing information. Changing this 548 information changes how the security target is treated by nodes 549 in the network even when the "user data" of the security target 550 are otherwise unchanged. 552 For example, if the block processing control flags of a security 553 target are different at a security verifier than they were 554 originally set at the security source then the policy for 555 handling the security target has been modified. 557 Including this information as part of additional authenticated 558 data ensures that the cipher text in the security target will not 559 be used with a different set of block policy than originally set 560 at the time of encryption. 562 BCB other fields 563 The other fields of the BCB include block identification and 564 processing information. Changing this information changes how 565 the BCB is treated by nodes in the network, even when other 566 aspects of the BCB are unchanged. 568 For example, if the block processing control flags of the BCB are 569 different at a security acceptor than they were originally set at 570 the security source then the policy for handling the BCB has been 571 modified. 573 Including this information as part of additional authenticated 574 data ensures that the policy and identification of the security 575 service in the bundle has not changed. 577 NOTE: The security context identifier and security context 578 parameters of the security block are not included as additional 579 authenticated data because these parameters, by definition, are 580 those needed to verify or accept the security service. 581 Therefore, it is expected that changes to these values would 582 result in failures at security verifiers and security acceptors. 584 The scope of the BCB-AES-GCM security context is configured using an 585 optional security context parameter. 587 4.3. Parameters 589 BCB-AES-GCM can be parameterized to specify the AES variant, 590 initialization vector, key information, and identify additional 591 authenticated data. 593 4.3.1. Initialization Vector (IV) 595 This optional parameter identifies the initialization vector (IV) 596 used to initialize the AES-GCM cipher. 598 The length of the initialization vector, prior to any CBOR encoding, 599 MUST be between 8-16 bytes. A value of 12 bytes SHOULD be used 600 unless local security policy requires a different length. 602 This value MUST be encoded as a CBOR byte string. 604 The initialization vector may have any value with the caveat that a 605 value MUST NOT be re-used for multiple encryptions using the same 606 encryption key. This value MAY be re-used when encrypting with 607 different keys. For example, if each encryption operation using BCB- 608 AES-GCM uses a newly generated key, then the same IV may be reused. 610 4.3.2. AES Variant 612 This optional parameter identifies the AES variant being used for the 613 AES-GCM encryption, where the variant is identified by the length of 614 key used. 616 This value MUST be encoded as a CBOR unsigned integer. 618 Valid values for this parameter are as follows. 620 AES Variant Parameter Values 622 +-------+-----------------------------------------------------------+ 623 | Value | Description | 624 +-------+-----------------------------------------------------------+ 625 | 1 | A128GCM as defined in [RFC8152] Table 9: Algorithm Values | 626 | | for AES-GCM | 627 | 3 | A256GCM as defined in [RFC8152] Table 9: Algorithm Values | 628 | | for AES-GCM | 629 +-------+-----------------------------------------------------------+ 631 When not provided, implementations SHOULD assume a value of 3 632 (indicating use of A256GCM), unless an alternate default is 633 established by security policy at the security source, verifier, or 634 acceptor of this integrity service. 636 Regardless of the variant, the generated authentication tag MUST 637 always be 128 bits. 639 4.3.3. Encapsulated Key 641 This optional parameter contains the output of a Key Encapsulation 642 Mechanism (KEM) run at the security source of this security context. 644 This value MUST be encoded as a CBOR byte string. 646 If provided, this information is used to retrieve the symmetric AES 647 key used in the generation of security results for this security 648 context. If not provided, security verifiers and acceptors MUST 649 determine the proper key as a function of their local BPSec policy 650 and configuration, as discussed in Section 4.5. 652 4.3.4. AAD Scope Flags 654 This optional parameter contains a series of flags that describe what 655 information is to be included with the block-type-specific data of 656 the security target as part of additional authenticated data (AAD). 658 This value MUST be represented as a CBOR unsigned integer, the value 659 of which MUST be processed as a bit field containing no more than 16 660 bits. 662 Bits in this field represent additional information to be included 663 when generating an integrity signature over the security target. 664 These bits are defined as follows. 666 - Bit 0 (the low-order bit, 0x1): Primary Block Flag. 668 - Bit 1 (0x02): Target Header Flag. 670 - Bit 2 (0x03): Security Header Flag. 672 - Bits 3-7 are reserved. 674 - Bits 8-15 are unassigned. 676 4.3.5. Enumerations 678 BCB-AES-GCM defines the following security context parameters. 680 BCB-AES-GCM Security Parameters 682 +----+-----------------------+--------------------+---------------+ 683 | Id | Name | CBOR Encoding Type | Default Value | 684 +----+-----------------------+--------------------+---------------+ 685 | 1 | Initialization Vector | Byte String | NONE | 686 | 2 | AES Variant | UINT | 3 | 687 | 3 | Encapsulation Key | Byte String | NONE | 688 | 4 | AAD Scope Flags | UINT | 0x7 | 689 +----+-----------------------+--------------------+---------------+ 691 Table 4 693 4.4. Results 695 The BCB-AES-GCM security context produces a single security result 696 carried in the security block: the authentication tag. 698 NOTES: 700 The cipher text generated by the cipher suite is not considered a 701 security result as it is stored in the block-type-specific data 702 field of the security target block. When operating in GCM mode, 703 AES produces cipher text of the same size as its plain text and, 704 therefore, no additional logic is required to handle padding or 705 overflow caused by the encryption in most cases (see below). 707 If the generated cipher text contains the authentication tag and 708 the tag can be separated from the cipher text then the tag MUST be 709 separated and stored in the Authentication Tag security result 710 field. 712 If the generated cipher text contains the authentication tag and 713 the tag cannot be separated from the cipher text then the tag MUST 714 NOT be included in the Authentication tag security result field. 715 Instead the security target block MUST be resized to accommodate 716 the additional 128 bits of authentication tag included in the 717 generated cipher text. 719 4.4.1. Authentication Tag 721 The authentication tag is generated by the cipher suite over the 722 security target plain text input to the cipher suite as combined with 723 any optional additional authenticated data. This tag is used to 724 ensure that the plain text (and important information associated with 725 the plain text) is authenticated prior to decryption. 727 If the authentication tag is included in the cipher text placed in 728 the security target block-type-specific data field, then this 729 security result MUST NOT be included in the BCB for that security 730 target. 732 The length of the authentication tag, prior to any CBOR encoding, 733 MUST be 128 bits. 735 This value MUST be encoded as a CBOR byte string. 737 4.4.2. Enumerations 739 BCB-AES-GCM defines the following security context parameters. 741 BCB-AES-GCM Security Results 743 +-----------+--------------------+--------------------+ 744 | Result Id | Result Name | CBOR Encoding Type | 745 +-----------+--------------------+--------------------+ 746 | 1 | Authentication Tag | Byte String | 747 +-----------+--------------------+--------------------+ 749 Table 5 751 4.5. Key Considerations 753 BCB-AES-GCM does not define or otherwise mandate any method for key 754 exchange, encryption, or encapsulation. The derivation of an 755 appropriate key is considered separate from the application of the 756 authenticated confidentiality service provided by this context. 758 Keys used with this context MUST be symmetric and MUST have a key 759 length equal to the key length defined in the security context 760 parameters or as defined by local security policy at security 761 verifiers and acceptors. 763 It is assumed that any security verifier or security acceptor can 764 determine the proper key to be used. Potential sources of the key 765 include (but are not limited to) the following. 767 Pre-placed keys selected based on local policy. 769 Keys extracted from encapsulated key material carried in the BCB. 771 Session keys negotiated via a mechanism external to the BCB. 773 NOTE: When keys are extracted from key material carried in the BCB 774 itself, the encapsulated key SHOULD be protected by an approved 775 algorithm such as NIST SP-800-38F. The determination to use approved 776 algorithms increases interoperability and can be specified as part of 777 local security policy. 779 BCB-AES-GCM provides no explicit requirements on the configuration, 780 storage, or exchange of keys. 782 4.6. Canonicalization Algorithms 784 This section defines the canonicalization algorithms used to prepare 785 the inputs used to generate both the cipher text and the 786 authentication tag. 788 In all cases, the canonical form of any portion of an extension block 789 MUST be performed as described in [I-D.ietf-dtn-bpsec]. The 790 canonicalization algorithms defined in [I-D.ietf-dtn-bpsec] adhere to 791 the canonical forms for extension blocks defined in 792 [I-D.ietf-dtn-bpbis] but resolve ambiguities related to how values 793 are represented in CBOR. 795 4.6.1. Cipher text related calculations 797 The plain text used during encryption MUST be calculated as the 798 single, definite-length CBOR byte string representing the block-type- 799 specific data field of the security target excluding the CBOR byte 800 string identifying byte and optional CBOR byte string length field. 802 For example, consider the following two CBOR byte strings and the 803 plain text that would be extracted from them. 805 CBOR Byte String Examples 807 +------------------------------+---------+--------------------------+ 808 | CBOR Byte String (Hex) | CBOR | Plain Text Part (Hex) | 809 | | Part | | 810 | | (Hex) | | 811 +------------------------------+---------+--------------------------+ 812 | 18ED | 18 | ED | 813 +------------------------------+---------+--------------------------+ 814 | C24CDEADBEEFDEADBEEFDEADBEEF | C24C | DEADBEEFDEADBEEFDEADBEEF | 815 +------------------------------+---------+--------------------------+ 817 Table 6 819 Similarly, the cipher text used during decryption MUST be calculated 820 as the single, definite-length CBOR byte string representing the 821 block-type-specific data field excluding the CBOR byte string 822 identifying byte and optional CBOR byte string length field. 824 All other fields of the security target (such as the block type code, 825 block number, block processing control flags, or any CRC information) 826 MUST NOT be considered as part of encryption or decryption. 828 4.6.2. Additional Authenticated Data 830 The construction of additional authenticated data depends on the AAD 831 Scope flags that may be provided as part of customizing the behavior 832 of this security context. 834 The canonical form of the AAD input to the BCB-AES-GCM mechanism is 835 constructed using the following process. This process MUST be 836 followed when generating AAD for either encryption or decryption. 838 1. The canonical form of the AAD starts as the empty set with length 839 0. 841 2. If the AAD Scope parameter is present and the Primary Block Flag 842 is set to 1, then a canonical form of the bundle's primary block 843 MUST be calculated and the result appended to the AAD. 845 3. If the AAD Scope parameter is present and the Security Header 846 flag is set to 1, then the canonical form of the Block Type Code, 847 Block Number, and Block Processing Control Flags associated with 848 the BIB MUST be calculated and, in that order, appended to the 849 AAD. 851 4. If the AAD Scope parameter is present and the Target Header flag 852 is set to 1, then the canonical form of the Block Type Code, 853 Block Number, and Block Processing Control Flags associated with 854 the security target MUST be calculated and, in that order, 855 appended to the AAD. 857 If, after this process, the AAD remains at length 0, then no AAD 858 exists to be input to the cipher suite. 860 4.7. Processing 862 4.7.1. Encryption 864 During encryption, four inputs are prepared for input to the AES/GCM 865 cipher: the encryption key, the Initialization Vector (IV), the 866 security target plain text to be encrypted, and any additional 867 authenticated data. These data items MUST be generated as follows. 869 Prior to encryption, if a CRC value is present for the target block, 870 then that CRC value MUST be removed. This requires removing the CRC 871 field from the target block and setting the CRC Type field of the 872 target block to "no CRC is present." 874 The encryption key MUST have the appropriate length as required by 875 local security policy. The key may be generated specifically for 876 this encryption, given as part of local security policy, or 877 through some other key management mechanism as discussed in 878 Section 4.5. 880 The Initialization Vector (IV) selected MUST be of the appropriate 881 length. Because replaying an IV in counter mode voids the 882 confidentiality of all messages encrypted with said IV, this 883 context also requires a unique IV for every encryption performed 884 with the same key. This means the same key and IV combination 885 MUST NOT be used more than once. 887 The security target plain text for encryption MUST be generated as 888 discussed in Section 4.6.1. 890 Additional authenticated data, if present, MUST be generated as 891 discussed in Section 4.6.2 with the value of AAD Scope flags being 892 taken from local security policy. 894 Upon successful encryption the following actions MUST occur. 896 The cipher text produced by AES/GCM MUST replace the bytes used to 897 define the plain text in the security target block's block-type- 898 specific data field. The block length of the security target MUST 899 be updated if the generated cipher text is larger than the plain 900 text (which can occur when the authentication tag is included in 901 the cipher text calculation, as discussed in Section 4.4). 903 The authentication tag calculated by the AES/GCM cipher MUST be 904 added as a security result for the security target in the BCB 905 holding results for this security operation. 907 Cases where the authentication tag is generated as part of the 908 cipher text MUST be processed as described in Section 4.4. 910 Finally, the BCB containing information about this security operation 911 MUST be updated as follows. These operations may occur in any order. 913 The security context ID for the BCB MUST be set to the context 914 identifier for BCB-AES-GCM. 916 The IV input to the cipher MUST be added as the IV security 917 parameter for the BCB. 919 Any local flags used to generated AAD for this cipher MUST be 920 added as the AAD Scope flags security parameter for the BCB. 922 The encryption key MAY be encapsulated using some key 923 encapsulation mechanism (to include encrypting with a key 924 encryption key) and the results of the encapsulation added as the 925 Encapsulated Key security parameter for the BCB. 927 The key length used by this security context MUST be considered 928 when setting the AES Variant security parameter for the BCB if it 929 differs from the default AES Variant. Otherwise, the AES Variant 930 MAY be omitted if doing so provides a useful reduction in message 931 sizes. 933 Problems encountered in the encryption MUST be processed in 934 accordance with local security policy. This MAY include restoring a 935 CRC value removed from the target block prior to encryption, if the 936 target block is allowed to be transmitted after an encryption error. 938 4.7.2. Decryption 940 During encryption, five inputs are prepared for input to the AES/GCM 941 cipher: the decryption key, the Initialization Vector (IV), the 942 security target cipher text to be decrypted, any additional 943 authenticated data, and the authentication tag generated from the 944 original encryption. These data items MUST be generated as follows. 946 The decryption key MUST be derived using the Encapsulated Key 947 security parameter if such a parameter is included in the security 948 context parameters of the BCB. Otherwise this key MUST be derived 949 in accordance with security policy at the decrypting node as 950 discussed in Section 4.5. 952 The Initialization Vector (IV) MUST be set to the value of the IV 953 security parameter included in the BCB. If the IV parameter is 954 not included as a security parameter, an IV MAY be derived as a 955 function of local security policy and other BCB contents or a lack 956 of an IV security parameter in the BCB MAY be treated as an error 957 by the decrypting node. 959 The security target cipher text for decryption MUST be generated 960 as discussed in Section 4.6.1. 962 Additional authenticated data, if present, MUST be generated as 963 discussed in Section 4.6.2 with the value of AAD Scope flags being 964 taken from the AAD Scope flags security context parameter. If the 965 AAD Scope flags parameter is not included in the security context 966 parameters then these flags MAY be derived from local security 967 policy in cases where the set of such flags is determinable in the 968 network. 970 The authentication tag MUST be present in the BCB security context 971 parameters field if additional authenticated data are defined for 972 the BCB (either in the AAD Scope flags parameter or as specified 973 by local policy). This tag MUST be 128 bits in length. 975 Upon successful decryption the following actions MUST occur. 977 The plain text produced by AES/GCM MUST replace the bytes used to 978 define the cipher text in the security target block's block-type- 979 specific data field. Any changes to the security target block 980 length field MUST be corrected in cases where the plain text has a 981 different length than the replaced cipher text. 983 If the security acceptor is not the bundle destination and if no 984 other integrity or confidentiality service is being applied to the 985 target block, then a CRC MUST be included for the target block. The 986 CRC type, as determined by policy, is set in the target block's CRC 987 type field and the corresponding CRC value is added as the CRC field 988 for that block. 990 If the cipher text fails to authenticate, if any needed parameters 991 are missing, or if there are other problems in the decryption then 992 the decryption MUST be treated as failed and processed in accordance 993 with local security policy. 995 5. IANA Considerations 997 5.1. Security Context Identifiers 999 This specification allocates two security context identifiers from 1000 the "BPSec Security Context Identifier" registry defined in 1001 [I-D.ietf-dtn-bpsec]. 1003 Additional Entries for the BPSec Security Context Identifiers 1004 Registry: 1006 +-------+---------------+---------------+ 1007 | Value | Description | Reference | 1008 +-------+---------------+---------------+ 1009 | TBA | BIB-HMAC-SHA2 | This document | 1010 | TBA | BCB-AES-GCM | This document | 1011 +-------+---------------+---------------+ 1013 Table 7 1015 6. Normative References 1017 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 1018 Recommendation for Block Cipher Modes of Operation: 1019 Galois/Counter Mode (GCM) and GMAC.", November 2007. 1021 [I-D.ietf-dtn-bpbis] 1022 Burleigh, S., Fall, K., and E. Birrane, "Bundle Protocol 1023 Version 7", draft-ietf-dtn-bpbis-31 (work in progress), 1024 January 2021. 1026 [I-D.ietf-dtn-bpsec] 1027 Birrane, E. and K. McKeever, "Bundle Protocol Security 1028 Specification", draft-ietf-dtn-bpsec-26 (work in 1029 progress), January 2021. 1031 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1032 Hashing for Message Authentication", RFC 2104, 1033 DOI 10.17487/RFC2104, February 1997, 1034 . 1036 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1037 Requirement Levels", BCP 14, RFC 2119, 1038 DOI 10.17487/RFC2119, March 1997, 1039 . 1041 [RFC4634] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1042 (SHA and HMAC-SHA)", RFC 4634, DOI 10.17487/RFC4634, July 1043 2006, . 1045 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1046 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1047 . 1049 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1050 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1051 May 2017, . 1053 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1054 Representation (CBOR)", STD 94, RFC 8949, 1055 DOI 10.17487/RFC8949, December 2020, 1056 . 1058 Appendix A. Acknowledgements 1060 The following participants contributed useful review and analysis of 1061 these security contexts: Amy Alford and Sarah Heiner of the Johns 1062 Hopkins University Applied Physics Laboratory. 1064 Author's Address 1066 Edward J. Birrane, III 1067 The Johns Hopkins University Applied 1068 Physics Laboratory 1069 11100 Johns Hopkins Rd. 1070 Laurel, MD 20723 1071 US 1073 Phone: +1 443 778 7423 1074 Email: Edward.Birrane@jhuapl.edu