idnits 2.17.00 (12 Aug 2021) /tmp/idnits58685/draft-friel-tls-atls-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- 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 (July 31, 2018) is 1390 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 325, but not defined == Missing Reference: 'MAX' is mentioned on line 1175, but not defined == Outdated reference: draft-ietf-anima-bootstrapping-keyinfra has been published as RFC 8995 == Outdated reference: draft-ietf-core-object-security has been published as RFC 8613 == Outdated reference: A later version (-15) exists of draft-ietf-httpbis-bcp56bis-06 == Outdated reference: draft-ietf-tls-dtls13 has been published as RFC 9147 == Outdated reference: draft-ietf-tls-tls13 has been published as RFC 8446 == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-09 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) Summary: 0 errors (**), 0 flaws (~~), 9 warnings (==), 3 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: February 1, 2019 Cisco 6 H. Tschofenig 7 ARM Limited 8 M. Baugher 9 Consultant 10 July 31, 2018 12 Application-Layer TLS 13 draft-friel-tls-atls-01 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 February 1, 2019. 50 Copyright Notice 52 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . 13 89 7. Key Exporting and Application Data Encryption . . . . . . . . 15 90 7.1. Key Exporter Label . . . . . . . . . . . . . . . . . . . 15 91 7.2. Cipher Suite Selection . . . . . . . . . . . . . . . . . 15 92 7.3. Key Derivation . . . . . . . . . . . . . . . . . . . . . 15 93 8. ATLS Session Establishment . . . . . . . . . . . . . . . . . 16 94 9. ATLS over HTTP Transport . . . . . . . . . . . . . . . . . . 18 95 9.1. Protocol Summary . . . . . . . . . . . . . . . . . . . . 18 96 9.2. Content-Type Header . . . . . . . . . . . . . . . . . . . 18 97 9.3. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 18 98 9.4. ATLS Session Tracking . . . . . . . . . . . . . . . . . . 18 99 9.5. Session Establishment and Key Exporting . . . . . . . . . 19 100 9.6. Application Data Encryption . . . . . . . . . . . . . . . 19 101 9.7. Illustrative ATLS over HTTP Session Establishment . . . . 19 102 9.8. ATLS and HTTP CONNECT . . . . . . . . . . . . . . . . . . 20 103 10. ATLS over CoAP Transport . . . . . . . . . . . . . . . . . . 23 104 11. RTT Considerations . . . . . . . . . . . . . . . . . . . . . 23 105 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 106 13. Security Considerations . . . . . . . . . . . . . . . . . . . 23 107 14. Informative References . . . . . . . . . . . . . . . . . . . 24 108 Appendix A. TLS Software Stack Configuration . . . . . . . . . . 26 109 Appendix B. Pseudo Code . . . . . . . . . . . . . . . . . . . . 26 110 B.1. OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . 26 111 B.2. Java JSSE . . . . . . . . . . . . . . . . . . . . . . . . 28 112 Appendix C. Example ATLS Handshake . . . . . . . . . . . . . . . 30 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 115 1. Introduction 117 There are multiple scenarios where there is a need for application 118 layer end-to-end security between clients and application services. 119 Two examples include: 121 o Bootstrapping devices that must connect to HTTP application 122 services across untrusted TLS interception middleboxes 124 o Constrained devices connecting via gateways to application 125 services, where different transport layer protocols may be in use 126 on either side of the gateway, with the gateway transcoding 127 between the different transport layer protocols. 129 These two scenarios are described in more detail in Section 3. 131 Related to this document, there is ongoing work across the industry 132 to define requirements for end-to-end security. 133 [I-D.hartke-core-e2e-security-reqs] documents requirements for CoAP 134 [RFC7252] End-to-End Security. The Open Mobile Alliance (OMA) has 135 published a candidate standard Lightweight Machine to Machine 136 Requirements [LwM2M] which defines multiple requirements for end-to- 137 end security. 139 This document describes how clients and applications can leverage 140 standard TLS software stacks to establish secure end-to-end encrypted 141 connections at the application layer. The connections may establish 142 TLS [RFC5246] [I-D.ietf-tls-tls13] or DTLS [RFC6347] 143 [I-D.ietf-tls-dtls13] sessions. There are multiple advantages to 144 reuse of existing TLS software stacks for establishment of 145 application layer secure connections. These include: 147 o many clients and application services already include a TLS 148 software stack, so there is no need to include yet another 149 software stack in the software build 151 o no need to define a new cryptographic negotiation, authentication, 152 and key exchange protocol between clients and services 154 o provides standards based PKI mutual authentication between clients 155 and services 157 o no need to train software developers on how to use a new 158 cryptographic protocols or libraries 160 o automatically benefit from new cipher suites by simply upgrading 161 the TLS software stack 163 o automatically benefit from new features, bugfixes, etc. in TLS 164 software stack upgrades 166 This document also explicitly defines how application layer TLS 167 connections can be established using HTTP [RFC7230] [RFC7540] or CoAP 168 as transport layers. This document does not preclude the user of 169 other transport layers, however defining how application layer TLS 170 connections can be established over other transport layers such as 171 [ZigBee] or [Bluetooth] is beyond the scope of this document. 173 Explicitly identifying application layer TLS packets enables 174 transport layer middleboxes to provide transport capabilities and 175 enforce suitable transport policies for these payloads, without 176 requiring access to unencrypted application data. 178 2. Terminology 180 Application layer TLS is referred to as ATLS throughout this 181 document. 183 3. Application Layer End-to-End Security Use Cases 185 This section describes in more detail the bootstrapping and 186 constrained device use cases mentioned in the introduction. 188 3.1. Bootstrapping Devices 190 There are far more classes of clients being deployed on today's 191 networks than at any time previously. This poses challenges for 192 network administrators who need to manage their network and the 193 clients connecting to their network, and poses challenges for client 194 vendors and client software developers who must ensure that their 195 clients can connect to all required services. 197 One common example is where a client is deployed on a local domain 198 TCP/IP network that protects its perimeter using a TLS terminating 199 middlebox, and the client needs to establish a secure connection to a 200 service in a different network via the middlebox. This is 201 illustrated in Figure 1. 203 Traditionally, this has been enabled by the network administrator 204 deploying the necessary certificate authority trusted roots on the 205 client. This can be achieved at scale using standard tools that 206 enable the administrator to automatically push trusted roots out to 207 all client machines in the network from a centralized domain 208 controller. This works for personal computers, laptops and servers 209 running standard Operating Systems that can be centrally managed. 210 This client management process breaks for multiple classes of clients 211 that are being deployed today, there is no standard mechanism for 212 configuring trusted roots on these clients, and there is no standard 213 mechanism for these clients to securely traverse middleboxes. 215 +--------+ C->M TLS +-----------+ M->S TLS +---------+ 216 | Client |--------------->| Middlebox |------------->| Service | 217 +--------+ +-----------+ +---------+ 218 ^ ^ 219 | | 220 +-----------Client to Service ATLS Connection---------+ 222 Figure 1: Bootstrapping Devices 224 The ATLS mechanism defined in this document enables clients to 225 traverse middleboxes and establish secure connections to services 226 across network domain boundaries. The purpose of this connection may 227 simply be to facilitate a bootstrapping process, for example 228 [I-D.ietf-anima-bootstrapping-keyinfra], whereby the client securely 229 discovers the local domain certificate authorities required to 230 establish a trusted network layer TLS connection to the middlebox. 232 3.2. Constrained Devices 234 Two constrained device use cases are outlined here. 236 3.2.1. Constrained Device Connecting over a Closed Network 238 There are industry examples of home smart lighting systems where the 239 smart light bulbs connect using ZigBee to a gateway device. A 240 controller application running on a mobile device connects to the 241 gateway using CoAP over DTLS. The controller can then control the 242 light bulbs by sending messages and commands via the gateway. The 243 gateway device has full access to all messages sent between the light 244 bulbs and the controller application. 246 A generic use case similar to the smart lighting system outlined 247 above has an IoT device talking ZigBee to a gateway, with the gateway 248 in turn talking CoAP over DTLS to a controller application running on 249 a mobile device. This is illustrated in Figure 2. 251 There are scenarios where the messages sent between the IoT device 252 and the controller application must not be exposed to the gateway 253 function. Additionally, the end devices (the IoT device and the 254 controller application service) have no visibility to and no 255 guarantees about what transport layer security and encryption is 256 enforced across all hops end-to-end as they only have visibility to 257 their immediate next hop. ATLS addresses these concerns. 259 +--------+ ZigBee +---------+ CoAP/DTLS +------------+ 260 | Device |-------------->| Gateway |------------->| Mobile App | 261 +--------+ +---------+ +------------+ 262 ^ ^ 263 | | 264 +--------Device to Mobile App ATLS Connection-------+ 266 Figure 2: IoT Closed Network Gateway 268 3.2.2. Constrained Device Connecting over the Internet 270 A somewhat similar example has an IoT device connecting to a gateway 271 using a suitable transport mechanism such as ZigBee, CoAP, MQTT, etc. 272 The gateway function in turn talks HTTP over TLS (or, for example, 273 HTTP over QUIC) to an application service over the Internet. This is 274 illustrated in Figure 3. 276 The gateway may not be trusted and all messages between the IoT 277 device and the application service must be end-to-end encrypted. 278 Similar to the previous use case, the endpoints have no guarantees 279 about what level of transport layer security is enforced across all 280 hops. Again, ATLS addresses these concerns. 282 +--------+ CoAP/DTLS +------------------+ HTTP/TLS +---------+ 283 | Device |-------------->| Internet Gateway |------------>| Service | 284 +--------+ +------------------+ +---------+ 285 ^ ^ 286 | | 287 +---------Device to Cloud Service ATLS Connection----------+ 289 Figure 3: IoT Internet Gateway 291 4. Current Approaches to Application Layer End-to-End Security 293 End-to-end security at the application layer is increasing seen as a 294 key requirement across multiple applications and services. Some 295 examples of end-to-end security mechanisms are outlined here. All 296 the solutions outlined here have some common characteristics. The 297 solutions: 299 o do not rely on transport layer security 301 o define a new handshake protocol for establishment of a secure end- 302 to-end session 304 4.1. Noise 306 [Noise] is a framework for cryptographic protocols based on Elliptic 307 Curve Diffie-Hellman (ECDH) key agreement, AEAD encryption, and 308 BLAKE2 and SHA2 hash functions. Noise is currently used by WhatsApp, 309 WireGuard, and Lightning. 311 The current Noise protocol framework defines mechanisms for proving 312 possession of a private key, but does not define authentication 313 mechanisms. Section 14 "Security Considerations" of Noise states: 314 ~~~ it's up to the application to determine whether the remote 315 party's static public key is acceptable ~~~ 317 4.2. Signal 319 The [Signal] protocol provides end-to-end encryption and uses EdDSA 320 signatures, Triple Diffie-Hellman handshake for shared secret 321 establishment, and the Double Ratchet Algorithm for key management. 322 It is used by Open Whisper Systems, WhatsApp and Google. 324 Similar to Noise, Signal does not define an authentication mechanism. 325 The current [X3DH] specification states in section 4.1 326 "Authentication": 328 Methods for doing this are outside the scope of this document 330 4.3. Google ALTS 332 Google's Application Layer Transport Security [ALTS] is a mutual 333 authentication and transport encryption system used for securing 334 Remote Procedure Call (RPC) communications within Google's 335 infrastructure. ALTS uses an ECDH handshake protocol and a record 336 protocol containing AES encrypted payloads. 338 4.4. Ephemeral Diffie-Hellman Over COSE 340 There is ongoing work to standardise [I-D.selander-ace-cose-ecdhe]. 341 This defines a ECDH SIGMA based authenticated key exchange algorithm 342 using COSE and COBR objects. 344 5. ATLS Goals 346 The high level goals driving the design of this mechanism are: 348 o enable authenticated key exchange at the application layer by 349 reusing existing technologies 351 o ensure that ATLS packets are explicitly identified thus ensuring 352 that any middleboxes or gateways at the transport layer are 353 content aware 355 o leverage existing TLS stacks and handshake protocols thus avoiding 356 introducing new software or protocol dependencies in clients and 357 applications 359 o reuse existing TLS [RFC5246] [I-D.ietf-tls-tls13] and DTLS 360 [RFC6347] [I-D.ietf-tls-dtls13] specifications as is without 361 requiring any protocol changes or software stack changes 363 o do not mandate constraints on how the TLS stack is configured or 364 used 366 o be forward compatible with future TLS versions 368 o avoid introducing TLS protocol handling logic or semantics into 369 the application layer i.e. TLS protocol knowledge and logic is 370 handled by the TLS stack, not the application 372 o ensure the client and server software implementations are as 373 simple as possible 375 6. Architecture Overview 377 6.1. Application Architecture 379 TLS software stacks allow application developers to 'unplug' the 380 default network socket transport layer and read and write TLS records 381 directly from byte buffers. This enables application developers to 382 create application layer TLS sessions, extract the raw TLS record 383 bytes from the bottom of the TLS stack, and transport these bytes 384 over any suitable transport. The TLS software stacks can generate 385 byte streams of full TLS flights which may include multiple TLS 386 records. Additionally, TLS software stacks support Keying Material 387 Exporters [RFC5705] and allow applications to export keying material 388 from established TLS sessions. This keying material can then be used 389 by the application for encryption of data outside the context of the 390 TLS session. This is illustrated in Figure 4 below. 392 +------------+ +---------+ 393 Handshake Records | | Handshake Records | | 394 ------------------->| |------------------->| | 395 | | | Byte | 396 Unencrypted Data | TLS | Encrypted Data | | 397 ------------------->| |------------------->| Buffers | 398 | Software | | | 399 Encrypted Data | | Unencrypted Data | | 400 ------------------->| Stack |------------------->| | 401 | | +---------+ 402 Keying Material | | 403 <-------------------| | 404 + -----------+ 406 Figure 4: TLS Stack Interfaces 408 These TLS software stack APIs enable application developers to build 409 the software architectures illustrated in Figure 5 and Figure 6. 411 In both architectures, the application creates and interacts with an 412 application layer TLS session in order to generate and consume raw 413 TLS records. The application transports these raw TLS records inside 414 transport layer message bodies using whatever standard transport 415 layer stack is suitable for the application or architecture. This 416 document does not place any restrictions on the choice of transport 417 layer and any suitable protocol such as HTTP, TCP, CoAP, ZigBee, 418 Bluetooth, etc. could be used. 420 The transport layer will typically encrypt data, and this encryption 421 is completely independent from any application layer encryption. The 422 transport stack may create a transport layer TLS session. The 423 application layer TLS session and transport layer TLS session can 424 both leverage a shared, common TLS software stack. This high level 425 architecture is applicable to both clients and application services. 426 The key differences between the architectures are as follows. 428 In the model illustrated in Figure 5, the application sends all 429 sensitive data that needs to be securely exchanged with the peer 430 application through the Application TLS session in order to be 431 encrypted and decrypted. All sensitive application data is thus 432 encoded within TLS records by the TLS stack, and these TLS records 433 are transmitted over the transport layer. 435 +-------------+ 436 | | App 437 | | Data +---------+ 438 | Application |<---------->| App | +---------+ 439 | | TLS | TLS |----->| TLS | 440 | | Records | Session | | Stack | 441 | +--->|<---------->| | +---------+ 442 | | | +---------+ ^ 443 | | | |? 444 | | | Transport +-----------+ +------------+ 445 | | | Payload | Transport | | Transport | 446 | +--->|<--------->| Stack |--->| Encryption |-->Packets 447 +-------------+ +-----------+ +------------+ 449 Figure 5: TLS Stack used for all data encryption 451 In the model illustrated in Figure 6, the application establishes an 452 application layer TLS session purely for the purposes of key 453 exchange. Therefore, the only TLS records that are sent or received 454 by the application layer are TLS handshake records. Once the 455 application layer TLS session is established, the application uses 456 Keying Material Exporter [RFC5705] APIs to export keying material 457 from the TLS stack from this application layer TLS session. The 458 application can then use these exported keys to derive suitable 459 shared encryption keys with its peer for exchange of encrypted data. 460 The application encrypts and decrypts sensitive data using these 461 shared encryption keys using any suitable cryptographic library 462 (which may be part of the same library that provides the TLS stack), 463 and transports the encrypted data directly over the transport layer. 465 +--------------+ 466 | | 467 | Application | 468 | | 469 | +-------+ | +---------+ 470 | | App | | Key Export | | 471 | | Data |<---|<-----------| | 472 | | Crypto| | | App | 473 | +-------+ | TLS | TLS | +---------+ 474 | ^ | Handshake | Session |----->| TLS | 475 | | | Records | | | Stack | 476 | | +--->|<---------->| | +---------+ 477 | | | | +---------+ ^ 478 | | | | |? 479 | | | | Transport +-----------+ +------------+ 480 | | | | Payload | Transport | | Transport | 481 | +----+--->|<--------->| Stack |--->| Encryption |-->Packets 482 +--------------+ +-----------+ +------------+ 484 Figure 6: TLS stack used for key agreement and exporting 486 The choice of which application architecture to use will depend on 487 the overall solution architecture, and the underlying transport layer 488 or layers in use. While the choice of application architecture is 489 outside the scope of this document, some considerations are outlined 490 here. 492 o for constrained devices, every single byte of payload is 493 important. [I-D.mattsson-core-security-overhead] analyses the 494 overhead of TLS headers compared with OSCORE 495 [I-D.ietf-core-object-security] illustrating the additional 496 overhead associated with TLS headers. It may be more appropriate 497 to use the architecture defined in Figure 6 in order to establish 498 shared encryption keys, and then transport encrypted data directly 499 without the overhead of unwanted TLS record headers. 501 o when using HTTP as a transport layer, it may be more appropriate 502 to use the architecture defined in Figure 6 in order to avoid any 503 TLS session vs. HTTP session affinity issues. 505 6.1.1. Application Architecture Benefits 507 There are several benefits to using a standard TLS software stack to 508 establish an application layer secure communications channel between 509 a client and a service. These include: 511 o no need to define a new cryptographic negotiation and exchange 512 protocol between client and service 514 o automatically benefit from new cipher suites by simply upgrading 515 the TLS software stack 517 o automatically benefit from new features, bugfixes, etc. in TLS 518 software stack upgrades 520 6.1.2. ATLS Packet Identification 522 It is recommended that ATLS packets are explicitly identified by a 523 standardized, transport-specific identifier enabling any gateways and 524 middleboxes to identify ATLS packets. Middleboxes have to contend 525 with a vast number of applications and network operators have 526 difficulty configuring middleboxes to distinguish unencrypted but not 527 explicitly identified application data from end-to-end encrypted 528 data. This specification aims to assist network operators by 529 explicitly identifying ATLS packets. The HTTP and CoAP encodings 530 documented in Section 9 and Section 10 explicitly identify ATLS 531 packets. 533 6.1.3. ATLS Session Tracking 535 The ATLS application service establishes multiple ATLS sessions with 536 multiple clients. As TLS sessions are stateful, the application 537 service must be able to correlate ATLS records from different clients 538 across the relevant ATLS sessions. The details of how session 539 tracking is implemented are outside the scope of this document. 540 Recommendations are given in Section 9 and Section 10, but session 541 tracking is application and implementation specific. 543 6.1.4. ATLS Record Inspection 545 It should not be necessary for the application layer to have to 546 inspect, parse or understand the contents of ATLS records. No 547 constraints are placed on the ContentType contained within the 548 transported TLS records. The TLS records may contain handshake, 549 application_data, alert or change_cipher_spec messages. If new 550 ContentType messages are defined in future TLS versions, these may 551 also be transported using this protocol. 553 6.1.5. Implementation 555 Pseudo code illustrating how to read and write TLS records directly 556 from byte buffers using both OpenSSL BIO functions and Java JSSE 557 SSLEngine is given in the appendices. A blog post by [Norrell] 558 outlines a similar approach to leveraging OpenSSL BIO functions, and 559 Oracle publish example code for leveraging [SSLEngine]. 561 6.2. Functional Design 563 [ todo: insert Hannes functional design section here including the 564 policy layers ] 566 Policy examples: 568 Mention that the app layer policy could be to not do ATLS if the 569 transport layer establishes an e2e session with the peer. e.g. for 570 HTTP use cases where there is no middlebox and cert validation 571 passes. 573 Mention that the client could report in the ATLS session any 574 middlebox cert seen at the transport layer. 576 6.3. Network Architecture 578 An example network deployment is illustrated in Figure 7. It shows a 579 constrained client connecting to an application service via an 580 internet gateway. The client uses CoAP over DTLS to communicate with 581 the gateway. The gateway extracts the messages the client sent over 582 CoAP and sends these messages inside HTTP message bodies to the 583 application service. It also shows a TLS terminator deployed in 584 front of the application service. The client establishes a transport 585 layer CoAP/DTLS connection with the gateway (C->G DTLS), the gateway 586 in turn opens a transport layer TLS connection with the TLS 587 terminator deployed in front of the service (G->T TLS). The client 588 can ignore any certificate validation errors when it connects to the 589 gateway. CoAP messages are transported between the client and the 590 gateway, and HTTP messages are transported between the client and the 591 service. Finally, application layer TLS messages are exchanged 592 inside the CoAP and HTTP message bodies in order to establish an end- 593 to-end TLS session between the client and the service (C->S TLS). 595 +----------+ +----------+ 596 | App Data | | App Data | 597 +----------+ +----------+ +----------+ 598 | C->S TLS | | C->S TLS | | App Data | 599 +----------+ +----------+ +----------+ 600 | CoAP | | HTTP | | C->S TLS | 601 +----------+ +----------+ +----------+ 602 | C->G DTLS| | M->T TLS | | HTTP | 603 +----------+ +----------+ +----------+ 604 | UDP | | TCP | | TCP | 605 +----------+ +----------+ +----------+ 607 +--------+ +-----------+ +----------------+ +---------+ 608 | Client |----->| Gateway |----->| TLS Terminator |---->| Service | 609 +--------+ +-----------+ +----------------+ +---------+ 610 ^ ^ 611 | | 612 +-------------Client to Service ATLS Connection-------------+ 614 Figure 7: Constrained Device Gateway Network Architecture 616 Another typical network deployment is illustrated in Figure 8. It 617 shows a client connecting to a service via a middlebox. It also 618 shows a TLS terminator deployed in front of the service. The client 619 establishes a transport layer TLS connection with the middlebox (C->M 620 TLS), the middlebox in turn opens a transport layer TLS connection 621 with the TLS terminator deployed in front of the service (M->T TLS). 622 The client can ignore any certificate validation errors when it 623 connects to the middlebox. HTTP messages are transported over this 624 layer between the client and the service. Finally, application layer 625 TLS messages are exchanged inside the HTTP message bodies in order to 626 establish an end-to-end TLS session between the client and the 627 service (C->S TLS). 629 +----------+ +----------+ 630 | App Data | | App Data | 631 +----------+ +----------+ +----------+ 632 | C->S TLS | | C->S TLS | | App Data | 633 +----------+ +----------+ +----------+ 634 | HTTP | | HTTP | | C->S TLS | 635 +----------+ +----------+ +----------+ 636 | C->M TLS | | M->T TLS | | HTTP | 637 +----------+ +----------+ +----------+ 638 | TCP | | TCP | | TCP | 639 +----------+ +----------+ +----------+ 641 +--------+ +-----------+ +----------------+ +---------+ 642 | Client |----->| Middlebox |----->| TLS Terminator |---->| Service | 643 +--------+ +-----------+ +----------------+ +---------+ 644 ^ ^ 645 | | 646 +-------------Client to Service ATLS Connection-------------+ 648 Figure 8: HTTP Middlebox Network Architecture 650 7. Key Exporting and Application Data Encryption 652 When solutions implement the architecture described in Figure 6, they 653 leverage [RFC5705] for key exporting from the ATLS session. The 654 client and service then use the exported keys to derive shared 655 encryption keys. The encryption keys are then used with a suitable 656 cipher suite to encrypt application data for exchange with the peer. 658 7.1. Key Exporter Label 660 A new TLS Exporter Label is defined for ATLS key exporting. Its 661 value is: 663 TLS Exporter Label: application-layer-tls 665 7.2. Cipher Suite Selection 667 Application layer encryption performed outside the context of the 668 ATLS session using exported keys should use the cipher suite 669 negotiated during ATLS session establishment. 671 7.3. Key Derivation 673 [RFC5705] key exporting functions allow specification of the number 674 of bytes of keying material that should be exported from the TLS 675 session. The application should export the exact number of bytes 676 required to generate the necessary client and server cipher suite 677 encryption key and IV values. 679 [[TODO]] Maybe need to reference the relevant sections from 680 https://tools.ietf.org/html/draft-ietf-tls-tls13-23#section-7 and 681 https://tools.ietf.org/html/rfc5246#section-6.3. 683 8. ATLS Session Establishment 685 Figure 9 illustrates how an ATLS session is established using the key 686 exporting architectural model shown in Figure 6. The outline is as 687 follows: 689 o the client creates an ATLS session object 691 o the client initiates a TLS handshake on the session 693 o the client extracts the TLS records for the first TLS flight (the 694 first RTT) 696 o the client sends the TLS records over the transport layer to the 697 server 699 o on receipt of the TLS flight, the server creates an ATLS session 700 object 702 o the server injects the received TLS flight into the session 704 o the server extracts the TLS records for the first TLS flight 705 response 707 o the server sends the TLS response records over the transport layer 708 to the client 710 o the client injects the received TLS records into its TLS session 711 completing the first full RTT 713 o the client and server repeat the above process and complete the 714 second RTT 716 o once the ATLS session is up, both sides export keying material 718 o both sides now can exchange data encrypted using shared keys 719 derived from the keying material 721 +-------------------------------+ +-------------------------------+ 722 | Client | | ATLS Server | 723 +---------+---+-----+---+-------+ +-------+---+-----+---+---------+ 724 | ATLS | | App | |Transport| |Transport| | App | | ATLS | 725 | Session | +-----+ | Stack | | Stack | +-----+ | Session | 726 +---------+ | +---------+ +---------+ | +---------+ 727 | | | | | | 728 | | | | | | 729 | | | | | | 730 | Create | | | | | 731 | Session | | | | | 732 + |<---------| | | | | 733 | | Start | | | | | 734 | | Handshake| | | | | 735 | |<---------| | | | | 736 | | TLS | | | | | 737 | | Records | Pack | | | | 738 | |--------->| Records | | | | 739 | |-------->| send packet | Unpack | | 740 R | | |------------>| Records | Create | 741 T | | | |--------->| Session | 742 T | | | | |--------->| 743 | | | | | TLS | 744 1 | | | | | Records | 745 | | | | |--------->| 746 | | | | | | TLS | 747 | | | | | Pack | Records | 748 | | | | | Records |<---------| 749 | | | Unpack |send response|<---------| | 750 | | TLS | Records |<------------| | | 751 | | Records |<--------| | | | 752 + |<---------| | | | | 753 | TLS | | | | | 754 | Records | | | | | 755 + |--------->|-------->|------------>|--------->|--------->| 756 | | | | | | | 757 | | | | | Session | 758 R | | | | | Up | 759 T | | | | |<---------| 760 T | | | | | TLS | 761 | | | | | Records | 762 2 |<---------|<--------|<------------|<---------|<---------| 763 | Session | | | | | 764 | | Up | | | | | 765 + |--------->| | | | | 766 | Export | | | | Export | 767 | Keys | | | | Keys | 768 |--------->| | E2E Session | |<---------| 769 | |<--------|-------------|--------->| | 771 Figure 9: ATLS Session Establishment 773 9. ATLS over HTTP Transport 775 The assumption is that the client will establish a transport layer 776 connection to the server for exchange of HTTP messages. The 777 underlying transport layer connection could be over TCP or TLS. The 778 client will then establish an application layer TLS connection with 779 the server by exchanging TLS records with the server inside HTTP 780 message request and response bodies. 782 9.1. Protocol Summary 784 All ATLS records are transported unmodified as binary data within 785 HTTP message bodies. The application simply extracts the TLS records 786 from the TLS stack and inserts them directly into HTTP message 787 bodies. Each message body contains a full TLS flight, which may 788 contain multiple TLS records. 790 The client sends all ATLS records to the server in the bodies of POST 791 requests. 793 The server sends all ATLS records to the client in the bodies of 200 794 OK responses to the POST requests. 796 9.2. Content-Type Header 798 A new Content-Type header value is defined: 800 Content-type: application/atls+octet-stream 802 All message bodies containing ATLS records must set this Content- 803 Type. This enables middleboxes to readily identify ATLS payloads. 805 9.3. HTTP Status Codes 807 This document does not define any new HTTP status codes, and does not 808 specify additional semantics or refine existing semantics for status 809 codes. This is the best current practice as outlined in 810 [I-D.ietf-httpbis-bcp56bis]. 812 9.4. ATLS Session Tracking 814 The application service needs to track multiple client application 815 layer TLS sessions so that it can correlate TLS records received in 816 HTTP message bodies with the appropriate TLS session. The 817 application service should use stateful cookies [RFC6265] in order to 818 achieve this as recommended in [I-D.ietf-httpbis-bcp56bis]. 820 9.5. Session Establishment and Key Exporting 822 It is recommended that applications using ATLS over HTTP transport 823 only use ATLS for session establishment and key exchange, resulting 824 in only 2 ATLS RTTs between the client and the application service. 826 Key exporting must be carried out as described in Section 7.3. 828 9.6. Application Data Encryption 830 [editors note: I am on the fence about using [RFC8188] as this 831 hardcodes the ciphersuite to aes128gcm. It would be nice to use the 832 cipher suite negotiated as part of ATLS session establishment. ] 834 9.7. Illustrative ATLS over HTTP Session Establishment 836 A client initiates an ATLS session by sending the first TLS flight in 837 a POST request message body to the ATLS server. 839 POST /atls 840 Content-Type: application/atls+octet-stream 842 844 The server handles the request, creates an ATLS session object, and 845 replies by including its first TLS flight in a 200 OK message body. 846 The server also sets a suitable cookie for session tracking purposes. 848 200 OK 849 Content-Type: application/atls+octet-stream 850 Set-Cookie: my-atls-cookie=my-cookie-value 852 854 The client handles the server first flight TLS records and replies 855 with its second flight. 857 POST /atls 858 Content-Type: application/atls+octet-stream 859 Cookie: my-atls-cookie=my-cookie-value 861 863 The server handles the second flight, establishes the ATLS session, 864 and replies with its second flight. 866 200 OK 867 Content-Type: application/atls+octet-stream 869 871 9.8. ATLS and HTTP CONNECT 873 It is worthwhile comparing and contrasting ATLS with HTTP CONNECT 874 tunneling. 876 First, let us introduce some terminology: 878 o HTTP Proxy: A HTTP Proxy operates at the application layer, 879 handles HTTP CONNECT messages from clients, and opens tunnels to 880 remote origin servers on behalf of clients. If a client 881 establishes a tunneled TLS connection to the origin server, the 882 HTTP Proxy does not attempt to intercept or inspect the HTTP 883 messages exchanged between the client and the server 885 o middlebox: A middlebox operates at the transport layer, terminates 886 TLS connections from clients, and originates new TLS connections 887 to services. A middlebox inspects all messages sent between 888 clients and services. Middleboxes are generally completely 889 transparent to applications, provided that the necessary PKI root 890 Certificate Authority is installed in the client's trust store. 892 HTTP Proxies and middleboxes are logically separate entities and one 893 or both of these may be deployed in a network. 895 HTTP CONNECT is used by clients to instruct a HTTP Forward Proxy 896 deployed in the local domain to open up a tunnel to a remote origin 897 server that is typically deployed in a different domain. Assuming 898 that TLS transport is used between both client and proxy, and proxy 899 and origin server, the network architecture is as illustrated in 900 Figure 10. Once the proxy opens the transport tunnel to the service, 901 the client establishes an end-to-end TLS session with the service, 902 and the proxy is blindly transporting TLS records (the C->S TLS 903 session records) between the client and the service. From the client 904 perspective, it is tunneling a TLS session to the service inside the 905 TLS session it has established to the proxy (the C->P TLS session). 906 No middlebox is attempting to intercept or inspect the HTTP messages 907 between the client and the service. 909 +----------+ +----------+ 910 | C->S HTTP| | C->S HTTP| 911 +----------+ +----------+ 912 | C->S TLS | | C->S TLS | 913 +----------+ +----------+ 914 | C->P TLS | | P->S TCP | 915 +----------+ +----------+ 916 | C->P TCP | 917 +----------+ 919 +--------+ +------------+ +---------+ 920 | Client |----->| HTTP Proxy |----->| Service | 921 +--------+ +------------+ +---------+ 923 Figure 10: HTTP Proxy transport layers 925 A more complex network topology where the network operator has both a 926 HTTP Proxy and a middlebox deployed is illustrated in Figure 11. In 927 this scenario, the proxy has tunneled the TLS session from the client 928 towards the origin server, however the middlebox is intercepting and 929 terminating this TLS session. A TLS session is established between 930 the client and the middlebox (C->M TLS), and not end-to-end between 931 the client and the server. It can clearly be seen that HTTP CONNECT 932 and HTTP Proxies serve completely different functions than 933 middleboxes. 935 Additionally, the fact that the TLS session is established between 936 the client and the middlebox can be problematic for two reasons: 938 o the middle box is inspecting traffic that is sent between the 939 client and the service 941 o the client may not have the necessary PKI root Certificate 942 Authority installed that would enable it to validate the TLS 943 connection to the middlebox. This is the scenario outlined in 944 Section 3.1. 946 +----------+ +----------+ +----------+ 947 | C->S HTTP| | C->S HTTP| | C->S HTTP| 948 +----------+ +----------+ +----------+ 949 | C->M TLS | | C->M TLS | | M->S TLS | 950 +----------+ +----------+ +----------+ 951 | C->P TLS | | P->M TCP | | M->S TCP | 952 +----------+ +----------+ +----------+ 953 | C->P TCP | 954 +----------+ 956 +--------+ +------------+ +-----------+ +---------+ 957 | Client |----->| HTTP Proxy |----->| Middlebox |----->| Service | 958 +--------+ +------------+ +-----------+ +---------+ 960 Figure 11: HTTP Proxy and middlebox transport layers 962 As HTTP CONNECT can be used to establish a tunneled TLS connection, 963 one hypothetical solution to this middlebox issue is for the client 964 to issue a HTTP CONNECT command to a HTTP Reverse Proxy deployed in 965 front of the origin server. This solution is not practical for 966 several reasons: 968 o if there is a local domain HTTP Forward Proxy deployed, this would 969 result in the client doing a first HTTP CONNECT to get past the 970 Forward Proxy, and then a second HTTP CONNECT to get past the 971 Reverse Proxy. No client or client library supports the concept 972 of HTTP CONNECT inside HTTP CONNECT. 974 o if there is no local domain HTTP Proxy deployed, the client still 975 has to do a HTTP CONNECT to the HTTP Reverse Proxy. This breaks 976 with standard and expected HTTP CONNECT operation, as HTTP CONNECT 977 is only ever called if there is a local domain proxy. 979 o clients cannot generate CONNECT from XHR in web applications. 981 o this would require the deployment of a Reverse Proxy in front of 982 the origin server, or else support of the HTTP CONNECT method in 983 standard web frameworks. This is not an elegant design. 985 o using HTTP CONNECT with HTTP 1.1 to a Reverse Proxy will break 986 middleboxes inspecting HTTP traffic, as the middlebox would see 987 TLS records when it expects to see HTTP payloads. 989 In contrast to trying to force HTTP CONNECT to address a problem for 990 which it was not designed to address, and having to address all the 991 issues just outlined; ATLS is specifically designed to address the 992 middlebox issue in a simple, easy to develop, and easy to deploy 993 fashion. 995 o ATLS works seamlessly with HTTP Proxy deployments 997 o no changes are required to HTTP CONNECT semantics 999 o no changes are required to HTTP libraries or stacks 1001 o no additional Reverse Proxy is required to be deployed in front of 1002 origin servers 1004 It is also worth noting that if HTTP CONNECT to a Reverse Proxy were 1005 a conceptually sound solution, the solution still ultimately results 1006 in encrypted traffic traversing the middlebox that the middlebox 1007 cannot intercept and inspect. That is ultimately what ATLS results 1008 in - traffic traversing the middle box that the middlebox cannot 1009 intercept and inspect. Therefore, from a middlebox perspective, the 1010 differences between the two solutions are in the areas of solution 1011 complexity and protocol semantics. It is clear that ATLS is a 1012 simpler, more elegant solution that HTTP CONNECT. 1014 10. ATLS over CoAP Transport 1016 [ todo: Help needed Hannes ] 1018 11. RTT Considerations 1020 The number of RTTs that take place when establishing a TLS session 1021 depends on the version of TLS and what capabilities are enabled on 1022 the TLS software stack. For example, a 0-RTT exchange is possible 1023 with TLS1.3. 1025 If applications wish to ensure a predictable number of RTTs when 1026 establishing an application layer TLS connection, this may be 1027 achieved by configuring the TLS software stack appropriately. 1028 Relevant configuration parameters for OpenSSL and Java SunJSSE stacks 1029 are outlined in the appendix. 1031 12. IANA Considerations 1033 [[ TODO - New Content-Type and TLS Exporter Label must be registered. 1034 ]] 1036 13. Security Considerations 1038 [[ TODO ]] 1040 14. Informative References 1042 [ALTS] Google, "Application Layer Transport Security", December 1043 2017, . 1046 [Bluetooth] 1047 Bluetooth, "Bluetooth Core Specification v5.0", 2016, 1048 . 1050 [I-D.hartke-core-e2e-security-reqs] 1051 Selander, G., Palombini, F., and K. Hartke, "Requirements 1052 for CoAP End-To-End Security", draft-hartke-core-e2e- 1053 security-reqs-03 (work in progress), July 2017. 1055 [I-D.ietf-anima-bootstrapping-keyinfra] 1056 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 1057 S., and K. Watsen, "Bootstrapping Remote Secure Key 1058 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 1059 keyinfra-16 (work in progress), June 2018. 1061 [I-D.ietf-core-object-security] 1062 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1063 "Object Security for Constrained RESTful Environments 1064 (OSCORE)", draft-ietf-core-object-security-14 (work in 1065 progress), July 2018. 1067 [I-D.ietf-httpbis-bcp56bis] 1068 Nottingham, M., "Building Protocols with HTTP", draft- 1069 ietf-httpbis-bcp56bis-06 (work in progress), July 2018. 1071 [I-D.ietf-tls-dtls13] 1072 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 1073 Datagram Transport Layer Security (DTLS) Protocol Version 1074 1.3", draft-ietf-tls-dtls13-28 (work in progress), July 1075 2018. 1077 [I-D.ietf-tls-tls13] 1078 Rescorla, E., "The Transport Layer Security (TLS) Protocol 1079 Version 1.3", draft-ietf-tls-tls13-28 (work in progress), 1080 March 2018. 1082 [I-D.mattsson-core-security-overhead] 1083 Mattsson, J., "Message Size Overhead of CoAP Security 1084 Protocols", draft-mattsson-core-security-overhead-02 (work 1085 in progress), November 2017. 1087 [I-D.selander-ace-cose-ecdhe] 1088 Selander, G., Mattsson, J., and F. Palombini, "Ephemeral 1089 Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- 1090 cose-ecdhe-09 (work in progress), July 2018. 1092 [LwM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1093 Requirements", December 2017, 1094 . 1096 [Noise] Perrin, T., "Noise Protocol Framework", October 2017, 1097 . 1099 [Norrell] Norrell, ., "Use SSL/TLS within a different protocol with 1100 BIO pairs", 2016, 1101 . 1104 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1105 (TLS) Protocol Version 1.2", RFC 5246, 1106 DOI 10.17487/RFC5246, August 2008, 1107 . 1109 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 1110 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 1111 March 2010, . 1113 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1114 DOI 10.17487/RFC6265, April 2011, 1115 . 1117 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1118 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1119 January 2012, . 1121 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1122 Protocol (HTTP/1.1): Message Syntax and Routing", 1123 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1124 . 1126 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1127 Application Protocol (CoAP)", RFC 7252, 1128 DOI 10.17487/RFC7252, June 2014, 1129 . 1131 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1132 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1133 DOI 10.17487/RFC7540, May 2015, 1134 . 1136 [RFC8188] Thomson, M., "Encrypted Content-Encoding for HTTP", 1137 RFC 8188, DOI 10.17487/RFC8188, June 2017, 1138 . 1140 [Signal] Open Whisper Systems, "Signal Protocol", 2016, 1141 . 1143 [SSLEngine] 1144 Oracle, "SSLEngineSimpleDemo.java", 2004, . 1148 [ZigBee] ZigBee Alliance, "ZigBee Specification", 2012, 1149 . 1151 Appendix A. TLS Software Stack Configuration 1153 [[ EDITOR'S NOTE: We could include details here on how TLS stack 1154 configuration items control the number of round trips between the 1155 client and server. 1156 And just give two examples: OpenSSL and Java SunJSSE]] 1158 Appendix B. Pseudo Code 1160 This appendix gives both C and Java pseudo code illustrating how to 1161 inject and extract raw TLS records from a TLS software stack. Please 1162 not that this is illustrative, non-functional pseudo code that does 1163 not compile. Functioning proof-of-concept code is available on the 1164 following public repository [[ EDITOR'S NOTE: Add the URL here ]]. 1166 B.1. OpenSSL 1168 OpenSSL provides a set of Basic Input/Output (BIO) APIs that can be 1169 used to build a custom transport layer for TLS connections. This 1170 appendix gives pseudo code on how BIO APIs could be used to build a 1171 client application that completes a TLS handshake and exchanges 1172 application data with a service. 1174 char inbound[MAX]; 1175 char outbound[MAX]; 1176 int rx_bytes; 1177 SSL_CTX *ctx = SSL_CTX_new(); 1178 SSL *ssl = SSL_new(ctx); 1180 // Create in-memory BIOs and plug in to the SSL session 1181 BOI* bio_in = BIO_new(BIO_s_mem()); 1182 BOI* bio_out = BIO_new(BIO_s_mem()); 1183 SSL_set_bio(ssl, bio_in, bio_out); 1185 // We are a client 1186 SSL_set_connect_state(ssl); 1188 // Loop through TLS flights until we are done 1189 do { 1190 // Calling SSL_do_handshake() will result in a full 1191 // TLS flight being written to the BIO buffer 1192 SSL_do_handshake(ssl); 1194 // Read the client flight that the TLS session 1195 // has written to memory 1196 BIO_read(bio_out, outbound, MAX); 1198 // POST the outbound bytes to the server using a suitable 1199 // function. Lets assume that the server response will be 1200 // written to the 'inbound' buffer 1201 num_bytes = postTlsRecords(outbound, inbound); 1203 // Write the server flight to the memory BIO so the TLS session 1204 // can read it. The next call to SSL_do_handshake() will handle 1205 // this received server flight 1206 BIO_write(bio_in, inbound, num_bytes); 1208 } while (!SSL_is_init_finished(ssl)); 1210 // Send a message to the server. Calling SSL_write() will run the 1211 // plaintext through the TLS session and write the encrypted TLS 1212 // records to the BIO buffer 1213 SSL_write(ssl, "Hello World", strlen("Hello World")); 1215 // Read the TLS records from the BIO buffer and 1216 // POST them to the server 1217 BIO_read(bio_out, outbound, MAX); 1218 num_bytes = postTlsRecords(outbound, inbound); 1220 B.2. Java JSSE 1222 The Java SSLEngine class "enables secure communications using 1223 protocols such as the Secure Sockets Layer (SSL) or IETF RFC 2246 1224 "Transport Layer Security" (TLS) protocols, but is transport 1225 independent". This pseudo code illustrates how a server could use 1226 the SSLEngine class to handle an inbound client TLS flight and 1227 generate an outbound server TLS flight response. 1229 SSLEngine sslEngine = SSLContext.getDefault().createSSLEngine(); 1230 sslEngine.setUseClientMode(false); 1231 sslEngine.beginHandshake(); 1233 // Lets assume 'inbound' has been populated with 1234 // the Client 1st Flight 1235 ByteBuffer inbound; 1237 // 'outbound' will be populated with the 1238 // Server 1st Flight response 1239 ByteBuffer outbound; 1241 // SSLEngine handles one TLS Record per call to unwrap(). 1242 // Loop until the engine is finished unwrapping. 1243 while (sslEngine.getHandshakeStatus() == 1244 HandshakeStatus.NEED_UNWRAP) { 1245 SSLEngineResult res = sslEngine.unwrap(inbound, outbound); 1247 // SSLEngine may need additional tasks run 1248 if (res.getHandshakeStatus() == NEED_TASK) { 1249 Runnable run = sslEngine.getDelegatedTask(); 1250 run.run(); 1251 } 1252 } 1254 // The SSLEngine has now finished handling all inbound TLS Records. 1255 // Check if it wants to generate outbound TLS Records. SSLEngine 1256 // generates one TLS Record per call to wrap(). 1257 // Loop until the engine is finished wrapping. 1258 while (sslEngine.getHandshakeStatus() == 1259 HandshakeStatus.NEED_WRAP) { 1260 SSLEngineResult res = sslEngine.wrap(inbound, outbound); 1262 // SSLEngine may need additional tasks run 1263 if (res.getHandshakeStatus() == NEED_TASK) { 1264 Runnable run = sslEngine.getDelegatedTask(); 1265 run.run(); 1266 } 1267 } 1269 // outbound ByteBuffer now contains a complete server flight 1270 // containing multiple TLS Records 1271 // Rinse and repeat! 1273 Appendix C. Example ATLS Handshake 1275 [[ EDITOR'S NOTE: For completeness, include a simple full TLS 1276 handshake showing the raw binary flights, along with the HTTP 1277 request/response/headers. And also the raw hex TLS records showing 1278 protocol bits ]] 1280 Authors' Addresses 1282 Owen Friel 1283 Cisco 1285 Email: ofriel@cisco.com 1287 Richard Barnes 1288 Cisco 1290 Email: rlb@ipv.sx 1292 Max Pritikin 1293 Cisco 1295 Email: pritikin@cisco.com 1297 Hannes Tschofenig 1298 ARM Limited 1300 Email: hannes.tschofenig@gmx.net 1302 Mark Baugher 1303 Consultant 1305 Email: mark@mbaugher.com