idnits 2.17.1 draft-hargreaves-odap-00.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 (October 10, 2020) is 1287 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFC 1738' is mentioned on line 196, but not defined ** Obsolete undefined reference: RFC 1738 (Obsoleted by RFC 4248, RFC 4266) == Missing Reference: 'RFC 5939' is mentioned on line 348, but not defined == Missing Reference: 'HS19' is mentioned on line 435, but not defined == Unused Reference: 'RFC2234' is defined on line 461, but no explicit reference was found in the text == Unused Reference: 'HS2019' is defined on line 467, but no explicit reference was found in the text == Unused Reference: 'NIST' is defined on line 473, but no explicit reference was found in the text == Unused Reference: 'RFC5939' is defined on line 477, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) Summary: 2 errors (**), 0 flaws (~~), 8 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: April 13, 2021 MIT 6 October 10, 2020 8 Open Digital Asset Protocol 9 draft-hargreaves-odap-00 11 Abstract 13 This memo describes the Open Digital Asset Protocol (ODAP). ODAP is 14 intended for describing assets held on distributed ledgers in an open 15 and interoperable format, session negotiation and message passing 16 between gateways connecting disparate blockchain systems. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on April 13, 2021. 35 Copyright Notice 37 Copyright (c) 2020 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Open Digital Asset Protocol . . . . . . . . . . . . . . . 3 54 2. Conventions used in this document . . . . . . . . . . . . . . 4 55 3. ODAP: Elements of the proposal . . . . . . . . . . . . . . . 4 56 3.1. ODAP Message Flow Context . . . . . . . . . . . . . . . . 4 57 3.2. ODAP Message Format . . . . . . . . . . . . . . . . . . . 4 58 3.3. Digital Asset Resource Descriptors . . . . . . . . . . . 5 59 3.3.1. Organisation Identifier . . . . . . . . . . . . . . . 5 60 3.3.2. DLT Gateway / Endpoint ID . . . . . . . . . . . . . . 5 61 3.3.3. DLT Identifier . . . . . . . . . . . . . . . . . . . 5 62 3.3.4. Resource . . . . . . . . . . . . . . . . . . . . . . 6 63 3.3.5. Examples . . . . . . . . . . . . . . . . . . . . . . 6 64 3.4. Digital Asset Resource Client Descriptors . . . . . . . . 6 65 3.4.1. Organization Identifier . . . . . . . . . . . . . . . 6 66 3.4.2. DLT Gateway / Endpoint ID . . . . . . . . . . . . . . 6 67 3.4.3. Organizational Unit . . . . . . . . . . . . . . . . . 7 68 3.4.4. Name . . . . . . . . . . . . . . . . . . . . . . . . 7 69 3.4.5. Examples . . . . . . . . . . . . . . . . . . . . . . 7 70 3.5. Gateway Level Access Control . . . . . . . . . . . . . . 7 71 3.6. Negotiation of Security Protocols and Parameters . . . . 8 72 3.6.1. TLS Established . . . . . . . . . . . . . . . . . . . 8 73 3.6.2. Client offers supported credential schemes . . . . . 8 74 3.6.3. Server selects supported credential scheme . . . . . 8 75 3.6.4. Client asserts of proves identity . . . . . . . . . . 8 76 3.6.5. Sequence numbers initialized . . . . . . . . . . . . 8 77 3.6.6. Messages can now be exchanged . . . . . . . . . . . . 9 78 3.7. Digital Asset Resource Discovery . . . . . . . . . . . . 9 79 3.7.1. Format . . . . . . . . . . . . . . . . . . . . . . . 9 80 3.8. Accessing Resources via a DLT Gateway . . . . . . . . . . 9 81 3.8.1. Backward Compatibility . . . . . . . . . . . . . . . 9 82 4. Security Consideration . . . . . . . . . . . . . . . . . . . 9 83 5. IANA Consideration . . . . . . . . . . . . . . . . . . . . . 10 84 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 85 6.1. Normative References . . . . . . . . . . . . . . . . . . 10 86 6.2. Informative References . . . . . . . . . . . . . . . . . 10 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 89 1. Introduction 91 There is a lack of interoperability between individual blockchains, 92 but also a general difficulty building open DLT networks. Extant 93 networks are custom built and relatively closed, usually limited to 94 networks of a single DLT type 95 This memo proposes at blockchain-agnostic protocol in order to allow 96 the creation of business applications that use and modify multiple 97 blockchains or DLT systems, through a single programmatic interface. 99 The target blockchain systems can be of any type, operated by 100 different owners and managed using different DLT management platforms 101 that implement ODAP interfaces. 103 These platforms may act as gateways or relays for the application to 104 interact with the blockchain systemn. They are referred to herein as 105 blockchain or DLT Gateways. 107 When correctly implemented and deployed, the protocol should provide 108 the basis for solutions involving asset migration between two DLT 109 systems, as well as use-cases when one side is a non-DLT system (e.g. 110 legacy system). 112 1.1. Open Digital Asset Protocol 114 This draft proposes a standard framework to address the following: 116 o Resource addressing for DLTs, using the URL syntax. 118 o Client identification based on the URN format. These are for 119 identifying clients (developers and applications) who access these 120 resources, and which in some use-cases require access 121 authorization. 123 o Protocol message family for negotiating authentication, 124 authorisation, and parameters for confidential channel 125 establishment. 127 o Resource discovery mechanism for developers and applications to 128 discover DLT-based resources hosted at a DLT gateway. The gateway 129 response is subject to the level of access granted to that 130 developer or application. 132 We propose a protocol for accessing DLT resources (read and modify) 133 that are hosted behind gateways, either directly or via a local 134 intermediate gateway. 136 We propose a method to support pass-through of native DLT messaging 137 where necessary for compatibility. 139 2. Conventions used in this document 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 document are to be interpreted as described in RFC 2119 [RFC2119]. 145 In this document, these words will appear with that interpretation 146 only when in ALL CAPS. Lower case uses of these words are not to be 147 interpreted as carrying significance described in RFC 2119. 149 3. ODAP: Elements of the proposal 151 This section describes (i) the phases of the ODAP protocol; (ii) the 152 format of ODAP messages; (iii) the format for resource descriptors; 153 (iv) a method for gateways to implement access controls; (v) protocol 154 for negotiating security capabilities; (vi) discovery and accessing 155 resources and provisions for backward compatibility with existing 156 systems. 158 3.1. ODAP Message Flow Context 160 o OSimple Client to Gateway (Diagram to follow). 162 o Client to Multiple Gateways (Diagram to follow). 164 o Client to Local Gateway to Remote Gateway(s) (Diagram to follow). 166 3.2. ODAP Message Format 168 ODAP messages are exchanged between applications (clients) and DLT 169 gateways (servers). They consist of protocol negotiation and 170 functional messages. 172 Messages are JSON format, with protocol specific mandatory fields, 173 support for arbitrary authentication and authorization schemes and 174 support for a free format field for plaintext or encrypted payloads 175 directed at the DLT gateway or an underlying DLT. 177 JSON format message, mandatory fields are shown below: 179 o Version: ODAP protocol Version (major, minor). 181 o Resource URL: Location of Resource to be accessed. 183 o Developer URN: Assertion of developer / application identity. 185 o Credential Scheme: Specify type of authorization (e.g. SAML, 186 OAuth, X.509). 188 o Credential Block: Credential token, certificate, string. 190 o Payload: Payload for POST, responses, and native DLT txns. 192 o Sequence Number: Sequence Number. 194 3.3. Digital Asset Resource Descriptors 196 Resources are identified by URL [RFC 1738] as described below: 198 o The type is new: application/odapres 200 o The access protocol is ODAP. 202 Data included in the URL includes the folowing: 204 3.3.1. Organisation Identifier 206 This drafts supports a variety organization identification schemes. 207 For example, the Legal Entity Identifier (LEI)scheme or other 208 identifier linking resource ownership to real world entity can be 209 used. 211 Any scheme for identifying DLT Gateway owners may be implemented 212 (e.g. LEI directory, closed user group membership, SWIFT BIC, etc.). 214 The developer or application MAY validate the identity with the 215 issuing authority. The identifier is not a trusted identity, but MAY 216 be relied on where trust has been established between the two parties 217 (e.g. in a closed user group). 219 The mechanisms to determine organizations identifiers is out of scope 220 for the current specification. 222 3.3.2. DLT Gateway / Endpoint ID 224 FQDN of the ODAP compliant DLT gateway. Required to establish IP 225 connectivity. This MUST resolve to a valid IP address. 227 3.3.3. DLT Identifier 229 Specify to gateway behind which the target DLTs operates. This field 230 is local to the DLT gateway and is used to direct ODAP interactions 231 to the correct underlying DLT. 233 For example: "Hyperledger1", "Bitcoin, "EU-supply-chain". 235 3.3.4. Resource 237 Specifies a resource held on the underlying DLT. This field must be 238 meaningful to the DLT in question but is otherwise an arbitrary 239 string. The underlying object it points to may be a DLT address, 240 block, transaction ID, alias, etc. or a future object type not yet 241 defined. 243 3.3.5. Examples 245 odapres://quant/api.gateway1.com/ripple 247 odapres://quant/api.gateway1.com/bitcoin/xxxxxADDRESSxxxxx 249 3.4. Digital Asset Resource Client Descriptors 251 Resources are identified by URN as described below: 253 o The type is new: application/odapclient 255 The URN format does not imply availability or access protocol. 257 Data included in the URN includes the folowing: 259 3.4.1. Organization Identifier 261 Legal Entity Identifier (LEI) or other identifier linking resource 262 ownership to real world entity. Any scheme for identifying DLT 263 Gateway owners may be implemented (e.g. LEI directory, closed user 264 group membership, BIC, etc.). 266 The DLT Gateway MAY validate the identity with the issuing authority. 267 The identifier is not a trusted identity, but MAY be relied on where 268 trust has been established between the two parties (e.g. in a closed 269 user group). 271 3.4.2. DLT Gateway / Endpoint ID 273 Multi-DLT applications can operate in a mode whereby the application 274 connects to its local DLT gateway, which then forwards application 275 traffic to local DLTS and to remote DLTs via other ODAP gateways. 277 Where this is the case, this field identifies the "home" gateway for 278 this application. This may be required to carry out Gateway to 279 Gateway handshaking and protocol negotiation, or for the server to 280 look up use case specific data relating to the client. 282 3.4.3. Organizational Unit 284 The organization unit within the organization that the client 285 (application or developer) belongs to. This assertion should be 286 backed up with authentication via the negotiated protocol. 288 The purpose of this field is to allow DLT gateways to maintain access 289 control mapping between applications and resources that are 290 independent of the authentication and authorization schemes used, 291 supporting future changes and supporting counterparties that operate 292 different schemes. 294 3.4.4. Name 296 A locally unique (within the OU) identifier, which can identify the 297 application, project or individual developer responsible for this 298 client connection. This is the most granular unit of access control, 299 and DLT Gateways should ensure appropriate identifiers are used for 300 the needs of the application or use case. 302 3.4.5. Examples 304 odapclient:quant/api.overledger.quant.com/research/luke.riley 306 3.5. Gateway Level Access Control 308 Gateways can enforce access rules based on standard naming 309 conventions using novel or existing mechanisms such as AuthZ 310 protocols using the resource identifiers above, for example: 312 odapclient://hsbc/api.overledger.hsbc.com/lending/eric.devloper 314 can READ/WRITE 316 odapres://quant/api.gateway1.com/bitcoin 318 AND 320 odapres://quant/api.gateway1.com/ripple 322 These rules would allow a client so identified to access resources 323 directly, for example: 325 odapres://quant/api.gateway1.com/bitcoin/xxxxxADDRESSxxxxx 327 This example could be an client subscribing to or writing to an 328 address associated with a smart contract as part of its 329 functionality. 331 This method allows resource owners to easily grant access to 332 individuals, groups and organizations. Individual gateway 333 implementations may implement access controls, including subsetting 334 and supersetting or applications or resources according to their own 335 requirements. 337 3.6. Negotiation of Security Protocols and Parameters 339 3.6.1. TLS Established 341 TLS 1.2 or higher MUST be implemented to protect gateway 342 communications. TLS 1.3 or higher SHOULD be implemented where both 343 gateways support TLS 1.3 or higher. 345 3.6.2. Client offers supported credential schemes 347 Capability negotiation prior to data exchange, follows a scheme 348 similar to the Session Description Protocol [RFC 5939]. Initially 349 the client (application) sends a JSON block containing acceptable 350 credential schemes, e.g. OAuth2.0, SAML in the "Credential Scheme" 351 field of the ODAP message. 353 3.6.3. Server selects supported credential scheme 355 The server (DLT Gateway) selects one acceptable credential scheme 356 from the offered schemes, returning the selection in the "Credential 357 Scheme" field of the ODAP message. 359 If no acceptable credential scheme was offered, an HTPP 511 "Network 360 Authentication Required" error is returned in the Action/Response 361 field of the ODAP message. 363 3.6.4. Client asserts of proves identity 365 The details of the assertion / verification step are specific to the 366 chosen credential scheme and are out of scope of this document. 368 3.6.5. Sequence numbers initialized 370 Sequence numbers are used to allow the server to correctly order 371 operations from the client, some of which may be asynchronous, 372 synchronous, idempotent with duplicate requests handled in different 373 ways according to the use case. 375 The initial sequence number is proposed by the client (Application) 376 after the finalization of credential verification. The server (DLT 377 gateway) MUST respond with the same sequence number to indicate 378 acceptance. 380 The client (application) increments the sequence number with each new 381 request. Sequence numbers can be reused for retries in the event of 382 a gateway timeout. 384 3.6.6. Messages can now be exchanged 386 Handshaking is complete at this point, and the client (application) 387 can send ODAP messages to perform actions of DLT resources, which MAY 388 reference the ODAP Payload field. 390 3.7. Digital Asset Resource Discovery 392 Resource discovery is handled by the DLT gateway, a GET request 393 against the gateway URL with no DLT or resource MUST returns a list 394 of URLs available to the requester to DLT level. This list is 395 subject to the access controls above. 397 DLT Gateways may allow applications to discover URLs they do not have 398 access to, this should be indicated the free test field, and they 399 should implement a process for applications to request access. 401 3.7.1. Format 403 JSON structure, consisting of a set of responses, each is: URL, free 404 text field, admin contact 406 3.8. Accessing Resources via a DLT Gateway 408 The "Action" field is used to access resources via the gateway. We 409 suggest these interactions use REST semantics however a detailed API 410 specification is out of scope of this memo. 412 In general, we suggest exposing a common subset of functionality via 413 API using the Action field, augmented with DLT specific or smart 414 contract specific functionality as needed. 416 3.8.1. Backward Compatibility 418 It is also possible to send a fully formatted native message to the 419 underlying DLT in the Payload field, directed to a resource URL. 420 This allows existing DLT native code to be ported to ODAP 421 infrastructures with minimal change. 423 4. Security Consideration 425 Although the current interoperability architecture for blockchain 426 gateways assumes the externalization of the value of assets, as a 427 blockchain system holds an increasing number of virtual assets it 428 becomes attractive to attackers seeking to obtain cryptographic keys 429 of its nodes and its end-users. 431 Gateway nodes are of particular interest to attackers because they 432 enable the transferal of virtual assets to external blockchain 433 systems, which may or may not be regulated. As such, hardening 434 technologies and tamper-resistant crypto-processors (e.g. TPM, SGX) 435 should be used for implementations of gateways [HS19]. 437 Due to the consensus-based nature of the underlying DLT technologies, 438 gateway responses may be conditional and require verification, for 439 instance if the DLT is undergoing a byzantine attack at the time of 440 the request. 442 The application must evaluate the correctness of responses from the 443 gateway in context and may need to perform further verification steps 444 with later ODAP calls. The application may base this evaluation on 445 the number of DLT nodes the gateway has interacted with in order to 446 fulfil the request. 448 5. IANA Consideration 450 (TBD) 452 6. References 454 6.1. Normative References 456 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 457 Requirement Levels", BCP 14, RFC 2119, 458 DOI 10.17487/RFC2119, March 1997, 459 . 461 [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 462 Specifications: ABNF", RFC 2234, DOI 10.17487/RFC2234, 463 November 1997, . 465 6.2. Informative References 467 [HS2019] Hardjono, T. and N. Smith, "Decentralized Trusted 468 Computing Base for Blockchain Infrastructure Security, 469 Frontiers Journal, Sepcial Issue on Blockchain Technology, 470 Vol. 2, No. 24", December 2019, 471 . 473 [NIST] Yaga, D., Mell, P., Roby, N., and K. Scarfone, "NIST 474 Blockchain Technology Overview (NISTR-8202)", October 475 2018, . 477 [RFC5939] Andreasen, F., "Session Description Protocol (SDP) 478 Capability Negotiation", RFC 5939, DOI 10.17487/RFC5939, 479 September 2010, . 481 Authors' Addresses 483 Martin Hargreaves 484 Quant Network 486 Email: martin.hargreaves@quant.network 488 Thomas Hardjono 489 MIT 491 Email: hardjono@mit.edu