idnits 2.17.00 (12 Aug 2021) /tmp/idnits7609/draft-hargreaves-sat-core-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 document date (May 3, 2022) is 11 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'JWT' is mentioned on line 176, but not defined == Missing Reference: 'RFC 1738' is mentioned on line 346, but not defined ** Obsolete undefined reference: RFC 1738 (Obsoleted by RFC 4248, RFC 4266) == Missing Reference: 'RFC 5939' is mentioned on line 490, but not defined == Missing Reference: 'RATS' is mentioned on line 604, but not defined == Missing Reference: 'RFC2616' is mentioned on line 1010, 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 1209, but no explicit reference was found in the text == Unused Reference: 'RFC7519' is defined on line 1213, but no explicit reference was found in the text == Unused Reference: 'NIST' is defined on line 1219, but no explicit reference was found in the text == Unused Reference: 'RFC5939' is defined on line 1223, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) Summary: 3 errors (**), 0 flaws (~~), 9 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: November 4, 2022 MIT 6 R. Belchior 7 Technico Lisboa 8 May 3, 2022 10 Secure Asset Transfer Protocol 11 draft-hargreaves-sat-core-00 13 Abstract 15 This memo This memo describes the Secure Asset Transfer (SAT) 16 Protocol for digital assets. SAT is a protocol operating between two 17 gateways that conducts the transfer of a digital asset from one 18 gateway to another. The protocol establishes a secure channel 19 between the endpoints and implements a 2-phase commit to ensure the 20 properties of transfer atomicity, consistency, isolation and 21 durability. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on November 4, 2022. 40 Copyright Notice 42 Copyright (c) 2022 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Conventions used in this document . . . . . . . . . . . . . . 4 59 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 4. The Open Digital Asset Protocol . . . . . . . . . . . . . . . 4 61 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 4 62 4.2. SAT Model . . . . . . . . . . . . . . . . . . . . . . . . 5 63 4.3. Types of APIs . . . . . . . . . . . . . . . . . . . . . . 5 64 4.4. Types of Flows . . . . . . . . . . . . . . . . . . . . . 6 65 4.5. Resources and Identifiers . . . . . . . . . . . . . . . . 6 66 5. SAT Message Format, identifiers and Descriptors . . . . . . . 7 67 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 68 5.2. SAT Message Format . . . . . . . . . . . . . . . . . . . 7 69 5.3. Digital Asset Resource Descriptors . . . . . . . . . . . 8 70 5.3.1. Organization Identifier . . . . . . . . . . . . . . . 8 71 5.3.2. Gateway / Endpoint ID . . . . . . . . . . . . . . . . 8 72 5.3.3. Network or system Identifier . . . . . . . . . . . . 8 73 5.3.4. Resource . . . . . . . . . . . . . . . . . . . . . . 9 74 5.3.5. Examples . . . . . . . . . . . . . . . . . . . . . . 9 75 5.4. Digital Asset Resource Client Descriptors . . . . . . . . 9 76 5.4.1. Organization Identifier . . . . . . . . . . . . . . . 9 77 5.4.2. Gateway / Endpoint ID . . . . . . . . . . . . . . . . 9 78 5.4.3. Organizational Unit . . . . . . . . . . . . . . . . . 10 79 5.4.4. Name . . . . . . . . . . . . . . . . . . . . . . . . 10 80 5.4.5. Examples . . . . . . . . . . . . . . . . . . . . . . 10 81 5.5. Gateway Level Access Control . . . . . . . . . . . . . . 10 82 5.6. Negotiation of Security Protocols and Parameters . . . . 11 83 5.6.1. TLS Established . . . . . . . . . . . . . . . . . . . 11 84 5.6.2. Client offers supported credential schemes . . . . . 11 85 5.6.3. Server selects supported credential scheme . . . . . 11 86 5.6.4. Client asserts or proves identity . . . . . . . . . . 11 87 5.6.5. Sequence numbers initialized . . . . . . . . . . . . 11 88 5.6.6. Messages can now be exchanged . . . . . . . . . . . . 12 89 5.7. Asset Profile Identification . . . . . . . . . . . . . . 12 90 5.8. Application Profile Negotiation . . . . . . . . . . . . . 12 91 5.9. Discovery of Digital Asset Resources . . . . . . . . . . 13 92 6. Identity and Asset Verfication Flow (Phase 0) . . . . . . . . 13 93 7. Transfer Initiation Flow (Phase 1) . . . . . . . . . . . . . 14 94 7.1. Initialization Request Message . . . . . . . . . . . . . 14 95 7.2. Initialization Request Message Response (ACK) . . . . . . 16 96 8. Lock-Evidence Verification Flow (Phase 2) . . . . . . . . . . 17 97 8.1. Transfer Commence Message . . . . . . . . . . . . . . . . 17 98 8.2. Transfer Commence Response Message (Ack) . . . . . . . . 19 99 8.3. Lock Evidence Message . . . . . . . . . . . . . . . . . . 20 100 8.4. Lock Evidence Response Message (Ack) . . . . . . . . . . 21 101 9. Commitment Establishment Flow (Phase 3) . . . . . . . . . . . 22 102 9.1. Commit Preparation Message . . . . . . . . . . . . . . . 22 103 9.2. Commit Preparation Response . . . . . . . . . . . . . . . 23 104 9.3. Commit Final Message . . . . . . . . . . . . . . . . . . 23 105 9.4. Commit Final Response Message . . . . . . . . . . . . . . 24 106 9.5. Transfer Complete Message . . . . . . . . . . . . . . . . 25 107 10. Security Consideration . . . . . . . . . . . . . . . . . . . 26 108 11. IANA Consideration . . . . . . . . . . . . . . . . . . . . . 26 109 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 110 12.1. Normative References . . . . . . . . . . . . . . . . . . 26 111 12.2. Informative References . . . . . . . . . . . . . . . . . 26 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 114 1. Introduction 116 This memo proposes a secure asset transfer (SAT) protocol that is 117 intended to be deployed between two gateway endpoints, where the 118 protocol itself is agnostic to the backend system or network behind 119 the respective gateway. 121 The SAT protocol is defined for a unidirectional transfer, with the 122 understanding that it can be deployed as a building block for a 123 bidirectional transfer or exchange of assets. 125 There are several desirable properties of the protocol. The protocol 126 must ensure that non-repudiability of transfers is achieved, and that 127 the classic properties of atomicity, consistency, isolation, and 128 durability (ACID) must be satisfied. 130 The requirement of consistency implies that the asset transfer 131 protocol always leaves both networks in a consistent state (that the 132 asset is located in one system/network only at any time). 134 Atomicity means that the protocol must guarantee that either the 135 transfer commits (completes) or entirely fails, where failure is 136 taken to mean there is no change to the state of the asset in the 137 origin (sender) network. 139 The property of isolation means that while a transfer is occurring to 140 a digital asset from an origin network, no other state changes can 141 occur to the asset. 143 The property of durability means that once the transfer has been 144 committed by both gateways, that this commitment must hold regardless 145 of subsequent unavailability (e.g. crash) of the gateways 146 implementing the SAT protocol. 148 2. Conventions used in this document 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 152 document are to be interpreted as described in RFC 2119 [RFC2119]. 154 In this document, these words will appear with that interpretation 155 only when in ALL CAPS. Lower case uses of these words are not to be 156 interpreted as carrying significance described in RFC 2119. 158 3. Terminology 160 The following are some terminology used in the current document: 162 Client application: This is the application employed by a user to 163 interact with a gateway. 165 Gateway: The computer system functionally capable of acting as a 166 gateway in an asset transfer. 168 Sender gateway: The gateway that initiates a unidirectional asset 169 transfer. 171 Recipient gateway: The gateway that is the recipient side of a 172 unidirectional asset transfer. 174 Claim: An assertion made by an Entity [JWT]. 176 Claim Type: Syntax used for representing a Claim Value [JWT]. 178 Gateway Claim: An assertion made by a Gateway regarding the status or 179 condition of resources (e.g. assets, public keys, etc.) accessible to 180 that gateway (e.g. within its network or system). 182 4. The Open Digital Asset Protocol 184 4.1. Overview 186 The Secure Asset Transfer Protocol (SAT) is a gateway-to-gateway 187 protocol used by a sender gateway with a recipient gateway to perform 188 a unidirectional transfer of a virtual asset. 190 The protocol defines a number of API endpoints, resources and 191 identifier definitions, and message flows corresponding to the asset 192 transfer between the two gateways. 194 +----------+ +----------+ 195 | Client | | Off-net | 196 | (Applic) | | Resource | 197 +----------+ +----------+ 198 | |API Type-3| 199 | +----------+ 200 | ^ 201 V | 202 +----------+ | 203 |API Type-1| | 204 +------+ +----------+----+ +----+----------+ +------+ 205 | | | | | | | | | | 206 | Net. | | Gateway |API | |API | Gateway | | Net. | 207 | L1 |---| G1 |Type|<------>|Type| G2 |---| L2 | 208 | | | | 2 | | 2 | | | | 209 +------+ +----------+----+ +----+----------+ +------+ 211 Figure 1 213 4.2. SAT Model 215 The model for SAT is shown in Figure 1. 217 The Client (application) interacts with its local gateway (G1) over 218 an interface (API Type-1) in order to provide instructions to the 219 gateway with regards to actions to assets and related resources 220 located in the local system (L1). 222 Gateways interact with each other over a gateway interface (API Type- 223 2). A given gateway may be required to access resources that are not 224 located in network L1 or network L2. Access to these types of 225 resources are performed over an off-network interface (API Type-3). 227 4.3. Types of APIs 229 The following are the types of APIs in SAT: 231 o Gateway APIs for client (API Type-1): This the REST APIs that 232 permit a Client (application) to interact with a local gateway, 233 and issue instructions for actions pertaining to resources 234 accessible to the gateway. 236 o Gateway APIs for peer gateways (API Type-2): This is the REST APIs 237 employed by two (2) peer gateways in performing unidirectional 238 asset transfers. 240 o APIs for validation of off-network resources (API Type-3): This is 241 the REST APIs made available by a resource server (resource owner) 242 at which a gateway can access resources. 244 The use of these APIs is dependent on the mode of access and the type 245 of flow in question. 247 4.4. Types of Flows 249 The SAT protocol defines the following three (3) flows: 251 o Transfer Initiation flow: This flow deals with commencing a 252 transfer from one gateway to another. Several tasks are involved, 253 including (but not limited to): (i) gateway identification and 254 mutual authentication; (ii) exchange of asset type (definition) 255 information; (iii) verification of the asset definition, and 256 others. 258 o Lock-Evidence flow: This flow deals with the conveyance of 259 evidence regarding the lock status (e.g. escrow) of an asset by 260 one gateway, and the verification of the evidence by the other 261 gateway. 263 o Commitment Establishment flow: This flow deals with the asset 264 transfer and commitment establishment between two gateways. 266 These flow will be discussed below. 268 4.5. Resources and Identifiers 270 o (a) Resource addressing for systems or networks, using the URL 271 syntax. 273 o (b) Client identification based on the URN format. These are for 274 identifying clients (developers and applications) who access these 275 resources, and which in some use-cases require access 276 authorization. 278 o (c) Protocol message family for negotiating authentication, 279 authorisation, and parameters for confidential channel 280 establishment. 282 o (d) Resource discovery mechanism for developers and applications 283 to discover resources hosted at a gateway. The gateway response 284 is subject to the level of access granted to that developer or 285 application. 287 5. SAT Message Format, identifiers and Descriptors 289 5.1. Overview 291 This section describes (i) the phases of the SAT protocol; (ii) the 292 format of SAT messages; (iii) the format for resource descriptors; 293 (iv) a method for gateways to implement access controls; (iv) 294 protocol for negotiating security capabilities; (v) discovery and 295 accessing resources and provisions for backward compatibility with 296 existing systems. 298 5.2. SAT Message Format 300 SAT messages are exchanged between applications (clients) and 301 gateways (servers). They consist of protocol negotiation and 302 functional messages. 304 Messages are in JSON format, with protocol specific mandatory fields, 305 support for several authentication and authorization schemes and 306 support for a free format field for plaintext or encrypted payloads 307 directed at the gateway. 309 JSON format message, mandatory fields are shown below: 311 o Version: SAT protocol Version (major, minor). 313 o Session ID: unique identifier (UUIDv2) representing a session 315 o Sequence Number: monotonically increasing counter that uniquely 316 represents a message from a session. 318 o SAT Phase: The current SAT phase. 320 o Resource URL: Location of Resource to be accessed. 322 o Developer URN: Assertion of developer / application identity. 324 o Action/Response: GET/POST and arguments (or Response Code) 326 o Credential Profile: Specify type of auth (e.g. SAML, OAuth, 327 X.509) 329 o Credential Block: Credential token, certificate, string 331 o Payload Profile: Asset profile and capabilities 333 o Application Profile: Vendor or Application specific profile 334 o Payload: Payload for POST, responses, and local networks. The 335 payload is specific to the current SAT phase. 337 o Payload Hash: hash of the current message payload. 339 o Message signature: Gateway EDCSA signature over the message 341 Other relevant attributes may exists that need to be captured for 342 logging purposes. 344 5.3. Digital Asset Resource Descriptors 346 Resources are identified by URL [RFC 1738] as described below: 348 o The type is new: application/satres 350 o The access protocol is SAT. 352 Data included in the URL includes the folowing: 354 5.3.1. Organization Identifier 356 This MAY be a Legal Entity Identifier (LEI) or other identifier 357 linking resource ownership to a real world entity. Any scheme for 358 identifying gateway owners may be implemented (e.g. LEI directory, 359 closed user group membership, SWIFT BIC, etc.). 361 The developer or application MAY validate the identity with the 362 issuing authority. The identifier is not a trusted identity, but MAY 363 be relied on where trust has been established between the two parties 364 (e.g. in a closed user group). 366 The mechanisms to determine organizations identifiers is out of scope 367 for the current specification. 369 5.3.2. Gateway / Endpoint ID 371 FQDN of the SAT compliant gateway. Required to establish IP 372 connectivity. This MUST resolve to a valid IP address. 374 5.3.3. Network or system Identifier 376 Specific to the gateway behind which the target network operates. 377 This field is local to the gateway and is used to direct SAT 378 interactions to the correct underlying network. 380 For example: "tradelens-network", "EU-supply-chain". 382 5.3.4. Resource 384 Specifies a resource held on the underlying network. This field must 385 be meaningful to the network in question but is otherwise an 386 arbitrary string. The underlying object it points to may be a 387 network address, data block, transaction ID, alias, etc. or a future 388 object type not yet defined. 390 5.3.5. Examples 392 satres://quant/api.gateway1.com/swift 394 5.4. Digital Asset Resource Client Descriptors 396 Resources are identified by URN as described below: 398 o The type is new: application/satclient 400 The URN format does not imply availability or access protocol. 402 Data included in the URN includes the folowing: 404 5.4.1. Organization Identifier 406 Legal Entity Identifier (LEI) or other identifier linking resource 407 ownership to a real-world entity. Any scheme for identifying Gateway 408 owners may be implemented (e.g. LEI directory, closed user group 409 membership, BIC, etc.). 411 The Gateway MAY validate the identity with the issuing authority. 412 The identifier is not a trusted identity, but MAY be relied on where 413 trust has been established between the two parties (e.g. in a closed 414 user group). 416 5.4.2. Gateway / Endpoint ID 418 Applications which interact with multiple networks can operate in a 419 mode whereby the application connects to its local gateway, which 420 then forwards application traffic to local networks and to remote 421 networks via other SAT gateways. 423 Where this is the case, this field identifies the "home" gateway for 424 this application. This may be required to carry out gateway to 425 gateway handshaking and protocol negotiation, or for the server to 426 look up use case specific data relating to the client. 428 5.4.3. Organizational Unit 430 The organization unit within the organization that the client 431 (application or developer) belongs to. This assertion should be 432 backed up with authentication via the negotiated protocol. 434 The purpose of this field is to allow gateways to maintain access 435 control mapping between applications and resources that are 436 independent of the authentication and authorization schemes used, 437 supporting future changes and supporting counterparties that operate 438 different schemes. 440 5.4.4. Name 442 A locally unique (within the OU) identifier, which can identify the 443 application, project or individual developer responsible for this 444 client connection. This is the most granular unit of access control, 445 and gateways should ensure appropriate identifiers are used for the 446 needs of the application or use case. 448 5.4.5. Examples 450 satclient:quant/api.overledger.quant.com/research/luke.riley 452 5.5. Gateway Level Access Control 454 Gateways can enforce access rules based on standard naming 455 conventions using novel or existing mechanisms such as AuthZ 456 protocols using the resource identifiers above, for example: 458 satclient://hsbc/api.overledger.hsbc.com/lending/eric.devloper 460 can READ/WRITE 462 satres://quant/api.gateway1.com/tradelens 464 AND 466 satres://quant/api.gateway1.com/ripple 468 These rules would allow a client so identified to access resources 469 directly, for example: 471 satres://quant/api.gateway1.com/tradelens/xxxxxADDRESSxxxxx 473 This method allows resource owners to easily grant access to 474 individuals, groups and organizations. Individual gateway 475 implementations may implement access controls, including subsetting 476 and supersetting or applications or resources according to their own 477 requirements. 479 5.6. Negotiation of Security Protocols and Parameters 481 5.6.1. TLS Established 483 TLS 1.2 or higher MUST be implemented to protect gateway 484 communications. TLS 1.3 or higher SHOULD be implemented where both 485 gateways support TLS 1.3 or higher. 487 5.6.2. Client offers supported credential schemes 489 Capability negotiation prior to data exchange, follows a scheme 490 similar to the Session Description Protocol [RFC 5939]. Initially 491 the client (application) sends a JSON block containing acceptable 492 credential schemes, e.g. OAuth2.0, SAML in the "Credential Scheme" 493 field of the SAT message. 495 5.6.3. Server selects supported credential scheme 497 The server (recipient Gateway) selects one acceptable credential 498 scheme from the offered schemes, returning the selection in the 499 "Credential Scheme" field of the SAT message. 501 If no acceptable credential scheme was offered, an HTPP 511 "Network 502 Authentication Required" error is returned in the Action/Response 503 field of the SAT message. 505 5.6.4. Client asserts or proves identity 507 The details of the assertion / verification step are specific to the 508 chosen credential scheme and are out of scope of this document. 510 5.6.5. Sequence numbers initialized 512 Sequence numbers are used to allow the server to correctly order 513 operations from the client, some of which may be asynchronous, 514 synchronous, idempotent with duplicate requests handled in different 515 ways according to the use case. 517 The initial sequence number is proposed by the client (sender 518 gateway) after the finalization of credential verification. The 519 server (recipient gateway) MUST respond with the same sequence number 520 to indicate acceptance. 522 The client (sender gateway) increments the sequence number with each 523 new request. Sequence numbers can be reused for retries in the event 524 of a gateway timeout. 526 5.6.6. Messages can now be exchanged 528 Handshaking is complete at this point, and the client can send SAT 529 messages to perform actions on resources, which MAY reference the SAT 530 Payload field. 532 5.7. Asset Profile Identification 534 The client and server must mutually agree as to the asset type or 535 profile that is the subject to the current transfer from the client 536 and server. The client must provide the server with the asset- 537 identification number, or the server may provide the client with the 538 asset-identification numbers for the digital asset supported by the 539 server. 541 Formal specification of asset identification is out of scope of this 542 document. Global numbering of digital asset types or profiles is 543 expected to be performed by a legally recognized entity. 545 5.8. Application Profile Negotiation 547 Where an application relies on specific extensions for operation, 548 these can be represented in an Application Profile. 550 For example, a payments application tracks payments through the use 551 of a cloud based API and will only interact with gateways that log 552 messages to that API, a resource profile can be established: 554 Application Name: TRACKER 556 X-Tracker_URL: https://api.tracker.com/updates 558 X-Tracking-Policy: Always 560 As gateways implement this functionality, they support the TRACKER 561 application profile, and the application is able to expand its reach 562 by periodically polling for the availability of the profile. 564 This is an intentionally generalized extension mechanism for 565 application or vendor specific functionality. 567 5.9. Discovery of Digital Asset Resources 569 Applications located outside a network or system SHOULD be able to 570 discover which resources they are authorized to access in a network 571 or system. 573 Resource discovery is handled by the gateway in front of the network. 574 For instance using a GET request against the gateway URL with no 575 resource identifier could return a list of URLs available to the 576 requester. This list is subject to the access controls above. 578 Gateways MAY allow applications to discover resources they do not 579 have access to. This should be indicated in the free text field, and 580 gateways SHOULD implement a process for applications to request 581 access. 583 Formal specification of supported resource discovery methods is out 584 of scope of this document. 586 6. Identity and Asset Verfication Flow (Phase 0) 588 Prior to commencing the asset transfer from the sender gateway 589 (client) to the recipient gateway (server), both gateways must 590 perform a number of verifications steps. The types of information 591 required by both the sender and recipient are use-case dependent and 592 asset-type dependent. 594 The verifications include, but not limited to, the following: 596 o Gateway identity mutual verification: This is the identity of the 597 gateway at the protocol and network layer. This may include the 598 public-keys of the gateways. 600 o Gateway owner verification: This is the verification of the 601 identity (e.g. LEI) of the owners of the gateways. 603 o Gateway device and state validation: This is the device 604 attestation evidence [RATS] that a gateway must collect and convey 605 to each other, where a verifier is assumed to be available to 606 decode, parse and appraise the evidence. 608 o Originator and beneficiary identity verification: This is the 609 identity and public-key of the entity (originator) in the origin 610 network seeking to transfer the asset to another entity 611 (beneficiary) in the destination network. 613 These are considered out of scope in the current specifications, and 614 are assumed to have been successfully completed prior to the 615 commencement of the transfer initiation flow. 617 7. Transfer Initiation Flow (Phase 1) 619 This section describes the SAT initialization phase, where a sender 620 gateway interacts with a recipient gateway, proposing a session. 622 For this, several artifacts need to be validated: asset profile, 623 asset ownership evidence, identities, and logging-related operations 624 (log profile, access control profile). 626 In this phase, gateways implement the Transfer Initiation Flows 627 endpoint. 629 In the following, the sender gateway takes instructions from an 630 application, while the recipient gateway may act on behalf of its 631 applications. 633 The flow follows a request-response model. The sender gateway makes 634 a request (POST) to the Transfer Initiation endpoint at the recipient 635 gateway. 637 Gateways MUST support the use of the HTTP GET and POST methods 638 defined in RFC 2616 [RFC2616] for the endpoint. 640 Clients (sender gateway) MAY use the HTTP GET or POST methods to send 641 messages in this phase to the server (recipient gateway). If using 642 the HTTP GET method, the request parameters may be serialized using 643 URI Query String Serialization. 645 The client and server may be required to sign certain messages in 646 order to provide standalone proof (for non-repudiation) independent 647 of the secure channel between the client and server. This proof may 648 be required for audit verifications (e.g. post-event). 650 (NOTE: Flows occur over TLS. Nonces are not shown). 652 7.1. Initialization Request Message 654 This message is sent from the sender gateway (client) to the 655 recipient gateway (server). 657 The purpose of this message is for the client to initiate an asset 658 transfer. Depending on the proposal, multiple rounds of 659 communication between the client and the server may happen. 661 The parameters of this message consists of the following: 663 o Version: SAT protocol Version (major, minor). 665 o Developer URN: Assertion of developer / application identity. 667 o Credential Profile: Specify type of auth (e.g. SAML, OAuth, 668 X.509) 670 o Payload Profile: Asset Profile provenance and capabilities 672 o Application Profile: Vendor or Application specific profile 674 o logging_profile REQUIRED: contains the profile regarding the 675 logging procedure. Default is local store. 677 o Access_control_profile REQUIRED: the profile regarding the 678 confidentiality of the log entries being stored. Default is only 679 the gateway that created the logs can access them. 681 o Initialization Request Message signature REQUIRED: Gateway EDCSA 682 signature over the message 684 o Sender_gateway_pubkey REQUIRED: the public key of the gateway 685 initiating a transfer 687 o Sender_gateway_network_id REQUIRED: the ID of the source network 689 o Recipient_gateway_pubkey REQUIRED: the public key of the gateway 690 involved in a transfer 692 o Recipient_gateway_network_id REQUIRED: the ID of the recipient 693 network 695 o Escrow type: faucet, timelock, hashlock, hashtimelock, multi-claim 696 PC, destroy/burn (escrowed cross-claim). 698 o Expiry time: when will the escrow or lock expire 700 o Multiple claims allowed: true/false 702 o Multiple cancels allowed: true/false 704 o Permissions: list of identities (public-keys or X.509 705 certificates) that can perform operations on the escrow or lock on 706 the asset in the origin network. 708 o Origin: along with the sender gateway identification, allows 709 identifying from where are the asset is escrowed/provided 711 o Destination: along with the recipient gateway identification, 712 allows identifying to where are the escrowed asset is going 714 o Subsequent calls: details possible escrow actions 716 o History (optional): provides an history of the escrow, in case it 717 has previously been initialized. 719 The sender gateway makes the following HTTP request using TLS. 721 Example: TBD. 723 7.2. Initialization Request Message Response (ACK) 725 After receiving an Initialization Request Message, the recipient 726 gateway needs to validate the profiles. 728 This validation could be performed automatically (using a defined set 729 of rules), or by requiring approval by an application. 731 If one of the profiles is rejected, the recipient gateway constructs 732 a Initialization Denied Message, stating what was rejected, and 733 proposing an alternative (if applicable). 735 Otherwise, if approved, the recipient gateway constructs an 736 Initialization Request Message Response. 738 The purpose of this message is for the server (recipient gateway) to 739 indicate agreement to proceed with the proposed operations, under the 740 proposed profiles. 742 This message is sent from the recipient gateway to the sender gateway 743 (client) in response to a Initialization Request from the sender 744 gateway. 746 The message must be signed by the server. 748 The parameters of this message consists of the following: 750 o Session ID: unique identifier (UUIDv2) representing a session. 752 o Sequence Number: monotonically increasing counter that uniquely 753 represents a message from a session. 755 o SAT Phase: The current SAT phase. 757 o Hash of the Initialization Request Message REQUIRED: the hash of 758 the proposal. 760 o Destination: if the recipient gateway calculates the destination 761 address dynamically. 763 o Timestamp REQUIRED: timestamp referring to when the Initialization 764 Request Message was received. 766 o Processed Timestamp REQUIRED: timestamp referring to when the 767 Initialization Response Message was constructed. 769 Example: TBD. 771 8. Lock-Evidence Verification Flow (Phase 2) 773 This section describes the conveyance of claims regarding the status 774 of the asset (or resource) from a sender gateway to a recipient 775 gateway. 777 In this phase, the gateways implement the Lock-Evidence Agreement 778 endpoint. 780 In the following, the sender gateway takes the role of the client 781 while the recipient gateway takes the role of the server. 783 The flow follows a request-response model. The client makes a 784 request (POST) to the Lock-Evidence Agreement endpoint at the server. 786 Gateways MUST support the use of the HTTP GET and POST methods 787 defined in RFC 2616 [RFC2616] for the endpoint. 789 Clients MAY use the HTTP GET or POST methods to send messages in this 790 phase to the server. If using the HTTP GET method, the request 791 parameters may be serialized using URI Query String Serialization. 793 The client and server may be required to sign certain messages in 794 order to provide standalone proof (for non-repudiation) independent 795 of the secure channel between the client and server. This proof may 796 be required for audit verifications post-event. 798 (NOTE: Flows occur over TLS. Nonces are not shown). 800 8.1. Transfer Commence Message 802 This message is sent from the client (sender gateway) to the Transfer 803 Request Endpoint at the server (recipient gateway). It signals to 804 the server that the client is ready to start the transfer of the 805 digital asset. 807 The message must contain claims related to the information from the 808 previous flow (Phase 1). It must be signed by the client. 810 The parameters of this message consists of the following: 812 o message_type REQUIRED. MUST be the value 813 urn:ietf:sat:msgtype:transfer-commence-msg 815 o originator_pubkey REQUIRED. This is the public key of the asset 816 owner (originator) in the origin network or system. 818 o beneficiary_pubkey REQUIRED. This is the public key of the 819 beneficiary in the destination network. 821 o sender_gateway_network_id REQUIRED. This is the identifier of the 822 origin network or system behind the client. 824 o recipient_gateway_network_id REQUIRED. This is the identifier of 825 the destination network or system behind the server. 827 o client_identity_pubkey REQUIRED. The public key of client who 828 sent this message. 830 o server_identity_pubkey REQUIRED. The public key of server for 831 whom this message is intended. 833 o hash_asset_profile REQUIRED. This is the hash of the asset 834 profile previously agreed upon in Phase 1. 836 o asset_unit OPTIONAL. If applicable this is the unit amount of the 837 asset being transferred, previously agreed upon. 839 o hash_prev_message REQUIRED. The hash of the last message in Phase 840 1. 842 o client_transfer_number OPTIONAL. This is the transfer 843 identification number chosen by the client. This number is 844 meaningful only the client. 846 o client_signature REQUIRED. The digital signature of the client. 848 For example, the client makes the following HTTP request using TLS 849 (with extra line breaks for display purposes only): 851 POST /token HTTP/1.1 852 Host: server.example.com 853 Authorization: Basic awHCaGRSa3F0MzpnWDFmQmF0M2ZG 854 Content-Type: application/x-www-form-urlencoded 856 { 857 "message_type": "urn:ietf:sat:msgtype:transfer-commence-msg", 858 "originator_pubkey":"zGy89097hkbfgkjvVbNH", 859 "beneficiary_pubkey": "mBGHJjjuijh67yghb", 860 "sender_net_system": "originNETsystem", 861 "recipient_net_system":"recipientNETsystem", 862 "client_identity_pubkey":"fgH654tgeryuryuy", 863 "server_identity_pubkey":"dFgdfgdfgt43tetr535teyrfge4t54334", 864 "hash_asset_profile":"nbvcwertyhgfdsertyhgf2h3v4bd3v21", 865 "asset_unit": "ghytredcfvbhfr", 866 "hash_prev_message":"DRvfrb654vgreDerverv654nhRbvder4", 867 "client_transfer_number":"ji9876543ewdfgh", 868 "client_signature":"fdw34567uyhgfer45" 869 } 871 Figure 2 873 8.2. Transfer Commence Response Message (Ack) 875 The purpose of this message is for the server to indicate agreement 876 to proceed with the asset transfer. 878 This message is sent from the server (recipient gateway) to client 879 (sender gateway) in response to a Transfer Commence Request from the 880 client. 882 The message must be signed by the server. 884 The parameters of this message consists of the following: 886 o message_type REQUIRED urn:ietf:sat:msgtype:transfer-commenceack- 887 msg 889 o client_identity_pubkey REQUIRED. The client for whom this message 890 is intended. 892 o server_identity_pubkey REQUIRED. The server who sent this 893 message. 895 o hash_commence_request REQUIRED. The hash of previous message. 897 o server_transfer_number OPTIONAL. This is the transfer 898 identification number chosen by the server. This number is 899 meaningful only to the server. 901 o server_signature REQUIRED. The digital signature of the server. 903 An example of a success response could be as follows: 905 ``` 906 HTTP/1.1 200 OK 907 Content-Type: application/json;charset=UTF-8 908 Cache-Control: no-store 909 Pragma: no-cache 911 { 912 "message_type":"urn:ietf:sat:msgtype:transfer-commenceack-msg", 913 "client_identity_pubkey":"fgH654tgeryuryuy", 914 "server_identity_pubkey":"dFgdfgdfgt43tetr535teyrfge4t54334", 915 "hash_commence_request":"DRvfrb654vgreDerverv654nhRbvder4", 916 "server_transfer_number":"ji9876543ewdfgh", 917 "server_signature":"aaw34567uyhgfer66" 918 } 919 ``` 921 Figure 3 923 8.3. Lock Evidence Message 925 The purpose of this message is for the client (sender gateway) to 926 deliver the relevant asset locking (or escrow) evidence to the server 927 (recipient gateway). 929 The format of the evidence is dependent on the network or system 930 fronted by the client and is outside the scope of this specification. 932 This message is sent from the client to the Evidence Validation 933 Endpoint at the server. 935 The server must validate the lock evidence claims (payload) in this 936 message prior to the next step. 938 The message must be signed by the client (sender gateway). 940 The parameters of this message consists of the following: 942 o message_type REQUIRED urn:ietf:sat:msgtype:lock-evidence-req-msg 943 o client_identity_pubkey REQUIRED. The client who sent this 944 message. 946 o server_identity_pubkey REQUIRED. The server for whom this message 947 is intended. 949 o lock_evidence_claim REQUIRED. The lock or escrow evidence (on the 950 network behind the client). 952 o lock_claim_format OPTIONAL. The format of the evidence. 954 o lock_evidence_expiration REQUIRED. The duration of time of lock 955 on the asset (after which the lock is released). 957 o hash_commence_ack_request REQUIRED. The hash of the previous 958 message. 960 o client_transfer_number OPTIONAL. This is the transfer 961 identification number chosen by the client. This number is 962 meaningful only to the client. 964 o client_signature REQUIRED. The digital signature of the client. 966 8.4. Lock Evidence Response Message (Ack) 968 The purpose of this message is for the transfer server (recipient 969 gateway) to indicate acceptance of the asset-escrow (or lock) 970 evidence delivered by the client (sender gateway) in the previous 971 message. 973 The message must be signed by the server. 975 The parameters of this message consists of the following: 977 o message_type REQUIRED urn:ietf:sat:msgtype:lock-evidence-ack-msg 979 o client_identity_pubkey REQUIRED. The client for whom this message 980 is intended. 982 o server_identity_pubkey REQUIRED. The server who sent this 983 message. 985 o hash_lockevidence_request REQUIRED. The hash of previous message. 987 o server_transfer_number OPTIONAL. This is the transfer 988 identification number chosen by the server. This number is 989 meaningful only to the server. 991 o server_signature REQUIRED. The digital signature of the server. 993 9. Commitment Establishment Flow (Phase 3) 995 This section describes the transfer commitment agreement between the 996 sender gateway to a recipient gateway. 998 This phase must be completed within the asset-lock duration time 999 specificied in the previous lock_evidence_expiration parameter. 1001 In this phase gateways implement the Transfer Commitment endpoint. 1003 In the following, the sender gateway takes the role of the client 1004 while the recipient gateway takes the role of the server. 1006 The flow follows a request-response model. The client makes a 1007 request (POST) to the Transfer Commitment endpoint at the server. 1009 Gateways MUST support the use of the HTTP GET and POST methods 1010 defined in RFC 2616 [RFC2616] for the endpoint. 1012 Clients MAY use the HTTP GET or POST methods to send messages in this 1013 phase to the server. If using the HTTP GET method, the request 1014 parameters maybe serialized using URI Query String Serialization. 1016 The client and server may be required to sign certain messages in 1017 order to provide standalone proof (for non-repudiation) independent 1018 of the secure channel between the client and server. This proof 1019 maybe required for audit verifications post-event. 1021 (NOTE: Flows occur over TLS. Nonces are not shown). 1023 9.1. Commit Preparation Message 1025 The purpose of this message is for the client to indicate its 1026 readiness to begin the commitment of the transfer. 1028 The message must be signed by the client. 1030 The parameters of this message consists of the following: 1032 o message_type REQUIRED. It MUST be the value 1033 urn:ietf:sat:msgtype:commit-prepare-msg 1035 o client_identity_pubkey REQUIRED. The client who sent this 1036 message. 1038 o server_identity_pubkey REQUIRED. The server for whom this message 1039 is intended. 1041 o hash_lockevidence_ack REQUIRED. The hash of previous message. 1043 o client_transfer_number OPTIONAL. This is the transfer 1044 identification number chosen by the client. This number is 1045 meaningful only the client. 1047 o client_signature REQUIRED. The digital signature of the client. 1049 9.2. Commit Preparation Response 1051 The purpose of this message is for the server to indicate to the 1052 client its readiness to proceed with the commitment finalization 1053 step. 1055 The message must be signed by the server. 1057 The parameters of this message consists of the following: 1059 o message_type REQUIRED. It MUST be the value 1060 urn:ietf:sat:msgtype:commit-prepare-ack-msg 1062 o client_identity_pubkey REQUIRED. The client for whom this message 1063 is intended. 1065 o server_identity_pubkey REQUIRED. The server who sent this 1066 message. 1068 o hash_commitprep REQUIRED. The hash of previous commit preparation 1069 message. 1071 o server_transfer_number OPTIONAL. This is the transfer 1072 identification number chosen by the server. This number is 1073 meaningful only the server. 1075 o server_signature REQUIRED. The digital signature of the server. 1077 9.3. Commit Final Message 1079 The purpose of this message is for the client to indicate to the 1080 server that the client (sender gateway) has completed local 1081 extinguishment of the asset on its network or system (L1), and that 1082 now on its part the server (recipient gateway) must re-generate the 1083 asset on its network or system (L2). 1085 The message must contain standalone claims related to the 1086 extinguishment of the asset by the client. The claim must be signed 1087 by the client. 1089 The parameters of this message consists of the following: 1091 o message_type REQUIRED. It MUST be the value 1092 urn:ietf:sat:msgtype:commit-final-msg 1094 o client_identity_pubkey REQUIRED. The client who sent this 1095 message. 1097 o server_identity_pubkey REQUIRED. The server for whom this message 1098 is intended. 1100 o commit_final_claim REQUIRED. This is one or more claims signed by 1101 the client that the asset in question has been extinguished by the 1102 client in its local network or system. 1104 o commit_final_claim_format OPTIONAL. This is the format of the 1105 claim provided by the client in this message. 1107 o hash_commitprepare_ack REQUIRED. The hash of previous message. 1109 o client_transfer_number OPTIONAL. This is the transfer 1110 identification number chosen by the client. This number is 1111 meaningful only the client. 1113 o client_signature REQUIRED. The digital signature of the client. 1115 9.4. Commit Final Response Message 1117 The purpose of this message is for the server to indicate to the 1118 client that the server has completed the asset re-generation at its 1119 network or system (L2). 1121 The message must contain standalone claims related to the re- 1122 generated of the asset by the server. It must be signed by the 1123 server. 1125 The parameters of this message consists of the following: 1127 o message_type REQUIRED. It MUST be the value 1128 urn:ietf:sat:msgtype:commit-final-ack-msg 1130 o client_identity_pubkey REQUIRED. The client for whom this message 1131 is intended.. 1133 o server_identity_pubkey REQUIRED. The server who sent this 1134 message. 1136 o commit_acknowledgement_claim REQUIRED. This is one or more claims 1137 signed by the server that the asset in question has been 1138 regenerated by the server in its local network or system. 1140 o commit_acknowledgement_claim_format OPTIONAL. This is the format 1141 of the claim provided by the server in this message. 1143 o hash_commitfinal REQUIRED. The hash of previous commit final 1144 message. 1146 o server_transfer_number OPTIONAL. This is the transfer 1147 identification number chosen by the server. This number is 1148 meaningful only the server. 1150 o server_signature REQUIRED. The digital signature of the server. 1152 9.5. Transfer Complete Message 1154 The purpose of this message is for the client to indicate to the 1155 server that the asset transer has been completed and that no further 1156 messages are to be expected from the client in regards to this 1157 transfer instance. 1159 The message logically closes the first message of Phase 2 (Transfer 1160 Commence Message). It must be signed by the client. 1162 The parameters of this message consists of the following: 1164 o message_type REQUIRED. It MUST be the value 1165 urn:ietf:sat:msgtype:commit-transfer-complete-msg 1167 o client_identity_pubkey REQUIRED. The client who sent this 1168 message. 1170 o server_identity_pubkey REQUIRED. The server for whom this message 1171 is intended. 1173 o hash_commit_final_ack REQUIRED. The hash of previous message. 1175 o hash_transfer_commence REQUIRED. The hash of the Transfer 1176 Commence message at the start of Phase 2. 1178 o client_transfer_number OPTIONAL. This is the transfer 1179 identification number chosen by the client. This number is 1180 meaningful only the client. 1182 o client_signature REQUIRED. The digital signature of the client. 1184 10. Security Consideration 1186 Gateways are of particular interest to attackers because they are a 1187 kind of end-to-end pipeline that enable the transferral of digital 1188 assets to external networks or systems. Thus, attacking a gateway 1189 may be attractive to attackers instead of the network behind a 1190 gateway. 1192 As such, hardware hardening technologies and tamper-resistant crypto- 1193 processors (e.g. TPM, Secure Enclaves, SGX) should be considered for 1194 implementations of gateways. 1196 11. IANA Consideration 1198 (TBD) 1200 12. References 1202 12.1. Normative References 1204 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1205 Requirement Levels", BCP 14, RFC 2119, 1206 DOI 10.17487/RFC2119, March 1997, 1207 . 1209 [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1210 Specifications: ABNF", RFC 2234, DOI 10.17487/RFC2234, 1211 November 1997, . 1213 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1214 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1215 . 1217 12.2. Informative References 1219 [NIST] Yaga, D., Mell, P., Roby, N., and K. Scarfone, "NIST 1220 Blockchain Technology Overview (NISTR-8202)", October 1221 2018, . 1223 [RFC5939] Andreasen, F., "Session Description Protocol (SDP) 1224 Capability Negotiation", RFC 5939, DOI 10.17487/RFC5939, 1225 September 2010, . 1227 Authors' Addresses 1229 Martin Hargreaves 1230 Quant Network 1232 Email: martin.hargreaves@quant.network 1234 Thomas Hardjono 1235 MIT 1237 Email: hardjono@mit.edu 1239 Rafael Belchior 1240 Technico Lisboa 1242 Email: rafael.belchior@tecnico.ulisboa.pt