idnits 2.17.1 draft-ietf-dtn-bpsec-default-sc-00.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 (January 26, 2021) is 1178 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 January 26, 2021 5 Expires: July 30, 2021 7 BPSec Default Security Contexts 8 draft-ietf-dtn-bpsec-default-sc-00 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 July 30, 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. Key Length . . . . . . . . . . . . . . . . . . . . . 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 5 249 (indicating use of HMAC256/SHA256), 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 | Encoding Type | Default Value | 298 +----+-----------------------+---------------+---------------+ 299 | 1 | SHA Variant | UINT | 256 | 300 | 2 | Encapsulated Key | Byte Array | NONE | 301 | 3 | Integrity Scope Flags | UINT | 0 | 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 BIB-HMAC-SHA2 provides no explicit requirements on the configuration, 347 storage, or exchange of HMAC keys. 349 3.6. Canonicalization Algorithms 351 This section defines the canonicalization algorithm used to prepare 352 the IPPT input to the BIB-HMAC-SHA2 integrity mechanism. The 353 construction of the IPPT depends on the settings of the Integrity 354 Scope Flags that may be provided as part of customizing the behavior 355 of this security context. 357 In all cases, the canonical form of any portion of an extension block 358 MUST be performed as described in [I-D.ietf-dtn-bpsec]. The 359 canonicalization algorithms defined in [I-D.ietf-dtn-bpsec] adhere to 360 the canonical forms for extension blocks defined in 361 [I-D.ietf-dtn-bpbis] but resolve ambiguities related to how values 362 are represented in CBOR. 364 The IPPT is constructed using the following process. 366 1. The canonical form of the IPPT starts as the empty set with 367 length 0. 369 2. If the Integrity Scope parameter is present and the Primary Block 370 Flag is set to 1, then a canonical form of the bundle's primary 371 block MUST be calculated and the result appended to the IPPT. 373 3. If the Integrity Scope parameter is present and the Security 374 Header flag is set to 1, then the canonical form of the Block 375 Type Code, Block Number, and Block Processing Control Flags 376 associated with the BIB MUST be calculated and, in that order, 377 appended to the IPPT. 379 4. If the Integrity Scope parameter is present and the Target Header 380 flag is set to 1, then the canonical form of the Block Type Code, 381 Block Number, and Block Processing Control Flags associated with 382 the security target MUST be calculated and, in that order, 383 appended to the IPPT. 385 5. The canonical form of the security target block-type-specific 386 data MUST be calculated and appended to the IPPT. 388 3.7. Processing 390 3.7.1. Keyed Hash Generation 392 During keyed hash generation, two inputs are prepared for the the 393 appropriate HMAC/SHA2 algorithm: the HMAC key and the IPPT. These 394 data items MUST be generated as follows. 396 The HMAC key MUST have the appropriate length as required by local 397 security policy. The key may be generated specifically for this 398 integrity service, given as part of local security policy, or 399 through some other key management mechanism as discussed in 400 Section 3.5. 402 Prior to the generation of the IPPT, if a CRC value is present for 403 the target block of the BIB, then that CRC value MUST be removed 404 from the target block. This involves both removing the CRC value 405 from the target block and setting the CRC Type field of the target 406 block to "no CRC is present." 408 Once CRC information is removed, the IPPT MUST be generated as 409 discussed in Section 3.6. 411 Upon successful hash generation the following actions MUST occur. 413 The keyed hash produced by the HMAC/SHA2 variant MUST be added as 414 a security result for the BIB representing the security operation 415 on this security target, as discussed in Section 3.4). 417 Finally, the BIB containing information about this security operation 418 MUST be updated as follows. These operations may occur in any order. 420 The security context ID for the BIB MUST be set to the context 421 identifier for BIB-HMAC-SHA2. 423 Any local flags used to generate the IPPT SHOULD be placed in the 424 Integrity Scope flags security parameter for the BIB unless these 425 flags are expected to be correctly configured at security 426 verifiers and acceptors in the network. 428 The HMAC key MAY be encapsulated using some key encapsulation 429 mechanism (to include encrypting with a key encryption key) and 430 the results of the encapsulation added as the Encapsulated Key 431 security parameter for the BIB. 433 The SHA Variant used by this security context SHOULD be added as 434 the SHA Variant security parameter for the BIB if it differs from 435 the default key length. Otherwise, this parameter MAY be omitted 436 if doing so provides a useful reduction in message sizes. 438 Problems encountered in the keyed hash generation MUST be processed 439 in accordance with local BPSec security policy. 441 3.7.2. Keyed Hash Verification 443 During keyed hash verification, the input of the security target and 444 a HMAC key are provided to the appropriate HMAC/SHA2 algorithm. 446 During keyed hash verification, two inputs are prepared for the the 447 appropriate HMAC/SHA2 algorithm: the HMAC key and the IPPT. These 448 data items MUST be generated as follows. 450 The HMAC key MUST be derived using the Encapsulated Key security 451 parameter if such a parameter is included in the security context 452 parameters of the BIB. Otherwise, this key MUST be derived in 453 accordance with security policy at the verifying node as discussed 454 in Section 3.5. 456 The IPPT MUST be generated as discussed in Section 3.6 with the 457 value of Integrity Scope flags being taken from the Integrity 458 Scope flags security context parameter. If the Integrity Scope 459 flags parameter is not included in the security context parameters 460 then these flags MAY be derived from local security policy. 462 The calculated HMAC output MUST be compared to the expected HMAC 463 output encoded in the security results of the BIB for the security 464 target. If the calculated HMAC and expected HMAC are identical, the 465 verification MUST be considered a success. Otherwise, the 466 verification MUST be considered a failure. 468 If the verification fails or if any needed parameters are missing 469 then the verification MUST be treated as failed and processed in 470 accordance with local security policy. 472 This security service is removed from the bundle at the security 473 acceptor as required by the BPSec specification. If the security 474 acceptor is not the bundle destination and if no other integrity 475 service is being applied to the target block, then a CRC MUST be 476 included for the target block. The CRC type, as determined by 477 policy, is set in the target block's CRC type field and the 478 corresponding CRC value is added as the CRC field for that block. 480 4. Security Context BCB-AES-GCM 482 4.1. Overview 484 The BCB-AES-GCM security context replaces the block-type-specific 485 data field of its security target with cipher text generated using 486 the Advanced Encryption Standard (AES) cipher operating in Galois/ 487 Counter Mode (GCM) [AES-GCM]. 489 Additionally, the BCB-AES-GCM security context generates an 490 authentication tag based on the plain text value of the block-type- 491 specific data and other additional authenticated data that may be 492 specified via parameters to this security context. 494 This security context supports three variants of AES-GCM, based on 495 the supported length of the symmetric key. These variants correspond 496 to A128GCM, A192GCM, and A256GCM as defined in [RFC8152] Table 9: 497 Algorithm Value for AES-GCM. 499 The BCB-AES-GCM security context shall have the Security Context ID 500 specified in Section 5.1. 502 4.2. Scope 504 There are two scopes associated with BCB-AES-GCM: the scope of the 505 confidentiality service and the scope of the authentication service. 506 The first defines the set of information provided to the AES-GCM 507 cipher for the purpose of producing cipher text. The second defines 508 the set of information used to generate an authentication tag. 510 The scope of the confidentiality service defines the set of 511 information provided to the AES-GCM cipher for the purpose of 512 producing cipher text. This MUST be the full set of plain text 513 contained in the block-type-specific data field of the security 514 target. 516 The scope of the authentication service defines the set of 517 information used to generate an authentication tag carried with the 518 security block. This information MUST include the plain text of the 519 block-type-specific data field of the security target. This 520 information MAY include other information (additional authenticated 521 data), as follows. 523 Primary block 524 The primary block identifies a bundle and, once created, the 525 contents of this block are immutable. Changes to the primary 526 block associated with the security target indicate that the 527 security target (and BCB) may no longer be in the correct bundle. 529 For example, if a security target and associated BCB are copied 530 from one bundle to another bundle, the BCB may still be able to 531 decrypt the security target even though these blocks were never 532 intended to exist in the copied-to bundle. 534 Including this information as part of additional authenticated 535 data ensures that security target (and security block) appear in 536 the same bundle at the time of decryption as at the time of 537 encryption. 539 Security target other fields 540 The other fields of the security target include block 541 identification and processing information. Changing this 542 information changes how the security target is treated by nodes 543 in the network even when the "user data" of the security target 544 are otherwise unchanged. 546 For example, if the block processing control flags of a security 547 target are different at a security verifier than they were 548 originally set at the security source then the policy for 549 handling the security target has been modified. 551 Including this information as part of additional authenticated 552 data ensures that the cipher text in the security target will not 553 be used with a different set of block policy than originally set 554 at the time of encryption. 556 BCB other fields 557 The other fields of the BCB include block identification and 558 processing information. Changing this information changes how 559 the BCB is treated by nodes in the network, even when other 560 aspects of the BCB are unchanged. 562 For example, if the block processing control flags of the BCB are 563 different at a security acceptor than they were originally set at 564 the security source then the policy for handling the BCB has been 565 modified. 567 Including this information as part of additional authenticated 568 data ensures that the policy and identification of the security 569 service in the bundle has not changed. 571 NOTE: The security context identifier and security context 572 parameters of the security block are not included as additional 573 authenticated data because these parameters, by definition, are 574 those needed to verify or accept the security service. 575 Therefore, it is expected that changes to these values would 576 result in failures at security verifiers and security acceptors. 578 The scope of the BCB-AES-GCM security context is configured using an 579 optional security context parameter. 581 4.3. Parameters 583 BCB-AES-GCM can be parameterized to specify the AES key length, 584 initialization vector, key information, and identify additional 585 authenticated data. 587 4.3.1. Initialization Vector (IV) 589 This optional parameter identifies the initialization vector (IV) 590 used to initialize the AES-GCM cipher. 592 The length of the initialization vector, prior to any CBOR encoding, 593 MUST be between 8-16 bytes. A value of 12 bytes SHOULD be used 594 unless local security policy requires a different length. 596 This value MUST be encoded as a CBOR byte string. 598 The initialization vector may have any value with the caveat that a 599 value MUST NOT be re-used for multiple encryptions using the same 600 encryption key. This value MAY be re-used when encrypting with 601 different keys. For example, if each encryption operation using BCB- 602 AES-GCM uses a newly generated key, then the same IV may be reused. 604 4.3.2. Key Length 606 This optional parameter identifies the key length being used for the 607 AES-GCM encryption. 609 This value MUST be encoded as a CBOR unsigned integer. 611 Valid values for this parameter are as follows. 613 Key Length Parameter Values 615 +-------+-----------------------------------------------------------+ 616 | Value | Description | 617 +-------+-----------------------------------------------------------+ 618 | 1 | A128GCM as defined in [RFC8152] Table 9: Algorithm Values | 619 | | for AES-GCM | 620 | 2 | A192GCM as defined in [RFC8152] Table 9: Algorithm Values | 621 | | for AES-GCM | 622 | 3 | A256GCM as defined in [RFC8152] Table 9: Algorithm Values | 623 | | for AES-GCM | 624 +-------+-----------------------------------------------------------+ 626 When not provided, implementations SHOULD assume a value of 3 627 (indicating use of A256GCM), unless an alternate default is 628 established by security policy at the security source, verifier, or 629 acceptor of this integrity service. 631 Regardless of the key length, the generated authentication tag MUST 632 always be 128 bits. 634 4.3.3. Encapsulated Key 636 This optional parameter contains the output of a Key Encapsulation 637 Mechanism (KEM) run at the security source of this security context. 639 This value MUST be encoded as a CBOR byte string. 641 If provided, this information is used to retrieve the symmetric AES 642 key used in the generation of security results for this security 643 context. If not provided, security verifiers and acceptors MUST 644 determine the proper key as a function of their local BPSec policy 645 and configuration, as discussed in Section 4.5. 647 4.3.4. AAD Scope Flags 649 This optional parameter contains a series of flags that describe what 650 information is to be included with the block-type-specific data of 651 the security target as part of additional authenticated data (AAD). 653 This value MUST be represented as a CBOR unsigned integer, the value 654 of which MUST be processed as a bit field containing no more than 16 655 bits. 657 Bits in this field represent additional information to be included 658 when generating an integrity signature over the security target. 659 These bits are defined as follows. 661 - Bit 0 (the low-order bit, 0x1): Primary Block Flag. 663 - Bit 1 (0x02): Target Header Flag. 665 - Bit 2 (0x03): Security Header Flag. 667 - Bits 3-7 are reserved. 669 - Bits 8-15 are unassigned. 671 4.3.5. Enumerations 673 BCB-AES-GCM defines the following security context parameters. 675 BCB-AES-GCM Security Parameters 677 +----+-----------------------+---------------+---------------+ 678 | Id | Name | Encoding Type | Default Value | 679 +----+-----------------------+---------------+---------------+ 680 | 1 | Initialization Vector | byte string | NONE | 681 | 2 | Key Length | UINT | 3 | 682 | 3 | Encapsulation Key | Byte Array | NONE | 683 | 4 | AAD Scope Flags | UINT | 0 | 684 +----+-----------------------+---------------+---------------+ 686 Table 4 688 4.4. Results 690 The BCB-AES-GCM security context produces a single security result 691 carried in the security block: the authentication tag. 693 NOTES: 695 The cipher text generated by the cipher suite is not considered a 696 security result as it is stored in the block-type-specific data 697 field of the security target block. When operating in GCM mode, 698 AES produces cipher text of the same size as its plain text and, 699 therefore, no additional logic is required to handle padding or 700 overflow caused by the encryption in most cases (see below). 702 If the generated cipher text contains the authentication tag and 703 the tag can be separated from the cipher text then the tag MUST be 704 separated and stored in the Authentication Tag security result 705 field. 707 If the generated cipher text contains the authentication tag and 708 the tag cannot be separated from the cipher text then the tag MUST 709 NOT be included in the Authentication tag security result field. 710 Instead the security target block MUST be resized to accommodate 711 the additional 128 bits of authentication tag included in the 712 generated cipher text. 714 4.4.1. Authentication Tag 716 The authentication tag is generated by the cipher suite over the 717 security target plain text input to the cipher suite as combined with 718 any optional additional authenticated data. This tag is used to 719 ensure that the plain text (and important information associated with 720 the plain text) is authenticated prior to decryption. 722 If the authentication tag is included in the cipher text placed in 723 the security target block-type-specific data field, then this 724 security result MUST NOT be included in the BCB for that security 725 target. 727 The length of the authentication tag, prior to any CBOR encoding, 728 MUST be 128 bits. 730 This value MUST be encoded as a CBOR byte string. 732 4.4.2. Enumerations 734 BCB-AES-GCM defines the following security context parameters. 736 BCB-AES-GCM Security Results 738 +-----------+--------------------+--------------------+ 739 | Result Id | Result Name | CBOR Encoding Type | 740 +-----------+--------------------+--------------------+ 741 | 1 | Authentication Tag | byte string | 742 +-----------+--------------------+--------------------+ 744 Table 5 746 4.5. Key Considerations 748 BCB-AES-GCM does not define or otherwise mandate any method for key 749 exchange, encryption, or encapsulation. The derivation of an 750 appropriate key is considered separate from the application of the 751 authenticated confidentiality service provided by this context. 753 Keys used with this context MUST be symmetric and MUST have a key 754 length equal to the key length defined in the security context 755 parameters or as defined by local security policy at security 756 verifiers and acceptors. 758 It is assumed that any security verifier or security acceptor can 759 determine the proper key to be used. Potential sources of the key 760 include (but are not limited to) the following. 762 Pre-placed keys selected based on local policy. 764 Keys extracted from encapsulated key material carried in the BCB. 766 Session keys negotiated via a mechanism external to the BCB. 768 BCB-AES-GCM provides no explicit requirements on the configuration, 769 storage, or exchange of keys. 771 4.6. Canonicalization Algorithms 773 This section defines the canonicalization algorithms used to prepare 774 the inputs used to generate both the cipher text and the 775 authentication tag. 777 In all cases, the canonical form of any portion of an extension block 778 MUST be performed as described in [I-D.ietf-dtn-bpsec]. The 779 canonicalization algorithms defined in [I-D.ietf-dtn-bpsec] adhere to 780 the canonical forms for extension blocks defined in 781 [I-D.ietf-dtn-bpbis] but resolve ambiguities related to how values 782 are represented in CBOR. 784 4.6.1. Cipher text related calculations 786 The plain text used during encryption MUST be calculated as the 787 single, definite-length CBOR byte string representing the block-type- 788 specific data field of the security target excluding the CBOR byte 789 string identifying byte and optional CBOR byte string length field. 791 For example, consider the following two CBOR byte strings and the 792 plain text that would be extracted from them. 794 CBOR byte string Examples 796 +------------------------------+---------+--------------------------+ 797 | CBOR Byte String (Hex) | CBOR | Plain Text Part (Hex) | 798 | | Part | | 799 | | (Hex) | | 800 +------------------------------+---------+--------------------------+ 801 | 18ED | 18 | ED | 802 +------------------------------+---------+--------------------------+ 803 | C24CDEADBEEFDEADBEEFDEADBEEF | C24C | DEADBEEFDEADBEEFDEADBEEF | 804 +------------------------------+---------+--------------------------+ 806 Table 6 808 Similarly, the cipher text used during decryption MUST be calculated 809 as the single, definite-length CBOR byte string representing the 810 block-type-specific data field excluding the CBOR byte string 811 identifying byte and optional CBOR byte string length field. 813 All other fields of the security target (such as the block type code, 814 block number, block processing control flags, or any CRC information) 815 MUST NOT be considered as part of encryption or decryption. 817 4.6.2. Additional Authenticated Data 819 The construction of additional authenticated data depends on the AAD 820 Scope flags that may be provided as part of customizing the behavior 821 of this security context. 823 The canonical form of the AAD input to the BCB-AES-GCM mechanism is 824 constructed using the following process. This process MUST be 825 followed when generating AAD for either encryption or decryption. 827 1. The canonical form of the AAD starts as the empty set with length 828 0. 830 2. If the AAD Scope parameter is present and the Primary Block Flag 831 is set to 1, then a canonical form of the bundle's primary block 832 MUST be calculated and the result appended to the AAD. 834 3. If the AAD Scope parameter is present and the Security Header 835 flag is set to 1, then the canonical form of the Block Type Code, 836 Block Number, and Block Processing Control Flags associated with 837 the BIB MUST be calculated and, in that order, appended to the 838 AAD. 840 4. If the AAD Scope parameter is present and the Target Header flag 841 is set to 1, then the canonical form of the Block Type Code, 842 Block Number, and Block Processing Control Flags associated with 843 the security target MUST be calculated and, in that order, 844 appended to the AAD. 846 If, after this process, the AAD remains at length 0, then no AAD 847 exists to be input to the cipher suite. 849 4.7. Processing 851 4.7.1. Encryption 853 During encryption, four inputs are prepared for input to the AES/GCM 854 cipher: the encryption key, the Initialization Vector (IV), the 855 security target plain text to be encrypted, and any additional 856 authenticated data. These data items MUST be generated as follows. 858 Prior to encryption, if a CRC value is present for the target block, 859 then that CRC value MUST be removed. This requires removing the CRC 860 field from the target block and setting the CRC Type field of the 861 target block to "no CRC is present." 863 The encryption key MUST have the appropriate length as required by 864 local security policy. The key may be generated specifically for 865 this encryption, given as part of local security policy, or 866 through some other key management mechanism as discussed in 867 Section 4.5. 869 The Initialization Vector (IV) selected MUST be of the appropriate 870 length. Because replaying an IV in counter mode voids the 871 confidentiality of all messages encrypted with said IV, this 872 context also requires a unique IV for every encryption performed 873 with the same key. This means the same key and IV combination 874 MUST NOT be used more than once. 876 The security target plain text for encryption MUST be generated as 877 discussed in Section 4.6.1. 879 Additional authenticated data, if present, MUST be generated as 880 discussed in Section 4.6.2 with the value of AAD Scope flags being 881 taken from local security policy. 883 Upon successful encryption the following actions MUST occur. 885 The cipher text produced by AES/GCM MUST replace the bytes used to 886 define the plain text in the security target block's block-type- 887 specific data field. The block length of the security target MUST 888 be updated if the generated cipher text is larger than the plain 889 text (which can occur when the authentication tag is included in 890 the cipher text calculation, as discussed in Section 4.4). 892 The authentication tag calculated by the AES/GCM cipher MUST be 893 added as a security result for the security target in the BCB 894 holding results for this security operation. 896 Cases where the authentication tag is generated as part of the 897 cipher text MUST be processed as described in Section 4.4. 899 Finally, the BCB containing information about this security operation 900 MUST be updated as follows. These operations may occur in any order. 902 The security context ID for the BCB MUST be set to the context 903 identifier for BCB-AES-GCM. 905 The IV input to the cipher MUST be added as the IV security 906 parameter for the BCB. 908 Any local flags used to generated AAD for this cipher MUST be 909 added as the AAD Scope flags security parameter for the BCB. 911 The encryption key MAY be encapsulated using some key 912 encapsulation mechanism (to include encrypting with a key 913 encryption key) and the results of the encapsulation added as the 914 Encapsulated Key security parameter for the BCB. 916 The key length used by this security context MUST be added as the 917 Key Length security parameter for the BCB if it differs from the 918 default key length. Otherwise, the key length MAY be omitted if 919 doing so provides a useful reduction in message sizes. 921 Problems encountered in the encryption MUST be processed in 922 accordance with local security policy. This MAY include restoring a 923 CRC value removed from the target block prior to encryption, if the 924 target block is allowed to be transmitted after an encryption error. 926 4.7.2. Decryption 928 During encryption, five inputs are prepared for input to the AES/GCM 929 cipher: the decryption key, the Initialization Vector (IV), the 930 security target cipher text to be decrypted, any additional 931 authenticated data, and the authentication tag generated from the 932 original encryption. These data items MUST be generated as follows. 934 The decryption key MUST be derived using the Encapsulated Key 935 security parameter if such a parameter is included in the security 936 context parameters of the BCB. Otherwise this key MUST be derived 937 in accordance with security policy at the decrypting node as 938 discussed in Section 4.5. 940 The Initialization Vector (IV) MUST be set to the value of the IV 941 security parameter included in the BCB. If the IV parameter is 942 not included as a security parameter, an IV MAY be derived from 943 local security policy in cases where IVs are predictable (such as 944 always using an IV of 0 with constantly differing keys). 945 Alternatively, a lack of an IV security parameter MAY be treated 946 as an error by the decrypting node. 948 The security target cipher text for decryption MUST be generated 949 as discussed in Section 4.6.1. 951 Additional authenticated data, if present, MUST be generated as 952 discussed in Section 4.6.2 with the value of AAD Scope flags being 953 taken from the AAD Scope flags security context parameter. If the 954 AAD Scope flags parameter is not included in the security context 955 parameters then these flags MAY be derived from local security 956 policy in cases where the set of such flags is determinable in the 957 network. 959 The authentication tag MUST be present in the BCB security context 960 parameters field if additional authenticated data are defined for 961 the BCB (either in the AAD Scope flags parameter or as specified 962 by local policy). This tag MUST be 128 bits in length. 964 Upon successful decryption the following actions MUST occur. 966 The plain text produced by AES/GCM MUST replace the bytes used to 967 define the cipher text in the security target block's block-type- 968 specific data field. Any changes to the security target block 969 length field MUST be corrected in cases where the plain text has a 970 different length than the replaced cipher text. 972 If the security acceptor is not the bundle destination and if no 973 other integrity or confidentiality service is being applied to the 974 target block, then a CRC MUST be included for the target block. The 975 CRC type, as determined by policy, is set in the target block's CRC 976 type field and the corresponding CRC value is added as the CRC field 977 for that block. 979 If the cipher text fails to authenticate, if any needed parameters 980 are missing, or if there are other problems in the decryption then 981 the decryption MUST be treated as failed and processed in accordance 982 with local security policy. 984 5. IANA Considerations 986 5.1. Security Context Identifiers 988 This specification allocates two security context identifiers from 989 the "BPSec Security Context Identifier" registry defined in 990 [I-D.ietf-dtn-bpsec]. 992 Additional Entries for the BPSec Security Context Identifiers 993 Registry: 995 +-------+---------------+---------------+ 996 | Value | Description | Reference | 997 +-------+---------------+---------------+ 998 | TBA | BIB-HMAC-SHA2 | This document | 999 | TBA | BCB-AES-GCM | This document | 1000 +-------+---------------+---------------+ 1002 Table 7 1004 6. Normative References 1006 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 1007 Recommendation for Block Cipher Modes of Operation: 1008 Galois/Counter Mode (GCM) and GMAC.", November 2007. 1010 [I-D.ietf-dtn-bpbis] 1011 Burleigh, S., Fall, K., and E. Birrane, "Bundle Protocol 1012 Version 7", draft-ietf-dtn-bpbis-31 (work in progress), 1013 January 2021. 1015 [I-D.ietf-dtn-bpsec] 1016 Birrane, E. and K. McKeever, "Bundle Protocol Security 1017 Specification", draft-ietf-dtn-bpsec-26 (work in 1018 progress), January 2021. 1020 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1021 Hashing for Message Authentication", RFC 2104, 1022 DOI 10.17487/RFC2104, February 1997, 1023 . 1025 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1026 Requirement Levels", BCP 14, RFC 2119, 1027 DOI 10.17487/RFC2119, March 1997, 1028 . 1030 [RFC4634] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1031 (SHA and HMAC-SHA)", RFC 4634, DOI 10.17487/RFC4634, July 1032 2006, . 1034 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1035 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1036 . 1038 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1039 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1040 May 2017, . 1042 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1043 Representation (CBOR)", STD 94, RFC 8949, 1044 DOI 10.17487/RFC8949, December 2020, 1045 . 1047 Appendix A. Acknowledgements 1049 The following participants contributed useful review and analysis of 1050 these security contexts: Amy Alford and Sarah Heiner of the Johns 1051 Hopkins University Applied Physics Laboratory. 1053 Author's Address 1055 Edward J. Birrane, III 1056 The Johns Hopkins University Applied 1057 Physics Laboratory 1058 11100 Johns Hopkins Rd. 1059 Laurel, MD 20723 1060 US 1062 Phone: +1 443 778 7423 1063 Email: Edward.Birrane@jhuapl.edu