]>
Crypto-ConditionsRipple300 Montgomery StreetSan FranciscoCA94104US-----------------stefan@ripple.comhttps://www.ripple.comRipple300 Montgomery StreetSan FranciscoCA94104US-----------------rome@ripple.comhttps://www.ripple.comRipple300 Montgomery StreetSan FranciscoCA94104US-----------------adrian@ripple.comhttps://www.ripple.com
security
Crypto-conditions provide a mechanism to describe a signed message such that multiple actors in a distributed system can all verify the same signed message and agree on whether it matches the description. This provides a useful primitive for event-based systems that are distributed on the Internet since we can describe events in a standard deterministic manner (represented by signed messages) and therefore define generic authenticated event handlers.This specification is a part of the Interledger Protocol work. Feedback related to this specification should be sent to public-interledger@w3.org.This specification describes a message format for crypto-conditions and fulfillments, with binary and string-based encodings for each.Crypto-conditions are distributable event descriptions. This means crypto-conditions say how to recognize a message without saying exactly what the message is. You can transmit a crypto-condition freely, but you cannot forge the message it describes. For convenience, we hash the description so that the crypto-condition can be a fixed size.Fulfillments are cryptographically verifiable messages that prove an event occurred. If you transmit a fulfillment, then everyone who has the condition can agree that the condition has been met.In the Interledger protocol, crypto-conditions and fulfillments provide irrepudiable proof that a transfer occurred in one ledger, as messages that can be easily shared with other ledgers. This allows ledgers to escrow funds or hold a transfer conditionally, then execute the transfer automatically when the ledger sees the fulfillment of the stated condition.Crypto-conditions may also be useful in other contexts where a system needs to make a decision based on predefined criteria, such as smart contracts.The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .Within this specification, the term "condition" refers to the hash of a description of a signed message. The hash function must be preimage-resistant.The term "fulfillment" refers to a description of a signed message and a signed message that matches the description. We hash the description and compare that to the condition, and also compare the signed message to the description. If the message matches the description and the hash of the description matches the condition, we say that the fulfillment fulfills the condition.In the simplest case, the fulfillment can be a preimage that hashes to the condition, in which case the preimage is both the description and the message.Crypto-conditions are a standard format for expressing conditions and fulfillments. The format supports multiple algorithms, including different hash functions and cryptographic signing schemes. Crypto-conditions can be nested in multiple levels, with each level possibly having multiple signatures.This format has been designed so that it can be expanded. For example, you can add new cryptographic signature schemes or hash functions. This is important because advances in cryptography frequently render old algorithms insecure or invent newer, more effective algorithms.The of a crypto-condition indicates which algorithms it uses, so a compliant implementation can know whether it supports the functionality required to interpret the crypto-condition.The crypto-condition format contains a that specifies which hash function and signing scheme to use. Any message format for a condition or a fulfillment contains such a bitmask.Implementations MAY state their supported algorithms by providing a bitmask in the same format. To verify that a given implementation can verify a fulfillment for a given condition, you compare the bitmasks. If all bits set in the condition's bitmask are also set in the implementation's bitmask, then the implementation can verify the condition's fulfillment.Crypto-conditions can abstract away many of the details of multi-sign. When a party provides a condition, other parties can treat it opaquely and do not need to know about its internal structure. That allows parties to define arbitrary multi-signature setups without breaking compatibility.Protocol designers can use crypto-conditions as a drop-in replacement for public key signature algorithms and add multi-signature support to their protocols without adding any additional complexity.Crypto-conditions elegantly support weighted multi-signatures and multi-level signatures. A threshold condition has a number of weighted subconditions, and a target threshold. Each subcondition can be a signature or another threshold condition. This provides flexibility in forming complex conditions.For example, consider a threshold condition that consists of two subconditions, one each from Agnes and Bruce. Agnes's condition can be a signature condition while Bruce's condition is a threshold condition, requiring both Claude and Dan to sign for him.Weighted signatures allow more complex relationships than simple M-of-N signing. For example, a weighted condition can support an arrangement of subconditions such as, "Either Ron, Adi, and Leonard must approve; or Clifford must approve."A description of crypto-conditions is provided in this document using Abstract Syntax Notation One (ASN.1) as defined in . Implementations of this spec MUST support encoding and decoding using Octet Encoding Rules (OER) as defined in .Crypto-conditions use the following types within string encoding:
Variable-length integer encoded as a base-10 (decimal) number. Implementations MUST reject encoded values that are too large for them to parse. Implementations MUST be tested for overflows.
Variable-length integer encoded as a base-16 (hexadecimal) number. Implementations MUST reject encoded values that are too large for them to parse. Implementations MUST be tested for overflows. No leading zeros.
Base64-URL encoding. See , Section 5.Any system that accepts crypto-conditions must be able to state its supported algorithms. It must be possible to verify that all algorithms used in a certain condition are indeed supported even if the fulfillment is not available yet. Therefore, all conditions and fulfillments contain a bitmask to express the required features. Implementations provide a bitmask of features they support.Each bit represents a different suite of features. Each type of crypto-condition depends on one or more feature suites. If an implementation supports all feature suites that a certain type depends on, the implementation MUST support that condition type. The list of known types and feature suites is the IANA-maintained Crypto-Condition Type Registry .To save space, the bitmask is encoded as a variable-length integer.Below are the string and binary encoding formats for a condition.Conditions are ASCII encoded as:Conditions are binary encoded as:
is the numeric type identifier representing the condition type.
is an unsigned integer encoding the set of feature suites an implementation must support in order to be able to successfully parse the fulfillment to this condition. This is the boolean OR of the featureBitmask values of the top-level condition type and all subcondition types, recursively.
is an octet string uniquely representing the condition with respect to other conditions of the same type. Implementations which index conditions MUST use the entire string or binary encoded condition as the key, not just the fingerprint - as different conditions of different types may have the same fingerprint. The length and contents of the fingerprint are defined by the condition type. For most condition types, the fingerprint is a cryptographically secure hash of the data which defines the condition, such as a public key. This is encoded as a variable length octet string as different condition types may use different functions to produce the fingerprint which may therefore have different lengths. While it would be possible to determine the expected length of the fingerprint based on the type it is useful to be able to decode a condition even if the type is not recognized.
is the maximum length of the fulfillment payload that can fulfill this condition, in bytes. The payload size is measured unencoded. (The size of the payload is larger in BASE64URL format.) When a crypto-condition is submitted to an implementation, this implementation MUST verify that it will be able to process a fulfillment with a payload of size maxFulfillmentLength.An example condition in string format:The example has the following attributes:FieldValueDescriptionprefaceccConstant. Indicates this is a condition.type0Type 0 is [PREIMAGE-SHA-256][].featuresBitmask3Boolean-OR combination of feature suites SHA-256 (feature bit 0x01) and PREIMAGE (feature bit 0x02).fingerprintdB-8fb14MdO75Brp_Pvh4d7ganckilrRl13RS_UmrXAThe hash of the fulfillment for this condition.maxFulfillmentLength66The fulfillment payload is 66 bytes long, before being BASE64URL-encoded.Below are the string and binary encoding formats for a fulfillment.Fulfillments are ASCII encoded as:Fulfillments are binary encoded as:
is the numeric type identifier representing the condition type. For some condition types the fulfillment will contain further subfulfillments, however the type field always represents the outermost, or top-level, type.
The payload is an octet string whose internal format is defined by each of the types.The following is an example fulfillment in string format, for the example condition:The example has the following attributes:FieldValueDescriptionprefacecfConstant. Indicates this is a fulfillment.type0Type 0 is [PREIMAGE-SHA-256][].payloadVGhlIG...pbGRlThe BASE64URL-encoded SHA-256 preimage of the condition, since this is a PREIMAGE-SHA-256 type fulfillment. In this case, it is an arbitrary string.This specification defines a starting set of feature suites necessary to support the [Condition Types][] also defined in this specification. Future versions of this spec MAY introduce new feature suites and condition types, which SHALL be registered in the IANA maintained Crypto-Condition Type Registry.Support for a condition type MUST depend on one or more feature suites. However, all new condition types MUST depend on at least one of the new feature suites. This ensures that all previously created implementations correctly recognize that they do not support the new type.Feature suites are chosen such that they represent reasonable clusters of functionality. For instance, it is reasonable to require that an implementation which supports SHA-256 in one context MUST support it in all contexts, since it already needed to implement the algorithm.An implementation which supports a certain set of feature suites MUST accept all condition types which depend only on that set or any subset of feature suites.Suite NameFeature BitFeature Bit (BASE16)SummarySHA-2562^00x01The SHA-256 hashing algorithm.PREIMAGE2^10x02The functionality of comparing a hash to a preimage.PREFIX2^20x04The functionality of prefixing the fulfillment with a prefix before generating the condition.THRESHOLD2^30x08The functionality of composing a condition out of several weighted subconditions.RSA-PSS2^40x10The RSA-PSS signature algorithm.ED255192^50x20The ED25519 signature algorithm.The SHA-256 feature suite provides the SHA-256 hash function. SHA-256 is a cryptographic hash function published by the US National Institute of Standards and Technology that produces 256 bits of output. This feature suite is assigned the feature bit 2^0 = 0x01.The PREIMAGE feature suite provides conditions that use a preimage as a one-time signature. This feature suite is assigned the feature bit 2^1 = 0x02.The fingerprint of a preimage condition is the hash of an arbitrary value. The payload of a preimage fulfillment is the hashed arbitrary value before hashing, also known as the preimage. Conditions that use this preimage MUST also rely on a cryptographically secure hashing algorithm. Since cryptographically secure hashing functions are preimage-resistant, only the original creator of a preimage condition can produce the preimage, as long as it contains a large amount of random entropy.The PREFIX feature suite provides conditions that prepend a fixed message to a subcondition. This feature suite is assigned the feature bit 2^2 = 0x04.A prefix condition prepends the message to be validated with a constant string before passing it on to the subcondition's validation function. The THRESHOLD feature suite provides conditions that have several weighted subconditions and a threshold number. This feature suite is assigned the feature bit 2^3 = 0x08.Threshold conditions provide flexible multi-signing, such as requiring "M-of-N" subconditions be fulfilled. Subconditions can also be weighted so that one subcondition can count multiple times towards meeting the threshold.The RSA-PSS feature suite provides the RSS-PSA signature algorithm. RSA-PSS is a signature algorithm based on the RSA cryptosystem, which relates to the problem of factoring the product of two large prime numbers. This feature suite is assigned the feature bit 2^4 = 0x10.The ED25519 feature suite provides the Ed25519 signature algorithm. Ed25519 is a signature algorithm based on the EdDSA signing scheme and the compact elliptic curve known as Ed25519. This feature suite is assigned the feature bit 2^5 = 0x20.The following condition types are defined in this version of the specification. Future versions of this spec MAY introduce new feature suites and condition types, which SHALL be registered in the IANA maintained Crypto-Condition Type Registry.PREIMAGE-SHA-256 is assigned the type ID 0. It relies on the SHA-256 and PREIMAGE feature suites which corresponds to a feature bitmask of 0x03.This type of condition is also called a "hashlock". By creating a hash of a difficult-to-guess 256-bit random or pseudo-random integer it is possible to create a condition which the creator can trivially fulfill by publishing the random value. However, for anyone else, the condition is cryptographically hard to fulfill, because they would have to find a preimage for the given condition hash.Implementations MUST ignore any input message when validating a PREIMAGE-SHA-256 fulfillment.The fingerprint of a PREIMAGE-SHA-256 condition is the SHA-256 hash of the preimage.The fulfillment payload of a PREIMAGE-SHA-256 condition is the preimage.Example condition:Example fulfillment:PREFIX-SHA-256 is assigned the type ID 1. It relies on the SHA-256 and PREFIX feature suites which corresponds to a feature bitmask of 0x05.Prefix conditions provide a way to effective narrow the scope of other conditions. A condition can be used as the fingerprint of a public key to sign an arbitrary message. By creating a prefix subcondition we can narrow the scope from signing an arbitrary message to signing a message with a specific prefix.When a prefix fulfillment is validated against a message, it will prepend the prefix to the provided message and will use the result as the message to validate against the subfulfillment.The fingerprint of a PREFIX-SHA-256 condition is the SHA-256 digest of the fingerprint contents given below:
is an arbitrary octet string which will be prepended to the message during validation.
is the subcondition which the subfulfillment must match.
is an arbitrary octet string which will be prepended to the message during validation.
is the fulfilled subcondition.Example condition:Example fulfillment:THRESHOLD-SHA-256 is assigned the type ID 2. It relies on the SHA-256 and THRESHOLD feature suites which corresponds to a feature bitmask of 0x09.The fingerprint of a THRESHOLD-SHA-256 condition is the SHA-256 digest of the fingerprint contents given below:The list of conditions is sorted first based on length, shortest first. Elements of the same length are sorted in lexicographic (big-endian) order, smallest first.
threshold MUST be an integer in the range 1 … 2^32 - 1. In order to fulfill a threshold condition, the weights of the provided fulfillments MUST be greater than or equal to the threshold.
is the set of subconditions, each provided as a tuple of weight and condition.
is the numeric weight of this subcondition, i.e. how many times it counts against the threshold.
is the subcondition.
is a number and MUST be an integer in the range 1 … 2^32 - 1. In order to fulfill a threshold condition, the weights of the provided fulfillments MUST be greater than or equal to the threshold.
is the set of subconditions and subfulfillments, each provided as a tuple of weight and condition or fulfillment.
is the numeric weight of this subcondition, i.e. how many times it counts against the threshold. It MUST be an integer in the range 1 … 2^32 - 1.
is the subcondition if this subcondition is not fulfilled.
is the subfulfillment if this subcondition is fulfilled.Example condition:Example fulfillment:RSA-SHA-256 is assigned the type ID 3. It relies on the SHA-256 and RSA-PSS feature suites which corresponds to a feature bitmask of 0x11.The signature algorithm used is RSASSA-PSS as defined in PKCS#1 v2.2. Implementations MUST NOT use the default RSASSA-PSS-params. Implementations MUST use the SHA-256 hash algorithm and therefor, the same algorithm in the mask generation algorithm, as recommended in . Implementations MUST also use a salt length of 32 bytes (equal to the size of the output from the SHA-256 algorithm). Therefore the algorithm identifier will have the following value:The fingerprint of a RSA-SHA-256 condition is the SHA-256 digest of the fingerprint contents given below:
is an octet string representing the RSA public modulus in big-endian byte order. The first byte of the modulus MUST NOT be zero.The corresponding public exponent e is assumed to be 65537 as recommended in . Very large exponents can be a DoS vector and 65537 is the largest Fermat prime, which has some nice properties .Implementations MUST reject moduli smaller than 128 bytes (1017 bits) or greater than 512 bytes (4096 bits.) Large moduli slow down signature verification which can be a denial-of-service vector. DNSSEC also limits the modulus to 4096 bits . OpenSSL supports up to 16384 bits .
is an octet string representing the RSA public modulus in big-endian byte order. See
is an octet string representing the RSA signature. It MUST be encoded in big-endian byte order with the exact same number of octets as the modulus, even if this means adding leading zeros. This ensures that the fulfillment size is constant and known ahead of time. Note that the field is still binary encoded with a length prefix for consistency.Implementations MUST verify that the signature and modulus consist of the same number of octets and that the signature is numerically less than the modulus.The message to be signed is provided separately. If no message is provided, the message is assumed to be an octet string of length zero.The recommended modulus size as of 2016 is 2048 bits . In the future we anticipate an upgrade to 3072 bits which provides approximately 128 bits of security (p. 64), about the same level as SHA-256.Example condition:Example fulfillment:ED25519 is assigned the type ID 4. It relies only on the ED25519 feature suite which corresponds to a bitmask of 0x20.The exact algorithm and encodings used for public key and signature are defined in as Ed25519. SHA-512 is used as the hashing function.Note: This document is not defining the SHA-512 versions of other condition types. In addition, the Ed25519 condition type is already uniquely identified by a corresponding Ed25519 feature suite. Therefore we intentionally do not introduce a SHA-512 feature suite in this document.The fingerprint of a ED25519 condition is the 32 byte Ed25519 public key. Since the public key is already very small, we do not hash it.
is an octet string containing the Ed25519 public key.
is an octet string containing the Ed25519 signature.Example condition:Example fulfillment:
&RFC3447;
&RFC4648;
&I-D.draft-irtf-cfrg-eddsa-04;
Information technology – Abstract Syntax Notation One (ASN.1): Specification of basic notationInternational Telecommunications UnionInformation technology – ASN.1 encoding rules: Specification of Octet Encoding Rules (OER)International Telecommunications Union
&RFC2119;
&RFC3110;
&RFC4871;
Imperial Violet - Very large RSA public exponents (17 Mar 2012)Cryptography - StackExchange - Impacts of not using RSA exponent of 65537BlueKrypt - Cryptographic Key Length RecommendationNIST - Recommendation for Key Management - Part 1 - General (Revision 3)OpenSSL - X509 certificate examples for testing and verificationThis section to be expanded in a later draft. This section to be expanded in a later draft. For now, see the test cases for the reference implementation: https://github.com/interledger/five-bells-condition/tree/master/testThe following initial entries should be added to the Crypto-Condition Type registry to be created and maintained at (the suggested URI)
http://www.iana.org/assignments/crypto-condition-types:The following feature suite bits are registered:Type BitExp.HexFeature12^00x01SHA-256102^10x02PREIMAGE1002^20x04PREFIX10002^30x08THRESHOLD100002^40x10RSA1000002^50x20ED25519The following types are registered:Type IDRequired BitmaskType Name00x03PREIMAGE-SHA-25610x05PREFIX-SHA-25620x09THRESHOLD-SHA-25630x11RSA-SHA-25640x20ED25519