idnits 2.17.00 (12 Aug 2021) /tmp/idnits17792/draft-hargreaves-odap-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 7, 2021) is 188 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'JWT' is mentioned on line 193, but not defined == Missing Reference: 'RFC 1738' is mentioned on line 363, but not defined ** Obsolete undefined reference: RFC 1738 (Obsoleted by RFC 4248, RFC 4266) == Missing Reference: 'RFC 5939' is mentioned on line 511, but not defined == Missing Reference: 'RFC2616' is mentioned on line 1040, but not defined ** Obsolete undefined reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Unused Reference: 'RFC2234' is defined on line 1229, but no explicit reference was found in the text == Unused Reference: 'RFC7519' is defined on line 1233, but no explicit reference was found in the text == Unused Reference: 'HS2019' is defined on line 1245, but no explicit reference was found in the text == Unused Reference: 'NIST' is defined on line 1251, but no explicit reference was found in the text == Unused Reference: 'RFC5939' is defined on line 1261, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) == Outdated reference: A later version (-03) exists of draft-hardjono-blockchain-interop-arch-02 == Outdated reference: A later version (-03) exists of draft-belchior-gateway-recovery-01 Summary: 3 errors (**), 0 flaws (~~), 12 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M. Hargreaves 3 Internet-Draft Quant Network 4 Intended status: Informational T. Hardjono 5 Expires: May 11, 2022 MIT 6 R. Belchior 7 Technico Lisboa 8 November 7, 2021 10 Open Digital Asset Protocol 11 draft-hargreaves-odap-03 13 Abstract 15 This memo describes the Open Digital Asset Protocol (ODAP). ODAP is 16 an asset transfer protocol that operates between two gateway devices. 17 The protocol includes a description of virtual or digital assets held 18 on distributed ledgers in an open and interoperable format, a session 19 negotiation part and message passing flows between gateways 20 connecting disparate distributed ledger technologies (DLTs). 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on May 11, 2022. 39 Copyright Notice 41 Copyright (c) 2021 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Conventions used in this document . . . . . . . . . . . . . . 4 58 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 4. The Open Digital Asset Protocol . . . . . . . . . . . . . . . 5 60 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 5 61 4.2. ODAP Model . . . . . . . . . . . . . . . . . . . . . . . 5 62 4.3. Types of APIs . . . . . . . . . . . . . . . . . . . . . . 6 63 4.4. Types of Flows . . . . . . . . . . . . . . . . . . . . . 6 64 4.5. Resources and Identifiers . . . . . . . . . . . . . . . . 7 65 5. ODAP Message Format, identifiers and Descriptors . . . . . . 7 66 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 67 5.2. ODAP Message Format . . . . . . . . . . . . . . . . . . . 7 68 5.3. Digital Asset Resource Descriptors . . . . . . . . . . . 8 69 5.3.1. Organization Identifier . . . . . . . . . . . . . . . 8 70 5.3.2. DLT Gateway / Endpoint ID . . . . . . . . . . . . . . 9 71 5.3.3. DLT Identifier . . . . . . . . . . . . . . . . . . . 9 72 5.3.4. Resource . . . . . . . . . . . . . . . . . . . . . . 9 73 5.3.5. Examples . . . . . . . . . . . . . . . . . . . . . . 9 74 5.4. Digital Asset Resource Client Descriptors . . . . . . . . 9 75 5.4.1. Organization Identifier . . . . . . . . . . . . . . . 9 76 5.4.2. DLT Gateway / Endpoint ID . . . . . . . . . . . . . . 10 77 5.4.3. Organizational Unit . . . . . . . . . . . . . . . . . 10 78 5.4.4. Name . . . . . . . . . . . . . . . . . . . . . . . . 10 79 5.4.5. Examples . . . . . . . . . . . . . . . . . . . . . . 10 80 5.5. Gateway Level Access Control . . . . . . . . . . . . . . 10 81 5.6. Negotiation of Security Protocols and Parameters . . . . 11 82 5.6.1. TLS Established . . . . . . . . . . . . . . . . . . . 11 83 5.6.2. Client offers supported credential schemes . . . . . 11 84 5.6.3. Server selects supported credential scheme . . . . . 11 85 5.6.4. Client asserts of proves identity . . . . . . . . . . 12 86 5.6.5. Sequence numbers initialized . . . . . . . . . . . . 12 87 5.6.6. Messages can now be exchanged . . . . . . . . . . . . 12 88 5.7. Asset Profile Identification . . . . . . . . . . . . . . 12 89 5.8. Application Profile Negotiation . . . . . . . . . . . . . 12 90 5.9. Discovery of Digital Asset Interior Resources . . . . . . 13 91 5.10. Response Codes . . . . . . . . . . . . . . . . . . . . . 13 92 5.11. Backward Compatibility . . . . . . . . . . . . . . . . . 14 93 6. Transfer Initiation Flow (Phase 1) . . . . . . . . . . . . . 14 94 6.1. Initialization Request Message . . . . . . . . . . . . . 15 95 6.2. Initialization Request Message Response (ACK) . . . . . . 16 96 7. Lock-Evidence Verification Flow (Phase 2) . . . . . . . . . . 17 97 7.1. Transfer Commence Message . . . . . . . . . . . . . . . . 18 98 7.2. Transfer Commence Response Message (Ack) . . . . . . . . 19 99 7.3. Lock Evidence Message . . . . . . . . . . . . . . . . . . 21 100 7.4. Lock Evidence Response Message (Ack) . . . . . . . . . . 22 101 8. Commitment Establishment Flow (Phase 3) . . . . . . . . . . . 22 102 8.1. Commit Preparation Message . . . . . . . . . . . . . . . 23 103 8.2. Commit Preparation Response . . . . . . . . . . . . . . . 23 104 8.3. Commit Final Message . . . . . . . . . . . . . . . . . . 24 105 8.4. Commit Final Response Message . . . . . . . . . . . . . . 25 106 8.5. Transfer Complete Message . . . . . . . . . . . . . . . . 25 107 9. Security Consideration . . . . . . . . . . . . . . . . . . . 26 108 10. IANA Consideration . . . . . . . . . . . . . . . . . . . . . 26 109 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 110 11.1. Normative References . . . . . . . . . . . . . . . . . . 26 111 11.2. Informative References . . . . . . . . . . . . . . . . . 27 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 114 1. Introduction 116 There is a lack of interoperability between individual blockchains, 117 but also a general difficulty building open DLT networks. Extant 118 networks are custom built and relatively closed, usually limited to 119 networks of a single DLT type. 121 This memo proposes at DLT-agnostic protocol in order to allow the 122 creation of business applications that use and modify multiple DLTs, 123 through a single programmatic interface. 125 The target DLTs can be of any type, operated by different owners and 126 managed using different DLT interoperability and management platforms 127 that implement ODAP interfaces. 129 These platforms may act as gateways or relays for the application to 130 interact with the hosted DLTs. They are referred to herein as DLT 131 Gateways. 133 When correctly implemented and deployed, the protocol should provide 134 the basis for solutions involving asset migration between two DLT 135 systems, as well as use-cases when one side is non-DLT system (e.g. 136 legacy system). 138 This memo focuses on the core aspects of the ODAP protocol, with the 139 understanding that profiles of this core protocol would need to be 140 utilized for implementations that target specific use-cases and 141 employing different technologies to implement their DLT network. 143 The mechanisms used by client applications to interact with a sender 144 gateway is out of scope for this specification and will be specified 145 elsewhere. 147 2. Conventions used in this document 149 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 150 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 151 document are to be interpreted as described in RFC 2119 [RFC2119]. 153 In this document, these words will appear with that interpretation 154 only when in ALL CAPS. Lower case uses of these words are not to be 155 interpreted as carrying significance described in RFC 2119. 157 3. Terminology 159 The following are some terminology used in the current document. 160 Further terminology can be found in [Arch]. 162 Client application: This is the application employed by a user to 163 interact with a gateway node. 165 Gateway: The node of the DLT system functionally capable of acting as 166 a gateway in an asset transfer. 168 Sender gateway: The gateway that initiates a unidirectional asset 169 transfer. 171 Transfer client: An alternate name for the sender gateway (protocol 172 level). 174 Recipient gateway: The gateway that is the recipient side of a 175 unidirectional asset transfer. 177 Transfer server: An alternate name for the recipient gateway 178 (protocol level). 180 DLT resources: The various interior protocols, data structures and 181 cryptographic constructs that are a core part of a DLT system. 183 Off-DLT resources: The various resources that are outside a DLT 184 system, and are not part of the operations of the DLT system. 186 Role: As in the classic client-server roles. In the gateway-to- 187 gateway interaction, one gateway will take the role of the client 188 while the other takes the role of the server, depending on the type 189 of interaction flow. 191 Claim: An assertion made by an Entity [JWT]. 193 Claim Type: Syntax used for representing a Claim Value [JWT]. 195 DLT Claim: An assertion made by a Gateway regarding the status or 196 condition of resources (e.g. asset, public keys, etc.) accessible to 197 that gateway within its DLT system. 199 4. The Open Digital Asset Protocol 201 4.1. Overview 203 The Open Digital Asset Protocol (ODAP) is a gateway-to-gateway 204 protocol used by a sender gateway with a recipient gateway to perform 205 a unidirectional transfer of a virtual asset [Arch]. 207 The protocol defines a number of API endpoints, resources and 208 identifier definitions, and message flows corresponding to the asset 209 transfer between the two gateways. 211 +----------+ +----------+ 212 | Client | | Off-DLT | 213 | (Applic) | | Resource | 214 +----------+ +----------+ 215 | |API Type-3| 216 | +----------+ 217 | ^ 218 V | 219 +----------+ | 220 |API Type-1| | 221 +------+ +----------+----+ +----+----------+ +------+ 222 | | | | | | | | | | 223 | DLT | | Gateway |API | |API | Gateway | | DLT | 224 | L1 |---| G1 |Type|<------>|Type| G2 |---| L2 | 225 | | | | 2 | | 2 | | | | 226 +------+ +----------+----+ +----+----------+ +------+ 228 Figure 1 230 4.2. ODAP Model 232 Following the gateway interoperability architecture [Arch], the model 233 for ODAP is shown in Figure 1. 235 The Client (application) interacts with its local gateway (G1) over 236 an interface (API Type-1) in order to provide instructions directly 237 or indirectly to the gateway with regards to actions related 238 resources located in the local DLT system (L1) and resources located 239 in remote DLT system (L2). 241 Gateways interact with each other over a gateway interface (API Type- 242 2). A given gateway may be required to access resources that are not 243 located in DLT system L1 or DLT system L2. Access to these types of 244 resources are performed over an Off-DLT interface (API Type-3). 246 4.3. Types of APIs 248 The following are the types of APIs in ODAP: 250 o Gateway APIs for client (API Type-1): This the REST APIs that 251 permit a Client (application) to interact with a local gateway, 252 and issue instructions for actions pertaining to resources 253 accessible to the gateway in the local DLT system. 255 o Gateway APIs for peer gateways (API Type-2): This is the REST APIs 256 employed by two (2) peer gateways in performing unidirectional 257 asset transfers. 259 o APIs for validation of off-DLT resources (API Type-3): This is the 260 REST APIs made available by a resource server (resource owner) at 261 which a gateway can access Off-DLT resources. 263 The use of these APIs is dependent on the mode of access and the type 264 of flow in question. 266 4.4. Types of Flows 268 The ODAP protocol defines the following three (3) flows: 270 o Transfer Initiation flow: This flow deals with the asset profile 271 verification, asset ownership evidence verification and identities 272 verification. 274 o Lock-Evidence flow: This flow deals with the conveyance of 275 evidence regarding the lock (escrow) status of an asset by one 276 gateway, and the verification of the evidence by the other 277 gateway. 279 o Commitment Establishment flow: This flow deals with the asset 280 transfer and commitment establishment between two gateways on 281 behalf of their DLT systems. 283 These flow will be discussed below. 285 4.5. Resources and Identifiers 287 o (a) Resource addressing for DLTs, using the URL syntax. 289 o (b) Client identification based on the URN format. These are for 290 identifying clients (developers and applications) who access these 291 resources, and which in some use-cases require access 292 authorization. 294 o (c) Protocol message family for negotiating authentication, 295 authorisation, and parameters for confidential channel 296 establishment. 298 o (d) Resource discovery mechanism for developers and applications 299 to discover DLT-based resources hosted at a DLT gateway. The 300 gateway response is subject to the level of access granted to that 301 developer or application. 303 5. ODAP Message Format, identifiers and Descriptors 305 5.1. Overview 307 This section describes (i) the phases of the ODAP protocol; (ii) the 308 format of ODAP messages; (iii) the format for resource descriptors; 309 (iv) a method for gateways to implement access controls; (iv) 310 protocol for negotiating security capabilities; (v) discovery and 311 accessing resources and provisions for backward compatibility with 312 existing systems. 314 5.2. ODAP Message Format 316 ODAP messages are exchanged between applications (clients) and DLT 317 gateways (servers). They consist of protocol negotiation and 318 functional messages. 320 Messages are JSON format, with protocol specific mandatory fields, 321 support for arbitrary authentication and authorization schemes and 322 support for a free format field for plaintext or encrypted payloads 323 directed at the DLT gateway or an underlying DLT. 325 JSON format message, mandatory fields are shown below: 327 o Version: ODAP protocol Version (major, minor). 329 o Session ID: unique identifier (UUIDv2) representing a session 331 o Sequence Number: monotonically increasing counter that uniquely 332 represents a message from a session. 334 o ODAP Phase: The current ODAP phase. 336 o Resource URL: Location of Resource to be accessed. 338 o Developer URN: Assertion of developer / application identity. 340 o Action/Response: GET/POST and arguments (or Response Code) 342 o Credential Profile: Specify type of auth (e.g. SAML, OAuth, 343 X.509) 345 o Credential Block: Credential token, certificate, string 347 o Payload Profile: Asset Profile provenance and capabilities 349 o Application Profile: Vendor or Application specific profile 351 o Payload: Payload for POST, responses, and native DLT txns. The 352 payload is specific to the current ODAP phase. 354 o Payload Hash: hash of the current message payload. 356 o Message signature: Gateway EDCSA signature over the message 358 Other relevant attributes may exists that need to be captured for 359 logging purposes. See [ODAP-2PC]. 361 5.3. Digital Asset Resource Descriptors 363 Resources are identified by URL [RFC 1738] as described below: 365 o The type is new: application/odapres 367 o The access protocol is ODAP. 369 Data included in the URL includes the folowing: 371 5.3.1. Organization Identifier 373 This Legal Entity Identifier (LEI) or other identifier linking 374 resource ownership to real world entity. Any scheme for identifying 375 DLT Gateway owners may be implemented (e.g. LEI directory, closed 376 user group membership, SWIFT BIC, etc.). 378 The developer or application MAY validate the identity with the 379 issuing authority. The identifier is not a trusted identity, but MAY 380 be relied on where trust has been established between the two parties 381 (e.g. in a closed user group). 383 The mechanisms to determine organizations identifiers is out of scope 384 for the current specification. 386 5.3.2. DLT Gateway / Endpoint ID 388 FQDN of the ODAP compliant DLT gateway. Required to establish IP 389 connectivity. This MUST resolve to a valid IP address. 391 5.3.3. DLT Identifier 393 Specify to gateway behind which the target DLTs operates. This field 394 is local to the DLT gateway and is used to direct ODAP interactions 395 to the correct underlying DLT. 397 For example: "Hyperledger1", "Bitcoin, "EU-supply-chain". 399 5.3.4. Resource 401 Specifies a resource held on the underlying DLT. This field must be 402 meaningful to the DLT in question but is otherwise an arbitrary 403 string. The underlying object it points to may be a DLT address, 404 block, transaction ID, alias, etc. or a future object type not yet 405 defined. 407 5.3.5. Examples 409 odapres://quant/api.gateway1.com/ripple 411 odapres://quant/api.gateway1.com/bitcoin/xxxxxADDRESSxxxxx 413 5.4. Digital Asset Resource Client Descriptors 415 Resources are identified by URN as described below: 417 o The type is new: application/odapclient 419 The URN format does not imply availability or access protocol. 421 Data included in the URN includes the folowing: 423 5.4.1. Organization Identifier 425 Legal Entity Identifier (LEI) or other identifier linking resource 426 ownership to real world entity. Any scheme for identifying DLT 427 Gateway owners may be implemented (e.g. LEI directory, closed user 428 group membership, BIC, etc.). 430 The DLT Gateway MAY validate the identity with the issuing authority. 431 The identifier is not a trusted identity, but MAY be relied on where 432 trust has been established between the two parties (e.g. in a closed 433 user group). 435 5.4.2. DLT Gateway / Endpoint ID 437 Multi-DLT applications can operate in a mode whereby the application 438 connects to its local DLT gateway, which then forwards application 439 traffic to local DLTs and to remote DLTs via other ODAP gateways. 441 Where this is the case, this field identifies the "home" gateway for 442 this application. This may be required to carry out Gateway to 443 Gateway handshaking and protocol negotiation, or for the server to 444 look up use case specific data relating to the client. 446 5.4.3. Organizational Unit 448 The organization unit within the organization that the client 449 (application or developer) belongs to. This assertion should be 450 backed up with authentication via the negotiated protocol. 452 The purpose of this field is to allow DLT gateways to maintain access 453 control mapping between applications and resources that are 454 independent of the authentication and authorization schemes used, 455 supporting future changes and supporting counterparties that operate 456 different schemes. 458 5.4.4. Name 460 A locally unique (within the OU) identifier, which can identify the 461 application, project or individual developer responsible for this 462 client connection. This is the most granular unit of access control, 463 and DLT Gateways should ensure appropriate identifiers are used for 464 the needs of the application or use case. 466 5.4.5. Examples 468 odapclient:quant/api.overledger.quant.com/research/luke.riley 470 5.5. Gateway Level Access Control 472 Gateways can enforce access rules based on standard naming 473 conventions using novel or existing mechanisms such as AuthZ 474 protocols using the resource identifiers above, for example: 476 odapclient://hsbc/api.overledger.hsbc.com/lending/eric.devloper 477 can READ/WRITE 479 odapres://quant/api.gateway1.com/bitcoin 481 AND 483 odapres://quant/api.gateway1.com/ripple 485 These rules would allow a client so identified to access resources 486 directly, for example: 488 odapres://quant/api.gateway1.com/bitcoin/xxxxxADDRESSxxxxx 490 This example could be an client subscribing to or writing to an 491 address associated with a smart contract as part of its 492 functionality. 494 This method allows resource owners to easily grant access to 495 individuals, groups and organizations. Individual gateway 496 implementations may implement access controls, including subsetting 497 and supersetting or applications or resources according to their own 498 requirements. 500 5.6. Negotiation of Security Protocols and Parameters 502 5.6.1. TLS Established 504 TLS 1.2 or higher MUST be implemented to protect gateway 505 communications. TLS 1.3 or higher SHOULD be implemented where both 506 gateways support TLS 1.3 or higher. 508 5.6.2. Client offers supported credential schemes 510 Capability negotiation prior to data exchange, follows a scheme 511 similar to the Session Description Protocol [RFC 5939]. Initially 512 the client (application) sends a JSON block containing acceptable 513 credential schemes, e.g. OAuth2.0, SAML in the "Credential Scheme" 514 field of the ODAP message. 516 5.6.3. Server selects supported credential scheme 518 The server (DLT Gateway) selects one acceptable credential scheme 519 from the offered schemes, returning the selection in the "Credential 520 Scheme" field of the ODAP message. 522 If no acceptable credential scheme was offered, an HTPP 511 "Network 523 Authentication Required" error is returned in the Action/Response 524 field of the ODAP message. 526 5.6.4. Client asserts of proves identity 528 The details of the assertion / verification step are specific to the 529 chosen credential scheme and are out of scope of this document. 531 5.6.5. Sequence numbers initialized 533 Sequence numbers are used to allow the server to correctly order 534 operations from the client, some of which may be asynchronous, 535 synchronous, idempotent with duplicate requests handled in different 536 ways according to the use case. 538 The initial sequence number is proposed by the client (Application) 539 after the finalization of credential verification. The server (DLT 540 gateway) MUST respond with the same sequence number to indicate 541 acceptance. 543 The client (application) increments the sequence number with each new 544 request. Sequence numbers can be reused for retries in the event of 545 a gateway timeout. 547 5.6.6. Messages can now be exchanged 549 Handshaking is complete at this point, and the client (application) 550 can send ODAP messages to perform actions of DLT resources, which MAY 551 reference the ODAP Payload field. 553 5.7. Asset Profile Identification 555 The client and server must mutually agree as to the asset type or 556 profile that is the subject to the current transfer from the client 557 and server. The client must provide the server with the asset- 558 identification number, or the server may provide the client with the 559 asset-identification numbers for the digital asset supported by the 560 server. 562 Formal specification of asset identification is out of scope of this 563 document. Global numbering of digital asset types or profiles is 564 expected to be performed by a legally recognized entity. 566 5.8. Application Profile Negotiation 568 Where an application relies on specific extensions for operation, 569 these can be represented in an Application Profile. 571 For example, a payments application tracks payments through the use 572 of a cloud based API and will only interact with Gateways that log 573 messages to that API, a resource profile can be established: 575 Application Name: TRACKER 577 X-Tracker_URL: https://api.tracker.com/updates 579 X-Tracking-Policy: Always 581 As Gateways implement this functionality, they support the TRACKER 582 application profile, and the application is able to expand its reach 583 by periodically polling for the availability of the profile. 585 This is an intentionally generalized extension mechanism for 586 application or vendor specific functionality. 588 5.9. Discovery of Digital Asset Interior Resources 590 Applications located outside the DLT network MUST be able to discover 591 which resources they are authorized to access to the level of 592 individual DLTs. They MAY be able to discover lower level resources. 594 Resource discovery is handled by the DLT gateway. For instance using 595 a GET request against the gateway URL with no DLT or resource 596 identifier could return a list of URLs available to the requester at 597 DLT level. This list is subject to the access controls above. 599 DLT Gateways MAY allow applications to discover resources they do not 600 have access to. This should be indicated in the free text field, and 601 gateways SHOULD implement a process for applications to request 602 access. 604 Formal specification of supported resource discovery methods is out 605 of scope of this document. 607 5.10. Response Codes 609 The DLT Gateway MUST respond with return codes indicating the failure 610 or success of each operation. For DLTs with slow consensus 611 mechanism, the Gateway may return codes indicating the operation has 612 been submitted. The application may carry out further operation in 613 future to determine the ultimate status of the operation. 615 For Non-native transactions, the Gateway is responsible for 616 translating the request into the appropriate native format and 617 ensuring correct signing takes place. 619 5.11. Backward Compatibility 621 It is also possible to send a fully formatted native message to the 622 underlying DLT in the Payload field using the NATIVE_TXN operation, 623 directed to a resource URL. This allows existing DLT native code to 624 be ported to ODAP infrastructures with minimal change. 626 6. Transfer Initiation Flow (Phase 1) 628 This section describes ODAP initialization phase, where a sender 629 gateway (transfer client) interacts with a recipient gateway 630 (transfer server), proposing a session. 632 The session may be triggered directly or indirectly by a client 633 application behind the sender gateway. The method employed by an 634 application to invoke the sender gateway is out of scope for this 635 specification. 637 For this phase, several artifacts related to the asset transfer must 638 be validated: asset profile, asset ownership evidence, identities, 639 and logging-related operations (log profile, access control profile 640 [ODAP-2PC]). 642 In this phase, gateways implement the Transfer Initiation Flows 643 endpoint. 645 The flow follows a request-response model. The sender gateway 646 (transfer client) makes a request (POST) to the Transfer Initiation 647 endpoint at the recipient gateway (transfer server). 649 Gateways MUST support the use of the HTTP GET and POST methods 650 defined in RFC 2616 [RFC2616] for the endpoint. 652 The transfer clients MAY use the HTTP GET or POST methods to send 653 messages in this phase to the transfer server. If using the HTTP GET 654 method, the request parameters maybe serialized using URI Query 655 String Serialization. 657 The transfer client and server may be required to sign certain 658 messages in order to provide standalone proof (for non-repudiation) 659 independent of the secure channel between the client and server. 660 This proof maybe required for audit verifications post-event. 662 Flows occur over TLS secure session that must be established between 663 the client and server. 665 6.1. Initialization Request Message 667 This message is sent from the sender gateway to the recipient gateway 668 This message may be the result of a client application invoking its 669 local gateway to request an asset transfer event 671 Depending on the transfer proposal, multiple rounds of communications 672 between the client application and its sender gateway may occur. 673 Similarly, multiple rounds of communication between gateways may 674 occur. 676 The parameters of this message consists of the following: 678 o Version: ODAP protocol Version (major, minor). 680 o Developer URN: Assertion of developer / application identity. 682 o Credential Profile: Specify type of auth (e.g. SAML, OAuth, 683 X.509) 685 o Payload Profile: Asset Profile provenance and capabilities 687 o Application Profile: Vendor or Application specific profile 689 o logging_profile REQUIRED: contains the profile regarding the 690 logging procedure. Default is local store. 692 o Access_control_profile REQUIRED: the profile regarding the 693 confidentiality of the log entries being stored. Default is only 694 the gateway that created the logs can access them. 696 o Initialization Request Message signature REQUIRED: Gateway EDCSA 697 signature over the message 699 o Source_gateway_pubkey REQUIRED: the public key of the gateway 700 initiating a transfer 702 o Source_gateway_dlt_system REQUIRED: the ID of the source DLT 704 o Recipient_gateway_pubkey REQUIRED: the public key of the gateway 705 involved in a transfer 707 o Recipient_gateway_dlt_system REQUIRED: the ID of the recipient 708 gatewayinvolved in a transfer 710 o Escrow type: faucet, timelock, hashlock, hashtimelock, multi-claim 711 PC, destroy/burn (escrowed cross-claim). 713 o Expiry time: when will the escrow or lock expire 715 o Multiple claims allowed: true/false 717 o Multiple cancels allowed: true/false 719 o Permissions: list of identities (addresses or X.509 certificates) 720 that can perform operations on the escrow or lock on the asset in 721 the origin DLT network. 723 o Originator address: along with the source gateway DLT, allows for 724 the correct identification of the entity in the origin DLT 725 transmitting the asset. 727 o Beneficiary address: along with the recipient gateway DLT, allows 728 for the correct identification of the entity in the destination 729 DLT receiving the asset. 731 o Subsequent calls: details possible escrow actions 733 o History (optional): provides an history of the escrow, in case it 734 has previously been initialized. This includes a list of the 735 transactions on that escrow (transaction ID) and which action it 736 performed (ActionCategory), the origin and destination, balance, 737 current status, and ActionLockSpecificParameters. 739 The sender gateway makes the following HTTP request using TLS (with 740 extra line breaks for display purposes only). 742 Example: TBD. 744 6.2. Initialization Request Message Response (ACK) 746 After receiving an Initialization Request Message from the sender 747 gateway (transfer client), the recipient gateway (transfer server) 748 must validate the profiles stated in the request message. 750 This validation could be performed automatically (using a defined set 751 of rules), or by requiring approval by an application operated by the 752 beneficiary. 754 If one of the profiles is erroneous or rejected, the recipient 755 gateway constructs an Initialization Denied Message, stating what was 756 rejected, and proposing an alternative (if applicable). 758 Otherwise, if approved, the recipient gateway constructs a 759 Initialization Request Message Response. 761 The purpose of this acknowledgement message is for the recipient 762 gateway to indicate agreement to proceed with the proposed 763 operations, under the proposed profiles. 765 This message is sent from the recipient gateway to the sender gateway 766 in response to a received Initialization Request from the sender 767 gateway. 769 The message must be signed by the recipient gateway. 771 The parameters of this message consists of the following: 773 o Session ID: unique identifier (UUIDv2) representing a session. 775 o Sequence Number: monotonically increasing counter that uniquely 776 represents a message from a session. 778 o ODAP Phase: The current ODAP phase. 780 o Hash of the Initialization Request Message REQUIRED: the hash of 781 the proposal. 783 o Destination: if the recipient gateway calculates the destination 784 address dynamically. 786 o Timestamp REQUIRED: timestamp referring to when the Initialization 787 Request Message was received. 789 o Processed Timestamp REQUIRED: timestamp referring to when the 790 Initialization Response Message was constructed. 792 Example: TBD. 794 7. Lock-Evidence Verification Flow (Phase 2) 796 This section describes the conveyance of claims regarding to the 797 status of assets or resources from a sender gateway to a recipient 798 gateway. 800 In this phase, gateways implement the Lock-Evidence Agreement 801 endpoint. 803 In the following, the sender gateway takes the role of the transfer- 804 client while the recipient gateway takes the role of the transfer- 805 server. 807 The flow follows a request-response model. The client makes a 808 request (POST) to the Lock-Evidence Agreement endpoint at the server. 810 Gateways MUST support the use of the HTTP GET and POST methods 811 defined in RFC 2616 [RFC2616] for the endpoint. 813 Clients MAY use the HTTP GET or POST methods to send messages in this 814 phase to the server. If using the HTTP GET method, the request 815 parameters maybe serialized using URI Query String Serialization. 817 The client and server may be required to sign certain messages in 818 order to provide standalone proof (for non-repudiation) independent 819 of the secure channel between the client and server. This proof 820 maybe required for audit verifications post-event. 822 (NOTE: Flows occur over TLS. Nonces are not shown). 824 7.1. Transfer Commence Message 826 This message is sent from the transfer-client (sender gateway) to the 827 Transfer Request Endpoint at the transfer-server (recipient gateway). 828 It signals to the server that the client is ready to start the 829 transfer of the digital asset. 831 The message must contain claims related to the information from the 832 previous flow (Phase 1). It must be signed by the client (sender 833 gateway). 835 The parameters of this message consists of the following: 837 o message_type REQUIRED. MUST be the value 838 urn:ietf:odap:msgtype:transfer-commence-msg 840 o originator_pubkey REQUIRED. This is the public key of the asset 841 owner (originator) in the origin DLT system. 843 o beneficiary_pubkey REQUIRED. This is the public key of the 844 beneficiary in the destination DLT system. 846 o sender_dlt_system REQUIRED. This is the identifier of the origin 847 DLT system behind the client. 849 o recipient_dlt_system REQUIRED. This is the identifier of the 850 destination DLT system behind the server. 852 o client_identity_pubkey REQUIRED. The client who sent this 853 message. 855 o server_identity_pubkey REQUIRED. The server for whom this message 856 is intended. 858 o hash_asset_profile REQUIRED. This is the hash of the asset 859 profile previously agreed upon in Phase 1. 861 o asset_unit OPTIONAL. If applicable this is the unit amount of the 862 asset being transferred, previously agreed upon. 864 o hash_prev_message REQUIRED. The hash of the last message in Phase 865 1. 867 o client_transfer_number OPTIONAL. This is the transfer 868 identification number chosen by the client. This number is 869 meaningful only the client. 871 o client_signature REQUIRED. The digital signature of the client. 873 For example, the client makes the following HTTP request using TLS 874 (with extra line breaks for display purposes only): 876 POST /token HTTP/1.1 877 Host: server.example.com 878 Authorization: Basic awHCaGRSa3F0MzpnWDFmQmF0M2ZG 879 Content-Type: application/x-www-form-urlencoded 881 { 882 "message_type": "urn:ietf:odap:msgtype:transfer-commence-msg", 883 "originator_pubkey":"zGy89097hkbfgkjvVbNH", 884 "beneficiary_pubkey": "mBGHJjjuijh67yghb", 885 "sender_dlt_system": "originDLTsystem", 886 "recipient_dlt_system":"recipientDLTsystem", 887 "client_identity_pubkey":"fgH654tgeryuryuy", 888 "server_identity_pubkey":"dFgdfgdfgt43tetr535teyrfge4t54334", 889 "hash_asset_profile":"nbvcwertyhgfdsertyhgf2h3v4bd3v21", 890 "asset_unit": "ghytredcfvbhfr", 891 "hash_prev_message":"DRvfrb654vgreDerverv654nhRbvder4", 892 "client_transfer_number":"ji9876543ewdfgh", 893 "client_signature":"fdw34567uyhgfer45" 894 } 896 Figure 2 898 7.2. Transfer Commence Response Message (Ack) 900 The purpose of this message is for the transfer server to indicate 901 agreement to proceed with the asset transfer. 903 This message is sent from the transfer server (recipient gateway) to 904 the transfer client (sender gateway) in response to a Transfer 905 Commence Request from the client. 907 The message must be signed by the server. 909 The parameters of this message consists of the following: 911 o message_type REQUIRED urn:ietf:odap:msgtype:transfer-commenceack- 912 msg 914 o client_identity_pubkey REQUIRED. The client for whom this message 915 is intended. 917 o server_identity_pubkey REQUIRED. The server who sent this 918 message. 920 o hash_commence_request REQUIRED. The hash of previous message. 922 o server_transfer_number OPTIONAL. This is the transfer 923 identification number chosen by the server. This number is 924 meaningful only to the server. 926 o server_signature REQUIRED. The digital signature of the server. 928 An example of a success response could be as follows: 930 ``` 931 HTTP/1.1 200 OK 932 Content-Type: application/json;charset=UTF-8 933 Cache-Control: no-store 934 Pragma: no-cache 936 { 937 "message_type":"urn:ietf:odap:msgtype:transfer-commenceack-msg", 938 "client_identity_pubkey":"fgH654tgeryuryuy", 939 "server_identity_pubkey":"dFgdfgdfgt43tetr535teyrfge4t54334", 940 "hash_commence_request":"DRvfrb654vgreDerverv654nhRbvder4", 941 "server_transfer_number":"ji9876543ewdfgh", 942 "server_signature":"aaw34567uyhgfer66" 943 } 944 ``` 946 Figure 3 948 7.3. Lock Evidence Message 950 The purpose of this message is for the transfer client (sender 951 gateway) to deliver the relevant asset-lock (or escrow) evidence to 952 the server (recipient gateway). 954 The format of the evidence is dependent on the DLT fronted by the 955 client and is outside the scope of this specification. 957 The message must be signed by the client. 959 This message is used client (sender gateway) to convey lock/escrow 960 evidence to the server (recipient gateway). 962 This message is sent from the client to the Evidence Validation 963 Endpoint at the server. The server must validate the lock evidence 964 claims in this message. 966 The message must be signed by the client (sender gateway). 968 The parameters of this message consists of the following: 970 o message_type REQUIRED urn:ietf:odap:msgtype:lock-evidence-req-msg 972 o client_identity_pubkey REQUIRED. The client who sent this 973 message. 975 o server_identity_pubkey REQUIRED. The server for whom this message 976 is intended. 978 o lock_evidence_claim REQUIRED. The lock or escrow evidence (on the 979 ledger L1 fronted by the client G1). 981 o lock_claim_format OPTIONAL. The format of the evidence. 983 o lock_evidence_expiration REQUIRED. The duration of time of lock 984 on ledger L1 (after which the lock is released). 986 o hash_commence_ack_request REQUIRED. The hash of previous message. 988 o client_transfer_number OPTIONAL. This is the transfer 989 identification number chosen by the client. This number is 990 meaningful only to the client. 992 o client_signature REQUIRED. The digital signature of the client. 994 7.4. Lock Evidence Response Message (Ack) 996 The purpose of this message is for the transfer server (recipient 997 gateway) to indicate acceptance of the asset-escrow (or lock) 998 evidence delivered by the client (sender gateway) in the previous 999 message. 1001 The message must be signed by the server. 1003 The parameters of this message consists of the following: 1005 o message_type REQUIRED urn:ietf:odap:msgtype:lock-evidence-ack-msg 1007 o client_identity_pubkey REQUIRED. The client for whom this message 1008 is intended. 1010 o server_identity_pubkey REQUIRED. The server who sent this 1011 message. 1013 o hash_lockevidence_request REQUIRED. The hash of previous message. 1015 o server_transfer_number OPTIONAL. This is the transfer 1016 identification number chosen by the server. This number is 1017 meaningful only to the server. 1019 o server_signature REQUIRED. The digital signature of the server. 1021 8. Commitment Establishment Flow (Phase 3) 1023 This section describes the transfer commitment agreement between the 1024 sender gateway (transfer client) to a recipient gateway (transfer 1025 server). 1027 This phase must be completed within the asset-lock duration time 1028 specificied in the previous lock_evidence_expiration parameter 1029 (message 7.3). 1031 In this phase gateways implement the Transfer Commitment endpoint. 1033 In the following, the sender gateway takes the role of the client 1034 while the recipient gateway takes the role of the server. 1036 The flow follows a request-response model. The client makes a 1037 request (POST) to the Transfer Commitment endpoint at the server. 1039 Gateways MUST support the use of the HTTP GET and POST methods 1040 defined in RFC 2616 [RFC2616] for the endpoint. 1042 Clients MAY use the HTTP GET or POST methods to send messages in this 1043 phase to the server. If using the HTTP GET method, the request 1044 parameters maybe serialized using URI Query String Serialization. 1046 The client and server may be required to sign certain messages in 1047 order to provide standalone proof (for non-repudiation) independent 1048 of the secure channel between the client and server. This proof 1049 maybe required for audit verifications post-event. 1051 (NOTE: Flows occur over TLS. Nonces are not shown). 1053 8.1. Commit Preparation Message 1055 The purpose of this message is for the client to indicate its 1056 readiness to begin the commitment of the transfer. 1058 The message must be signed by the client. 1060 The parameters of this message consists of the following: 1062 o message_type REQUIRED. It MUST be the value 1063 urn:ietf:odap:msgtype:commit-prepare-msg 1065 o client_identity_pubkey REQUIRED. The client who sent this 1066 message. 1068 o server_identity_pubkey REQUIRED. The server for whom this message 1069 is intended. 1071 o hash_lockevidence_ack REQUIRED. The hash of previous message. 1073 o client_transfer_number OPTIONAL. This is the transfer 1074 identification number chosen by the client. This number is 1075 meaningful only the client. 1077 o client_signature REQUIRED. The digital signature of the client. 1079 8.2. Commit Preparation Response 1081 The purpose of this message is for the server to indicate to the 1082 client its readiness to proceed with the commitment finalization 1083 step. 1085 The message must be signed by the server. 1087 The parameters of this message consists of the following: 1089 o message_type REQUIRED. It MUST be the value 1090 urn:ietf:odap:msgtype:commit-prepare-ack-msg 1092 o client_identity_pubkey REQUIRED. The client for whom this message 1093 is intended. 1095 o server_identity_pubkey REQUIRED. The server who sent this 1096 message. 1098 o hash_commitprep REQUIRED. The hash of previous commit preparation 1099 message. 1101 o server_transfer_number OPTIONAL. This is the transfer 1102 identification number chosen by the server. This number is 1103 meaningful only the server. 1105 o server_signature REQUIRED. The digital signature of the server. 1107 8.3. Commit Final Message 1109 The purpose of this message is for the client to indicate to the 1110 server that the client (sender gateway) has completed local 1111 extinguishment of the asset on its DLT (L1), and that now on its part 1112 the server (recipient gateway) must re-generated the asset on its DLT 1113 (L2). 1115 The message must contain claims related to the extinguishment of the 1116 asset by the client. It must be signed by the client. 1118 The parameters of this message consists of the following: 1120 o message_type REQUIRED. It MUST be the value 1121 urn:ietf:odap:msgtype:commit-final-msg 1123 o client_identity_pubkey REQUIRED. The client who sent this 1124 message. 1126 o server_identity_pubkey REQUIRED. The server for whom this message 1127 is intended. 1129 o commit_final_claim REQUIRED. This is one or more claims signed by 1130 the client that the asset in question has been extinguished by the 1131 client in its local DLT. 1133 o commit_final_claim_format OPTIONAL. This is the format of the 1134 claim provided by the client in this message. 1136 o hash_commitprepare_ack REQUIRED. The hash of previous message. 1138 o client_transfer_number OPTIONAL. This is the transfer 1139 identification number chosen by the client. This number is 1140 meaningful only the client. 1142 o client_signature REQUIRED. The digital signature of the client. 1144 8.4. Commit Final Response Message 1146 The purpose of this message is for the server to indicate to the 1147 client that it has completed the asset re-generation at its DLTS 1148 (L2). 1150 The message must contain claims related to the re-generated of the 1151 asset by the server. It must be signed by the server. 1153 The parameters of this message consists of the following: 1155 o message_type REQUIRED. It MUST be the value 1156 urn:ietf:odap:msgtype:commit-final-ack-msg 1158 o client_identity_pubkey REQUIRED. The client for whom this message 1159 is intended.. 1161 o server_identity_pubkey REQUIRED. The server who sent this 1162 message. 1164 o commit_acknowledgement_claim REQUIRED. This is one or more claims 1165 signed by the server that the asset in question has been 1166 regenerated by the server in its local DLT. 1168 o commit_acknowledgement_claim_format OPTIONAL. This is the format 1169 of the claim provided by the server in this message. 1171 o hash_commitfinal REQUIRED. The hash of previous commit final 1172 message. 1174 o server_transfer_number OPTIONAL. This is the transfer 1175 identification number chosen by the server. This number is 1176 meaningful only the server. 1178 o server_signature REQUIRED. The digital signature of the server. 1180 8.5. Transfer Complete Message 1182 The purpose of this message is for the client to indicate to the 1183 server that the asset transer has been completed and that no further 1184 messages are to be expected from the client in regards to this 1185 transfer instance. 1187 The message closes the first message of Phase 2 (Transfer Commence 1188 Message). It must be signed by the client. 1190 The parameters of this message consists of the following: 1192 o message_type REQUIRED. It MUST be the value 1193 urn:ietf:odap:msgtype:commit-transfer-complete-msg 1195 o client_identity_pubkey REQUIRED. The client who sent this 1196 message. 1198 o server_identity_pubkey REQUIRED. The server for whom this message 1199 is intended. 1201 o hash_commit_final_ack REQUIRED. The hash of previous message. 1203 o hash_transfer_commence REQUIRED. The hash of the Transfer 1204 Commence message at the start of Phase 2 (see section 7.1). 1206 o client_transfer_number OPTIONAL. This is the transfer 1207 identification number chosen by the client. This number is 1208 meaningful only the client. 1210 o client_signature REQUIRED. The digital signature of the client.. 1212 9. Security Consideration 1214 (TBD) 1216 10. IANA Consideration 1218 (TBD) 1220 11. References 1222 11.1. Normative References 1224 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1225 Requirement Levels", BCP 14, RFC 2119, 1226 DOI 10.17487/RFC2119, March 1997, 1227 . 1229 [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1230 Specifications: ABNF", RFC 2234, DOI 10.17487/RFC2234, 1231 November 1997, . 1233 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1234 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1235 . 1237 11.2. Informative References 1239 [Arch] Hardjono, T., Hargreaves, M., and N. Smith, "An 1240 Interoperability Architecture for Blockchain Gateways. 1241 draft-hardjono-blockchain-interop-arch-02", April 2021, 1242 . 1245 [HS2019] Hardjono, T. and N. Smith, "Decentralized Trusted 1246 Computing Base for Blockchain Infrastructure Security, 1247 Frontiers Journal, Sepcial Issue on Blockchain Technology, 1248 Vol. 2, No. 24", December 2019, 1249 . 1251 [NIST] Yaga, D., Mell, P., Roby, N., and K. Scarfone, "NIST 1252 Blockchain Technology Overview (NISTR-8202)", October 1253 2018, . 1255 [ODAP-2PC] 1256 Belchior, R., Correia, M., and T. Hardjono, "Gateway Crash 1257 Recovery Mechanism. draft-belchior-gateway-recovery-01", 1258 March 2021, . 1261 [RFC5939] Andreasen, F., "Session Description Protocol (SDP) 1262 Capability Negotiation", RFC 5939, DOI 10.17487/RFC5939, 1263 September 2010, . 1265 Authors' Addresses 1267 Martin Hargreaves 1268 Quant Network 1270 Email: martin.hargreaves@quant.network 1272 Thomas Hardjono 1273 MIT 1275 Email: hardjono@mit.edu 1276 Rafael Belchior 1277 Technico Lisboa 1279 Email: rafael.belchior@tecnico.ulisboa.pt