idnits 2.17.1 draft-thomas-crypto-conditions-03.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** There are 43 instances of too long lines in the document, the longest one being 68 characters in excess of 72. ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 857 has weird spacing: '...illment pre...' -- The document date (July 18, 2017) is 2467 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) -- Looks like a reference, but probably isn't: '1' on line 1513 -- Looks like a reference, but probably isn't: '2' on line 1514 -- Looks like a reference, but probably isn't: '0' on line 1512 -- Looks like a reference, but probably isn't: '3' on line 1515 -- Looks like a reference, but probably isn't: '4' on line 1516 == Unused Reference: 'RFC3280' is defined on line 1381, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 1387, but no explicit reference was found in the text ** Downref: Normative reference to an Informational draft: draft-irtf-cfrg-eddsa (ref. 'I-D.irtf-cfrg-eddsa') ** Obsolete normative reference: RFC 3280 (Obsoleted by RFC 5280) ** Downref: Normative reference to an Informational RFC: RFC 8017 -- Obsolete informational reference (is this intentional?): RFC 4871 (Obsoleted by RFC 6376) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Thomas 3 Internet-Draft R. Reginelli 4 Intended status: Standards Track A. Hope-Bailie 5 Expires: January 19, 2018 Ripple 6 July 18, 2017 8 Crypto-Conditions 9 draft-thomas-crypto-conditions-03 11 Abstract 13 The crypto-conditions specification defines a set of encoding formats 14 and data structures for *conditions* and *fulfillments*. A condition 15 uniquely identifies a logical "boolean circuit" constructed from one 16 or more logic gates, evaluated by either validating a cryptographic 17 signature or verifying the preimage of a hash digest. A fulfillment 18 is a data structure encoding one or more cryptographic signatures and 19 hash digest preimages that define the structure of the circuit and 20 provide inputs to the logic gates allowing for the result of the 21 circuit to be evaluated. 23 A fulfillment is validated by evaluating that the circuit output is 24 TRUE but also that the provided fulfillment matches the circuit 25 fingerprint, the condition. 27 Since evaluation of some of the logic gates in the circuit (those 28 that are signatures) also take a message as input the evaluation of 29 the entire fulfillment takes an optional input message which is 30 passed to each logic gate as required. As such the algorithm to 31 validate a fulfillment against a condition and a message matches that 32 of other signature schemes and a crypto-condition can serve as a 33 sophisticated and flexible replacement for a simple signature where 34 the condition is used as the public key and the fulfillment as the 35 signature. 37 Feedback 39 This specification is a part of the Interledger Protocol [1] work. 40 Feedback related to this specification should be sent to 41 ledger@ietf.org [2]. 43 Status of This Memo 45 This Internet-Draft is submitted in full conformance with the 46 provisions of BCP 78 and BCP 79. 48 Internet-Drafts are working documents of the Internet Engineering 49 Task Force (IETF). Note that other groups may also distribute 50 working documents as Internet-Drafts. The list of current Internet- 51 Drafts is at http://datatracker.ietf.org/drafts/current/. 53 Internet-Drafts are draft documents valid for a maximum of six months 54 and may be updated, replaced, or obsoleted by other documents at any 55 time. It is inappropriate to use Internet-Drafts as reference 56 material or to cite them other than as "work in progress." 58 This Internet-Draft will expire on January 19, 2018. 60 Copyright Notice 62 Copyright (c) 2017 IETF Trust and the persons identified as the 63 document authors. All rights reserved. 65 This document is subject to BCP 78 and the IETF Trust's Legal 66 Provisions Relating to IETF Documents 67 (http://trustee.ietf.org/license-info) in effect on the date of 68 publication of this document. Please review these documents 69 carefully, as they describe your rights and restrictions with respect 70 to this document. Code Components extracted from this document must 71 include Simplified BSD License text as described in Section 4.e of 72 the Trust Legal Provisions and are provided without warranty as 73 described in the Simplified BSD License. 75 Table of Contents 77 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 78 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 79 3. Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 80 3.1. Simple and Compound Types . . . . . . . . . . . . . . . . 5 81 3.2. Defining and Supporting New types . . . . . . . . . . . . 5 82 4. Features . . . . . . . . . . . . . . . . . . . . . . . . . . 6 83 4.1. Multi-Algorithm . . . . . . . . . . . . . . . . . . . . . 6 84 4.2. Multi-Signature . . . . . . . . . . . . . . . . . . . . . 6 85 4.3. Multi-Level . . . . . . . . . . . . . . . . . . . . . . . 6 86 4.4. Crypto-conditions as a signature scheme . . . . . . . . . 7 87 4.5. Crypto-conditions as a trigger in distributed systems . . 8 88 4.6. Smart signatures . . . . . . . . . . . . . . . . . . . . 9 89 5. Validation of a fulfillment . . . . . . . . . . . . . . . . . 9 90 5.1. Subfulfillments . . . . . . . . . . . . . . . . . . . . . 10 91 6. Deriving the Condition . . . . . . . . . . . . . . . . . . . 10 92 6.1. Conditions as Public Keys . . . . . . . . . . . . . . . . 10 93 7. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 94 7.1. Encoding Rules . . . . . . . . . . . . . . . . . . . . . 11 95 7.2. Condition . . . . . . . . . . . . . . . . . . . . . . . . 11 96 7.2.1. Fingerprint . . . . . . . . . . . . . . . . . . . . . 12 97 7.2.2. Cost . . . . . . . . . . . . . . . . . . . . . . . . 13 98 7.2.3. Subtypes . . . . . . . . . . . . . . . . . . . . . . 13 99 7.3. Fulfillment . . . . . . . . . . . . . . . . . . . . . . . 14 100 8. Crypto-Condition Types . . . . . . . . . . . . . . . . . . . 15 101 8.1. PREIMAGE-SHA-256 . . . . . . . . . . . . . . . . . . . . 15 102 8.1.1. Cost . . . . . . . . . . . . . . . . . . . . . . . . 16 103 8.1.2. ASN.1 . . . . . . . . . . . . . . . . . . . . . . . . 16 104 8.1.3. Condition Format . . . . . . . . . . . . . . . . . . 16 105 8.1.4. Fulfillment Format . . . . . . . . . . . . . . . . . 16 106 8.1.5. Validating . . . . . . . . . . . . . . . . . . . . . 16 107 8.1.6. Example . . . . . . . . . . . . . . . . . . . . . . . 16 108 8.2. PREFIX-SHA-256 . . . . . . . . . . . . . . . . . . . . . 17 109 8.2.1. Cost . . . . . . . . . . . . . . . . . . . . . . . . 17 110 8.2.2. ASN.1 . . . . . . . . . . . . . . . . . . . . . . . . 18 111 8.2.3. Condition Format . . . . . . . . . . . . . . . . . . 18 112 8.2.4. Fulfillment Format . . . . . . . . . . . . . . . . . 18 113 8.2.5. Validating . . . . . . . . . . . . . . . . . . . . . 19 114 8.2.6. Example . . . . . . . . . . . . . . . . . . . . . . . 19 115 8.3. THRESHOLD-SHA-256 . . . . . . . . . . . . . . . . . . . . 20 116 8.3.1. Cost . . . . . . . . . . . . . . . . . . . . . . . . 20 117 8.3.2. ASN.1 . . . . . . . . . . . . . . . . . . . . . . . . 20 118 8.3.3. Condition Format . . . . . . . . . . . . . . . . . . 20 119 8.3.4. Fulfillment Format . . . . . . . . . . . . . . . . . 21 120 8.3.5. Validating . . . . . . . . . . . . . . . . . . . . . 21 121 8.3.6. Example . . . . . . . . . . . . . . . . . . . . . . . 21 122 8.4. RSA-SHA-256 . . . . . . . . . . . . . . . . . . . . . . . 23 123 8.4.1. RSA Keys . . . . . . . . . . . . . . . . . . . . . . 23 124 8.4.2. Cost . . . . . . . . . . . . . . . . . . . . . . . . 24 125 8.4.3. ASN.1 . . . . . . . . . . . . . . . . . . . . . . . . 24 126 8.4.4. Condition Format . . . . . . . . . . . . . . . . . . 24 127 8.4.5. Fulfillment Format . . . . . . . . . . . . . . . . . 24 128 8.4.6. Validating . . . . . . . . . . . . . . . . . . . . . 25 129 8.4.7. Example . . . . . . . . . . . . . . . . . . . . . . . 25 130 8.5. ED25519-SHA256 . . . . . . . . . . . . . . . . . . . . . 26 131 8.5.1. Cost . . . . . . . . . . . . . . . . . . . . . . . . 27 132 8.5.2. ASN.1 . . . . . . . . . . . . . . . . . . . . . . . . 27 133 8.5.3. Condition Format . . . . . . . . . . . . . . . . . . 27 134 8.5.4. Fulfillment . . . . . . . . . . . . . . . . . . . . . 27 135 8.5.5. Validating . . . . . . . . . . . . . . . . . . . . . 27 136 8.5.6. Example . . . . . . . . . . . . . . . . . . . . . . . 28 137 9. URI Encoding Rules . . . . . . . . . . . . . . . . . . . . . 28 138 9.1. Condition URI Format . . . . . . . . . . . . . . . . . . 28 139 9.2. New URI Parameter Definitions . . . . . . . . . . . . . . 29 140 9.2.1. Parameter: Fingerprint Type (fpt) . . . . . . . . . . 29 141 9.2.2. Parameter: Cost (cost) . . . . . . . . . . . . . . . 29 142 9.2.3. Parameter: Subtypes (subtypes) . . . . . . . . . . . 29 143 10. Example Condition . . . . . . . . . . . . . . . . . . . . . . 29 144 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 145 11.1. Normative References . . . . . . . . . . . . . . . . . . 30 146 11.2. Informative References . . . . . . . . . . . . . . . . . 31 147 Appendix A. Security Considerations . . . . . . . . . . . . . . 32 148 Appendix B. Test Values . . . . . . . . . . . . . . . . . . . . 33 149 Appendix C. ASN.1 Module . . . . . . . . . . . . . . . . . . . . 33 150 Appendix D. IANA Considerations . . . . . . . . . . . . . . . . 35 151 D.1. Crypto-Condition Type Registry . . . . . . . . . . . . . 35 152 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 154 1. Introduction 156 Crypto-conditions is a scheme for composing signature-like structures 157 from one or more existing signature schemes or hash digest 158 primitives. It defines a mechanism for these existing primitives to 159 be combined and grouped to create complex signature arrangements but 160 still maintain the useful properties of a simple signature, most 161 notably, that a deterministic algorithm exists to verify the 162 signature against a message given a public key. 164 Using crypto-conditions, existing primitives such as RSA and ED25519 165 signature schemes and SHA256 digest algorithms can be used as logic 166 gates to construct complex boolean circuits which can then be used as 167 a compound signature. The validation function for these compound 168 signatures takes as input the fingerprint of the circuit, called the 169 condition, the circuit definition and minimum required logic gates 170 with their inputs, called the fulfillment, and a message. 172 The function returns a boolean indicating if the compound signature 173 is valid or not. This property of crypto-conditions means they can 174 be used in most scenarios as a replacement for existing signature 175 schemes which also take as input, a public key (the condition), a 176 signature (the fulfillment), and a message and return a boolean 177 result. 179 2. Terminology 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 183 document are to be interpreted as described in [RFC2119]. 185 3. Types 187 Crypto-conditions are a standard format for expressing conditions and 188 fulfillments. The format supports multiple algorithms, including 189 different hash functions and cryptographic signing schemes. Crypto- 190 conditions can be nested in multiple levels, with each level possibly 191 having multiple signatures. 193 The different types of crypto-conditions each have different internal 194 strutures and employ different cryptographic algorithms as 195 primitives. 197 3.1. Simple and Compound Types 199 Two categories of crypto-condition type exist. Simple crypto- 200 conditions provide a standard encoding of common cryptographic 201 primitives with hardcoded parameters, e.g RSA and ED25519 signature 202 or SHA256 hash digests. As such, simple types that use the same 203 underlying scheme (e.g. SHA) with different parameters (e.g. 256 or 204 512 bits) are considered different crypto-condition types. 206 As an example, the types defined in this version of the specification 207 all use the SHA-256 digest algorithm to generate the condition 208 fingerprint. If a future version were to introduce SHA-512 as an 209 alternative this would require that new types be defined for each 210 existing type that must have its condition generated using SHA-512. 212 Compound crypto-conditions contain one or more sub-crypto-conditions. 213 The compound crypto-condition will evaluate to TRUE or FALSE based on 214 the output of the evaluation of the sub-crypto-conditions. In this 215 way compound crypto-conditions are used to construct branches of a 216 boolean circuit. 218 To validate a compound crypto-condition all sub-crypto-conditions are 219 provided in the fulfillment so that the fingerprint of the compound 220 condition can be generated. However, some of these sub-crypto- 221 conditions may be sub-fulfillments and some may be sub-conditions, 222 depending on the type and properties of the compound crypto- 223 condition. 225 As an example, in the case of an m-of-n signature scheme, only m sub- 226 fulfillments are needed to validate the compound signature, but the 227 remaining n-m sub-conditions must still be provided to validate that 228 the complete fulfillment matches the originally provided condition. 229 This is an important feature for multi-party signing, when not all 230 parties are ready to provide fulfillment yet all parties still desire 231 fulfillment of the overall condition if enough counter-parties do 232 provide fulfillment. 234 3.2. Defining and Supporting New types 236 The crypto-conditions format has been designed so that it can be 237 expanded. For example, you can add new cryptographic signature 238 schemes or hash functions. This is important because advances in 239 cryptography frequently render old algorithms insecure or invent 240 newer, more effective algorithms. 242 Implementations are not required to support all condition types 243 therefore it is necessary to indicate which types an implementation 244 must support in order to validate a fulfillment. For this reason, 245 compound conditions are encoded with an additional field, subtypes, 246 indicating the set of types and subtypes of all sub-crypto- 247 conditions. 249 4. Features 251 Crypto-conditions offer many of the features required of a regular 252 signature scheme but also others which make them useful in a variety 253 of new use cases. 255 4.1. Multi-Algorithm 257 Each condition type uses one or more cryptographic primitives such as 258 digest or signature algorithms. Compound types may contain sub- 259 crypto-conditions of any type and indicate the set of underlying 260 types in the subtypes field of the condition 262 To verify that a given implementation can verify a fulfillment for a 263 given condition, implementations MUST ensure they are able to 264 validate fulfillments of all types indicated in the subtypes field of 265 a compound condition. If an implementation encounters an unknown 266 type it MUST reject the condition as it will almost certainly be 267 unable to validate the fulfillment. 269 4.2. Multi-Signature 271 Crypto-conditions can abstract away many of the details of multi- 272 sign. When a party provides a condition, other parties can treat it 273 opaquely and do not need to know about its internal structure. That 274 allows parties to define arbitrary multi-signature setups without 275 breaking compatibility. That said, it is important that 276 implementations must inspect the types and subtypes of any crypto- 277 conditions they encounter to ensure they do not pass on a condition 278 they will not be able to verify at a later stage. 280 In many instances protocol designers can use crypto-conditions as a 281 drop-in replacement for public key signature algorithms and add 282 multi-signature support to their protocols without adding any 283 additional complexity. 285 4.3. Multi-Level 287 Crypto-conditions elegantly support weighted multi-signatures and 288 multi-level signatures. A threshold condition has a number of 289 subconditions, and a target threshold. Each subcondition can be a 290 signature or another threshold condition. This provides flexibility 291 in forming complex conditions. 293 For example, consider a threshold condition that consists of two 294 subconditions, one each from Wayne and Alf. Alf's condition can be a 295 signature condition while Wayne's condition is a threshold condition, 296 requiring both Claude and Dan to sign for him. 298 Multi-level signatures allow more complex relationships than simple 299 M-of-N signing. For example, a weighted condition can support an 300 arrangement of subconditions such as, "Either Ron, Mac, and Ped must 301 approve; or Smithers must approve." 303 4.4. Crypto-conditions as a signature scheme 305 Crypto-conditions is a signature scheme for compound signatures which 306 has similar properties to most other signature schemes, such as: 308 1. Validation of the signature (the fulfillment) is done using a 309 public key (the condition) and a message as input 311 2. The same public key can be used to validate multiple different 312 signatures, each against a different message 314 3. It is not possible to derive the signature from the public key 316 However, the scheme also has a number of features that make it unique 317 such as: 319 1. It is possible to derive the same public key from any valid 320 signature without the message 322 2. It is possible for the same public key and message to be used to 323 validate multiple signatures. For example, the fulfillment of an 324 m-of-n condition will be different for each combination of n 325 signatures. 327 3. Composite signatures use one or more other signatures as 328 components allowing for recursive signature validation logic to 329 be defined. 331 4. A valid signature can be produced using different combinations of 332 private keys if the structure of the compound signature requires 333 only specific combinations of internal signatures to be valid (m 334 of n signature scheme). 336 4.5. Crypto-conditions as a trigger in distributed systems 338 One of the challenges facing a distributed system is achieving atomic 339 execution of a transaction across the system. A common pattern for 340 solving this problem is two-phase commit in which the most time and 341 resource-consuming aspects of the transaction are prepared by all 342 participants following which a simple trigger is sufficient to either 343 commit or abort the transaction. Described in more abstract terms, 344 the system consists of a number of participants that have prepared a 345 transaction pending the fulfillment of a predefined condition. 347 Crypto-conditions defines a mechanism for expressing these triggers 348 as pairs of unique trigger identifiers (conditions) and 349 cryptographically verifiable triggers (fulfillments) that can be 350 deterministically verified by all participants. 352 It is also important that all participants in such a distributed 353 system are able to evaluate, prior to the trigger being fired, that 354 they will be capable of verifying the trigger. Determinism is 355 useless if validation of the trigger requires algorithms or resources 356 that are not available to all participants. 358 Therefore conditions may be used as *distributable event 359 descriptions* in the form of a _fingerprint_, but also _event meta- 360 data_ that allows the event verification system to determine if they 361 have the necessary capabilities (such as required crypto-algorithms) 362 and resources (such as heap size or memory) to verify the event 363 notification later. 365 Fulfillments are therefore *cryptographically verifiable event 366 notifications* that can be used to verify the event occurred but also 367 that it matches the given description. 369 When using crypto-conditions as a trigger it will often make sense 370 for the message that is used for validation to be empty to match the 371 signature of the trigger processing system's API. This makes crypto- 372 conditions compatible with systems that use simple hash-locks as 373 triggers. 375 If a PKI signature scheme is being used for the triggers this would 376 require a new key pair for each trigger which is impractical. 377 Therefore the PREFIX compound type wraps a sub-crypto-condition with 378 a message prefix that is applied to the message before signature 379 validation. In this way a unique condition can be derived for each 380 trigger even if the same key pair is re-used with an empty message. 382 4.6. Smart signatures 384 In the Interledger protocol, fulfillments provide non-repudiable 385 proof that a transaction has been completed on a ledger. They are 386 simple messages that can be easily shared with other ledgers. This 387 allows ledgers to escrow funds or hold a transfer conditionally, then 388 execute the transfer automatically when the ledger sees the 389 fulfillment of the stated condition. In this way the Interledger 390 protocol synchronizes multiple transfers on distinct ledgers in an 391 almost atomic end-to-end transaction. 393 Crypto-conditions may also be useful in other contexts where a system 394 needs to make a decision based on predefined criteria, and the proof 395 from a trusted oracle(s) that the criteria have been met, such as 396 smart contracts. 398 The advantage of using crypto-conditions for such use cases as 399 opposed to a turing complete contract scripting language is the fact 400 that the outcome of a crypto-condition validation is deterministic 401 across platforms as long as the underlying cryptographic primitives 402 are correctly implemented. 404 5. Validation of a fulfillment 406 Validation of a fulfillment (F) against a condition (C) and a message 407 (M), in the majority of cases, follows these steps: 409 1. The implementation must derive a condition from the fulfillment 410 and ensure that the derived condition (D) matches the given 411 condition (C). 413 2. If the fulfillment is a simple crypto-condition AND is based upon 414 a signature scheme (such as RSA-PSS or ED25519) then any 415 signatures in the fulfillment (F) must be verified, using the 416 appropriate signature verification algorithm, against the 417 corresponding public key, also provided in the fulfillment and 418 the message (M) (which may be empty). 420 3. If the fulfillment is a compound crypto-condition then the sub- 421 fulfillments MUST each be validated. In the case of the PREFIX- 422 SHA-256 type the sub-fulfillment MUST be valid for F to be valid 423 and in the case of the THRESHOLD-SHA-256 type the number of valid 424 sub-fulfillments must be equal or greater than the threshold 425 defined in F. 427 If the derived condition (D) matches the input condition (C) AND the 428 boolean circuit defined by the fulfillment evaluates to TRUE then the 429 fulfillment (F) fulfills the condition (C). 431 A more detailed validation algorithm for each crypto-condition type 432 is provided with the details of the type later in this document. In 433 each case the notation F.x or C.y implies; the decoded value of the 434 field named x of the fulfillment and the decoded value of the field 435 named y of the Condition respectively. 437 5.1. Subfulfillments 439 In validating a fulfillment for a compound crypto-condition it is 440 necessary to validate one or more sub-fulfillments per step 3 above. 441 In this instance the condition for one or more of these sub- 442 fulfillments is often not available for comparison with the derived 443 condition. Implementations MUST skip the first fulfillment 444 validation step as defined above and only perform steps 2 and 3 of 445 the validation. 447 The message (M) used to validate sub-fulfillments is the same message 448 (M) used to validate F however in the case of the PREFIX-SHA-256 type 449 this is prefixed with F.prefix before validation of the sub- 450 fulfillment is performed. 452 6. Deriving the Condition 454 Since conditions provide a unique fingerprint for fulfillments it is 455 important that a determinisitic algorithm is used to derive a 456 condition. For each crypto-condition type details are provided on 457 how to: 459 1. Assemble the fingerprint content and calculate the hash digest of 460 this data. 462 2. Calculate the maximum cost of validating a fulfillment 464 For compound types the fingerprint content will contain the complete, 465 encoded, condition for all sub-crypto-conditions. Implementations 466 MUST abide by the ordering rules provided when assembling the 467 fingerprint content. 469 When calculating the fingerprint of a compound crypto-condition 470 implementations MUST first derive the condition for all sub- 471 fulfillments and include these conditions when assembling the 472 fingerprint content. 474 6.1. Conditions as Public Keys 476 Since the condition is just a fingerprint and meta-data about the 477 crypto-condition it can be transmitted freely in the same way a 478 public key is shared publicly. It's not possible to derive the 479 fulfillment from the condition. 481 7. Format 483 A description of crypto-conditions is provided in this document using 484 Abstract Syntax Notation One (ASN.1) as defined in [itu.X680.2015]. 486 7.1. Encoding Rules 488 Implementations of this specificiation MUST support encoding and 489 decoding using Distinguished Encoding Rules (DER) as defined in 490 [itu.X690.2015]. This is the canonical encoding format. 492 Alternative encodings may be used to represent top-level conditions 493 and fulfillments but to ensure a determinisitic outcome in producing 494 the condition fingerprint content, including any sub-conditions, MUST 495 be DER encoded prior to hashing. 497 The exception is the PREIMAGE-SHA-256 condition where the fingerprint 498 content is the raw preimage which is not encoded prior to hashing. 499 This is to allow a PREIMAGE-SHA-256 crypto-condition to be used in 500 systems where "hash-locks" are already in use. 502 7.2. Condition 504 The binary encoding of conditions differs based on their type. All 505 types define at least a fingerprint and cost sub-field. Some types, 506 such as the compound condition types, define additional sub-fields 507 that are required to convey essential properties of the crypto- 508 condition (such as the sub-types used by sub-conditions in the case 509 of the compound types). 511 Each crypto-condition type has a type ID. The list of known types is 512 the IANA-maintained Crypto-Condition Type Registry (Appendix D.1). 514 Conditions are encoded as follows: 516 Condition ::= CHOICE { 517 preimageSha256 [0] SimpleSha256Condition, 518 prefixSha256 [1] CompoundSha256Condition, 519 thresholdSha256 [2] CompoundSha256Condition, 520 rsaSha256 [3] SimpleSha256Condition, 521 ed25519Sha256 [4] SimpleSha256Condition 522 } 524 SimpleSha256Condition ::= SEQUENCE { 525 fingerprint OCTET STRING (SIZE(32)), 526 cost INTEGER (0..4294967295) 527 } 529 CompoundSha256Condition ::= SEQUENCE { 530 fingerprint OCTET STRING (SIZE(32)), 531 cost INTEGER (0..4294967295), 532 subtypes ConditionTypes 533 } 535 ConditionTypes ::= BIT STRING { 536 preImageSha256 (0), 537 prefixSha256 (1), 538 thresholdSha256 (2), 539 rsaSha256 (3), 540 ed25519Sha256 (4) 541 } 543 7.2.1. Fingerprint 545 The fingerprint is an octet string uniquely representing the 546 condition with respect to other conditions *of the same type*. 548 Implementations which index conditions MUST use the complete encoded 549 condition as the key, not just the fingerprint - as different 550 conditions of different types may have the same fingerprint. 552 For most condition types, the fingerprint is a cryptographically 553 secure hash of the data which defines the condition, such as a public 554 key. 556 For types that use PKI signature schemes, the signature is 557 intentionally not included in the content that is used to compose the 558 fingerprint. This means the fingerprint can be calculated without 559 needing to know the message or having access to the private key. 561 Future types may use different functions to produce the fingerprint, 562 which may have different lengths, therefore the field is encoded as a 563 variable length string. 565 7.2.2. Cost 567 For each type, a cost function is defined which produces a 568 determinsitic cost value based on the properties of the condition. 570 The cost functions are designed to produce a number that will 571 increase rapidly if the structure and properties of a crypto- 572 condition are such that they increase the resource requirements of a 573 system that must validate the fulfillment. 575 The constants used in the cost functions are selected in order to 576 provide some consistency across types for the cost value and the 577 expected "real cost" of validation. This is not an exact science 578 given that some validations will require signature verification (such 579 as RSA and ED25519) and others will simply require hashing and 580 storage of large values therefore the cost functions are roughly 581 configured (through selection of constants) to be the number of bytes 582 that would need to be processed by the SHA-256 hash digest algorithm 583 to produce the equivalent amount of work. 585 The goal is to produce an indicative number that implementations can 586 use to protect themselves from attacks involving crypto-conditions 587 that would require massive resources to validate (denial of service 588 type attacks). 590 Since dynamic heuristic measures can't be used to acheive this a 591 deterministic value is required that can be produced consistently by 592 any implementation, therefore for each crypto-condition type, an 593 algorithm is provided for consistently calculating the cost. 595 Implementations MUST determine a safe cost ceiling based on the 596 expected cost value of crypto-conditions they will need to process. 597 When a crypto-condition is submitted to an implementation, the 598 implementation MUST verify that it will be able to process a 599 fulfillment with the given cost (i.e. the cost is lower than the 600 allowed ceiling) and reject it if not. 602 Cost function constants have been rounded to numbers that have an 603 efficient base-2 representation to facilitate efficient arithmetic 604 operations. 606 7.2.3. Subtypes 608 Subtypes is a bitmap that indicates the set of types an 609 implementation must support in order to be able to successfully 610 validate the fulfillment of this condition. This is the set of types 611 and subtypes of all sub-crypto-conditions, recursively excluding the 612 type of the root crypto-condition. 614 It must be possible to verify that all types used in a crypto- 615 condition are supported (including the types and subtypes of any sub- 616 crypto-conditions) even if the fulfillment is not available to be 617 analysed yet. Therefore, all compound conditions set the bits in 618 this bitmap that correspond to the set of types and subtypes of all 619 sub-crypto-conditions. 621 The field is encoded as a variable length BIT STRING, as defined in 622 ASN.1, to accommodate new types that may be defined. 624 Each bit in the bitmap represents a type from the list of known types 625 in the IANA-maintained Crypto-Condition Type Registry (Appendix D.1) 626 and the bit corresponding to each type is the bit at position X where 627 X is the type ID of the type. 629 The presence of one or more sub-crypto-conditions of a specific type 630 is indicated by setting the numbered bit corresponding to the type ID 631 of that type. 633 In DER encoding, the bits in a bitstring are numbered from the MOST 634 significant bit (bit 0) to least significant (bit 7) of the first 635 byte and then continue with the MOST significant bit (bit 8) of the 636 next byte, and so on. For example, a compound condition that 637 contains an ED25519-SHA-256 crypto-condition as a sub-crypto- 638 condition will set the bit at position 4 and the BITSTRING will be 639 DER encoded with an appropriate tag byte followed by the three bytes 640 0x02 0x03 and 0x80, where 0x02 indicates the length (2 bytes, the 641 first being the padding indicator), 0x03 indicates that there are 3 642 padding bits in the last byte and 0x80 indicates the 5 bits in the 643 string are set to 00001. 645 7.3. Fulfillment 647 The ASN.1 definition for fulfillments is defined as follows: 649 Fulfillment ::= CHOICE { 650 preimageSha256 [0] PreimageFulfillment , 651 prefixSha256 [1] PrefixFulfillment, 652 thresholdSha256 [2] ThresholdFulfillment, 653 rsaSha256 [3] RsaSha256Fulfillment, 654 ed25519Sha256 [4] Ed25519Sha512Fulfillment 655 } 657 PreimageFulfillment ::= SEQUENCE { 658 preimage OCTET STRING 659 } 661 PrefixFulfillment ::= SEQUENCE { 662 prefix OCTET STRING, 663 maxMessageLength INTEGER (0..4294967295), 664 subfulfillment Fulfillment 665 } 667 ThresholdFulfillment ::= SEQUENCE { 668 subfulfillments SET OF Fulfillment, 669 subconditions SET OF Condition 670 } 672 RsaSha256Fulfillment ::= SEQUENCE { 673 modulus OCTET STRING, 674 signature OCTET STRING 675 } 677 Ed25519Sha512Fulfillment ::= SEQUENCE { 678 publicKey OCTET STRING (SIZE(32)), 679 signature OCTET STRING (SIZE(64)) 680 } 682 8. Crypto-Condition Types 684 The following condition types are defined in this version of the 685 specification. While support for additional crypto-condition types 686 may be added in the future and will be registered in the IANA 687 maintained Crypto-Condition Type Registry (Appendix D.1), no other 688 types are supported by this specification. 690 8.1. PREIMAGE-SHA-256 692 PREIMAGE-SHA-256 is assigned the type ID 0. It relies on the 693 availability of the SHA-256 digest algorithm. 695 This type of condition is also called a "hashlock". By creating a 696 hash of a difficult-to-guess 256-bit random or pseudo-random integer 697 it is possible to create a condition which the creator can trivially 698 fulfill by publishing the random value. However, for anyone else, 699 the condition is cryptographically hard to fulfill, because they 700 would have to find a preimage for the given condition hash. 702 Implementations MUST ignore any input message when validating a 703 PREIMAGE-SHA-256 fulfillment as the validation of this crypto- 704 condition type only requires that the SHA-256 digest of the preimage, 705 taken from the fulfillment, matches the fingerprint, taken from the 706 condition. 708 8.1.1. Cost 710 The cost is the size, in bytes, of the *unencoded* preimage. 712 cost = preimage length 714 8.1.2. ASN.1 716 -- Condition Fingerprint 717 -- The PREIMAGE-SHA-256 condition fingerprint content is not DER encoded 718 -- The fingerprint content is the preimage 720 -- Fulfillment 721 PreimageFulfillment ::= SEQUENCE { 722 preimage OCTET STRING 723 } 725 8.1.3. Condition Format 727 The fingerprint of a PREIMAGE-SHA-256 condition is the SHA-256 hash 728 of the *unencoded* preimage. 730 8.1.4. Fulfillment Format 732 The fulfillment simply contains the preimage (encoded into a SEQUENCE 733 of one element for consistency). 735 8.1.5. Validating 737 A PREIMAGE-SHA-256 fulfillment is valid iff C.fingerprint is equal to 738 the SHA-256 hash digest of F. 740 8.1.6. Example 741 examplePreimageCondition Condition ::= 742 preimageSha256 : { 743 fingerprint '7F83B165 7FF1FC53 B92DC181 48A1D65D FC2D4B1F A3D67728 4ADDD200 126D9069'H, 744 cost 12 745 } 747 examplePreimageFulfillment Fulfillment ::= 748 preimageSha256 : { 749 preimage '48656C6C 6F20576F 726C6421'H 750 } 752 8.2. PREFIX-SHA-256 754 PREFIX-SHA-256 is assigned the type ID 1. It relies on the 755 availability of the SHA-256 digest algorithm and any other algorithms 756 required by its sub-crypto-condition as it is a compound crypto- 757 condition type. 759 Prefix crypto-conditions provide a way to narrow the scope of other 760 crypto-conditions that are used inside the prefix crypto-condition as 761 a sub-crypto-condition. 763 Because a condition is the fingerprint of a public key, by creating a 764 prefix crypto-condition that wraps another crypto-condition we can 765 narrow the scope from signing an arbitrary message to signing a 766 message with a specific prefix. 768 We can also use the prefix condition in contexts where there is an 769 empty message used for validation of the fulfillment so that we can 770 reuse the same key pair for multiple crypto-conditions, each with a 771 different prefix, and therefore generate a unique condition and 772 fulfillment each time. 774 Implementations MUST prepend the prefix to the provided message and 775 will use the resulting value as the message to validate the sub- 776 fulfillment. 778 8.2.1. Cost 780 The cost is the size, in bytes, of the *unencoded* prefix, plus the 781 maximum message that will be accepted to be prefixed and validated by 782 the subcondition, plus the cost of the sub-condition, plus the 783 constant 1024. 785 cost = prefix.length (in bytes) + max_message_length + subcondition_cost + 1024 786 8.2.2. ASN.1 788 -- Condition Fingerprint 789 PrefixFingerprintContents ::= SEQUENCE { 790 prefix OCTET STRING, 791 maxMessageLength INTEGER (0..4294967295), 792 subcondition Condition 793 } 795 -- Fulfillment 796 PrefixFulfillment ::= SEQUENCE { 797 prefix OCTET STRING, 798 maxMessageLength INTEGER (0..4294967295), 799 subfulfillment Fulfillment 800 } 802 8.2.3. Condition Format 804 The fingerprint of a PREFIX-SHA-256 condition is the SHA-256 digest 805 of the DER encoded fingerprint contents which are a SEQUENCE of: 807 prefix An arbitrary octet string which will be prepended to the 808 message during validation of the sub-fulfillment. 810 maxMessageLength The maximum size, in bytes, of the message that 811 will be accepted during validation of the fulfillment of this 812 condition. 814 subcondition The condition derived from the sub-fulfillment of this 815 crypto-condition. 817 8.2.4. Fulfillment Format 819 The fulfillment of a PREFIX-SHA-256 crypto-condition is a 820 PrefixFulfillment which is a SEQUENCE of: 822 prefix An arbitrary octet string which will be prepended to the 823 message during validation of the sub-fulfillment. 825 maxMessageLength The maximum size, in bytes, of the message that 826 will be accepted during validation of the fulfillment of this 827 condition. 829 subfulfillment A fulfillment that will be verified against the 830 prefixed message. 832 8.2.5. Validating 834 A PREFIX-SHA-256 fulfillment is valid iff: 836 1. The size of M, in bytes, is less than or equal to 837 F.maxMessageLength AND 839 2. F.subfulfillment is valid, where the message used for validation 840 of f is M prefixed by F.prefix AND 842 3. D is equal to C 844 8.2.6. Example 846 examplePrefixCondition Condition ::= 847 prefixSha256 : { 848 fingerprint 'BB1AC526 0C0141B7 E54B26EC 2330637C 5597BF81 1951AC09 E744AD20 FF77E287'H, 849 cost 1024, 850 subtypes { preimageSha256 } 851 } 853 examplePrefixFulfillment Fulfillment ::= 854 prefixSha256 : { 855 prefix ''H, 856 maxMessageLength 0, 857 subfulfillment preimageSha256 : { preimage ''H } 858 } 860 examplePrefixFingerprintContents PrefixFingerprintContents ::= { 861 prefix ''H, 862 maxMessageLength 0, 863 subcondition preimageSha256 : { 864 fingerprint 'E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855'H, 865 cost 0 866 } 867 } 869 Note that the example given, while useful to demonstrate the 870 structure, has less practical security value that the use of an RSA- 871 SHA-256 or ED25519-SHA-256 subfulfillment. Since the subfulfillment 872 is a PREIMAGE-SHA-256, the validation of which ignores the incoming 873 message, as long as the prefix, maxMessagelength and preimage 874 provided in the subfulfillment are correct, the parent PREFIX-SHA-256 875 fulfillment will validate. 877 In this case, wrapping the PREIMAGE-SHA-256 crypto-condition in the 878 PREFIX-SHA-256 crypto-condition, has the effect of enforcing a 879 message length of 0 bytes. 881 Note also, any change to the PREFIX-SHA-256 crypto-condition's prefix 882 and maxMessageLength values result in a different fingerprint value, 883 effectively namespacing the underlying preimage and re-hashing it. 884 The result is a new crypto-condition with a new and unique 885 fingerprint with no change to the underlying sub-crypto-condition. 887 8.3. THRESHOLD-SHA-256 889 THRESHOLD-SHA-256 is assigned the type ID 2. It relies on the 890 availability of the SHA-256 digest algorithm and any other algorithms 891 required by any of its sub-crypto-conditions as it is a compound 892 crypto-condition type. 894 8.3.1. Cost 896 The cost is the sum of the F.threshold largest cost values of all 897 sub-conditions, added to 1024 times the total number of sub- 898 conditions. 900 cost = (sum of largest F.threshold subcondition.cost values) + 1024 * F.subconditions.count 902 For example, if a threshold crypto-condition contains 5 sub- 903 conditions with costs of 64, 64, 82, 84 and 84 and has a threshold of 904 3, the cost is equal to the sum of the largest three sub-condition 905 costs (82 + 84 + 84 = 250) plus 1024 times the number of sub- 906 conditions (1024 * 5 = 5120): 5370 908 8.3.2. ASN.1 910 -- Condition Fingerprint 911 ThresholdFingerprintContents ::= SEQUENCE { 912 threshold INTEGER (1..65535), 913 subconditions SET OF Condition 914 } 916 -- Fulfillment 917 ThresholdFulfillment ::= SEQUENCE { 918 subfulfillments SET OF Fulfillment, 919 subconditions SET OF Condition 920 } 922 8.3.3. Condition Format 924 The fingerprint of a THRESHOLD-SHA-256 condition is the SHA-256 925 digest of the DER encoded fingerprint contents which are a SEQUENCE 926 of: 928 threshold A number that MUST be an integer in the range 1 ... 65535. 929 In order to fulfill a threshold condition, the count of the sub- 930 fulfillments MUST be equal to the threshold. 932 subconditions The set of sub-conditions, F.threshold of which MUST 933 be satisfied by valid sub-fulfillments provided in the 934 fulfillment. The SET of DER encoded sub-conditions is sorted 935 according to the DER encoding rules for a SET, in lexicographic 936 (big-endian) order, smallest first as defined in section 11.6 of 937 [itu.X690.2015]. 939 8.3.4. Fulfillment Format 941 The fulfillment of a THRESHOLD-SHA-256 crypto-condition is a 942 ThresholdFulfillment which is a SEQUENCE of: 944 subfulfillments A SET OF fulfillments. The number of elements in 945 this set is equal to the threshold therefore implementations must 946 use the length of this SET as the threshold value when deriving 947 the fingerprint of this crypto-condition. 949 subconditions A SET OF conditions. This is the list of unfulfilled 950 sub-conditions. This list must be combined with the list of 951 conditions derived from the subfulfillments and the combined list, 952 sorted, and used as the subconditions value when deriving the 953 fingerprint of this crypto-condition. 955 This may be an empty list. 957 8.3.5. Validating 959 A THRESHOLD-SHA-256 fulfillment is valid iff : 961 1. All F.subfulfillments are valid. 963 2. D is equal to C. 965 8.3.6. Example 967 exampleThresholdCondition Condition ::= 968 thresholdSha256 : { 969 fingerprint 'B4B84136 DF48A71D 73F4985C 04C6767A 778ECB65 BA7023B4 506823BE EE7631B9'H, 970 cost 1024, 971 subtypes { preimageSha256 } 972 } 974 exampleThresholdFulfillment Fulfillment ::= 975 thresholdSha256 : { 976 subfulfillments { preimageSha256 : { preimage ''H } }, 977 subconditions { } 978 } 980 exampleThresholdFingerprintContents ThresholdFingerprintContents ::= { 981 threshold 1, 982 subconditions { 983 preimageSha256 : { 984 fingerprint 'E3B0C442 98FC1C14 9AFBF4C8 996FB924 27AE41E4 649B934C A495991B 7852B855'H, 985 cost 0 986 } 987 } 988 } 990 exampleThresholdCondition2 Condition ::= 991 thresholdSha256 : { 992 fingerprint '5A218ECE 7AC4BC77 157F04CB 4BC8DFCD 5C9D225A 55BD0AA7 60BCA2A4 F1773DC6'H, 993 cost 2060, 994 subtypes { preimageSha256 } 995 } 997 exampleThresholdFulfillment2 Fulfillment ::= 998 thresholdSha256 : { 999 subfulfillments { preimageSha256 : { preimage ''H } }, 1000 subconditions { 1001 preimageSha256 : { 1002 fingerprint '7F83B165 7FF1FC53 B92DC181 48A1D65D FC2D4B1F A3D67728 4ADDD200 126D9069'H, 1003 cost 12 1004 } 1005 } 1006 } 1008 exampleThresholdFingerprintContents2 ThresholdFingerprintContents ::= { 1009 threshold 1, 1010 subconditions { 1011 preimageSha256 : { 1012 fingerprint 'E3B0C442 98FC1C14 9AFBF4C8 996FB924 27AE41E4 649B934C A495991B 7852B855'H, 1013 cost 0 1014 }, 1015 preimageSha256 : { 1016 fingerprint '7F83B165 7FF1FC53 B92DC181 48A1D65D FC2D4B1F A3D67728 4ADDD200 126D9069'H, 1017 cost 12 1018 } 1019 } 1020 } 1021 8.4. RSA-SHA-256 1023 RSA-SHA-256 is assigned the type ID 3. It relies on the SHA-256 1024 digest algorithm and the RSA-PSS signature scheme. 1026 The signature algorithm used is RSASSA-PSS as defined in PKCS#1 v2.2. 1027 [RFC8017] 1029 Implementations MUST NOT use the default RSASSA-PSS-params. 1030 Implementations MUST use the SHA-256 hash algorithm and therefore, 1031 the same algorithm in the mask generation algorithm, as recommended 1032 in [RFC8017]. The algorithm parameters to use, as defined in 1033 [RFC4055] are: 1035 pkcs-1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) 1 } 1037 id-sha256 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 1 } 1039 sha256Identifier AlgorithmIdentifier ::= { 1040 algorithm id-sha256, 1041 parameters nullParameters 1042 } 1044 id-mgf1 OBJECT IDENTIFIER ::= { pkcs-1 8 } 1046 mgf1SHA256Identifier AlgorithmIdentifier ::= { 1047 algorithm id-mgf1, 1048 parameters sha256Identifier 1049 } 1051 rSASSA-PSS-SHA256-Params RSASSA-PSS-params ::= { 1052 hashAlgorithm sha256Identifier, 1053 maskGenAlgorithm mgf1SHA256Identifier, 1054 saltLength 20, 1055 trailerField 1 1056 } 1058 8.4.1. RSA Keys 1060 To optimize the RsaFulfillment, and enforce a public exponent value 1061 of 65537, only the RSA Public Key modulus is stored in the 1062 RsaFingerprintContents and RsaFulfillment. 1064 The modulus is stored as an OCTET STRING representing an unsigned 1065 integer (i.e. no sign byte) in big-endian byte-order, the most 1066 significant byte being the first in the string. 1068 Implementations MUST use moduli greater than 128 bytes (1017 bits) 1069 and smaller than or equal to 512 bytes (4096 bits.) Large moduli 1070 slow down signature verification which can be a denial-of-service 1071 vector. DNSSEC also limits the modulus to 4096 bits [RFC3110]. 1072 OpenSSL supports up to 16384 bits [OPENSSL-X509-CERT-EXAMPLES]. 1074 Implementations MUST use the value 65537 for the public exponent e as 1075 recommended in [RFC4871]. Very large exponents can be a DoS vector 1076 [LARGE-RSA-EXPONENTS] and 65537 is the largest Fermat prime, which 1077 has some nice properties [USING-RSA-EXPONENT-OF-65537]. 1079 The recommended modulus size as of 2016 is 2048 bits 1080 [KEYLENGTH-RECOMMENDATION]. In the future we anticipate an upgrade 1081 to 3072 bits which provides approximately 128 bits of security 1082 [NIST-KEYMANAGEMENT] (p. 64), about the same level as SHA-256. 1084 8.4.2. Cost 1086 The cost is the square of the RSA key modulus size (in bytes). 1088 cost = (modulus size in bytes) ^ 2 1090 8.4.3. ASN.1 1092 -- Condition Fingerprint 1093 RsaFingerprintContents ::= SEQUENCE { 1094 modulus OCTET STRING 1095 } 1097 -- Fulfillment 1098 RsaSha256Fulfillment ::= SEQUENCE { 1099 modulus OCTET STRING, 1100 signature OCTET STRING 1101 } 1103 8.4.4. Condition Format 1105 The fingerprint of an RSA-SHA-256 condition is the SHA-256 digest of 1106 the DER encoded fingerprint contents which is a SEQUENCE of a single 1107 element, the modulus of the RSA Key Pair. 1109 8.4.5. Fulfillment Format 1111 The fulfillment of an RSA-SHA-256 crypto-condition is an 1112 RsaSha256Fulfillment which is a SEQUENCE of: 1114 modulus The modulus of the RSA key pair used to sign and verify the 1115 signature provided. 1117 signature An octet string representing the RSA signature on the 1118 message M. 1120 Implementations MUST verify that the signature is numerically less 1121 than the modulus. 1123 Note that the message that has been signed is provided separately. 1124 If no message is provided, the message is assumed to be an octet 1125 string of length zero. 1127 8.4.6. Validating 1129 An RSA-SHA-256 fulfillment is valid iff : 1131 1. F.signature is valid for the message M, using the RSA public key 1132 with modulus = F.modulus and exponent = 65537 for verification. 1134 2. D is equal to C. 1136 8.4.7. Example 1137 exampleRsaCondition Condition ::= 1138 rsaSha256 : { 1139 fingerprint 'B31FA820 6E4EA7E5 15337B3B 33082B87 76518010 85ED84FB 4DAEB247 BF698D7F'H, 1140 cost 65536 1141 } 1143 exampleRsaSha256Fulfillment Fulfillment ::= 1144 rsaSha256 : { 1145 modulus 'E1EF8B24 D6F76B09 C81ED775 2AA262F0 44F04A87 4D43809D 31CEA612 F99B0C97 A8B43741 1146 53E3EEF3 D6661684 3E0E41C2 93264B71 B6173DB1 CF0D6CD5 58C58657 706FCF09 7F704C48 1147 3E59CBFD FD5B3EE7 BC80D740 C5E0F047 F3E85FC0 D7581577 6A6F3F23 C5DC5E79 7139A688 1148 2E38336A 4A5FB361 37620FF3 663DBAE3 28472801 862F72F2 F87B202B 9C89ADD7 CD5B0A07 1149 6F7C53E3 5039F67E D17EC815 E5B4305C C6319706 8D5E6E57 9BA6DE5F 4E3E57DF 5E4E072F 1150 F2CE4C66 EB452339 73875275 9639F025 7BF57DBD 5C443FB5 158CCE0A 3D36ADC7 BA01F33A 1151 0BB6DBB2 BF989D60 7112F234 4D993E77 E563C1D3 61DEDF57 DA96EF2C FC685F00 2B638246 1152 A5B309B9'H, 1153 signature '48E8945E FE007556 D5BF4D5F 249E4808 F7307E29 511D3262 DAEF61D8 8098F9AA 4A8BC062 1154 3A8C9757 38F65D6B F459D543 F289D73C BC7AF4EA 3A33FBF3 EC444044 7911D722 94091E56 1155 1833628E 49A772ED 608DE6C4 4595A91E 3E17D6CF 5EC3B252 8D63D2AD D6463989 B12EEC57 1156 7DF64709 60DF6832 A9D84C36 0D1C217A D64C8625 BDB594FB 0ADA086C DECBBDE5 80D424BF 1157 9746D2F0 C312826D BBB00AD6 8B52C4CB 7D47156B A35E3A98 1C973863 792CC80D 04A18021 1158 0A524158 65B64B3A 61774B1D 3975D78A 98B0821E E55CA0F8 6305D425 29E10EB0 15CEFD40 1159 2FB59B2A BB8DEEE5 2A6F2447 D2284603 D219CD4E 8CF9CFFD D5498889 C3780B59 DD6A57EF 1160 7D732620'H 1161 } 1163 exampleRsaFingerprintContents RsaFingerprintContents ::= { 1164 modulus 'E1EF8B24 D6F76B09 C81ED775 2AA262F0 44F04A87 4D43809D 31CEA612 F99B0C97 A8B43741 1165 53E3EEF3 D6661684 3E0E41C2 93264B71 B6173DB1 CF0D6CD5 58C58657 706FCF09 7F704C48 1166 3E59CBFD FD5B3EE7 BC80D740 C5E0F047 F3E85FC0 D7581577 6A6F3F23 C5DC5E79 7139A688 1167 2E38336A 4A5FB361 37620FF3 663DBAE3 28472801 862F72F2 F87B202B 9C89ADD7 CD5B0A07 1168 6F7C53E3 5039F67E D17EC815 E5B4305C C6319706 8D5E6E57 9BA6DE5F 4E3E57DF 5E4E072F 1169 F2CE4C66 EB452339 73875275 9639F025 7BF57DBD 5C443FB5 158CCE0A 3D36ADC7 BA01F33A 1170 0BB6DBB2 BF989D60 7112F234 4D993E77 E563C1D3 61DEDF57 DA96EF2C FC685F00 2B638246 1171 A5B309B9'H 1172 } 1174 8.5. ED25519-SHA256 1176 ED25519-SHA-256 is assigned the type ID 4. It relies on the SHA-256 1177 and SHA-512 digest algorithms and the ED25519 signature scheme. 1179 The exact algorithm and encodings used for the public key and 1180 signature are defined in [I-D.irtf-cfrg-eddsa] as Ed25519. SHA-512 1181 is used as the hashing function for this signature scheme. 1183 8.5.1. Cost 1185 The public key and signature are a fixed size therefore the cost for 1186 an ED25519 crypto-condition is fixed at 131072. 1188 cost = 131072 1190 8.5.2. ASN.1 1192 -- Condition Fingerprint 1193 Ed25519Sha512Fulfillment ::= SEQUENCE { 1194 publicKey OCTET STRING (SIZE(32)), 1195 signature OCTET STRING (SIZE(64)) 1196 } 1198 -- Fulfillment 1199 Ed25519FingerprintContents ::= SEQUENCE { 1200 publicKey OCTET STRING (SIZE(32)) 1201 } 1203 8.5.3. Condition Format 1205 The fingerprint of an ED25519-SHA-256 condition is the SHA-256 digest 1206 of the DER encoded Ed25519 public key included as the only value 1207 within a SEQUENCE. While the public key is already very small and 1208 constant size, we wrap it in a SEQUENCE type and hash it for 1209 consistency with the other types. 1211 8.5.4. Fulfillment 1213 The fulfillment of an ED25519-SHA-256 crypto-condition is an 1214 Ed25519Sha512Fulfillment which is a SEQUENCE of: 1216 publicKey An octet string containing the Ed25519 public key. 1218 signature An octet string containing the Ed25519 signature. 1220 8.5.5. Validating 1222 An ED25519-SHA-256 fulfillment is valid iff : 1224 1. F.signature is valid for the message M, given the ED25519 public 1225 key F.publicKey. 1227 2. D is equal to C. 1229 8.5.6. Example 1231 exampleEd25519Condition Condition ::= 1232 ed25519Sha256 : { 1233 fingerprint '799239AB A8FC4FF7 EABFBC4C 44E69E8B DFED9933 24E12ED6 4792ABE2 89CF1D5F'H, 1234 cost 131072 1235 } 1237 exampleEd25519Fulfillment Fulfillment ::= 1238 ed25519Sha256 : { 1239 publicKey 'D75A9801 82B10AB7 D54BFED3 C964073A 0EE172F3 DAA62325 AF021A68 F707511A'H, 1240 signature 'E5564300 C360AC72 9086E2CC 806E828A 84877F1E B8E5D974 D873E065 22490155 1241 5FB88215 90A33BAC C61E3970 1CF9B46B D25BF5F0 595BBE24 65514143 8E7A100B'H 1242 } 1244 exampleEd25519FingerprintContents Ed25519FingerprintContents ::= { 1245 publicKey 'D75A9801 82B10AB7 D54BFED3 C964073A 0EE172F3 DAA62325 AF021A68 F707511A'H 1246 } 1248 9. URI Encoding Rules 1250 Conditions can be encoded as URIs per the rules defined in the Named 1251 Information specification, [RFC6920]. There are no URI encoding 1252 rules for fulfillments. 1254 Applications that require a string encoding for fulfillments MUST use 1255 an appropriate string encoding of the DER encoded binary 1256 representation of the fulfillment. No string encoding is defined in 1257 this specification. For consistency with the URI encoding of 1258 conditions, BASE64URL is recommended as described in [RFC4648], 1259 Section 5. 1261 The URI encoding is only used to encode top-level conditions and 1262 never for sub-conditions. The binary encoding is considered the 1263 canonical encoding. 1265 9.1. Condition URI Format 1267 Conditions are represented as URIs using the rules defined in 1268 [RFC6920] where the object being hashed is the DER encoded 1269 fingerprint content of the condition as described for the specific 1270 condition type. 1272 While [RFC6920] allows for truncated hashes, implementations using 1273 the Named Information URI schemes for crypto-conditions MUST only use 1274 untruncated SHA-256 hashes (Hash Name: sha-256, ID: 1 from the "Named 1275 Information Hash Algorithm Registry" defined in [RFC6920]). 1277 9.2. New URI Parameter Definitions 1279 [RFC6920] established the IANA registry of "Named Information URI 1280 Parameter Definitions". This specification defines three new 1281 definitions that are added to that registry and passed in URI encoded 1282 conditions as query string parameters. 1284 9.2.1. Parameter: Fingerprint Type (fpt) 1286 The type parameter indicates the type of condition that is 1287 represented by the URI. The value MUST be one of the names from the 1288 Crypto-Condition Type Registry (Appendix D.1). 1290 9.2.2. Parameter: Cost (cost) 1292 The cost parameter is the cost of the condition that is represented 1293 by the URI. 1295 9.2.3. Parameter: Subtypes (subtypes) 1297 The subtypes parameter indicates the types of conditions that are 1298 subtypes of the condition represented by the URI. The value MUST be 1299 a comma seperated list of names from the Crypto-Condition Type 1300 Registry (Appendix D.1). 1302 The list MUST exclude the type of the root crypto-condition. i.e. The 1303 value of the fpt parameter should not appear in the list of types 1304 provided as the value of the subtypes parameter. 1306 The list MUST be ordered by the type id value of each type, in 1307 ascending order. i.e. preimage-sha-256 MUST appear before prefix-sha- 1308 256. 1310 The commas in the list should be treated as reserved characters per 1311 [RFC3986]and not be percent encoded when used as list delimiters in 1312 the subtypes parameter. 1314 10. Example Condition 1316 An example condition (PREIMAGE-SHA-256): 1318 0x00000000 A0 25 80 20 7F 83 B1 65 7F F1 FC 53 B9 2D C1 81 .%.....e...S.-.. 1319 0x00000010 48 A1 D6 5D FC 2D 4B 1F A3 D6 77 28 4A DD D2 00 H..].-K...w(J... 1320 0x00000020 12 6D 90 69 81 01 0C .m.i... 1322 ni:///sha-256;f4OxZX_x_FO5LcGBSKHWXfwtSx-j1ncoSt3SABJtkGk?fpt=preimage-sha-256&cost=12 1324 The example has the following attributes: 1326 +-----------+--------------------------------------+----------------+ 1327 | Field | Value | Description | 1328 +-----------+--------------------------------------+----------------+ 1329 | scheme | "ni:///" | The named | 1330 | | | information | 1331 | | | scheme. | 1332 | | | | 1333 | hash | "sha-256" | The | 1334 | function | | fingerprint is | 1335 | name | | hashed with | 1336 | | | the SHA-256 | 1337 | | | digest | 1338 | | | function | 1339 | | | | 1340 | fingerpri | "f4OxZX_x_FO5LcGBSKHWXfwtSx- | The | 1341 | nt | j1ncoSt3SABJtkGk" | fingerprint | 1342 | | | for this | 1343 | | | condition. | 1344 | | | | 1345 | type | "preimage-sha-256" | This is a | 1346 | | | PREIMAGE- | 1347 | | | SHA-256 | 1348 | | | (Section 8.1) | 1349 | | | condition. | 1350 | | | | 1351 | cost | "12" | The | 1352 | | | fulfillment | 1353 | | | payload is 12 | 1354 | | | bytes long, | 1355 | | | therefore the | 1356 | | | cost is 12. | 1357 +-----------+--------------------------------------+----------------+ 1359 11. References 1361 11.1. Normative References 1363 [I-D.irtf-cfrg-eddsa] 1364 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 1365 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-08 1366 (work in progress), August 2016. 1368 [itu.X680.2015] 1369 International Telecommunications Union, "Information 1370 technology - Abstract Syntax Notation One (ASN.1): 1371 Specification of basic notation", August 2015, 1372 . 1374 [itu.X690.2015] 1375 International Telecommunications Union, "Information 1376 technology - ASN.1 encoding rules: Specification of Basic 1377 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1378 Distinguished Encoding Rules (DER)", August 2015, 1379 . 1381 [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet 1382 X.509 Public Key Infrastructure Certificate and 1383 Certificate Revocation List (CRL) Profile", RFC 3280, 1384 DOI 10.17487/RFC3280, April 2002, 1385 . 1387 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1388 Resource Identifier (URI): Generic Syntax", STD 66, 1389 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1390 . 1392 [RFC4055] Schaad, J., Kaliski, B., and R. Housley, "Additional 1393 Algorithms and Identifiers for RSA Cryptography for use in 1394 the Internet X.509 Public Key Infrastructure Certificate 1395 and Certificate Revocation List (CRL) Profile", RFC 4055, 1396 DOI 10.17487/RFC4055, June 2005, 1397 . 1399 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1400 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1401 . 1403 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 1404 Keranen, A., and P. Hallam-Baker, "Naming Things with 1405 Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, 1406 . 1408 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 1409 "PKCS #1: RSA Cryptography Specifications Version 2.2", 1410 RFC 8017, DOI 10.17487/RFC8017, November 2016, 1411 . 1413 11.2. Informative References 1415 [KEYLENGTH-RECOMMENDATION] 1416 "BlueKrypt - Cryptographic Key Length Recommendation", 1417 September 2015, . 1419 [LARGE-RSA-EXPONENTS] 1420 "Imperial Violet - Very large RSA public exponents (17 Mar 1421 2012)", March 2012, 1422 . 1424 [NIST-KEYMANAGEMENT] 1425 and , "NIST - Recommendation for Key Management - Part 1 - 1426 General (Revision 3)", July 2012, 1427 . 1430 [OPENSSL-X509-CERT-EXAMPLES] 1431 "OpenSSL - X509 certificate examples for testing and 1432 verification", July 2012, 1433 . 1435 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1436 Requirement Levels", BCP 14, RFC 2119, 1437 DOI 10.17487/RFC2119, March 1997, 1438 . 1440 [RFC3110] Eastlake 3rd, D., "RSA/SHA-1 SIGs and RSA KEYs in the 1441 Domain Name System (DNS)", RFC 3110, DOI 10.17487/RFC3110, 1442 May 2001, . 1444 [RFC4871] Allman, E., Callas, J., Delany, M., Libbey, M., Fenton, 1445 J., and M. Thomas, "DomainKeys Identified Mail (DKIM) 1446 Signatures", RFC 4871, DOI 10.17487/RFC4871, May 2007, 1447 . 1449 [USING-RSA-EXPONENT-OF-65537] 1450 "Cryptography - StackExchange - Impacts of not using RSA 1451 exponent of 65537", November 2014, 1452 . 1455 Appendix A. Security Considerations 1457 This specification has a normative dependency on a number of other 1458 specifications with extensive security considerations therefore the 1459 consideratons defined for SHA-256 hashing and RSA signatures in 1460 [RFC8017] and [RFC4055] and for ED25519 signatures in 1461 [I-D.irtf-cfrg-eddsa] must be considered. 1463 The cost and subtypes values of conditions are provided to allow 1464 implementations to evaluate their ability to validate a fulfillment 1465 for the given condition later. 1467 Appendix B. Test Values 1469 This section to be expanded in a later draft. 1471 For now, see the test cases for the reference implementation: 1472 https://github.com/interledger/five-bells-condition/tree/master/test 1474 Appendix C. ASN.1 Module 1476 ---- 1478 Crypto-Conditions DEFINITIONS AUTOMATIC TAGS ::= BEGIN 1480 -- Conditions 1482 Condition ::= CHOICE { 1483 preimageSha256 [0] SimpleSha256Condition, 1484 prefixSha256 [1] CompoundSha256Condition, 1485 thresholdSha256 [2] CompoundSha256Condition, 1486 rsaSha256 [3] SimpleSha256Condition, 1487 ed25519Sha256 [4] SimpleSha256Condition 1488 } 1490 SimpleSha256Condition ::= SEQUENCE { 1491 fingerprint OCTET STRING (SIZE(32)), 1492 cost INTEGER (0..4294967295) 1493 } 1495 CompoundSha256Condition ::= SEQUENCE { 1496 fingerprint OCTET STRING (SIZE(32)), 1497 cost INTEGER (0..4294967295), 1498 subtypes ConditionTypes 1499 } 1501 ConditionTypes ::= BIT STRING { 1502 preImageSha256 (0), 1503 prefixSha256 (1), 1504 thresholdSha256 (2), 1505 rsaSha256 (3), 1506 ed25519Sha256 (4) 1507 } 1509 -- Fulfillments 1511 Fulfillment ::= CHOICE { 1512 preimageSha256 [0] PreimageFulfillment , 1513 prefixSha256 [1] PrefixFulfillment, 1514 thresholdSha256 [2] ThresholdFulfillment, 1515 rsaSha256 [3] RsaSha256Fulfillment, 1516 ed25519Sha256 [4] Ed25519Sha512Fulfillment 1517 } 1519 PreimageFulfillment ::= SEQUENCE { 1520 preimage OCTET STRING 1521 } 1523 PrefixFulfillment ::= SEQUENCE { 1524 prefix OCTET STRING, 1525 maxMessageLength INTEGER (0..4294967295), 1526 subfulfillment Fulfillment 1527 } 1529 ThresholdFulfillment ::= SEQUENCE { 1530 subfulfillments SET OF Fulfillment, 1531 subconditions SET OF Condition 1532 } 1534 RsaSha256Fulfillment ::= SEQUENCE { 1535 modulus OCTET STRING, 1536 signature OCTET STRING 1537 } 1539 Ed25519Sha512Fulfillment ::= SEQUENCE { 1540 publicKey OCTET STRING (SIZE(32)), 1541 signature OCTET STRING (SIZE(64)) 1542 } 1544 -- Fingerprint Content 1546 -- The PREIMAGE-SHA-256 condition fingerprint content is not DER encoded 1547 -- The fingerprint content is the preimage 1549 PrefixFingerprintContents ::= SEQUENCE { 1550 prefix OCTET STRING, 1551 maxMessageLength INTEGER (0..4294967295), 1552 subcondition Condition 1553 } 1555 ThresholdFingerprintContents ::= SEQUENCE { 1556 threshold INTEGER (1..65535), 1557 subconditions SET OF Condition 1558 } 1560 RsaFingerprintContents ::= SEQUENCE { 1561 modulus OCTET STRING 1562 } 1563 Ed25519FingerprintContents ::= SEQUENCE { 1564 publicKey OCTET STRING (SIZE(32)) 1565 } 1567 END 1569 Appendix D. IANA Considerations 1571 D.1. Crypto-Condition Type Registry 1573 The following initial entries should be added to the Crypto-Condition 1574 Type registry to be created and maintained at (the suggested URI) 1575 http://www.iana.org/assignments/crypto-condition-types: 1577 The following types are registered: 1579 +---------+-------------------+ 1580 | Type ID | Type Name | 1581 +---------+-------------------+ 1582 | 0 | PREIMAGE-SHA-256 | 1583 | | | 1584 | 1 | PREFIX-SHA-256 | 1585 | | | 1586 | 2 | THRESHOLD-SHA-256 | 1587 | | | 1588 | 3 | RSA-SHA-256 | 1589 | | | 1590 | 4 | ED25519 | 1591 +---------+-------------------+ 1593 Table 1: Crypto-Condition Types 1595 Authors' Addresses 1597 Stefan Thomas 1598 Ripple 1599 300 Montgomery Street 1600 San Francisco, CA 94104 1601 US 1603 Phone: ----------------- 1604 Email: stefan@ripple.com 1605 URI: https://www.ripple.com 1606 Rome Reginelli 1607 Ripple 1608 300 Montgomery Street 1609 San Francisco, CA 94104 1610 US 1612 Phone: ----------------- 1613 Email: rome@ripple.com 1614 URI: https://www.ripple.com 1616 Adrian Hope-Bailie 1617 Ripple 1618 300 Montgomery Street 1619 San Francisco, CA 94104 1620 US 1622 Phone: ----------------- 1623 Email: adrian@ripple.com 1624 URI: https://www.ripple.com