< draft-friel-tls-atls-00.txt		draft-friel-tls-atls-01.txt >
	Network Working Group O. Friel		Network Working Group O. Friel
	Internet-Draft R. Barnes		Internet-Draft R. Barnes
	Intended status: Standards Track M. Pritikin		Intended status: Standards Track M. Pritikin
	Expires: August 4, 2018 Cisco		Expires: February 1, 2019 Cisco
	H. Tschofenig		H. Tschofenig
	ARM Limited		ARM Limited
	M. Baugher		M. Baugher
	Consultant		Consultant
	January 31, 2018		July 31, 2018
	Application-Layer TLS (ATLS)		Application-Layer TLS
	draft-friel-tls-atls-00		draft-friel-tls-atls-01
	Abstract		Abstract
	This document specifies how TLS sessions can be established at the		This document specifies how TLS sessions can be established at the
	application layer over untrusted transport between clients and		application layer over untrusted transport between clients and
	services for the purposes of establishing secure end-to-end encrypted		services for the purposes of establishing secure end-to-end encrypted
	communications channels. Transport layer encodings for application		communications channels. Transport layer encodings for application
	layer TLS records are specified for HTTP and CoAP transport.		layer TLS records are specified for HTTP and CoAP transport.
	Explicit identification of application layer TLS packets enables		Explicit identification of application layer TLS packets enables
	middleboxes to provide transport services and enforce suitable		middleboxes to provide transport services and enforce suitable
	skipping to change at page 1, line 42 ¶		skipping to change at page 1, line 42 ¶
	outlined.		outlined.
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at http://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on August 4, 2018.		This Internet-Draft will expire on February 1, 2019.
	Copyright Notice		Copyright Notice
	Copyright (c) 2018 IETF Trust and the persons identified as the		Copyright (c) 2018 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents		Provisions Relating to IETF Documents
	(http://trustee.ietf.org/license-info) in effect on the date of		(https://trustee.ietf.org/license-info) in effect on the date of
	publication of this document. Please review these documents		publication of this document. Please review these documents
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Simplified BSD License text as described in Section 4.e of		include Simplified BSD License text as described in Section 4.e of
	the Trust Legal Provisions and are provided without warranty as		the Trust Legal Provisions and are provided without warranty as
	described in the Simplified BSD License.		described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. Application Layer End-to-End Security Use Cases . . . . . . . 4		3. Application Layer End-to-End Security Use Cases . . . . . . . 4
	3.1. Bootstrapping Devices . . . . . . . . . . . . . . . . . . 4		3.1. Bootstrapping Devices . . . . . . . . . . . . . . . . . . 4
	3.2. Constrained Devices . . . . . . . . . . . . . . . . . . . 5		3.2. Constrained Devices . . . . . . . . . . . . . . . . . . . 5
	3.2.1. Constrained Device Connecting over a Closed Network . 5		3.2.1. Constrained Device Connecting over a Closed Network . 5
	3.2.2. Constrained Device Connecting over the Internet . . . 6		3.2.2. Constrained Device Connecting over the Internet . . . 6
	4. Current Approaches to Application Layer End-to-End Security 7		4. Current Approaches to Application Layer End-to-End Security . 7
	4.1. Noise . . . . . . . . . . . . . . . . . . . . . . . . . . 7		4.1. Noise . . . . . . . . . . . . . . . . . . . . . . . . . . 7
	4.2. Signal . . . . . . . . . . . . . . . . . . . . . . . . . 7		4.2. Signal . . . . . . . . . . . . . . . . . . . . . . . . . 7
	4.3. Google ALTS . . . . . . . . . . . . . . . . . . . . . . . 8		4.3. Google ALTS . . . . . . . . . . . . . . . . . . . . . . . 7
	4.4. Ephemeral Diffie-Hellman Over COSE . . . . . . . . . . . 8		4.4. Ephemeral Diffie-Hellman Over COSE . . . . . . . . . . . 8
	5. ATLS Goals . . . . . . . . . . . . . . . . . . . . . . . . . 8		5. ATLS Goals . . . . . . . . . . . . . . . . . . . . . . . . . 8
	6. Architecture Overview . . . . . . . . . . . . . . . . . . . . 9		6. Architecture Overview . . . . . . . . . . . . . . . . . . . . 8
	6.1. Application Architecture . . . . . . . . . . . . . . . . 9		6.1. Application Architecture . . . . . . . . . . . . . . . . 8
	6.1.1. Application Architecture Benefits . . . . . . . . . . 11		6.1.1. Application Architecture Benefits . . . . . . . . . . 11
	6.1.2. ATLS Packet Identification . . . . . . . . . . . . . 12		6.1.2. ATLS Packet Identification . . . . . . . . . . . . . 12
	6.1.3. ATLS Session Tracking . . . . . . . . . . . . . . . . 12		6.1.3. ATLS Session Tracking . . . . . . . . . . . . . . . . 12
	6.1.4. ATLS Record Inspection . . . . . . . . . . . . . . . 12		6.1.4. ATLS Record Inspection . . . . . . . . . . . . . . . 12
	6.1.5. Implementation . . . . . . . . . . . . . . . . . . . 12		6.1.5. Implementation . . . . . . . . . . . . . . . . . . . 12
	6.2. Functional Design . . . . . . . . . . . . . . . . . . . . 13		6.2. Functional Design . . . . . . . . . . . . . . . . . . . . 13
	6.3. Network Architecture . . . . . . . . . . . . . . . . . . 13		6.3. Network Architecture . . . . . . . . . . . . . . . . . . 13
	7. Key Exporting and Application Data Encryption . . . . . . . . 15		7. Key Exporting and Application Data Encryption . . . . . . . . 15
	7.1. Key Exporter Label . . . . . . . . . . . . . . . . . . . 15		7.1. Key Exporter Label . . . . . . . . . . . . . . . . . . . 15
	7.2. Cipher Suite Selection . . . . . . . . . . . . . . . . . 15		7.2. Cipher Suite Selection . . . . . . . . . . . . . . . . . 15
	skipping to change at page 3, line 13 ¶		skipping to change at page 3, line 13 ¶
	9.3. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 18		9.3. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 18
	9.4. ATLS Session Tracking . . . . . . . . . . . . . . . . . . 18		9.4. ATLS Session Tracking . . . . . . . . . . . . . . . . . . 18
	9.5. Session Establishment and Key Exporting . . . . . . . . . 19		9.5. Session Establishment and Key Exporting . . . . . . . . . 19
	9.6. Application Data Encryption . . . . . . . . . . . . . . . 19		9.6. Application Data Encryption . . . . . . . . . . . . . . . 19
	9.7. Illustrative ATLS over HTTP Session Establishment . . . . 19		9.7. Illustrative ATLS over HTTP Session Establishment . . . . 19
	9.8. ATLS and HTTP CONNECT . . . . . . . . . . . . . . . . . . 20		9.8. ATLS and HTTP CONNECT . . . . . . . . . . . . . . . . . . 20
	10. ATLS over CoAP Transport . . . . . . . . . . . . . . . . . . 23		10. ATLS over CoAP Transport . . . . . . . . . . . . . . . . . . 23
	11. RTT Considerations . . . . . . . . . . . . . . . . . . . . . 23		11. RTT Considerations . . . . . . . . . . . . . . . . . . . . . 23
	12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23		12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
	13. Security Considerations . . . . . . . . . . . . . . . . . . . 23		13. Security Considerations . . . . . . . . . . . . . . . . . . . 23
	14. Appendix A. TLS Software Stack Configuration . . . . . . . . 24		14. Informative References . . . . . . . . . . . . . . . . . . . 24
	15. Appendix B. Pseudo Code . . . . . . . . . . . . . . . . . . . 24		Appendix A. TLS Software Stack Configuration . . . . . . . . . . 26
	15.1. B.1 OpenSSL . . . . . . . . . . . . . . . . . . . . . . 24		Appendix B. Pseudo Code . . . . . . . . . . . . . . . . . . . . 26
	15.2. B.2 Java JSSE . . . . . . . . . . . . . . . . . . . . . 26		B.1. OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . 26
	16. Appendix C. Example ATLS Handshake . . . . . . . . . . . . . 28		B.2. Java JSSE . . . . . . . . . . . . . . . . . . . . . . . . 28
	17. Informative References . . . . . . . . . . . . . . . . . . . 28		Appendix C. Example ATLS Handshake . . . . . . . . . . . . . . . 30
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30
	1. Introduction		1. Introduction
	There are multiple scenarios where there is a need for application		There are multiple scenarios where there is a need for application
	layer end-to-end security between clients and application services.		layer end-to-end security between clients and application services.
	Two examples include:		Two examples include:
	o Bootstrapping devices that must connect to HTTP application		o Bootstrapping devices that must connect to HTTP application
	services across untrusted TLS interception middleboxes		services across untrusted TLS interception middleboxes
	skipping to change at page 4, line 50 ¶		skipping to change at page 4, line 50 ¶
	3. Application Layer End-to-End Security Use Cases		3. Application Layer End-to-End Security Use Cases
	This section describes in more detail the bootstrapping and		This section describes in more detail the bootstrapping and
	constrained device use cases mentioned in the introduction.		constrained device use cases mentioned in the introduction.
	3.1. Bootstrapping Devices		3.1. Bootstrapping Devices
	There are far more classes of clients being deployed on today's		There are far more classes of clients being deployed on today's
	networks than at any time previously. This poses challenges for		networks than at any time previously. This poses challenges for
	network administrators who need to mange their network and the		network administrators who need to manage their network and the
	clients connecting to their network, and poses challenges for client		clients connecting to their network, and poses challenges for client
	vendors and client software developers who must ensure that their		vendors and client software developers who must ensure that their
	clients can connect to all required services.		clients can connect to all required services.
	One common example is where a client is deployed on a local domain		One common example is where a client is deployed on a local domain
	TCP/IP network that protects its perimeter using a TLS terminating		TCP/IP network that protects its perimeter using a TLS terminating
	middlebox, and the client needs to establish a secure connection to a		middlebox, and the client needs to establish a secure connection to a
	service in a different network via the middlebox. This is		service in a different network via the middlebox. This is
	illustrated in Figure 1.		illustrated in Figure 1.
	Traditionally, this has been enabled by the network administrator		Traditionally, this has been enabled by the network administrator
	deploying the necessary certificate authority trusted roots on the		deploying the necessary certificate authority trusted roots on the
	client. This can be achieved at scale using standard tools that		client. This can be achieved at scale using standard tools that
	enable the administrator to automatically push trusted roots out to		enable the administrator to automatically push trusted roots out to
	all client machines in the network from a centralized domain		all client machines in the network from a centralized domain
	controller. This works for for personal computers, laptops and		controller. This works for personal computers, laptops and servers
	servers running standard Operating Systems that can be centrally		running standard Operating Systems that can be centrally managed.
	managed. This client management process breaks for multiple classes		This client management process breaks for multiple classes of clients
	of clients that are being deployed today, there is no standard		that are being deployed today, there is no standard mechanism for
	mechanism for configuring trusted roots on these clients, and there		configuring trusted roots on these clients, and there is no standard
	is no standard mechanism for these clients to securely traverse		mechanism for these clients to securely traverse middleboxes.
	middleboxes.
	+--------+ C->M TLS +-----------+ M->S TLS +---------+		+--------+ C->M TLS +-----------+ M->S TLS +---------+
	| Client |--------------->| Middlebox |------------->| Service |		| Client |--------------->| Middlebox |------------->| Service |
	+--------+ +-----------+ +---------+		+--------+ +-----------+ +---------+
	^ ^		^ ^
	| |		| |
	+-----------Client to Service ATLS Connection---------+		+-----------Client to Service ATLS Connection---------+
	Figure 1: Bootstrapping Devices		Figure 1: Bootstrapping Devices
	skipping to change at page 12, line 20 ¶		skipping to change at page 12, line 20 ¶
	6.1.2. ATLS Packet Identification		6.1.2. ATLS Packet Identification
	It is recommended that ATLS packets are explicitly identified by a		It is recommended that ATLS packets are explicitly identified by a
	standardized, transport-specific identifier enabling any gateways and		standardized, transport-specific identifier enabling any gateways and
	middleboxes to identify ATLS packets. Middleboxes have to contend		middleboxes to identify ATLS packets. Middleboxes have to contend
	with a vast number of applications and network operators have		with a vast number of applications and network operators have
	difficulty configuring middleboxes to distinguish unencrypted but not		difficulty configuring middleboxes to distinguish unencrypted but not
	explicitly identified application data from end-to-end encrypted		explicitly identified application data from end-to-end encrypted
	data. This specification aims to assist network operators by		data. This specification aims to assist network operators by
	explicitly identifyng ATLS packets. The HTTP and CoAP encodings		explicitly identifying ATLS packets. The HTTP and CoAP encodings
	documented in Section 9 and Section 10 explicitly identify ATLS		documented in Section 9 and Section 10 explicitly identify ATLS
	packets.		packets.
	6.1.3. ATLS Session Tracking		6.1.3. ATLS Session Tracking
	The ATLS application service establishes multiple ATLS sessions with		The ATLS application service establishes multiple ATLS sessions with
	multiple clients. As TLS sessions are stateful, the application		multiple clients. As TLS sessions are stateful, the application
	service must be able to correlate ATLS records from different clients		service must be able to correlate ATLS records from different clients
	across the relevant ATLS sessions. The details of how session		across the relevant ATLS sessions. The details of how session
	tracking is implemented are outside the scope of this document.		tracking is implemented are outside the scope of this document.
	skipping to change at page 16, line 7 ¶		skipping to change at page 16, line 7 ¶
	negotiated during ATLS session establishment.		negotiated during ATLS session establishment.
	7.3. Key Derivation		7.3. Key Derivation
	[RFC5705] key exporting functions allow specification of the number		[RFC5705] key exporting functions allow specification of the number
	of bytes of keying material that should be exported from the TLS		of bytes of keying material that should be exported from the TLS
	session. The application should export the exact number of bytes		session. The application should export the exact number of bytes
	required to generate the necessary client and server cipher suite		required to generate the necessary client and server cipher suite
	encryption key and IV values.		encryption key and IV values.
	Maybe need to reference the relevant sections from		[[TODO]] Maybe need to reference the relevant sections from
	https://tools.ietf.org/html/draft-ietf-tls-tls13-23#section-7 and		https://tools.ietf.org/html/draft-ietf-tls-tls13-23#section-7 and
	https://tools.ietf.org/html/rfc5246#section-6.3.		https://tools.ietf.org/html/rfc5246#section-6.3.
	8. ATLS Session Establishment		8. ATLS Session Establishment
	Figure 9 illustrates how an ATLS session is established using the key		Figure 9 illustrates how an ATLS session is established using the key
	exporting architectural model shown in Figure 6. The outline is as		exporting architectural model shown in Figure 6. The outline is as
	follows:		follows:
	o the client creates an ATLS session object		o the client creates an ATLS session object
	skipping to change at page 18, line 39 ¶		skipping to change at page 18, line 39 ¶
	A new Content-Type header value is defined:		A new Content-Type header value is defined:
	Content-type: application/atls+octet-stream		Content-type: application/atls+octet-stream
	All message bodies containing ATLS records must set this Content-		All message bodies containing ATLS records must set this Content-
	Type. This enables middleboxes to readily identify ATLS payloads.		Type. This enables middleboxes to readily identify ATLS payloads.
	9.3. HTTP Status Codes		9.3. HTTP Status Codes
	Thsi document does not define any new HTTP status codes, and does not		This document does not define any new HTTP status codes, and does not
	specify additional semantics or refine existing semantics for status		specify additional semantics or refine existing semantics for status
	codes. This is the best current practice as outlined in		codes. This is the best current practice as outlined in
	[I-D.ietf-httpbis-bcp56bis].		[I-D.ietf-httpbis-bcp56bis].
	9.4. ATLS Session Tracking		9.4. ATLS Session Tracking
	The application service needs to track multiple client application		The application service needs to track multiple client application
	layer TLS sessions so that it can collerate TLS records received in		layer TLS sessions so that it can correlate TLS records received in
	HTTP message bodies with the appropriate TLS session. The		HTTP message bodies with the appropriate TLS session. The
	application service should use stateful cookies [RFC6265] in order to		application service should use stateful cookies [RFC6265] in order to
	achieve this as recommended in [I-D.ietf-httpbis-bcp56bis].		achieve this as recommended in [I-D.ietf-httpbis-bcp56bis].
	9.5. Session Establishment and Key Exporting		9.5. Session Establishment and Key Exporting
	It is recommended that applications using ATLS over HTTP transport		It is recommended that applications using ATLS over HTTP transport
	only use ATLS for session establishment and key exchange, resulting		only use ATLS for session establishment and key exchange, resulting
	in only 2 ATLS RTTs between the client and the application service.		in only 2 ATLS RTTs between the client and the application service.
	skipping to change at page 24, line 5 ¶		skipping to change at page 24, line 5 ¶
	12. IANA Considerations		12. IANA Considerations
	[[ TODO - New Content-Type and TLS Exporter Label must be registered.		[[ TODO - New Content-Type and TLS Exporter Label must be registered.
	]]		]]
	13. Security Considerations		13. Security Considerations
	[[ TODO ]]		[[ TODO ]]
	14. Appendix A. TLS Software Stack Configuration		14. Informative References
			[ALTS] Google, "Application Layer Transport Security", December
			2017, <https://cloud.google.com/security/encryption-in-
			transit/application-layer-transport-security/>.
			[Bluetooth]
			Bluetooth, "Bluetooth Core Specification v5.0", 2016,
			<https://www.bluetooth.com/>.
			[I-D.hartke-core-e2e-security-reqs]
			Selander, G., Palombini, F., and K. Hartke, "Requirements
			for CoAP End-To-End Security", draft-hartke-core-e2e-
			security-reqs-03 (work in progress), July 2017.
			[I-D.ietf-anima-bootstrapping-keyinfra]
			Pritikin, M., Richardson, M., Behringer, M., Bjarnason,
			S., and K. Watsen, "Bootstrapping Remote Secure Key
			Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping-
			keyinfra-16 (work in progress), June 2018.
			[I-D.ietf-core-object-security]
			Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
			"Object Security for Constrained RESTful Environments
			(OSCORE)", draft-ietf-core-object-security-14 (work in
			progress), July 2018.
			[I-D.ietf-httpbis-bcp56bis]
			Nottingham, M., "Building Protocols with HTTP", draft-
			ietf-httpbis-bcp56bis-06 (work in progress), July 2018.
			[I-D.ietf-tls-dtls13]
			Rescorla, E., Tschofenig, H., and N. Modadugu, "The
			Datagram Transport Layer Security (DTLS) Protocol Version
			1.3", draft-ietf-tls-dtls13-28 (work in progress), July
			2018.
			[I-D.ietf-tls-tls13]
			Rescorla, E., "The Transport Layer Security (TLS) Protocol
			Version 1.3", draft-ietf-tls-tls13-28 (work in progress),
			March 2018.
			[I-D.mattsson-core-security-overhead]
			Mattsson, J., "Message Size Overhead of CoAP Security
			Protocols", draft-mattsson-core-security-overhead-02 (work
			in progress), November 2017.
			[I-D.selander-ace-cose-ecdhe]
			Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
			Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
			cose-ecdhe-09 (work in progress), July 2018.
			[LwM2M] Open Mobile Alliance, "Lightweight Machine to Machine
			Requirements", December 2017,
			<http://www.openmobilealliance.org/>.
			[Noise] Perrin, T., "Noise Protocol Framework", October 2017,
			<http://noiseprotocol.org/>.
			[Norrell] Norrell, ., "Use SSL/TLS within a different protocol with
			BIO pairs", 2016,
			<https://thekerneldiaries.com/2016/06/13/
			openssl-ssltls-within-a-different-protocol/>.
			[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
			(TLS) Protocol Version 1.2", RFC 5246,
			DOI 10.17487/RFC5246, August 2008,
			<https://www.rfc-editor.org/info/rfc5246>.
			[RFC5705] Rescorla, E., "Keying Material Exporters for Transport
			Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705,
			March 2010, <https://www.rfc-editor.org/info/rfc5705>.
			[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
			DOI 10.17487/RFC6265, April 2011,
			<https://www.rfc-editor.org/info/rfc6265>.
			[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
			Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
			January 2012, <https://www.rfc-editor.org/info/rfc6347>.
			[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
			Protocol (HTTP/1.1): Message Syntax and Routing",
			RFC 7230, DOI 10.17487/RFC7230, June 2014,
			<https://www.rfc-editor.org/info/rfc7230>.
			[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
			Application Protocol (CoAP)", RFC 7252,
			DOI 10.17487/RFC7252, June 2014,
			<https://www.rfc-editor.org/info/rfc7252>.
			[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
			Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
			DOI 10.17487/RFC7540, May 2015,
			<https://www.rfc-editor.org/info/rfc7540>.
			[RFC8188] Thomson, M., "Encrypted Content-Encoding for HTTP",
			RFC 8188, DOI 10.17487/RFC8188, June 2017,
			<https://www.rfc-editor.org/info/rfc8188>.
			[Signal] Open Whisper Systems, "Signal Protocol", 2016,
			<https://signal.org/>.
			[SSLEngine]
			Oracle, "SSLEngineSimpleDemo.java", 2004, <https://docs.or
			acle.com/javase/7/docs/technotes/guides/security/jsse/samp
			les/sslengine/SSLEngineSimpleDemo.java>.
			[ZigBee] ZigBee Alliance, "ZigBee Specification", 2012,
			<http://www.zigbee.org>.
			Appendix A. TLS Software Stack Configuration
	[[ EDITOR'S NOTE: We could include details here on how TLS stack		[[ EDITOR'S NOTE: We could include details here on how TLS stack
	configuration items control the number of round trips between the		configuration items control the number of round trips between the
	client and server.		client and server.
	And just give two examples: OpenSSL and Java SunJSSE]]		And just give two examples: OpenSSL and Java SunJSSE]]
	15. Appendix B. Pseudo Code		Appendix B. Pseudo Code
	This appendix gives both C and Java pseudo code illustrating how to		This appendix gives both C and Java pseudo code illustrating how to
	inject and extract raw TLS records from a TLS software stack. Please		inject and extract raw TLS records from a TLS software stack. Please
	not that this is illustrative, non-functional pseudo code that does		not that this is illustrative, non-functional pseudo code that does
	not compile. Functioning proof-of-concept code is available on the		not compile. Functioning proof-of-concept code is available on the
	following public repository [[ EDITOR'S NOTE: Add the URL here ]].		following public repository [[ EDITOR'S NOTE: Add the URL here ]].
	15.1. B.1 OpenSSL		B.1. OpenSSL
	OpenSSL provides a set of Basic Input/Output (BIO) APIs that can be		OpenSSL provides a set of Basic Input/Output (BIO) APIs that can be
	used to build a custom transport layer for TLS connections. This		used to build a custom transport layer for TLS connections. This
	appendix gives pseudo code on how BIO APIs could be used to build a		appendix gives pseudo code on how BIO APIs could be used to build a
	client application that completes a TLS handshake and exchanges		client application that completes a TLS handshake and exchanges
	application data with a service.		application data with a service.
	char inbound[MAX];		char inbound[MAX];
	char outbound[MAX];		char outbound[MAX];
	int rx_bytes;		int rx_bytes;
	skipping to change at page 26, line 5 ¶		skipping to change at page 28, line 5 ¶
	// Send a message to the server. Calling SSL_write() will run the		// Send a message to the server. Calling SSL_write() will run the
	// plaintext through the TLS session and write the encrypted TLS		// plaintext through the TLS session and write the encrypted TLS
	// records to the BIO buffer		// records to the BIO buffer
	SSL_write(ssl, "Hello World", strlen("Hello World"));		SSL_write(ssl, "Hello World", strlen("Hello World"));
	// Read the TLS records from the BIO buffer and		// Read the TLS records from the BIO buffer and
	// POST them to the server		// POST them to the server
	BIO_read(bio_out, outbound, MAX);		BIO_read(bio_out, outbound, MAX);
	num_bytes = postTlsRecords(outbound, inbound);		num_bytes = postTlsRecords(outbound, inbound);
	15.2. B.2 Java JSSE		B.2. Java JSSE
	The Java SSLEngine class "enables secure communications using		The Java SSLEngine class "enables secure communications using
	protocols such as the Secure Sockets Layer (SSL) or IETF RFC 2246		protocols such as the Secure Sockets Layer (SSL) or IETF RFC 2246
	"Transport Layer Security" (TLS) protocols, but is transport		"Transport Layer Security" (TLS) protocols, but is transport
	independent". This pseudo code illustrates how a server could use		independent". This pseudo code illustrates how a server could use
	the SSLEngine class to handle an inbound client TLS flight and		the SSLEngine class to handle an inbound client TLS flight and
	generate an outbound server TLS flight response.		generate an outbound server TLS flight response.
	SSLEngine sslEngine = SSLContext.getDefault().createSSLEngine();		SSLEngine sslEngine = SSLContext.getDefault().createSSLEngine();
	sslEngine.setUseClientMode(false);		sslEngine.setUseClientMode(false);
	skipping to change at page 28, line 5 ¶		skipping to change at page 30, line 5 ¶
	if (res.getHandshakeStatus() == NEED_TASK) {		if (res.getHandshakeStatus() == NEED_TASK) {
	Runnable run = sslEngine.getDelegatedTask();		Runnable run = sslEngine.getDelegatedTask();
	run.run();		run.run();
	}		}
	}		}
	// outbound ByteBuffer now contains a complete server flight		// outbound ByteBuffer now contains a complete server flight
	// containing multiple TLS Records		// containing multiple TLS Records
	// Rinse and repeat!		// Rinse and repeat!
	16. Appendix C. Example ATLS Handshake		Appendix C. Example ATLS Handshake
	[[ EDITOR'S NOTE: For completeness, include a simple full TLS		[[ EDITOR'S NOTE: For completeness, include a simple full TLS
	handshake showing the B64 encoded flights in JSON, along with the		handshake showing the raw binary flights, along with the HTTP
	HTTP request/response/headers. And also the raw hex TLS records		request/response/headers. And also the raw hex TLS records showing
	showing protocol bits ]]		protocol bits ]]
	17. Informative References
	[ALTS] Google, "Application Layer Transport Security", December
	2017, <https://cloud.google.com/security/encryption-in-
	transit/application-layer-transport-security/>.
	[Bluetooth]
	Bluetooth, "Bluetooth Core Specification v5.0", 2016,
	<https://www.bluetooth.com/>.
	[I-D.hartke-core-e2e-security-reqs]
	Selander, G., Palombini, F., and K. Hartke, "Requirements
	for CoAP End-To-End Security", draft-hartke-core-e2e-
	security-reqs-03 (work in progress), July 2017.
	[I-D.ietf-anima-bootstrapping-keyinfra]
	Pritikin, M., Richardson, M., Behringer, M., Bjarnason,
	S., and K. Watsen, "Bootstrapping Remote Secure Key
	Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping-
	keyinfra-09 (work in progress), October 2017.
	[I-D.ietf-core-object-security]
	Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
	"Object Security for Constrained RESTful Environments
	(OSCORE)", draft-ietf-core-object-security-08 (work in
	progress), January 2018.
	[I-D.ietf-httpbis-bcp56bis]
	Nottingham, M., "On the use of HTTP as a Substrate",
	draft-ietf-httpbis-bcp56bis-00 (work in progress),
	December 2017.
	[I-D.ietf-tls-dtls13]
	Rescorla, E., Tschofenig, H., and N. Modadugu, "The
	Datagram Transport Layer Security (DTLS) Protocol Version
	1.3", draft-ietf-tls-dtls13-22 (work in progress),
	November 2017.
	[I-D.ietf-tls-tls13]
	Rescorla, E., "The Transport Layer Security (TLS) Protocol
	Version 1.3", draft-ietf-tls-tls13-23 (work in progress),
	January 2018.
	[I-D.mattsson-core-security-overhead]
	Mattsson, J., "Message Size Overhead of CoAP Security
	Protocols", draft-mattsson-core-security-overhead-02 (work
	in progress), November 2017.
	[I-D.selander-ace-cose-ecdhe]
	Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
	Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
	cose-ecdhe-07 (work in progress), July 2017.
	[LwM2M] Open Mobile Alliance, "Lightweight Machine to Machine
	Requirements", December 2017,
	<http://www.openmobilealliance.org/>.
	[Noise] Perrin, T., "Noise Protocol Framework", October 2017,
	<http://noiseprotocol.org/>.
	[Norrell] Norrell, ., "Use SSL/TLS within a different protocol with
	BIO pairs", 2016,
	<https://thekerneldiaries.com/2016/06/13/openssl-ssltls-
	within-a-different-protocol/>.
	[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
	(TLS) Protocol Version 1.2", RFC 5246,
	DOI 10.17487/RFC5246, August 2008, <https://www.rfc-
	editor.org/info/rfc5246>.
	[RFC5705] Rescorla, E., "Keying Material Exporters for Transport
	Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705,
	March 2010, <https://www.rfc-editor.org/info/rfc5705>.
	[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
	DOI 10.17487/RFC6265, April 2011, <https://www.rfc-
	editor.org/info/rfc6265>.
	[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
	Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
	January 2012, <https://www.rfc-editor.org/info/rfc6347>.
	[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Message Syntax and Routing",
	RFC 7230, DOI 10.17487/RFC7230, June 2014,
	<https://www.rfc-editor.org/info/rfc7230>.
	[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
	Application Protocol (CoAP)", RFC 7252,
	DOI 10.17487/RFC7252, June 2014, <https://www.rfc-
	editor.org/info/rfc7252>.
	[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
	Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
	DOI 10.17487/RFC7540, May 2015, <https://www.rfc-
	editor.org/info/rfc7540>.
	[RFC8188] Thomson, M., "Encrypted Content-Encoding for HTTP",
	RFC 8188, DOI 10.17487/RFC8188, June 2017,
	<https://www.rfc-editor.org/info/rfc8188>.
	[Signal] Open Whisper Systems, "Signal Protocol", 2016,
	<https://signal.org/>.
	[SSLEngine]
	Oracle, "SSLEngineSimpleDemo.java", 2004, <https://docs.or
	acle.com/javase/7/docs/technotes/guides/security/jsse/
	samples/sslengine/SSLEngineSimpleDemo.java>.
	[ZigBee] ZigBee Alliance, "ZigBee Specification", 2012,
	<http://www.zigbee.org>.
	Authors' Addresses		Authors' Addresses
	Owen Friel		Owen Friel
	Cisco		Cisco
	Email: ofriel@cisco.com		Email: ofriel@cisco.com
	Richard Barnes		Richard Barnes
	Cisco		Cisco
End of changes. 22 change blocks.
	149 lines changed or deleted		147 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/