draft-irtf-cfrg-cryptography-specification-00.txt		draft-irtf-cfrg-cryptography-specification-01.txt
	Network Working Group N. Sullivan		Network Working Group N. Sullivan
	Internet-Draft C. A. Wood		Internet-Draft Cryptography Consulting LLC
	Intended status: Informational Cloudflare, Inc.		Intended status: Informational C. A. Wood
	Expires: 11 January 2024 10 July 2023		Expires: 12 October 2024 Cloudflare, Inc.
			10 April 2024
	Guidelines for Writing Cryptography Specifications		Guidelines for Writing Cryptography Specifications
	draft-irtf-cfrg-cryptography-specification-00		draft-irtf-cfrg-cryptography-specification-01
	Abstract		Abstract
	This document provides guidelines and best practices for writing		This document provides guidelines and best practices for writing
	technical specifications for cryptography protocols and primitives,		technical specifications for cryptography protocols and primitives,
	targeting the needs of implementers, researchers, and protocol		targeting the needs of implementers, researchers, and protocol
	designers. It highlights the importance of technical specifications		designers. It highlights the importance of technical specifications
	and discusses strategies for creating high-quality specifications		and discusses strategies for creating high-quality specifications
	that cater to the needs of each community, including guidance on		that cater to the needs of each community, including guidance on
	representing mathematical operations, security definitions, and		representing mathematical operations, security definitions, and
	threat models.		threat models.
	Discussion Venues		Discussion Venues
	This note is to be removed before publishing as an RFC.		This note is to be removed before publishing as an RFC.
			Discussion of this document takes place on the Crypto Forum Research
			Group mailing list (cfrg@ietf.org), which is archived at
			https://mailarchive.ietf.org/arch/search/?email_list=cfrg.
	Source for this draft and an issue tracker can be found at		Source for this draft and an issue tracker can be found at
	https://github.com/grittygrease/draft-sullivan-cryptography-		https://github.com/cfrg/draft-irtf-cfrg-cryptography-specification.
	specification.
	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 https://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 11 January 2024.		This Internet-Draft will expire on 12 October 2024.
	Copyright Notice		Copyright Notice
	Copyright (c) 2023 IETF Trust and the persons identified as the		Copyright (c) 2024 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 (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	and restrictions with respect to this document.		and restrictions with respect to this document.
	Table of Contents		Table of Contents
	skipping to change at page 2, line 30 ¶		skipping to change at page 2, line 30 ¶
	3. Guidelines for Cryptographic Specification Presentation . . . 5		3. Guidelines for Cryptographic Specification Presentation . . . 5
	3.1. Simplicity . . . . . . . . . . . . . . . . . . . . . . . 5		3.1. Simplicity . . . . . . . . . . . . . . . . . . . . . . . 5
	3.2. Precision . . . . . . . . . . . . . . . . . . . . . . . . 6		3.2. Precision . . . . . . . . . . . . . . . . . . . . . . . . 6
	3.3. Consistency . . . . . . . . . . . . . . . . . . . . . . . 7		3.3. Consistency . . . . . . . . . . . . . . . . . . . . . . . 7
	3.3.1. Representing Mathematical Operations . . . . . . . . 9		3.3.1. Representing Mathematical Operations . . . . . . . . 9
	4. Guidelines for Cryptography Specification Content . . . . . . 10		4. Guidelines for Cryptography Specification Content . . . . . . 10
	4.1. Reusability . . . . . . . . . . . . . . . . . . . . . . . 10		4.1. Reusability . . . . . . . . . . . . . . . . . . . . . . . 10
	4.1.1. Build on Existing Specifications . . . . . . . . . . 11		4.1.1. Build on Existing Specifications . . . . . . . . . . 11
	4.1.2. Modular Design . . . . . . . . . . . . . . . . . . . 11		4.1.2. Modular Design . . . . . . . . . . . . . . . . . . . 11
	4.1.3. Clear Interfaces and Abstractions . . . . . . . . . . 11		4.1.3. Clear Interfaces and Abstractions . . . . . . . . . . 11
	4.1.4. Documentation and Examples . . . . . . . . . . . . . 12		4.1.4. Completeness . . . . . . . . . . . . . . . . . . . . 12
			4.1.5. Documentation and Examples . . . . . . . . . . . . . 12
	4.2. Defining Security Definitions and Threat Models . . . . . 12		4.2. Defining Security Definitions and Threat Models . . . . . 12
	4.2.1. Defining Security Goals . . . . . . . . . . . . . . . 12		4.2.1. Defining Security Goals . . . . . . . . . . . . . . . 13
	4.2.2. Formalizing Security Definitions . . . . . . . . . . 13		4.2.2. Formalizing Security Definitions . . . . . . . . . . 13
	4.2.3. Describing the Threat Model . . . . . . . . . . . . . 13		4.2.3. Describing the Threat Model . . . . . . . . . . . . . 13
	4.2.4. Addressing Known Vulnerabilities and Attacks . . . . 13		4.2.4. Addressing Known Vulnerabilities and Attacks . . . . 13
	4.2.5. Providing Guidance on Secure Implementation and		4.2.5. Providing Guidance on Secure Implementation and
	Deployment . . . . . . . . . . . . . . . . . . . . . 13		Deployment . . . . . . . . . . . . . . . . . . . . . 14
	5. Catering to Target Audiences . . . . . . . . . . . . . . . . 14		5. Catering to Target Audiences . . . . . . . . . . . . . . . . 14
	5.1. Catering to Implementers . . . . . . . . . . . . . . . . 14		5.1. Catering to Implementers . . . . . . . . . . . . . . . . 14
	5.1.1. Test vectors . . . . . . . . . . . . . . . . . . . . 14		5.1.1. Test vectors . . . . . . . . . . . . . . . . . . . . 15
	5.2. Catering to Researchers . . . . . . . . . . . . . . . . . 15		5.2. Catering to Researchers . . . . . . . . . . . . . . . . . 16
	5.3. Catering to Protocol Designers . . . . . . . . . . . . . 16		5.3. Catering to Protocol Designers . . . . . . . . . . . . . 16
	6. General Recommendations . . . . . . . . . . . . . . . . . . . 17		6. General Recommendations . . . . . . . . . . . . . . . . . . . 17
	6.1. Encourage Open Communication and Feedback . . . . . . . . 17		6.1. Encourage Open Communication and Feedback . . . . . . . . 18
	6.2. Seek External Expertise . . . . . . . . . . . . . . . . . 17		6.2. Seek External Expertise . . . . . . . . . . . . . . . . . 18
	6.3. Recognize and Address Conflicting Interests . . . . . . . 18		6.3. Recognize and Address Conflicting Interests . . . . . . . 18
	7. Examples of Well-Written Specifications . . . . . . . . . . . 18		7. Examples of Well-Written Specifications . . . . . . . . . . . 18
	7.1. ChaCha20 and Poly1305 for IETF Protocols (RFC 8439) . . . 18		7.1. ChaCha20 and Poly1305 for IETF Protocols (RFC 8439) . . . 18
	7.1.1. Introduction and Overview . . . . . . . . . . . . . . 18		7.1.1. Introduction and Overview . . . . . . . . . . . . . . 19
	7.1.2. Algorithm Descriptions . . . . . . . . . . . . . . . 18		7.1.2. Algorithm Descriptions . . . . . . . . . . . . . . . 19
	7.1.3. Test Vectors . . . . . . . . . . . . . . . . . . . . 19		7.1.3. Test Vectors . . . . . . . . . . . . . . . . . . . . 19
	7.1.4. Security Considerations . . . . . . . . . . . . . . . 19		7.1.4. Security Considerations . . . . . . . . . . . . . . . 19
	7.1.5. IANA Considerations and References . . . . . . . . . 19		7.1.5. IANA Considerations and References . . . . . . . . . 19
	7.1.6. Problematic Aspects . . . . . . . . . . . . . . . . . 19		7.1.6. Problematic Aspects . . . . . . . . . . . . . . . . . 20
	8. Examples of Specifications That Could Be Improved . . . . . . 19		8. Examples of Specifications That Could Be Improved . . . . . . 20
	8.1. Test Vectors . . . . . . . . . . . . . . . . . . . . . . 20		8.1. Test Vectors . . . . . . . . . . . . . . . . . . . . . . 20
	8.2. Unnecessary Branching . . . . . . . . . . . . . . . . . . 20		8.2. Unnecessary Branching . . . . . . . . . . . . . . . . . . 20
	8.3. Compatibility and Modularity . . . . . . . . . . . . . . 20		8.3. Compatibility and Modularity . . . . . . . . . . . . . . 21
	9. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . 20		9. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . 21
	10. Security Considerations . . . . . . . . . . . . . . . . . . . 21		10. Security Considerations . . . . . . . . . . . . . . . . . . . 21
	11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21		11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
	12. References . . . . . . . . . . . . . . . . . . . . . . . . . 21		12. References . . . . . . . . . . . . . . . . . . . . . . . . . 22
	12.1. Normative References . . . . . . . . . . . . . . . . . . 21		12.1. Normative References . . . . . . . . . . . . . . . . . . 22
	12.2. Informative References . . . . . . . . . . . . . . . . . 21		12.2. Informative References . . . . . . . . . . . . . . . . . 22
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22
	1. Introduction		1. Introduction
	High-quality cryptography specifications are critical for the for		High-quality cryptography specifications are critical for the for
	development and deployment of secure cryptographic protocols. This		development and deployment of secure cryptographic protocols. This
	document provides guidelines for specification writers to follow to		document provides guidelines for specification writers to follow to
	help ensure that their specifications are of high quality and are		help ensure that their specifications are of high quality and are
	useful for their intended audience. This document provides		useful for their intended audience. This document provides
	guidelines for writing clear, precise, and consistent specifications		guidelines for writing clear, precise, and consistent specifications
	skipping to change at page 12, line 5 ¶		skipping to change at page 12, line 5 ¶
	implementation. This approach allows for the replacement or		implementation. This approach allows for the replacement or
	modification of components with minimal impact on the overall system		modification of components with minimal impact on the overall system
	and encourages the development of interchangeable components that can		and encourages the development of interchangeable components that can
	be reused across different applications and within protocols.		be reused across different applications and within protocols.
	Cryptographic objects typically have a set of functions associated		Cryptographic objects typically have a set of functions associated
	with them that make up the interface. Structuring the functions to		with them that make up the interface. Structuring the functions to
	fit well-understood and existing abstractions help make the job of		fit well-understood and existing abstractions help make the job of
	using the object in higher-level algorithms easier and less prone to		using the object in higher-level algorithms easier and less prone to
	code duplication.		code duplication.
	4.1.4. Documentation and Examples		4.1.4. Completeness
			The operations defined in a cryptography specification should be
			complete, with defined behavior on all inputs. This includes error
			handing, and edge cases which would otherwise not impact the
			algorithm's cryptographic properties. In particular, when
			deserializing a byte string, the behavior on all byte strings should
			be defined, including cases which would not be valid outputs of the
			corresponding serialization function. A complete specification help
			avoids implementation variations. These variations can lead to
			interoperability failures, gaps between formal analysis and real-
			world practice, or security vulnerabilities.
			Avoid defining multiple implementation behaviors as valid. Leaving
			multiple options to implementators leads to compounding complexity:
			downstream specifications may need to profile the algorithm to pick
			the preferred option, and validation tools must be configurable to
			assert either case.
			4.1.5. Documentation and Examples
	Thorough documentation and illustrative examples play a crucial role		Thorough documentation and illustrative examples play a crucial role
	in promoting reusability. By providing comprehensive explanations of		in promoting reusability. By providing comprehensive explanations of
	the specification's components, interfaces, and intended use cases,		the specification's components, interfaces, and intended use cases,
	specification authors make it easier for developers to understand and		specification authors make it easier for developers to understand and
	implement the specification correctly. Including examples of how		implement the specification correctly. Including examples of how
	components can be combined or applied in various scenarios further		components can be combined or applied in various scenarios further
	clarifies their usage and encourages their reuse in different		clarifies their usage and encourages their reuse in different
	contexts.		contexts.
	skipping to change at page 22, line 30 ¶		skipping to change at page 22, line 49 ¶
	Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018,		Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018,
	<https://www.rfc-editor.org/rfc/rfc8439>.		<https://www.rfc-editor.org/rfc/rfc8439>.
	[RFC8874] Thomson, M. and B. Stark, "Working Group GitHub Usage		[RFC8874] Thomson, M. and B. Stark, "Working Group GitHub Usage
	Guidance", RFC 8874, DOI 10.17487/RFC8874, August 2020,		Guidance", RFC 8874, DOI 10.17487/RFC8874, August 2020,
	<https://www.rfc-editor.org/rfc/rfc8874>.		<https://www.rfc-editor.org/rfc/rfc8874>.
	Authors' Addresses		Authors' Addresses
	Nick Sullivan		Nick Sullivan
	Cloudflare, Inc.		Cryptography Consulting LLC
	101 Townsend St
	San Francisco,		San Francisco,
	United States of America		United States of America
	Email: nick@cloudflare.com		Email: nicholas.sullivan+ietf@gmail.com
	Christopher A. Wood		Christopher A. Wood
	Cloudflare, Inc.		Cloudflare, Inc.
	101 Townsend St		101 Townsend St
	San Francisco,		San Francisco,
	United States of America		United States of America
	Email: caw@heapingbits.net		Email: caw@heapingbits.net
End of changes. 18 change blocks.
	30 lines changed or deleted		52 lines changed or added
This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/