idnits 2.17.1 draft-friel-tls-atls-02.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2019) is 1872 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) == Missing Reference: 'X3DH' is mentioned on line 324, but not defined == Missing Reference: 'MAX' is mentioned on line 1428, but not defined == Unused Reference: 'LwM2M' is defined on line 1340, but no explicit reference was found in the text == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-19 == Outdated reference: A later version (-15) exists of draft-ietf-httpbis-bcp56bis-08 == Outdated reference: A later version (-13) exists of draft-ietf-tls-dtls-connection-id-04 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-30 == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-12 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7525 (Obsoleted by RFC 9325) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 0 errors (**), 0 flaws (~~), 9 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group O. Friel 3 Internet-Draft R. Barnes 4 Intended status: Standards Track M. Pritikin 5 Expires: September 12, 2019 Cisco 6 H. Tschofenig 7 ARM Limited 8 M. Baugher 9 Consultant 10 March 11, 2019 12 Application-Layer TLS 13 draft-friel-tls-atls-02 15 Abstract 17 This document specifies how TLS sessions can be established at the 18 application layer over untrusted transport between clients and 19 services for the purposes of establishing secure end-to-end encrypted 20 communications channels. Transport layer encodings for application 21 layer TLS records are specified for HTTP and CoAP transport. 22 Explicit identification of application layer TLS packets enables 23 middleboxes to provide transport services and enforce suitable 24 transport policies for these payloads, without requiring access to 25 the unencrypted payload content. Multiple scenarios are presented 26 identifying the need for end-to-end application layer encryption 27 between clients and services, and the benefits of reusing the well- 28 defined TLS protocol, and a standard TLS stack, to accomplish this 29 are described. Application software architectures for building, and 30 network architectures for deploying application layer TLS are 31 outlined. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at https://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on September 12, 2019. 50 Copyright Notice 52 Copyright (c) 2019 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 3. Application Layer End-to-End Security Use Cases . . . . . . . 4 70 3.1. Bootstrapping Devices . . . . . . . . . . . . . . . . . . 4 71 3.2. Constrained Devices . . . . . . . . . . . . . . . . . . . 5 72 3.2.1. Constrained Device Connecting over a Closed Network . 5 73 3.2.2. Constrained Device Connecting over the Internet . . . 6 74 4. Current Approaches to Application Layer End-to-End Security . 7 75 4.1. Noise . . . . . . . . . . . . . . . . . . . . . . . . . . 7 76 4.2. Signal . . . . . . . . . . . . . . . . . . . . . . . . . 7 77 4.3. Google ALTS . . . . . . . . . . . . . . . . . . . . . . . 7 78 4.4. Ephemeral Diffie-Hellman Over COSE . . . . . . . . . . . 8 79 5. ATLS Goals . . . . . . . . . . . . . . . . . . . . . . . . . 8 80 6. Architecture Overview . . . . . . . . . . . . . . . . . . . . 8 81 6.1. Application Architecture . . . . . . . . . . . . . . . . 8 82 6.1.1. Application Architecture Benefits . . . . . . . . . . 11 83 6.1.2. ATLS Packet Identification . . . . . . . . . . . . . 12 84 6.1.3. ATLS Session Tracking . . . . . . . . . . . . . . . . 12 85 6.1.4. ATLS Record Inspection . . . . . . . . . . . . . . . 12 86 6.1.5. Implementation . . . . . . . . . . . . . . . . . . . 12 87 6.2. Functional Design . . . . . . . . . . . . . . . . . . . . 13 88 6.3. Network Architecture . . . . . . . . . . . . . . . . . . 14 89 7. Key Exporting and Application Data Encryption . . . . . . . . 16 90 8. ATLS Session Establishment . . . . . . . . . . . . . . . . . 17 91 9. ATLS over HTTP Transport . . . . . . . . . . . . . . . . . . 19 92 9.1. Protocol Summary . . . . . . . . . . . . . . . . . . . . 20 93 9.2. Content-Type Header . . . . . . . . . . . . . . . . . . . 20 94 9.3. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 20 95 9.4. ATLS Session Tracking . . . . . . . . . . . . . . . . . . 20 96 9.5. Session Establishment and Key Exporting . . . . . . . . . 20 97 9.6. Illustrative ATLS over HTTP Session Establishment . . . . 21 98 9.7. ATLS and HTTP CONNECT . . . . . . . . . . . . . . . . . . 21 99 10. ATLS over CoAP Transport . . . . . . . . . . . . . . . . . . 24 100 11. The "oscore_connection_id" Extension . . . . . . . . . . . . 25 101 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 102 12.1. "oscore_connection_id" TLS extension . . . . . . . . . . 26 103 12.2. .well-known URI Registry . . . . . . . . . . . . . . . . 26 104 12.3. Media Types Registry . . . . . . . . . . . . . . . . . . 27 105 12.4. HTTP Content-Formats Registry . . . . . . . . . . . . . 28 106 12.5. CoAP Content-Formats Registry . . . . . . . . . . . . . 28 107 12.6. TLS Key Extractor Label . . . . . . . . . . . . . . . . 28 108 13. Security Considerations . . . . . . . . . . . . . . . . . . . 28 109 14. Informative References . . . . . . . . . . . . . . . . . . . 29 110 Appendix A. Pseudo Code . . . . . . . . . . . . . . . . . . . . 31 111 A.1. OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . 31 112 A.2. Java JSSE . . . . . . . . . . . . . . . . . . . . . . . . 33 113 Appendix B. Example ATLS Handshake . . . . . . . . . . . . . . . 35 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 116 1. Introduction 118 There are multiple scenarios where there is a need for application 119 layer end-to-end security between clients and application services. 120 Two examples include: 122 o Bootstrapping devices that must connect to HTTP application 123 services across untrusted TLS interception middleboxes 125 o Constrained devices connecting via gateways to application 126 services, where different transport layer protocols may be in use 127 on either side of the gateway, with the gateway transcoding 128 between the different transport layer protocols. 130 These two scenarios are described in more detail in Section 3. 132 This document describes how clients and applications can leverage 133 standard TLS software stacks to establish secure end-to-end encrypted 134 connections at the application layer. The connections may establish 135 TLS [RFC5246] [I-D.ietf-tls-tls13] or DTLS [RFC6347] 136 [I-D.ietf-tls-dtls13] sessions. There are multiple advantages to 137 reuse of existing TLS software stacks for establishment of 138 application layer secure connections. These include: 140 o many clients and application services already include a TLS 141 software stack, so there is no need to include yet another 142 software stack in the software build 144 o no need to define a new cryptographic negotiation, authentication, 145 and key exchange protocol between clients and services 147 o provides standards based PKI mutual authentication between clients 148 and services 150 o no need to train software developers on how to use a new 151 cryptographic protocols or libraries 153 o automatically benefit from new cipher suites by simply upgrading 154 the TLS software stack 156 o automatically benefit from new features, bugfixes, etc. in TLS 157 software stack upgrades 159 This document also explicitly defines how application layer TLS 160 connections can be established using HTTP [RFC7230] [RFC7540] or CoAP 161 as transport layers. This document does not preclude the use of 162 other transport layers. However, defining how application layer TLS 163 connections can be established over other transport layers, such as 164 [ZigBee] or [Bluetooth], is beyond the scope of this document. 166 Explicitly identifying application layer TLS packets enables 167 transport layer middleboxes to provide transport capabilities and 168 enforce suitable transport policies for these payloads, without 169 requiring access to unencrypted application data. 171 2. Terminology 173 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 174 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 175 "OPTIONAL" in this document are to be interpreted as described in BCP 176 14 [RFC2119] [RFC8174] when, and only when, they appear in all 177 capitals, as shown here. 179 Application layer TLS is referred to as ATLS throughout this 180 document. 182 3. Application Layer End-to-End Security Use Cases 184 This section describes in more detail the bootstrapping and 185 constrained device use cases mentioned in the introduction. 187 3.1. Bootstrapping Devices 189 There are far more classes of clients being deployed on today's 190 networks than at any time previously. This poses challenges for 191 network administrators who need to manage their network and the 192 clients connecting to their network, and poses challenges for client 193 vendors and client software developers who must ensure that their 194 clients can connect to all required services. 196 One common example is where a client is deployed on a local domain 197 TCP/IP network that protects its perimeter using a TLS terminating 198 middlebox, and the client needs to establish a secure connection to a 199 service in a different network via the middlebox. This is 200 illustrated in Figure 1. 202 Traditionally, this has been enabled by the network administrator 203 deploying the necessary certificate authority trusted roots on the 204 client. This can be achieved at scale using standard tools that 205 enable the administrator to automatically push trusted roots out to 206 all client machines in the network from a centralized domain 207 controller. This works for personal computers, laptops and servers 208 running standard Operating Systems that can be centrally managed. 209 This client management process breaks for multiple classes of clients 210 that are being deployed today, there is no standard mechanism for 211 configuring trusted roots on these clients, and there is no standard 212 mechanism for these clients to securely traverse middleboxes. 214 +--------+ C->M TLS +-----------+ M->S TLS +---------+ 215 | Client |--------------->| Middlebox |------------->| Service | 216 +--------+ +-----------+ +---------+ 217 ^ ^ 218 | | 219 +-----------Client to Service ATLS Connection---------+ 221 Figure 1: Bootstrapping Devices 223 The ATLS mechanism defined in this document enables clients to 224 traverse middleboxes and establish secure connections to services 225 across network domain boundaries. The purpose of this connection may 226 simply be to facilitate a bootstrapping process, for example 227 [I-D.ietf-anima-bootstrapping-keyinfra], whereby the client securely 228 discovers the local domain certificate authorities required to 229 establish a trusted network layer TLS connection to the middlebox. 231 3.2. Constrained Devices 233 Two constrained device use cases are outlined here. 235 3.2.1. Constrained Device Connecting over a Closed Network 237 There are industry examples of home smart lighting systems where the 238 smart light bulbs connect using ZigBee to a gateway device. A 239 controller application running on a mobile device connects to the 240 gateway using CoAP over DTLS. The controller can then control the 241 light bulbs by sending messages and commands via the gateway. The 242 gateway device has full access to all messages sent between the light 243 bulbs and the controller application. 245 A generic use case similar to the smart lighting system outlined 246 above has an IoT device talking ZigBee to a gateway, with the gateway 247 in turn talking CoAP over DTLS to a controller application running on 248 a mobile device. This is illustrated in Figure 2. 250 There are scenarios where the messages sent between the IoT device 251 and the controller application must not be exposed to the gateway 252 function. Additionally, the end devices (the IoT device and the 253 controller application service) have no visibility to and no 254 guarantees about what transport layer security and encryption is 255 enforced across all hops end-to-end as they only have visibility to 256 their immediate next hop. ATLS addresses these concerns. 258 +--------+ ZigBee +---------+ CoAP/DTLS +------------+ 259 | Device |-------------->| Gateway |------------->| Mobile App | 260 +--------+ +---------+ +------------+ 261 ^ ^ 262 | | 263 +--------Device to Mobile App ATLS Connection-------+ 265 Figure 2: IoT Closed Network Gateway 267 3.2.2. Constrained Device Connecting over the Internet 269 In this example an IoT device connecting to a gateway using a 270 suitable transport mechanism, such as ZigBee, CoAP, MQTT, etc. The 271 gateway function in turn talks HTTP over TLS (or, for example, HTTP 272 over QUIC) to an application service over the Internet. This is 273 illustrated in Figure 3. 275 The gateway may not be trusted and all messages between the IoT 276 device and the application service must be end-to-end encrypted. 277 Similar to the previous use case, the endpoints have no guarantees 278 about what level of transport layer security is enforced across all 279 hops. Again, ATLS addresses these concerns. 281 +--------+ CoAP/DTLS +------------------+ HTTP/TLS +---------+ 282 | Device |-------------->| Internet Gateway |------------>| Service | 283 +--------+ +------------------+ +---------+ 284 ^ ^ 285 | | 286 +---------Device to Cloud Service ATLS Connection----------+ 288 Figure 3: IoT Internet Gateway 290 4. Current Approaches to Application Layer End-to-End Security 292 End-to-end security at the application layer is increasing seen as a 293 key requirement across multiple applications and services. Some 294 examples of end-to-end security mechanisms are outlined here. All 295 the solutions outlined here have some common characteristics. The 296 solutions: 298 o do not rely on transport layer security 300 o define a new handshake protocol for establishment of a secure end- 301 to-end session 303 4.1. Noise 305 [Noise] is a framework for cryptographic protocols based on Elliptic 306 Curve Diffie-Hellman (ECDH) key agreement, AEAD encryption, and 307 BLAKE2 and SHA2 hash functions. Noise is currently used by WhatsApp, 308 WireGuard, and Lightning. 310 The current Noise protocol framework defines mechanisms for proving 311 possession of a private key, but does not define authentication 312 mechanisms. Section 14 "Security Considerations" of Noise states: 313 ~~~ it's up to the application to determine whether the remote 314 party's static public key is acceptable ~~~ 316 4.2. Signal 318 The [Signal] protocol provides end-to-end encryption and uses EdDSA 319 signatures, Triple Diffie-Hellman handshake for shared secret 320 establishment, and the Double Ratchet Algorithm for key management. 321 It is used by Open Whisper Systems, WhatsApp and Google. 323 Similar to Noise, Signal does not define an authentication mechanism. 324 The current [X3DH] specification states in Section 4.1 325 "Authentication": 327 Methods for doing this are outside the scope of this document 329 4.3. Google ALTS 331 Google's Application Layer Transport Security [ALTS] is a mutual 332 authentication and transport encryption system used for securing 333 Remote Procedure Call (RPC) communications within Google's 334 infrastructure. ALTS uses an ECDH handshake protocol and a record 335 protocol containing AES encrypted payloads. 337 4.4. Ephemeral Diffie-Hellman Over COSE 339 There is ongoing work to standardise [I-D.selander-ace-cose-ecdhe], 340 whiich defines a SIGMA-I based authenticated key exchange protocol 341 using COSE and CBOR. 343 5. ATLS Goals 345 The high level goals driving the design of this mechanism are: 347 o enable authenticated key exchange at the application layer by 348 reusing existing technologies 350 o ensure that ATLS packets are explicitly identified thus ensuring 351 that any middleboxes or gateways at the transport layer are 352 content aware 354 o leverage existing TLS stacks and handshake protocols thus avoiding 355 introducing new software or protocol dependencies in clients and 356 applications 358 o reuse existing TLS [RFC5246] [I-D.ietf-tls-tls13] and DTLS 359 [RFC6347] [I-D.ietf-tls-dtls13] specifications as is without 360 requiring any protocol changes or software stack changes 362 o do not mandate constraints on how the TLS stack is configured or 363 used 365 o be forward compatible with future TLS versions 367 o avoid introducing TLS protocol handling logic or semantics into 368 the application layer, i.e. TLS protocol knowledge and logic is 369 handled by the TLS stack, not the application 371 o ensure the client and server software implementations are as 372 simple as possible 374 6. Architecture Overview 376 6.1. Application Architecture 378 TLS software stacks allow application developers to 'unplug' the 379 default network socket transport layer and read and write TLS records 380 directly from byte buffers. This enables application developers to 381 create application layer TLS sessions, extract the raw TLS record 382 bytes from the bottom of the TLS stack, and transport these bytes 383 over any suitable transport. The TLS software stacks can generate 384 byte streams of full TLS flights which may include multiple TLS 385 records. Additionally, TLS software stacks support Keying Material 386 Exporters [RFC5705] and allow applications to export keying material 387 from established TLS sessions. This keying material can then be used 388 by the application for encryption of data outside the context of the 389 TLS session. This is illustrated in Figure 4 below. 391 +------------+ +---------+ 392 Handshake Records | | Handshake Records | | 393 ------------------->| |------------------->| | 394 | | | Byte | 395 Unencrypted Data | TLS | Encrypted Data | | 396 ------------------->| |------------------->| Buffers | 397 | Software | | | 398 Encrypted Data | | Unencrypted Data | | 399 ------------------->| Stack |------------------->| | 400 | | +---------+ 401 Keying Material | | 402 <-------------------| | 403 + -----------+ 405 Figure 4: TLS Stack Interfaces 407 These TLS software stack APIs enable application developers to build 408 the software architectures illustrated in Figure 5 and Figure 6. 410 In both architectures, the application creates and interacts with an 411 application layer TLS session in order to generate and consume raw 412 TLS records. The application transports these raw TLS records inside 413 transport layer message bodies using whatever standard transport 414 layer stack is suitable for the application or architecture. This 415 document does not place any restrictions on the choice of transport 416 layer and any suitable protocol such as HTTP, TCP, CoAP, ZigBee, 417 Bluetooth, etc. could be used. 419 The transport layer will typically encrypt data, and this encryption 420 is completely independent from any application layer encryption. The 421 transport stack may create a transport layer TLS session. The 422 application layer TLS session and transport layer TLS session can 423 both leverage a shared, common TLS software stack. This high level 424 architecture is applicable to both clients and application services. 425 The key differences between the architectures are as follows. 427 In the model illustrated in Figure 5, the application sends all 428 sensitive data that needs to be securely exchanged with the peer 429 application through the Application TLS session in order to be 430 encrypted and decrypted. All sensitive application data is thus 431 encoded within TLS records by the TLS stack, and these TLS records 432 are transmitted over the transport layer. 434 +-------------+ 435 | | App 436 | | Data +---------+ 437 | Application |<---------->| App | +---------+ 438 | | TLS | TLS |----->| TLS | 439 | | Records | Session | | Stack | 440 | +--->|<---------->| | +---------+ 441 | | | +---------+ ^ 442 | | | |? 443 | | | Transport +-----------+ +------------+ 444 | | | Payload | Transport | | Transport | 445 | +--->|<--------->| Stack |--->| Encryption |-->Packets 446 +-------------+ +-----------+ +------------+ 448 Figure 5: TLS Stack used for all data encryption 450 In the model illustrated in Figure 6, the application establishes an 451 application layer TLS session purely for the purposes of key 452 exchange. Therefore, the only TLS records that are sent or received 453 by the application layer are TLS handshake records. Once the 454 application layer TLS session is established, the application uses 455 Keying Material Exporter [RFC5705] APIs to export keying material 456 from the TLS stack from this application layer TLS session. The 457 application can then use these exported keys to derive suitable 458 shared encryption keys with its peer for exchange of encrypted data. 459 The application encrypts and decrypts sensitive data using these 460 shared encryption keys using any suitable cryptographic library 461 (which may be part of the same library that provides the TLS stack), 462 and transports the encrypted data directly over the transport layer. 464 +--------------+ 465 | | 466 | Application | 467 | | 468 | +-------+ | +---------+ 469 | | App | | Key Export | | 470 | | Data |<---|<-----------| | 471 | | Crypto| | | App | 472 | +-------+ | TLS | TLS | +---------+ 473 | ^ | Handshake | Session |----->| TLS | 474 | | | Records | | | Stack | 475 | | +--->|<---------->| | +---------+ 476 | | | | +---------+ ^ 477 | | | | |? 478 | | | | Transport +-----------+ +------------+ 479 | | | | Payload | Transport | | Transport | 480 | +----+--->|<--------->| Stack |--->| Encryption |-->Packets 481 +--------------+ +-----------+ +------------+ 483 Figure 6: TLS stack used for key agreement and exporting 485 The choice of which application architecture to use will depend on 486 the overall solution architecture, and the underlying transport layer 487 or layers in use. While the choice of application architecture is 488 outside the scope of this document, some considerations are outlined 489 here. 491 o in some IoT use cases reducing the number of bytes transmitted is 492 important. [I-D.mattsson-core-security-overhead] analyses the 493 overhead of TLS headers compared with OSCORE 494 [I-D.ietf-core-object-security] illustrating the additional 495 overhead associated with TLS headers. The overhead varies between 496 the different TLS versions and also between TLS and DTLS. It may 497 be more appropriate to use the architecture defined in Figure 6 in 498 order to establish shared encryption keys, and then transport 499 encrypted data directly without the overhead of unwanted TLS 500 record headers. 502 o when using HTTP as a transport layer, it may be more appropriate 503 to use the architecture defined in Figure 6 in order to avoid any 504 TLS session vs. HTTP session affinity issues. 506 6.1.1. Application Architecture Benefits 508 There are several benefits to using a standard TLS software stack to 509 establish an application layer secure communications channel between 510 a client and a service. These include: 512 o no need to define a new cryptographic negotiation and exchange 513 protocol between client and service 515 o automatically benefit from new cipher suites by simply upgrading 516 the TLS software stack 518 o automatically benefit from new features, bugfixes, etc. in TLS 519 software stack upgrades 521 6.1.2. ATLS Packet Identification 523 It is recommended that ATLS packets are explicitly identified by a 524 standardized, transport-specific identifier enabling any gateways and 525 middleboxes to identify ATLS packets. Middleboxes have to contend 526 with a vast number of applications and network operators have 527 difficulty configuring middleboxes to distinguish unencrypted but not 528 explicitly identified application data from end-to-end encrypted 529 data. This specification aims to assist network operators by 530 explicitly identifying ATLS packets. The HTTP and CoAP encodings 531 documented in Section 9 and Section 10 explicitly identify ATLS 532 packets. 534 6.1.3. ATLS Session Tracking 536 The ATLS application service establishes multiple ATLS sessions with 537 multiple clients. As TLS sessions are stateful, the application 538 service must be able to correlate ATLS records from different clients 539 across the relevant ATLS sessions. The details of how session 540 tracking is implemented are outside the scope of this document. 541 Recommendations are given in Section 9 and Section 10, but session 542 tracking is application and implementation specific. 544 6.1.4. ATLS Record Inspection 546 It should not be necessary for the application layer to have to 547 inspect, parse or understand the contents of ATLS records. No 548 constraints are placed on the ContentType contained within the 549 transported TLS records. The TLS records may contain handshake, 550 application_data, alert or change_cipher_spec messages. If new 551 ContentType messages are defined in future TLS versions, these may 552 also be transported using this protocol. 554 6.1.5. Implementation 556 Pseudo code illustrating how to read and write TLS records directly 557 from byte buffers using both OpenSSL BIO functions and Java JSSE 558 SSLEngine is given in the appendices. A blog post by [Norrell] 559 outlines a similar approach to leveraging OpenSSL BIO functions, and 560 Oracle publish example code for leveraging [SSLEngine]. 562 6.2. Functional Design 564 The functional design assumes that an authorization system has 565 established operational keys for authenticating endpoints. In a 566 layered design, this needs to be done for each layer, which may 567 operate in two separate authorization domains. Note that Figure 7 568 shows a generic setup where TLS/DTLS is used at two layers. In some 569 cases, use of TLS/DTLS at the application layer may be sufficient 570 where lower layer security mechanisms provide protection of the 571 transport-specific headers. 573 +-------------------------------------------------------+ 574 | +---+ +---+ | 575 | +--------+ |APP| |APP| +--------+ | 576 | |security| +---+ +---+ |security| | 577 | |--------+ ^ ^ |--------+ | 578 | |policies| | | |policies| | 579 | |LAYER 0 | | | |LAYER 0 | | 580 | +--------+ v v +--------+ | 581 | + +------+ APP +------+ + | 582 | | | TLS- |<--------->| TLS- | | | 583 | +----->|SERVER| LAYER |CLIENT|<-----+ | 584 | +------+ +------+ | 585 | TOP LAYER ^ ^ | 586 +-----------------|-------------------|-----------------+ 587 | BOTTTOM LAYER | | | 588 | v v | 589 | +------+ TRANSPORT +------+ | 590 | | TLS- |<--------->| TLS- | | 591 | +--------+ |SERVER| LAYER |CLIENT| +--------+ | 592 | |security| +------+ +------+ |security| | 593 | |--------+ ^ ^ |--------+ | 594 | |policies| | | |policies| | 595 | |LAYER 1 +-----+ +-----+LAYER 1 | | 596 | +--------+ +--------+ | 597 | | 598 +-------------------------------------------------------+ 600 Figure 7: Functional Design 602 The security policies of one layer are distinct from those of another 603 in Figure 7. They may overlap, but that is not necessary or perhaps 604 even likely since the key exchanges at the different layers terminate 605 at different endpoints and the two often have different authorization 606 domains. 608 TLS can protect IoT device-to-gateway communications "on the wire" 609 using the "bottom layer" of Figure 7, and it can protect application 610 data from the device to the application server using the "top layer." 611 Application and transport security each have a role to play. 612 Transport security restricts access to messages on the networks, 613 notably application headers and application-layer TLS restricts 614 access to the application payloads. 616 As shown in Figure 7, an application-layer message, which gets 617 encrypted and integrity protected and, in the generic case, the the 618 resulting TLS message and headers are passed to a TLS socket at the 619 bottom layer, which may have a different security policy than the 620 application layer. 622 6.3. Network Architecture 624 An example network deployment is illustrated in Figure 8. It shows a 625 constrained client connecting to an application service via an 626 internet gateway. The client uses CoAP over DTLS to communicate with 627 the gateway. The gateway extracts the messages the client sent over 628 CoAP and sends these messages inside HTTP message bodies to the 629 application service. It also shows a TLS terminator deployed in 630 front of the application service. The client establishes a transport 631 layer CoAP/DTLS connection with the gateway (C->G DTLS), the gateway 632 in turn opens a transport layer TLS connection with the TLS 633 terminator deployed in front of the service (G->T TLS). The client 634 can ignore any certificate validation errors when it connects to the 635 gateway. CoAP messages are transported between the client and the 636 gateway, and HTTP messages are transported between the client and the 637 service. Finally, application layer TLS messages are exchanged 638 inside the CoAP and HTTP message bodies in order to establish an end- 639 to-end TLS session between the client and the service (C->S TLS). 641 +----------+ +----------+ 642 | App Data | | App Data | 643 +----------+ +----------+ +----------+ 644 | C->S TLS | | C->S TLS | | App Data | 645 +----------+ +----------+ +----------+ 646 | CoAP | | HTTP | | C->S TLS | 647 +----------+ +----------+ +----------+ 648 | C->G DTLS| | M->T TLS | | HTTP | 649 +----------+ +----------+ +----------+ 650 | UDP | | TCP | | TCP | 651 +----------+ +----------+ +----------+ 653 +--------+ +-----------+ +----------------+ +---------+ 654 | Client |----->| Gateway |----->| TLS Terminator |---->| Service | 655 +--------+ +-----------+ +----------------+ +---------+ 656 ^ ^ 657 | | 658 +-------------Client to Service ATLS Connection-------------+ 660 Figure 8: Constrained Device Gateway Network Architecture 662 Another typical network deployment is illustrated in Figure 9. It 663 shows a client connecting to a service via a middlebox. It also 664 shows a TLS terminator deployed in front of the service. The client 665 establishes a transport layer TLS connection with the middlebox (C->M 666 TLS), the middlebox in turn opens a transport layer TLS connection 667 with the TLS terminator deployed in front of the service (M->T TLS). 668 The client can ignore any certificate validation errors when it 669 connects to the middlebox. HTTP messages are transported over this 670 layer between the client and the service. Finally, application layer 671 TLS messages are exchanged inside the HTTP message bodies in order to 672 establish an end-to-end TLS session between the client and the 673 service (C->S TLS). 675 +----------+ +----------+ 676 | App Data | | App Data | 677 +----------+ +----------+ +----------+ 678 | C->S TLS | | C->S TLS | | App Data | 679 +----------+ +----------+ +----------+ 680 | HTTP | | HTTP | | C->S TLS | 681 +----------+ +----------+ +----------+ 682 | C->M TLS | | M->T TLS | | HTTP | 683 +----------+ +----------+ +----------+ 684 | TCP | | TCP | | TCP | 685 +----------+ +----------+ +----------+ 687 +--------+ +-----------+ +----------------+ +---------+ 688 | Client |----->| Middlebox |----->| TLS Terminator |---->| Service | 689 +--------+ +-----------+ +----------------+ +---------+ 690 ^ ^ 691 | | 692 +-------------Client to Service ATLS Connection-------------+ 694 Figure 9: HTTP Middlebox Network Architecture 696 7. Key Exporting and Application Data Encryption 698 When solutions implement the architecture described in Figure 6, they 699 leverage [RFC5705] for exporting keys. When the OSCORE mode has been 700 agreed using the "oscore_connection_id" extension defined in this 701 document, different keys are used for ordinary DTLS/TLS record 702 protection and OSCORE packet protection. These keys are produced 703 using a TLS exporter [RFC5705] and the exporter takes three input 704 values: 706 o a disambiguating label string, 708 o a per-association context value provided by the application using 709 the exporter, and 711 o a length value. 713 The label string for use with this specification is defined as 714 'application-layer-tls'. The per-association context value is empty. 716 The length value is twice the size of the key size utilized by the 717 negotiated algorithm since the lower-half is used for the Master 718 Secret and the upper-half is used for the Master Salt. 720 For example, if a TLS/DTLS 1.2 handshake negotiated the 721 TLS_PSK_WITH_AES_128_CCM_8 ciphersuite then the key size utilized by 722 the negotiated algorithm, i.e. AES 128, is 128 bit. Hence, the key 723 extractor is requested to produce 2 x 128 bit keying material. 725 The following parameters are needed for use with OSCORE: 727 o Master Secret: The master secret is described as described above. 729 o Sender ID: This values is negotiated using the 730 "oscore_connection_id" extension, as described in Section 11. 732 o Recipient ID: This values is negotiated using the 733 "oscore_connection_id" extension, as described in Section 11. 735 o AEAD Algorithm: This value is negotiated using the ciphersuite 736 exchange provided by the TLS/DTLS handshake. For example, if a 737 TLS/DTLS 1.2 handshake negotiated the TLS_PSK_WITH_AES_128_CCM_8 738 ciphersuite then AEAD algorithm identifier is AES_128_CCM_8, which 739 corresponds to COSE algorithms AES-CCM-64-64-128 or AES-CCM- 740 16-64-128, whereby the former uses a 7-byte nonce and the later 741 13-byte nonce. Since in TLS/DTLS the nonce value is not 742 negotiated but rather fixed, a 7-byte nonce value is assumed as a 743 default in this document. 745 o Master Salt: The master salt is described as described above. 747 o HKDF Algorithm: This value is negotiated using the ciphersuite 748 exchange provided by the TLS/DTLS handshake. As a default, 749 SHA-256 is assumed as a HKDF algorithm. 751 o Replay Window: A default window size of 32 packets is assumed. 753 A future version of this specification will describe how to establish 754 keying material and parameters for security contexts other than 755 OSCORE. 757 8. ATLS Session Establishment 759 Figure 10 illustrates how an ATLS session is established using the 760 key exporting architectural model shown in Figure 6. The number of 761 RTTs that take place when establishing a TLS session depends on the 762 version of TLS and what capabilities are enabled on the TLS software 763 stack. For example, a 0-RTT exchange is possible with TLS 1.3. If 764 applications wish to ensure a predictable number of RTTs when 765 establishing an application layer TLS connection, this may be 766 achieved by configuring the TLS software stack appropriately. 768 The outline is as follows: 770 o the client creates an ATLS session object 772 o the client initiates a TLS handshake on the session 774 o the client extracts the TLS records for the first TLS flight (the 775 first RTT) 777 o the client sends the TLS records over the transport layer to the 778 server 780 o on receipt of the TLS flight, the server creates an ATLS session 781 object 783 o the server injects the received TLS flight into the session 785 o the server extracts the TLS records for the first TLS flight 786 response 788 o the server sends the TLS response records over the transport layer 789 to the client 791 o the client injects the received TLS records into its TLS session 792 completing the first full RTT 794 o the client and server repeat the above process and complete the 795 second RTT 797 o once the ATLS session is up, both sides export keying material 799 o both sides now can exchange data encrypted using shared keys 800 derived from the keying material 802 +-------------------------------+ +-------------------------------+ 803 | Client | | ATLS Server | 804 +---------+---+-----+-+---------+ +---------+--+-----+--+---------+ 805 | ATLS | | App | |Transport| |Transport| | App | | ATLS | 806 | Session | +-----+ | Stack | | Stack | +-----+ | Session | 807 +---------+ | +---------+ +---------+ | +---------+ 808 | | | | | | 809 | | | | | | 810 | | | | | | 811 | Create | | | | | 812 | Session | | | | | 813 + |<---------| | | | | 814 | | Start | | | | | 815 | | Handshake| | | | | 816 | |<---------| | | | | 817 | | TLS | | | | | 818 | | Records | Pack | | | | 819 | |--------->| Records | | | | 820 | |-------->| send packet | Unpack | | 821 R | | |------------>| Records | Create | 822 T | | | |--------->| Session | 823 T | | | | |--------->| 824 | | | | | TLS | 825 1 | | | | | Records | 826 | | | | |--------->| 827 | | | | | | TLS | 828 | | | | | Pack | Records | 829 | | | | | Records |<---------| 830 | | | Unpack |send response|<---------| | 831 | | TLS | Records |<------------| | | 832 | | Records |<--------| | | | 833 + |<---------| | | | | 834 | TLS | | | | | 835 | Records | | | | | 836 + |--------->|-------->|------------>|--------->|--------->| 837 | | | | | | | 838 | | | | | Session | 839 R | | | | | Up | 840 T | | | | |<---------| 841 T | | | | | TLS | 842 | | | | | Records | 843 2 |<---------|<--------|<------------|<---------|<---------| 844 | Session | | | | | 845 | | Up | | | | | 846 + |--------->| | | | | 847 | Export | | | | Export | 848 | Keys | | | | Keys | 849 |--------->| | E2E Session | |<---------| 850 | |<--------|-------------|--------->| | 852 Figure 10: ATLS Session Establishment 854 9. ATLS over HTTP Transport 856 The assumption is that the client will establish a transport layer 857 connection to the server for exchange of HTTP messages. The 858 underlying transport layer connection could be over TCP or TLS. The 859 client will then establish an application layer TLS connection with 860 the server by exchanging TLS records with the server inside HTTP 861 message request and response bodies. 863 9.1. Protocol Summary 865 All ATLS records are transported unmodified as binary data within 866 HTTP message bodies. The application simply extracts the TLS records 867 from the TLS stack and inserts them directly into HTTP message 868 bodies. Each message body contains a full TLS flight, which may 869 contain multiple TLS records. 871 The client sends all ATLS records to the server in the bodies of POST 872 requests. 874 The server sends all ATLS records to the client in the bodies of 200 875 OK responses to the POST requests. 877 The URI path used by ATLS is "/.well-known/atls". 879 9.2. Content-Type Header 881 A new Content-Type header value is defined: 883 Content-type: application/atls 885 All message bodies containing ATLS records must set this Content- 886 Type. This enables middleboxes to readily identify ATLS payloads. 888 9.3. HTTP Status Codes 890 This document does not define any new HTTP status codes, and does not 891 specify additional semantics or refine existing semantics for status 892 codes. This is the best current practice as outlined in 893 [I-D.ietf-httpbis-bcp56bis]. 895 9.4. ATLS Session Tracking 897 The application service needs to track multiple client application 898 layer TLS sessions so that it can correlate TLS records received in 899 HTTP message bodies with the appropriate TLS session. The 900 application service should use stateful cookies [RFC6265] in order to 901 achieve this as recommended in [I-D.ietf-httpbis-bcp56bis]. 903 9.5. Session Establishment and Key Exporting 905 It is recommended that applications using ATLS over HTTP transport 906 only use ATLS for session establishment and key exchange, resulting 907 in only 2 ATLS RTTs between the client and the application service. 909 Key exporting must be carried out as described in Section 7. 911 9.6. Illustrative ATLS over HTTP Session Establishment 913 A client initiates an ATLS session by sending the first TLS flight in 914 a POST request message body to the ATLS server. 916 POST /.well-known/atls 917 Content-Type: application/atls 919 921 The server handles the request, creates an ATLS session object, and 922 replies by including its first TLS flight in a 200 OK message body. 923 The server also sets a suitable cookie for session tracking purposes. 925 200 OK 926 Content-Type: application/atls 927 Set-Cookie: my-atls-cookie=my-cookie-value 929 931 The client handles the server first flight TLS records and replies 932 with its second flight. 934 POST /.well-known/atls 935 Content-Type: application/atls 936 Cookie: my-atls-cookie=my-cookie-value 938 940 The server handles the second flight, establishes the ATLS session, 941 and replies with its second flight. 943 200 OK 944 Content-Type: application/atls 946 948 9.7. ATLS and HTTP CONNECT 950 It is worthwhile comparing and contrasting ATLS with HTTP CONNECT 951 tunneling. 953 First, let us introduce some terminology: 955 o HTTP Proxy: A HTTP Proxy operates at the application layer, 956 handles HTTP CONNECT messages from clients, and opens tunnels to 957 remote origin servers on behalf of clients. If a client 958 establishes a tunneled TLS connection to the origin server, the 959 HTTP Proxy does not attempt to intercept or inspect the HTTP 960 messages exchanged between the client and the server 962 o middlebox: A middlebox operates at the transport layer, terminates 963 TLS connections from clients, and originates new TLS connections 964 to services. A middlebox inspects all messages sent between 965 clients and services. Middleboxes are generally completely 966 transparent to applications, provided that the necessary PKI root 967 Certificate Authority is installed in the client's trust store. 969 HTTP Proxies and middleboxes are logically separate entities and one 970 or both of these may be deployed in a network. 972 HTTP CONNECT is used by clients to instruct a HTTP Forward Proxy 973 deployed in the local domain to open up a tunnel to a remote origin 974 server that is typically deployed in a different domain. Assuming 975 that TLS transport is used between both client and proxy, and proxy 976 and origin server, the network architecture is as illustrated in 977 Figure 11. Once the proxy opens the transport tunnel to the service, 978 the client establishes an end-to-end TLS session with the service, 979 and the proxy is blindly transporting TLS records (the C->S TLS 980 session records) between the client and the service. From the client 981 perspective, it is tunneling a TLS session to the service inside the 982 TLS session it has established to the proxy (the C->P TLS session). 983 No middlebox is attempting to intercept or inspect the HTTP messages 984 between the client and the service. 986 +----------+ +----------+ 987 | C->S HTTP| | C->S HTTP| 988 +----------+ +----------+ 989 | C->S TLS | | C->S TLS | 990 +----------+ +----------+ 991 | C->P TLS | | P->S TCP | 992 +----------+ +----------+ 993 | C->P TCP | 994 +----------+ 996 +--------+ +------------+ +---------+ 997 | Client |----->| HTTP Proxy |----->| Service | 998 +--------+ +------------+ +---------+ 1000 Figure 11: HTTP Proxy transport layers 1002 A more complex network topology where the network operator has both a 1003 HTTP Proxy and a middlebox deployed is illustrated in Figure 12. In 1004 this scenario, the proxy has tunneled the TLS session from the client 1005 towards the origin server, however the middlebox is intercepting and 1006 terminating this TLS session. A TLS session is established between 1007 the client and the middlebox (C->M TLS), and not end-to-end between 1008 the client and the server. It can clearly be seen that HTTP CONNECT 1009 and HTTP Proxies serve completely different functions than 1010 middleboxes. 1012 Additionally, the fact that the TLS session is established between 1013 the client and the middlebox can be problematic for two reasons: 1015 o the middle box is inspecting traffic that is sent between the 1016 client and the service 1018 o the client may not have the necessary PKI root Certificate 1019 Authority installed that would enable it to validate the TLS 1020 connection to the middlebox. This is the scenario outlined in 1021 Section 3.1. 1023 +----------+ +----------+ +----------+ 1024 | C->S HTTP| | C->S HTTP| | C->S HTTP| 1025 +----------+ +----------+ +----------+ 1026 | C->M TLS | | C->M TLS | | M->S TLS | 1027 +----------+ +----------+ +----------+ 1028 | C->P TLS | | P->M TCP | | M->S TCP | 1029 +----------+ +----------+ +----------+ 1030 | C->P TCP | 1031 +----------+ 1033 +--------+ +------------+ +-----------+ +---------+ 1034 | Client |----->| HTTP Proxy |----->| Middlebox |----->| Service | 1035 +--------+ +------------+ +-----------+ +---------+ 1037 Figure 12: HTTP Proxy and middlebox transport layers 1039 As HTTP CONNECT can be used to establish a tunneled TLS connection, 1040 one hypothetical solution to this middlebox issue is for the client 1041 to issue a HTTP CONNECT command to a HTTP Reverse Proxy deployed in 1042 front of the origin server. This solution is not practical for 1043 several reasons: 1045 o if there is a local domain HTTP Forward Proxy deployed, this would 1046 result in the client doing a first HTTP CONNECT to get past the 1047 Forward Proxy, and then a second HTTP CONNECT to get past the 1048 Reverse Proxy. No client or client library supports the concept 1049 of HTTP CONNECT inside HTTP CONNECT. 1051 o if there is no local domain HTTP Proxy deployed, the client still 1052 has to do a HTTP CONNECT to the HTTP Reverse Proxy. This breaks 1053 with standard and expected HTTP CONNECT operation, as HTTP CONNECT 1054 is only ever called if there is a local domain proxy. 1056 o clients cannot generate CONNECT from XHR in web applications. 1058 o this would require the deployment of a Reverse Proxy in front of 1059 the origin server, or else support of the HTTP CONNECT method in 1060 standard web frameworks. This is not an elegant design. 1062 o using HTTP CONNECT with HTTP 1.1 to a Reverse Proxy will break 1063 middleboxes inspecting HTTP traffic, as the middlebox would see 1064 TLS records when it expects to see HTTP payloads. 1066 In contrast to trying to force HTTP CONNECT to address a problem for 1067 which it was not designed to address, and having to address all the 1068 issues just outlined; ATLS is specifically designed to address the 1069 middlebox issue in a simple, easy to develop, and easy to deploy 1070 fashion. 1072 o ATLS works seamlessly with HTTP Proxy deployments 1074 o no changes are required to HTTP CONNECT semantics 1076 o no changes are required to HTTP libraries or stacks 1078 o no additional Reverse Proxy is required to be deployed in front of 1079 origin servers 1081 It is also worth noting that if HTTP CONNECT to a Reverse Proxy were 1082 a conceptually sound solution, the solution still ultimately results 1083 in encrypted traffic traversing the middlebox that the middlebox 1084 cannot intercept and inspect. That is ultimately what ATLS results 1085 in - traffic traversing the middle box that the middlebox cannot 1086 intercept and inspect. Therefore, from a middlebox perspective, the 1087 differences between the two solutions are in the areas of solution 1088 complexity and protocol semantics. It is clear that ATLS is a 1089 simpler, more elegant solution that HTTP CONNECT. 1091 10. ATLS over CoAP Transport 1093 To carry TLS messages over CoAP it is recommended to use Confirmable 1094 messages while DTLS payloads may as well use non-confirmable 1095 messages. The exchange pattern in CoAP uses the following style: A 1096 request from the CoAP client to the CoAP server uses a POST with the 1097 ATLS message contained in the payload of the request. An ATLS 1098 response is returned by the CoAP server to the CoAP client in a 2.04 1099 (Changed) message. 1101 When DTLS messages are conveyed in CoAP over UDP then the DDoS 1102 protection offered by DTLS MAY be used instead of replicating the 1103 functionality at the CoAP layer. If TLS is conveyed in CoAP over UDP 1104 then DDoS protection by CoAP has to be utilized. Carrying ATLS 1105 messages in CoAP over TCP does not require any additional DDoS 1106 protection. 1108 The URI path used by ATLS is "/.well-known/atls". 1110 {{coap-example} shows a TLS 1.3 handshake inside CoAP graphically. 1112 Client Server 1113 | | 1114 +--------->| Header: POST (Code=0.02) 1115 | POST | Uri-Path: "/.well-known/atls" 1116 | | Content-Format: application/atls 1117 | | Payload: ATLS (ClientHello) 1118 | | 1119 |<---------+ Header: 2.04 Changed 1120 | 2.04 | Content-Format: application/atls 1121 | | Payload: ATLS (ServerHello, 1122 | | {EncryptedExtensions}, {CertificateRequest*} 1123 | | {Certificate*}, {CertificateVerify*} {Finished}) 1124 | | 1125 +--------->| Header: POST (Code=0.02) 1126 | POST | Uri-Path: "/.well-known/atls" 1127 | | Content-Format: application/atls 1128 | | Payload: ATLS ({Certificate*}, 1129 | | {CertificateVerify*}, {Finished}) 1130 | | 1131 |<---------+ Header: 2.04 Changed 1132 | 2.04 | 1133 | | 1135 Figure 13: Transferring ATLS in CoAP 1137 Note that application data can already be sent by the server in the 1138 second message and by the client in the third message, in case of the 1139 full TLS 1.3 handshake. In case of the 0-RTT handshake application 1140 data can be sent earlier. To mix different media types in the same 1141 CoAP payload the application/multipart-core content type is used. 1143 Note also that CoAP blockwise transfer MAY be used if the payload 1144 size, for example due to the size of the certificate chain, exceeds 1145 the MTU size. 1147 11. The "oscore_connection_id" Extension 1149 This document defines the "oscore_connection_id" extension, which is 1150 used in ClientHello and ServerHello messages. It is used only for 1151 establishing the client's OSCORE Sender ID and the server's OSCORE 1152 Sender ID. The client's OSCORE Sender ID maps to the CID provided by 1153 the server in the ServerHello and the server's OSCORE Sender ID maps 1154 to the CID provided by the client in the ClientHello. 1156 The negotiation mechanism follows the procedure used in 1157 [I-D.ietf-tls-dtls-connection-id] with the exception that the 1158 negotiated CIDs agreed with the "oscore_connection_id" extension is 1159 only used with OSCORE and does not impact the record layer format of 1160 the DTLS/TLS payloads nor the MAC calculation used by DTLS/TLS. As 1161 such, this extension can be used with DTLS as well as with TLS when 1162 those protocols are used at the application layer. 1164 The extension type is specified as follows. 1166 enum { oscore_connection_id(TBD), (65535) } ExtensionType; 1168 struct { opaque cid<0..2^8-1>; } ConnectionId; 1170 Note: This extension allows a client and a server to determine 1171 whether an OSCORE security context should be established. 1173 A future version of this specification may extend the negotiation 1174 capabilities. 1176 12. IANA Considerations 1178 12.1. "oscore_connection_id" TLS extension 1180 IANA is requested to allocate an entry to the existing TLS 1181 "ExtensionType Values" registry, defined in [RFC5246], for 1182 oscore_connection_id(TBD) defined in this document. 1184 12.2. .well-known URI Registry 1186 IANA is requested to add the well-known URI 'atls' to the Well-Known 1187 URIs registry. 1189 o URI suffix: atls 1191 o Change controller: IETF 1193 o Specification document(s): [[this document]] 1195 o Related information: None 1197 12.3. Media Types Registry 1199 IANA is requested to add the media type 'application/atls' to the 1200 Media Types registry. 1202 o Type name: application 1204 o Subtype name: atls 1206 o Required parameters: N/A 1208 o Optional parameters: N/A 1210 o Encoding considerations: binary 1212 o Security considerations: See Security Considerations section of 1213 this document. 1215 o Interoperability considerations: N/A 1217 o Published specification: [[this document]] (this document) 1219 o Applications that use this media type: Potentially any 1221 o Fragment identifier considerations: N/A 1223 o Additional information: 1225 * Magic number(s): N/A 1227 * File extension(s): N/A 1229 * Macintosh file type code(s): N/A 1231 o Person & email address to contact for further information: See 1232 "Authors' Addresses" section. 1234 o Intended usage: COMMON 1236 o Restrictions on usage: N/A 1238 o Author: See "Authors' Addresses" section. 1240 o Change Controller: IESG 1242 12.4. HTTP Content-Formats Registry 1244 IANA is requested to add the media type 'application/atls' to the 1245 HTTP Content-Formats registry. 1247 o Media Type: application/atls 1249 o Encoding: binary 1251 o ID: TBD 1253 o Reference: [[this document]] 1255 12.5. CoAP Content-Formats Registry 1257 IANA is requested to add the media type 'application/atls' to the 1258 CoAP Content-Formats registry. 1260 o Media Type: application/atls 1262 o Encoding: binary 1264 o ID: TBD 1266 o Reference: [[this document]] 1268 12.6. TLS Key Extractor Label 1270 IANA is requested to register the "application-layer-tls" label in 1271 the TLS Extractor Label Registry to correspond to this specification. 1273 13. Security Considerations 1275 This specification re-uses the TLS and DTLS and hence the security 1276 considerations of the respective TLS/DTLS version applies. As 1277 described in Section 6.2, implementers need to take the policy 1278 configuration into account when applying security protection at 1279 various layers of the stack even if the same protocol is used since 1280 the communiation endpoints and the security requirements are likely 1281 going to vary. 1283 For use in the IoT environment the considerations described in 1284 [RFC7925] apply and other environments the guidelines in [RFC7525] 1285 are applicable. 1287 14. Informative References 1289 [ALTS] Google, "Application Layer Transport Security", December 1290 2017, . 1293 [Bluetooth] 1294 Bluetooth, "Bluetooth Core Specification v5.0", 2016, 1295 . 1297 [I-D.ietf-anima-bootstrapping-keyinfra] 1298 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 1299 S., and K. Watsen, "Bootstrapping Remote Secure Key 1300 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 1301 keyinfra-19 (work in progress), March 2019. 1303 [I-D.ietf-core-object-security] 1304 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1305 "Object Security for Constrained RESTful Environments 1306 (OSCORE)", draft-ietf-core-object-security-16 (work in 1307 progress), March 2019. 1309 [I-D.ietf-httpbis-bcp56bis] 1310 Nottingham, M., "Building Protocols with HTTP", draft- 1311 ietf-httpbis-bcp56bis-08 (work in progress), November 1312 2018. 1314 [I-D.ietf-tls-dtls-connection-id] 1315 Rescorla, E., Tschofenig, H., and T. Fossati, "Connection 1316 Identifiers for DTLS 1.2", draft-ietf-tls-dtls-connection- 1317 id-04 (work in progress), March 2019. 1319 [I-D.ietf-tls-dtls13] 1320 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 1321 Datagram Transport Layer Security (DTLS) Protocol Version 1322 1.3", draft-ietf-tls-dtls13-30 (work in progress), 1323 November 2018. 1325 [I-D.ietf-tls-tls13] 1326 Rescorla, E., "The Transport Layer Security (TLS) Protocol 1327 Version 1.3", draft-ietf-tls-tls13-28 (work in progress), 1328 March 2018. 1330 [I-D.mattsson-core-security-overhead] 1331 Mattsson, J., "Message Size Overhead of CoAP Security 1332 Protocols", draft-mattsson-core-security-overhead-02 (work 1333 in progress), November 2017. 1335 [I-D.selander-ace-cose-ecdhe] 1336 Selander, G., Mattsson, J., and F. Palombini, "Ephemeral 1337 Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- 1338 cose-ecdhe-12 (work in progress), February 2019. 1340 [LwM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1341 Requirements", December 2017, 1342 . 1344 [Noise] Perrin, T., "Noise Protocol Framework", October 2017, 1345 . 1347 [Norrell] Norrell, ., "Use SSL/TLS within a different protocol with 1348 BIO pairs", 2016, 1349 . 1352 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1353 Requirement Levels", BCP 14, RFC 2119, 1354 DOI 10.17487/RFC2119, March 1997, 1355 . 1357 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1358 (TLS) Protocol Version 1.2", RFC 5246, 1359 DOI 10.17487/RFC5246, August 2008, 1360 . 1362 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 1363 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 1364 March 2010, . 1366 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1367 DOI 10.17487/RFC6265, April 2011, 1368 . 1370 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1371 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1372 January 2012, . 1374 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1375 Protocol (HTTP/1.1): Message Syntax and Routing", 1376 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1377 . 1379 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1380 "Recommendations for Secure Use of Transport Layer 1381 Security (TLS) and Datagram Transport Layer Security 1382 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1383 2015, . 1385 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1386 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1387 DOI 10.17487/RFC7540, May 2015, 1388 . 1390 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1391 Security (TLS) / Datagram Transport Layer Security (DTLS) 1392 Profiles for the Internet of Things", RFC 7925, 1393 DOI 10.17487/RFC7925, July 2016, 1394 . 1396 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1397 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1398 May 2017, . 1400 [Signal] Open Whisper Systems, "Signal Protocol", 2016, 1401 . 1403 [SSLEngine] 1404 Oracle, "SSLEngineSimpleDemo.java", 2004, . 1408 [ZigBee] ZigBee Alliance, "ZigBee Specification", 2012, 1409 . 1411 Appendix A. Pseudo Code 1413 This appendix gives both C and Java pseudo code illustrating how to 1414 inject and extract raw TLS records from a TLS software stack. Please 1415 not that this is illustrative, non-functional pseudo code that does 1416 not compile. Functioning proof-of-concept code is available on the 1417 following public repository [[ EDITOR'S NOTE: Add the URL here ]]. 1419 A.1. OpenSSL 1421 OpenSSL provides a set of Basic Input/Output (BIO) APIs that can be 1422 used to build a custom transport layer for TLS connections. This 1423 appendix gives pseudo code on how BIO APIs could be used to build a 1424 client application that completes a TLS handshake and exchanges 1425 application data with a service. 1427 char inbound[MAX]; 1428 char outbound[MAX]; 1429 int rx_bytes; 1430 SSL_CTX *ctx = SSL_CTX_new(); 1431 SSL *ssl = SSL_new(ctx); 1433 // Create in-memory BIOs and plug in to the SSL session 1434 BOI* bio_in = BIO_new(BIO_s_mem()); 1435 BOI* bio_out = BIO_new(BIO_s_mem()); 1436 SSL_set_bio(ssl, bio_in, bio_out); 1438 // We are a client 1439 SSL_set_connect_state(ssl); 1441 // Loop through TLS flights until we are done 1442 do { 1443 // Calling SSL_do_handshake() will result in a full 1444 // TLS flight being written to the BIO buffer 1445 SSL_do_handshake(ssl); 1447 // Read the client flight that the TLS session 1448 // has written to memory 1449 BIO_read(bio_out, outbound, MAX); 1451 // POST the outbound bytes to the server using a suitable 1452 // function. Lets assume that the server response will be 1453 // written to the 'inbound' buffer 1454 num_bytes = postTlsRecords(outbound, inbound); 1456 // Write the server flight to the memory BIO so the TLS session 1457 // can read it. The next call to SSL_do_handshake() will handle 1458 // this received server flight 1459 BIO_write(bio_in, inbound, num_bytes); 1461 } while (!SSL_is_init_finished(ssl)); 1463 // Send a message to the server. Calling SSL_write() will run the 1464 // plaintext through the TLS session and write the encrypted TLS 1465 // records to the BIO buffer 1466 SSL_write(ssl, "Hello World", strlen("Hello World")); 1468 // Read the TLS records from the BIO buffer and 1469 // POST them to the server 1470 BIO_read(bio_out, outbound, MAX); 1471 num_bytes = postTlsRecords(outbound, inbound); 1473 A.2. Java JSSE 1475 The Java SSLEngine class "enables secure communications using 1476 protocols such as the Secure Sockets Layer (SSL) or IETF RFC 2246 1477 "Transport Layer Security" (TLS) protocols, but is transport 1478 independent". This pseudo code illustrates how a server could use 1479 the SSLEngine class to handle an inbound client TLS flight and 1480 generate an outbound server TLS flight response. 1482 SSLEngine sslEngine = SSLContext.getDefault().createSSLEngine(); 1483 sslEngine.setUseClientMode(false); 1484 sslEngine.beginHandshake(); 1486 // Lets assume 'inbound' has been populated with 1487 // the Client 1st Flight 1488 ByteBuffer inbound; 1490 // 'outbound' will be populated with the 1491 // Server 1st Flight response 1492 ByteBuffer outbound; 1494 // SSLEngine handles one TLS Record per call to unwrap(). 1495 // Loop until the engine is finished unwrapping. 1496 while (sslEngine.getHandshakeStatus() == 1497 HandshakeStatus.NEED_UNWRAP) { 1498 SSLEngineResult res = sslEngine.unwrap(inbound, outbound); 1500 // SSLEngine may need additional tasks run 1501 if (res.getHandshakeStatus() == NEED_TASK) { 1502 Runnable run = sslEngine.getDelegatedTask(); 1503 run.run(); 1504 } 1505 } 1507 // The SSLEngine has now finished handling all inbound TLS Records. 1508 // Check if it wants to generate outbound TLS Records. SSLEngine 1509 // generates one TLS Record per call to wrap(). 1510 // Loop until the engine is finished wrapping. 1511 while (sslEngine.getHandshakeStatus() == 1512 HandshakeStatus.NEED_WRAP) { 1513 SSLEngineResult res = sslEngine.wrap(inbound, outbound); 1515 // SSLEngine may need additional tasks run 1516 if (res.getHandshakeStatus() == NEED_TASK) { 1517 Runnable run = sslEngine.getDelegatedTask(); 1518 run.run(); 1519 } 1520 } 1522 // outbound ByteBuffer now contains a complete server flight 1523 // containing multiple TLS Records 1524 // Rinse and repeat! 1526 Appendix B. Example ATLS Handshake 1528 [[ EDITOR'S NOTE: For completeness, include a simple full TLS 1529 handshake showing the raw binary flights, along with the HTTP 1530 request/response/headers. And also the raw hex TLS records showing 1531 protocol bits ]] 1533 Authors' Addresses 1535 Owen Friel 1536 Cisco 1538 Email: ofriel@cisco.com 1540 Richard Barnes 1541 Cisco 1543 Email: rlb@ipv.sx 1545 Max Pritikin 1546 Cisco 1548 Email: pritikin@cisco.com 1550 Hannes Tschofenig 1551 ARM Limited 1553 Email: hannes.tschofenig@gmx.net 1555 Mark Baugher 1556 Consultant 1558 Email: mark@mbaugher.com