| Internet-Draft | Crypto Specs | July 2023 |
| Sullivan & Wood | Expires 11 January 2024 | [Page] |
This document provides guidelines and best practices for writing technical specifications for cryptography protocols and primitives, targeting the needs of implementers, researchers, and protocol designers. It highlights the importance of technical specifications and discusses strategies for creating high-quality specifications that cater to the needs of each community, including guidance on representing mathematical operations, security definitions, and threat models.¶
This note is to be removed before publishing as an RFC.¶
Source for this draft and an issue tracker can be found at https://github.com/grittygrease/draft-sullivan-cryptography-specification.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 11 January 2024.¶
Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶
High-quality cryptography specifications are critical for the for development and deployment of secure cryptographic protocols. This document provides guidelines for specification writers to follow to help ensure that their specifications are of high quality and are useful for their intended audience. This document provides guidelines for writing clear, precise, and consistent specifications covering topics such as representing mathematical operations, defining security definitions, and describing threat models. Adhering to these guidelines helps ensure that specifications are easier to understand, implement, and analyze, leading to high assurance and interoperable systems.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The primary goal of these guidelines is to help guide the authorship of cryptographic specifications so that they are as useful as possible when creating high-assurance cryptographic software. Specifications that follow these guidelines should be able to be easily understood, implemented, and analyzed by different audiences, including the engineering community, research community, and standardization community. By addressing the unique needs and expectations of each group, these guidelines aim to:¶
Each of these stakeholder groups contributes something different to the overall process of deploying software:¶
By following these guidelines and addressing the distinct needs of each stakeholder group, specification authors can create well-structured, informative specfications documents that facilitate the development, analysis, and implementation of high assurance cryptographic solutions.¶
Technical specifications do not stand on their own. Their value is derived from their usefulness to the various communities that rely on them. A specification can have amazing content but without the appropriate presentation, it may not be as useful as intended. The guidelines in this section are a baseline set of recommendations for authors to consider when writing a cryptographic specification and are applicable beyond just cryptographic standards and are general good practices for specification writers.¶
Complexity is one of the main causes of software bugs. The opposite of complexity is simplicity, which is a key aspect of creating effective cryptography specifications. By striving for simplicity in problem statements, technical content, and presentation, specification authors can make their documents more accessible to a wider audience, including implementers, researchers, and protocol designers. Simplicity reduces the cognitive load required to understand the specification and minimizes the risk of misinterpretation, which can lead to incorrect implementations and security vulnerabilities.¶
To achieve simplicity, specification authors should focus on:¶
By focusing on simplicity in document structure and prose in the specification writing process, authors can create documents that are more accessible and easier to understand, ultimately resulting in more reliable and secure implementations of cryptographic algorithms and protocols. Focusing on simplicity in writing does not imply imprecision or brevity. Even long documents can embody simplicity with the right attention to detail and structuring of prose.¶
Precision is a crucial aspect of writing high-quality specifications, particularly for cryptography, where small deviations or ambiguities can lead to severe security vulnerabilities. A precise specification ensures that resulting implementations are consistent and correct, and that any analysis done matches the specification.¶
To achieve precision in your specifications, consider the following recommendations:¶
Precise specifications minimize ambiguity and reduce the likelihood of implementation errors or inconsistencies.¶
When a document is self-consistent and consistent with the expectations of documents of its type, it helps reduce ambiguity and is easier to consume. Ensuring consistency across concepts, vocabulary, language, and presentation helps lower the cognitive load necessary for readers to understand and work with the specification. To achieve consistency in your specifications, consider the following recommendations:¶
By focusing on consistency in your cryptography specification, you will make it more accessible and easier to understand for implementers, researchers, and protocol designers. This, in turn, will facilitate the development of correct, secure, and interoperable cryptographic systems based on your specification.¶
Cryptography specifications are often unique in their use of mathematical objects to define protocols. As such, presenting this content requires special guidance.¶
Mathematical operations are fundamental to cryptographic algorithms and protocols, and their clear and precise representation in specifications is crucial for correct implementation and analysis. This section provides guidelines for representing mathematical operations in cryptography specifications in a way that is both comprehensible and unambiguous to the target audiences, including implementers, researchers, and protocol designers.¶
Consistency in the notation used to represent mathematical operations is essential for avoiding confusion and ensuring that the specification is easy to understand. Specification authors should establish a clear notation system from the beginning and use it consistently throughout the document. This notation should be introduced with a comprehensive description or a reference to a well-known notation system to ensure that readers can easily follow the mathematical expressions. For example, exponentiation can be represented by superscript or by a carat, but not by both.¶
Specification authors should use standard mathematical symbols to represent mathematical operations whenever possible. This approach promotes clarity and reduces the risk of misinterpretation. It is important to remember that some symbols may have different meanings in different contexts or disciplines. In such cases, specification authors should clarify the intended meaning of a symbol within the context of the specification. For example, when describing group operations using multiplicative notation, the multiplication symbol * should be used instead of the x symbol.¶
When a specification requires custom mathematical operations or notation, these should be explicitly defined and accompanied by clear explanations and examples. Specification authors should take care to minimize the use of custom operations to avoid creating unnecessary complexity and potential confusion. When using custom operations, it is essential to ensure their definitions are unambiguous and easily understandable to the target audiences. A glossary of terms MAY be useful when there are multiple custom or uncommon operations introduced in the specification.¶
Providing algorithmic descriptions or pseudocode alongside mathematical expressions can greatly improve the clarity of a specification, particularly for implementers. Pseudocode should be clear, concise, and closely resemble the structure of actual programming languages. Including comments and explanations within the pseudocode can further enhance its readability and ease of understanding. Consistent notation for describing loops or if/then statements should be used throughout the document.¶
Visual representations, such as diagrams, tables or visualizations, can be a valuable tool for conveying complex mathematical concepts or relationships in a more digestible form. When including visual representations, specification authors should ensure they are clear, accurately labeled, and consistent with the overall notation system.¶
In addition to cryptographic specification clarity and accessibility through presentation format, the content of a specification also influences the overall value of the specification. The syntax of cryptographic objects introduced and their interfaces, as well as the way in which the object is structured for use in applications, is important for reliable and secure implementations of cryptographic algorithms and protocols. In this section, we discuss factors that relate to the content of the specifications and their impact on overall quality.¶
Cryptography specifications that rely on bespoke sub-algorithms or lower-level components tend to be brittle and invite implementation issues. To create efficient, interoperable, and widely adopted cryptographic systems, it is preferable to reuse existing components or primitives. Reusability allows developers to build on existing work, reducing the time and effort required to create new implementations while leveraging established security properties and analyses. This section discusses the importance of reusability in cryptography specifications and offers guidance for incorporating reusability principles into the specification development process.¶
When developing a cryptography specification, it is advantageous to build upon existing, well-established specifications, protocols, and primitives where possible. By doing so, specification authors can capitalize on the collective expertise of the community, as well as existing security analyses, implementation experiences, and best practices. This approach reduces the potential for introducing new vulnerabilities and inconsistencies while promoting interoperability between different systems.¶
Emphasizing modularity in the design of cryptography specifications allows for greater flexibility and reusability. By breaking down complex algorithms into smaller, self-contained components or modules, specification authors facilitate the reuse of these components in different contexts or applications. A modular design also simplifies the process of updating or replacing specific components without affecting the overall system, making it easier to incorporate new research findings or technological advancements. An example of a modular design is the prime-order group abstraction. Algorithms that use this abstraction admit a modular design where the group implementation is described in a separate document dedicated to the details of the implementation of the group.¶
To promote misuse resistance and elegant higher-level designs, cryptography specifications should provide clear interfaces and abstractions for the components and primitives they describe. Well-defined interfaces enable developers to understand and interact with a component without needing to know the details of its internal implementation. This approach allows for the replacement or modification of components with minimal impact on the overall system and encourages the development of interchangeable components that can be reused across different applications and within protocols. Cryptographic objects typically have a set of functions associated with them that make up the interface. Structuring the functions to fit well-understood and existing abstractions help make the job of using the object in higher-level algorithms easier and less prone to code duplication.¶
Thorough documentation and illustrative examples play a crucial role in promoting reusability. By providing comprehensive explanations of the specification's components, interfaces, and intended use cases, specification authors make it easier for developers to understand and implement the specification correctly. Including examples of how components can be combined or applied in various scenarios further clarifies their usage and encourages their reuse in different contexts.¶
By focusing on reusability in cryptography specifications, authors can help create secure, efficient, and adaptable cryptographic systems that can be more easily integrated, maintained, and updated, resulting in more robust and widely adopted solutions.¶
Cryptographic protocols are always used within a context of a broader system whose security relies on an understanding capabilities of potential attackers. An incorrect definition or assumption about the threat models to a protocol can make a protocol that is safe in one context unsafe in a different context. Precise definitions help researchers assess the security of the proposed algorithms and protocols, while comprehensible threat models enable implementers and protocol designers to understand the potential risks and limitations of the specification. This section provides guidelines for defining security definitions and threat models in a way that caters to the needs of all target audiences.¶
Specification authors should explicitly state the security goals that the proposed algorithms or protocols aim to achieve. These goals should be comprehensive, covering all relevant aspects, such as confidentiality, integrity, authentication, non-repudiation, and availability as well as resistance to implementation flaws such as side-channels. Furthermore, authors should clarify any trade-offs or limitations associated with the security goals, ensuring that the target audiences understand the intended balance between security and other factors, such as performance or ease of implementation.¶
Formalizing security definitions is essential for researchers to rigorously analyze the algorithms and protocols described in the specification. Specification authors should strive to express security definitions in a formal language, using consistent notation and terminology. The formal definitions should be accompanied by clear explanations and examples to make them more accessible to implementers and protocol designers who may not be familiar with formal methods.¶
A well-defined threat model provides an overview of the potential adversaries and the risks they pose to the security of the algorithms or protocols. Specification authors should describe the threat model in detail, including the capabilities, resources, and motivations of adversaries. Additionally, authors should identify any assumptions made about the adversarial model and explicitly state them to help the target audiences understand the intended scope and limitations of the specification's security guarantees.¶
Specification authors should discuss known vulnerabilities and attacks relevant to the proposed algorithms or protocols. This discussion should include an explanation of how the specification addresses or mitigates these issues, as well as any residual risks that remain. This information is valuable for implementers and protocol designers to understand the potential threats and for researchers to assess the robustness of the specification's security claims.¶
To help ensure that the security definitions and threat models are effectively realized in practice, specification authors should provide guidance on secure implementation and deployment of the proposed algorithms and protocols. This guidance may include best practices for avoiding common pitfalls, recommendations for cryptographic parameter selection, or considerations for securely integrating the specification into existing systems.¶
By clearly defining security definitions and threat models in cryptography specifications, authors can facilitate a better understanding of the security properties and limitations of the proposed algorithms and protocols among implementers, researchers, and protocol designers. Following these guidelines and the recommendations from [RFC3552] help make for a robust security considerations section for the specification. Having a complete discussion of the threat model and security definitions helps prevent the use of cryptographic algorithms in insecure contexts.¶
When writing a specification, it is important to consider the needs of the three primary audiences: implementers, researchers, and protocol designers. Each group has unique requirements and goals, and the specification should be written in a way that addresses their specific concerns.¶
Implementers require a clear, concise, and unambiguous specification to develop production-grade software. To cater to implementers:¶
Test vectors ideally cover all branches of the specification, with reasonable exceptions, such as branches that occur with negligible probability and as such are computationally infeasible to reproduce. To facilitate writing tests, where possible, all functions should be written with determinism in mind. In particular, this means that functions that produce random outputs, such as a function that produces random elements in a prime-order group, should accept randomness as input and test vectors should specify this randomness as an input to the function. Specifications should minimize internal calls to PRNGs or similar and emphasize determinism.¶
Finally, specifications should make the connection between specification and test vectors clear by including explicit reproducibility steps that describe how test vectors were derived for parts of the specification. This might mean pointing to a reference implementation with instructions for how to run it, where the reference implementation is written in a way that is clearly consistent with the specification.¶
It's possible to include too many test vectors in a specification, which increases document length and decreases readability. Authors should provide test vectors that cover:¶
It is NOT necessary to include test vectors for cases that are statistically improbable to be triggered, even by attacker-controlled input, based on the underlying cryptographic assumptions. For example, if an error case is only reachable when an intermediate data point matches the pre-image of a hash value that was randomly generated, finding a test vector to trigger that case would require the ability to compute a hash pre-image, which is deemed unfeasible for sufficiently strong hash functions. Exceptional cases that don't have test vectors should be explicitly noted in the algorithm description.¶
Lastly, specifications should provide references to machine-readable test vectors (e.g., in JSON format) that persist alongside the specification. This helps avoid possibly error-prone parsing in translating test vectors from a textual specification to test code inputs.¶
Researchers need to understand the syntax and functionality of the cryptographic protocol or primitive to ensure its correctness and analyze its security properties. To cater to researchers:¶
Protocol designers in the standards community use specifications to understand how to safely use the cryptographic protocol or primitive when designing a higher-level protocol that depends on it. To cater to protocol designers:¶
By addressing the specific needs of implementers, researchers, and protocol designers, a specification can be more effectively understood, implemented, and analyzed, leading to more secure and interoperable systems.¶
Developing effective cryptography specifications often requires collaboration between multiple stakeholders in the target audience, including engineers, researchers, and standardization organizations. Engaging in a collaborative process helps ensure that diverse perspectives and expertise are considered, resulting in more robust and widely applicable specifications. This section discusses the importance of collaboration and compromise in specification development and offers recommendations for fostering a collaborative environment.¶
Effective collaboration relies on open communication and an ongoing exchange of ideas and feedback. By creating channels for communication, such as mailing lists, pull request threads (as described in [RFC8874]), or regular meetings, specification authors can facilitate discussions, address concerns, and gather valuable input from various stakeholders. Encouraging an environment where feedback is welcomed and valued helps ensure that the specification benefits from diverse expertise and experiences.¶
Involving external experts, such as researchers or engineers from different organizations, can help identify potential issues, uncover new insights, and provide a broader perspective on the specification. Engaging with experts such as those in the IRTF Crypto Review Panel who have different backgrounds or areas of expertise can also help identify potential gaps in the specification or highlight areas where further research or clarification is needed.¶
Collaboration often involves addressing conflicting interests or opinions among stakeholders. It is essential to acknowledge these differences and work towards finding mutually agreeable solutions. This may require making compromises or revisiting previous decisions to ensure that the specification meets the needs of all involved parties. By maintaining a flexible and open-minded approach, specification authors can build consensus and develop a more robust specification.¶
To provide a better understanding of how to write high-quality cryptography specifications, we will analyze specific sections from a well-written example: ChaCha20 and Poly1305 for IETF Protocols ([RFC8439]).¶
[RFC8439] is a specification that describes the use of the ChaCha20 stream cipher and the Poly1305 message authentication code for IETF protocols. It demonstrates how to write a clear, comprehensive, and precise specification while catering to different audiences.¶
The introduction in [RFC8439] clearly defines the purpose and motivation for the specification. It provides context on the origins of ChaCha20 and Poly1305, and how they are used together to provide confidentiality and data integrity. By presenting a concise and informative introduction, the specification sets the stage for the detailed technical descriptions that follow.¶
The specification provides detailed and precise descriptions of the ChaCha20 and Poly1305 algorithms, including pseudocode, constants, and mathematical operations. This section caters to implementers, ensuring that they have all the necessary information to create consistent and correct implementations. The mathematical operations are expressed in a clear and unambiguous manner, which helps both implementers and researchers understand the algorithms better.¶
[RFC8439] includes test vectors for both ChaCha20 and Poly1305, providing concrete examples of inputs and expected outputs for the algorithms. This section is invaluable for implementers, allowing them to verify that their implementations are correct and compatible with others.¶
The specification dedicates an entire section to security considerations, catering to researchers and protocol designers. It discusses potential attacks and their mitigations, recommendations for nonce usage, and the security properties of the algorithms. This section also provides references to academic papers and other resources for further reading, enabling researchers to delve deeper into the security aspects of the specified algorithms.¶
[RFC8439] concludes with IANA considerations and a list of references, ensuring that the specification is well-integrated with existing IETF processes and standards. The IANA considerations section is essential for protocol designers who need to register new values or coordinate with existing registries.¶
A criticism of this document is that it does not cater enough to protocol designers in that it does not explicitly define a decryption algorithm. Researchers familiar with the concept of a stream cipher understand that decryption and encryption are identical in stream cipher constructions, but this may not be clear to implementers.¶
In summary, [RFC8439] serves as an excellent example of a well-written cryptography specification, providing clear, precise, and comprehensive information for implementers, researchers, and protocol designers alike. By studying and emulating the structure and content of specifications like [RFC8439], authors can create high-quality specifications that cater to the diverse needs of their target audiences.¶
[RFC8032] is a specification that describes the Edwards-curve Digital Signature Algorithm (EdDSA). This specification had several errata filed against it for corrections and has had documented criticisms published online.¶
The test vectors included in this document were not comprehensive and did not cover all the cases described in the algorithm, resulting in multiple incompatible implementations. There were also issues with a "greater than" comparison which should have been a "greater than or equal to" which were not explicitly covered by the test vectors.¶
Some components of the cryptographic algorithms in EdDSA had branches that sometimes led to different implementation behavior. In particular, in the verification step for Ed25519, the following text exists: "Check the group equation [8][S]B = [8]R + [8][k]A'. It's sufficient, but not required, to instead check [S]B = R + [k]A'." This alternative branch has led to disagreement between what signatures are valid or not, which has a profound effect on applications. Minimizing and removing similar branches - especially those that exist in the name of performance - should be a goal of all cryptographic specifications.¶
EdDSA is a variant of the Schnorr signature scheme, but with some small variations that make it incompatible with other related Schnorr signature schemes. This includes a "clamping" operation that makes EdDSA keys and operations incompatible with x25519 ([RFC7748]). Many of the issues in the specification derive from the fact that the specification was written to match an existing implementation rather than define an algorithm. This limited the authors from focusing on compatibility with other related standards and primitives, resulting in numerous issues.¶
This document provides guidelines for writing effective cryptography specifications, emphasizing the importance of catering to different audiences, such as implementers, researchers, and protocol designers, with the end goal of enabling high-assurance cryptographic software. By focusing on simplicity, precision, consistency, reusability, collaboration, and compromise, specification authors can create documents that are easier to understand, implement, and analyze.¶
We have also discussed the representation of mathematical operations and the importance of clearly defining security definitions and threat models. These elements are critical in ensuring that specifications are not only technically accurate but also convey the necessary information to properly assess the security properties of cryptographic algorithms and protocols.¶
Finally, we have examined a well-written example, [RFC8439], to demonstrate how these guidelines can be applied in practice. By highlighting specific sections of this specification, we have shown how authors can create high-quality specifications that cater to the diverse needs of their target audiences.¶
In conclusion, the process of writing cryptography specifications is both an art and a science. The guidelines presented in this document should serve as a foundation for authors, but it is essential to remain open to feedback and collaboration with the broader community. By doing so, we can continue to develop and refine the specifications that underpin the secure and reliable communication systems of today and the future.¶
This document discusses best practices for writing and editing cryptography specifications. It does not provide any guidance for the semantic contents of those specifications.¶
This document has no IANA actions.¶