Secure Asset Transfer Protocol M. Hargreaves Internet-Draft Quant Network Intended status: Informational T. Hardjono Expires: 21 September 2024 MIT R. Belchior INESC-ID, Técnico Lisboa, Blockdaemon 20 March 2024 Secure Asset Transfer Protocol (SATP) Core draft-ietf-satp-core-03 Abstract This memo describes the Secure Asset Transfer (SAT) Protocol for digital assets. SAT is a protocol operating between two gateways that conducts the transfer of a digital asset from one gateway to another. The protocol establishes a secure channel between the endpoints and implements a 2-phase commit (2PC) to ensure the properties of transfer atomicity, consistency, isolation and durability. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://ietf- satp.github.io/draft-ietf-satp-core/draft-ietf-satp-core.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-satp-core/. Discussion of this document takes place on the Secure Asset Transfer Protocol Working Group mailing list (mailto:sat@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/sat/. Subscribe at https://www.ietf.org/mailman/listinfo/sat/. Source for this draft and an issue tracker can be found at https://github.com/ietf-satp/draft-ietf-satp-core. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Hargreaves, et al. Expires 21 September 2024 [Page 1] Internet-Draft SATP Core March 2024 Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 21 September 2024. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Conventions used in this document . . . . . . . . . . . . . . 5 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. The Secure Asset Transfer Protocol . . . . . . . . . . . . . 6 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. SAT Model . . . . . . . . . . . . . . . . . . . . . . . . 6 4.3. Family of APIs . . . . . . . . . . . . . . . . . . . . . 7 4.4. Types of Flows . . . . . . . . . . . . . . . . . . . . . 7 5. SATP Message Format, identifiers and Descriptors . . . . . . 7 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2. SATP Message Format and Payloads . . . . . . . . . . . . 8 5.2.1. Protocol version . . . . . . . . . . . . . . . . . . 8 5.2.2. Message Type . . . . . . . . . . . . . . . . . . . . 8 5.2.3. Digital Asset Identifier . . . . . . . . . . . . . . 9 5.2.4. Session ID: . . . . . . . . . . . . . . . . . . . . . 9 5.2.5. Transfer-Context ID . . . . . . . . . . . . . . . . . 9 5.2.6. Gateway Credential Type . . . . . . . . . . . . . . . 9 5.2.7. Gateway Credential . . . . . . . . . . . . . . . . . 10 5.2.8. Payload Hash . . . . . . . . . . . . . . . . . . . . 10 5.2.9. Signature Algorithms Supported . . . . . . . . . . . 10 5.2.10. Message Signature . . . . . . . . . . . . . . . . . . 10 5.3. Negotiation of Security Protocols and Parameters . . . . 10 5.3.1. TLS Established . . . . . . . . . . . . . . . . . . . 10 5.3.2. Client offers supported credential schemes . . . . . 10 5.3.3. Server selects supported credential scheme . . . . . 10 Hargreaves, et al. Expires 21 September 2024 [Page 2] Internet-Draft SATP Core March 2024 5.3.4. Client asserts or proves identity . . . . . . . . . . 11 5.3.5. Sequence numbers initialized . . . . . . . . . . . . 11 5.3.6. Messages can now be exchanged . . . . . . . . . . . . 11 5.4. Asset Profile Identification . . . . . . . . . . . . . . 11 6. Overview of Message Flows . . . . . . . . . . . . . . . . . . 11 7. Identity and Asset Verification Flow (Stage 0) . . . . . . . 14 8. Transfer Initiation and Commencement Flows (Stage 1) . . . . 14 8.1. Transfer Initialization Claims . . . . . . . . . . . . . 15 8.2. Conveyance of Network Capabilities and Parameters . . . . 16 8.3. Transfer Proposal Message . . . . . . . . . . . . . . . . 17 8.4. Transfer Proposal Receipt Message . . . . . . . . . . . . 18 8.5. Transfer Proposal Reject and Conditional Reject Message . . . . . . . . . . . . . . . . . . . . . . . . . 18 8.6. Transfer Commence Message . . . . . . . . . . . . . . . . 19 8.7. Commence Response Message (ACK-Commence) . . . . . . . . 21 9. Lock Assertion and Receipt (Stage 2) . . . . . . . . . . . . 22 9.1. Lock Assertion Message . . . . . . . . . . . . . . . . . 22 9.2. Lock Assertion Receipt Message . . . . . . . . . . . . . 23 10. Commitment Preparation and Finalization (Stage 3) . . . . . . 24 10.1. Commit Preparation Message (Commit-Prepare) . . . . . . 24 10.2. Commit Ready Message (Commit-Ready) . . . . . . . . . . 25 10.3. Commit Final Assertion Message (Commit-Final) . . . . . 26 10.4. Commit-Final Acknowledgement Receipt Message (ACK-Final-Receipt) . . . . . . . . . . . . . . . . . . 27 10.5. Transfer Complete Message . . . . . . . . . . . . . . . 28 11. SATP Session Resumption . . . . . . . . . . . . . . . . . . . 29 11.1. Primary-Backup Session Resumption . . . . . . . . . . . 30 11.2. Recovery Messages . . . . . . . . . . . . . . . . . . . 30 12. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 31 12.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 32 12.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 32 13. Security Consideration . . . . . . . . . . . . . . . . . . . 32 14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . 33 15. Appendix A: API1 Considerations . . . . . . . . . . . . . . . 33 15.1. Digital Asset Resource Descriptors . . . . . . . . . . . 33 15.1.1. Organization Identifier . . . . . . . . . . . . . . 33 15.1.2. Gateway / Endpoint ID . . . . . . . . . . . . . . . 33 15.1.3. Network or System Identifier . . . . . . . . . . . . 34 15.1.4. Network Resource . . . . . . . . . . . . . . . . . . 34 15.1.5. Examples . . . . . . . . . . . . . . . . . . . . . . 34 15.2. Digital Asset Resource Client Descriptors . . . . . . . 34 15.2.1. Organization Identifier . . . . . . . . . . . . . . 34 15.2.2. Gateway / Endpoint ID . . . . . . . . . . . . . . . 35 15.2.3. Organizational Unit . . . . . . . . . . . . . . . . 35 15.2.4. Name . . . . . . . . . . . . . . . . . . . . . . . . 35 15.2.5. Examples . . . . . . . . . . . . . . . . . . . . . . 35 15.3. Gateway Level Access Control . . . . . . . . . . . . . . 35 15.4. Application Profile Negotiation . . . . . . . . . . . . 36 Hargreaves, et al. Expires 21 September 2024 [Page 3] Internet-Draft SATP Core March 2024 15.5. Discovery of Digital Asset Resources . . . . . . . . . . 36 16. Appendix B: API3 Considerations . . . . . . . . . . . . . . . 37 17. Appendix C: Error Types . . . . . . . . . . . . . . . . . . . 37 17.1. Transfer Commence and Response errors . . . . . . . . . 37 17.2. Lock Assertion errors . . . . . . . . . . . . . . . . . 37 17.3. Lock Assertion Receipt errors . . . . . . . . . . . . . 38 17.4. Commit Preparation errors . . . . . . . . . . . . . . . 38 17.5. Commit Preparation Acknowledgement errors . . . . . . . 38 17.6. Commit Ready errors . . . . . . . . . . . . . . . . . . 38 17.7. Commit Final Assertion errors . . . . . . . . . . . . . 39 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 18.1. Normative References . . . . . . . . . . . . . . . . . . 39 18.2. Informative References . . . . . . . . . . . . . . . . . 39 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 1. Introduction This memo proposes a secure asset transfer protocol (SATP) that is intended to be deployed between two gateway endpoints to transfer a digital asset from an origin network to a destination network. Both the origin and destination networks are assumed to be opaque in the sense that the interior constructs of a given network is not read/write accessible to unauthorized entities. The protocol utilizes the asset burn-and-mint paradigm whereby the asset to be transferred is permanently disabled or destroyed (burned) at the origin network and is re-generated (minted) at the destination network. This is achieved through the coordinated actions of the peer gateways handling the unidirectional transfer at the respective networks. A gateway is assumed to be trusted to perform the tasks involved in the asset transfer. The overall aim of the protocol is to ensure that the state of assets in the origin and destination networks remain consistent, and that asset movements into (out of) networks via gateways can be accounted for. There are several desirable technical properties of the protocol. The protocol must ensure that the properties of atomicity, consistency, isolation, and durability (ACID) are satisfied. The requirement of consistency implies that the asset transfer protocol always leaves both networks in a consistent state (that the asset is located in one system/network only at any time). Hargreaves, et al. Expires 21 September 2024 [Page 4] Internet-Draft SATP Core March 2024 Atomicity means that the protocol must guarantee that either the transfer commits (completes) or entirely fails, where failure is taken to mean there is no change to the state of the asset in the origin (sender) network. The property of isolation means that while a transfer is occurring to a digital asset from an origin network, no other state changes can occur to the asset. The property of durability means that once the transfer has been committed by both gateways, that this commitment must hold regardless of subsequent unavailability (e.g. crash) of the gateways implementing the SAT protocol. All messages exchanged between gateways are assumed to run over TLS1.2, and the endpoints at the respective gateways are associated with a certificate indicating the legal owner (or operator) of the gateway. 2. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [REQ-LEVEL]. In this document, these words will appear with that interpretation only when in ALL CAPS. Lower case uses of these words are not to be interpreted as carrying significance described in RFC 2119. 3. Terminology The following are some terminology used in the current document: * Client application: This is the application employed by a user to interact with a gateway. * Gateway: The computer system functionally capable of acting as a gateway in an asset transfer. * Sender gateway: The gateway that initiates a unidirectional asset transfer. * Recipient gateway: The gateway that is the recipient side of a unidirectional asset transfer. * Claim: An assertion made by an Entity [JWT]. * Claim Type: Syntax used for representing a Claim Value [JWT]. Hargreaves, et al. Expires 21 September 2024 [Page 5] Internet-Draft SATP Core March 2024 * Gateway Claim: An assertion made by a Gateway regarding the status or condition of resources (e.g. assets, public keys, etc.) accessible to that gateway (e.g. within its network or system). 4. The Secure Asset Transfer Protocol 4.1. Overview The Secure Asset Transfer Protocol (SATP) is a gateway-to-gateway protocol used by a sender gateway with a recipient gateway to perform a unidirectional transfer of a digital asset. The protocol defines a number of API endpoints, resources and identifier definitions, and message flows corresponding to the asset transfer between the two gateways. The current document pertains to the interaction between gateways through API2. +----------+ +----------+ | Client | | Off-net | | (App) | | Resource | +----------+ +----------+ | | API3 | | +----------+ | ^ V | +---------+ | | API1 | | +-----+ +---------+----+ +----+---------+ +-----+ | | | | | | | | | | | Net.| | Gateway |API2| |API2| Gateway | | Net.| | NW1 |---| G1 | |<------>| | G2 |---| NW2 | | | | | | | | | | | +-----+ +---------+----+ +----+---------+ +-----+ 4.2. SAT Model The model for SATP is shown in Figure 1. The Client (application) interacts with its local gateway (G1) over an interface (API1) in order to provide instructions to the gateway with regards to actions to assets and related resources located in the local system or network (NW1). Gateways interact with each other over a gateway interface (API2). A given gateway may be required to access resources that are not located in network NW1 or network NW2. Access to these types of resources are performed over an off-network interface (API3). Hargreaves, et al. Expires 21 September 2024 [Page 6] Internet-Draft SATP Core March 2024 4.3. Family of APIs The following are the types of APIs in SATP: * Gateway APIs for client (API1): This is the API that allows a Client (application) to interact with a local gateway and issue instructions for actions pertaining to resources accessible to the gateway. * Gateway APIs for peer gateways (API2): These are the APIs employed by two (2) peer gateways for performing unidirectional asset transfers. * APIs for validation of off-network resources (API3): These are the APIs made available by a resource server (resource owner) that a gateway can use to access resources. The use of these APIs is dependent on the mode of access and the type of flow in question. 4.4. Types of Flows The SAT protocol defines the following three (3) flows: * Transfer Initiation flow: This flow deals with commencing a transfer from one gateway to another. Several tasks are involved, including (but not limited to): (i) gateway identification and mutual authentication; (ii) exchange of asset type (definition) information; (iii) verification of the asset definition, and others. * Lock-Assertion flow: This flow deals with the conveyance of signed assertions from the sender gateway to the receiver gateway regarding the locked status of an asset at the origin network. * Commitment Establishment flow: This flow deals with the asset transfer and commitment establishment between two gateways. These flows will be discussed below. 5. SATP Message Format, identifiers and Descriptors 5.1. Overview This section describes the stages of SATP, the format of the messages exchanged between two gateways and the format for resource descriptors. Hargreaves, et al. Expires 21 September 2024 [Page 7] Internet-Draft SATP Core March 2024 The following lists all of the message payloads in SATP. The mandatory fields are determined by the message type exchanged between the two gateways (see Section 7). 5.2. SATP Message Format and Payloads SATP messages are exchanged between peer gateways, where depending on the message type one gateway may act as a client of the other (and vice versa). 5.2.1. Protocol version This refers to SATP protocol Version, encoded as "major.minor" (separated by a period symbol). 5.2.2. Message Type This refers to the type of request or response to be conveyed in the message. The possible values are: * transfer-init-request: Request to begin transfer parameter negotiations. * transfer-init-response: Response to the request for parameter negotiations. * transfer-commence-msg: Request to begin the commencement of the asset transfer. * ack-commence-msg: Response to accept to the commencement of the asset transfer. * lock-assert-msg: Sender gateway has performed the lock of the asset in the origin network. * assertion-receipt-msg: Receiver gateway acknowledges receiving of the signed lock-assert-msg. * commit-prepare-msg: Sender gateway requests the start of the commitment stage. * ack-prepare-msg: Receiver gateway acknowledges receiving the previous commit-prepare-msg and agrees to start the commitment stage. Hargreaves, et al. Expires 21 September 2024 [Page 8] Internet-Draft SATP Core March 2024 * commit-final-msg: Sender gateway has performed the extinguishment (burn) of the asset in the origin network. * ack-commit-final-msg: Receiver gateway acknowledges receiving of the signed commit-final-msg and has performed the asset creation and assignment in the destination network. * commit-transfer-complete-msg: Sender gateway indicates closure of the current transfer session. 5.2.3. Digital Asset Identifier This is the unique identifier (UUIDv2) that uniquely identifies the digital asset in the origin network which is to be transferred to the destination network. The digital asset identifier is a value that is derived by the applications utilized by the originator and the beneficiary prior to starting the asset transfer. The mechanism used to derive the digital asset identifier is outside the scope of the current document. 5.2.4. Session ID: This is the unique identifier (UUIDv2) representing a session between two gateways handling a single unidirectional transfer. This may be derived from the context-ID at the application level. 5.2.5. Transfer-Context ID This is the unqiue optional identifier (UUIDv2) representing the application layer context. Sequence Number: This is an increasing counter uniquely representing a message from a session. This can be utilikzed used to assist the peer gateways when they are processing multiple simultaneous unrelated transfers. 5.2.6. Gateway Credential Type This is the type type of authentication mechanism supported by the gateway (e.g. SAML, OAuth, X.509) Hargreaves, et al. Expires 21 September 2024 [Page 9] Internet-Draft SATP Core March 2024 5.2.7. Gateway Credential This payload is the actual credential of the gateway (token, certificate, string, etc.). 5.2.8. Payload Hash This is the hash of the current message payload. 5.2.9. Signature Algorithms Supported This is the list of digital signature algorithm supported by a gateway, with the base default being the NIST ECDSA standard. 5.2.10. Message Signature This payload is the actual the ECDSA signature portion over a message. 5.3. Negotiation of Security Protocols and Parameters We present the negotiation stage of the protocols and their parameters. 5.3.1. TLS Established TLS 1.2 or higher MUST be implemented to protect gateway communications. TLS 1.3 or higher SHOULD be implemented where both gateways support TLS 1.3 or higher. 5.3.2. Client offers supported credential schemes Capability negotiation, similar to the Session Description Protocol [RFC5939], occurs prior to data exchange. Initially, the client (application) sends a JSON block containing acceptable credential schemes, such as OAuth2.0 or SAML, in the "Credential Scheme" field of the SATP message. 5.3.3. Server selects supported credential scheme The server (recipient Gateway) selects one acceptable credential scheme from the offered schemes, returning the selection in the "Credential Scheme" field of the SATP message. If no acceptable credential scheme was offered, an HTTP 511 "Network Authentication Required" error is returned in the Action/Response field of the SATP message. Hargreaves, et al. Expires 21 September 2024 [Page 10] Internet-Draft SATP Core March 2024 5.3.4. Client asserts or proves identity The details of the assertion/verification step are specific to the chosen credential scheme and are outside the scope of this document. 5.3.5. Sequence numbers initialized Sequence numbers are used to allow the server to correctly order operations from the client. Some operations may be asynchronous, synchronous, or idempotent with duplicate requests handled differently according to the use case. The initial sequence number is proposed by the client (sender gateway) after credential verification is finalized. The server (recipient gateway) MUST respond with the same sequence number to indicate acceptance. The client increments the sequence number with each new request. Sequence numbers can be reused for retries in the event of a gateway timeout. 5.3.6. Messages can now be exchanged Handshaking is complete at this point, and the client can send SAT messages to perform actions on resources, which MAY reference the SAT Payload field. 5.4. Asset Profile Identification The client and server must mutually agree on the asset type or profile that is the subject of the current transfer. The client provides the server with the asset identification number, or the server may provide the client with the asset identification numbers for the digital asset it supports. Formal specification of asset identification is outside the scope of this document. Globally numbering digital asset types or profiles is expected to be performed by a legally recognized entity. 6. Overview of Message Flows The SATP message flows are logically divided into three (3) stages, with the preparatory stage denoted as Stage-0. How the tasks are achieved in Stage-0 is out of scope for the current document. The Stage-1 flows pertains to the initialization of the transfer between the two gateways. Hargreaves, et al. Expires 21 September 2024 [Page 11] Internet-Draft SATP Core March 2024 After both gateways agree to commence the transfer at the start of Stage-2, the sending gateway G1 must deliver a signed assertion that it has performed the correct lock (burn) on the asset in network NW1. If that assertion is accepted by gateway G2, it must in return transmit a signed receipt to gateway G1 that it has created (minted) a temporary asset in NW2. The Stage-3 flows commits gateways G1 and G2 to the burn and mint in Stage-2. The reader is directed to [SATP-ARCH] for further discussion of this model. Hargreaves, et al. Expires 21 September 2024 [Page 12] Internet-Draft SATP Core March 2024 App1 NW1 G1 G2 NW2 App2 ..|.....|............|......................|............|.....|.. | | | Stage 1 | | | | | | | | | | | (1.1)|--- Init. Request --->| | | | | | | | | | | (1.2)|<--- Init. Response---| | | | | | | | | ..|.....|............|......................|............|.....|.. | | | Stage 2 | | | | | | | | | | | (2.1)|<--Transf. Commence-->| | | | | | | | | | | (2.2)|<--- ACK Commence --->| | | | | | | | | | | | | | | | |<---Lock----|(2.3) | | | | | | | | | | | (2.4)|--- Lock-Assertion--->| | | | | | | | | | | | (2.5)|----Bcast-->| | | | | | | | | | |<--Assertion Receipt--|(2.6) | | | | | | | | ..|.....|............|......................|............|.....|.. | | | Stage 3 | | | | | | | | | | | (3.1)|----Commit Prepare--->| | | | | | | | | | | | (3.2)|----Mint--->| | | | | | | | | | |<--- Commit Ready ----|(3.3) | | | | | | | | | |<---Burn----|(3.4) | | | | | | | | | | | (3.5)|---- Commit Final --->| | | | | | | | | | | | (3.6)|---Assign-->| | | | | | | | | | |<-----ACK Final-------|(3.7) | | | | | | | | | | | | | | | |<---Bcast---|(3.8) | | | | | | | | | | | (3.9)|--Transfer Complete-->| | | ..|.....|............|......................|............|.....|.. Hargreaves, et al. Expires 21 September 2024 [Page 13] Internet-Draft SATP Core March 2024 7. Identity and Asset Verification Flow (Stage 0) Prior to commencing the asset transfer from the sender gateway (client) to the recipient gateway (server), both gateways must perform a number of verifications steps. The types of information required by both the sender and recipient are use-case dependent and asset-type dependent. The verifications include, but not limited to, the following: * Gateway identity mutual verification: This is the identity of the gateway at the protocol and network layer. This may include validating the X509 certificates of the gateways. * Gateway owner verification: This is the verification of the identity (e.g. LEI) of the owners of the gateways. * Gateway device and state validation: This is the device attestation evidence [RATS] that a gateway must collect and convey to each other, where a verifier is assumed to be available to decode, parse and appraise the evidence. * Originator and beneficiary identity verification: This is the identity and public-key of the entity (originator) in the origin network seeking to transfer the asset to another entity (beneficiary) in the destination network. These are considered out of scope in the current specifications, and are assumed to have been successfully completed prior to the commencement of the transfer initiation flow. 8. Transfer Initiation and Commencement Flows (Stage 1) This section describes the SATP Set-up stage, where a sender gateway interacts with a recipient gateway, proposing a session. These artifacts are contained in the Transfer Initiation Claims. Gateways MUST support the use of the HTTP GET and POST methods defined in RFC 2616 [RFC2616] for the endpoint. Clients (sender gateway) MAY use the HTTP GET or POST methods to send messages in this stage to the server (recipient gateway). If using the HTTP GET method, the request parameters may be serialized using URI Query String Serialization. Hargreaves, et al. Expires 21 September 2024 [Page 14] Internet-Draft SATP Core March 2024 The client and server may be required to sign certain messages in order to provide standalone proof (for non-repudiation) independent of the secure channel between the client and server. This proof may be required for audit verifications (e.g. post-event). (NOTE: Flows occur over TLS. Nonces are not shown). 8.1. Transfer Initialization Claims This is set of artifacts pertaining to the asset that must be agreed upon between the client (sender gateway) and the server (recipient gateway). The Transfer Initialization Claims consists of the following: * digital_asset_id: This is the globally unique identifier for the digital asset located in the origin network. * asset_profile_id: This is the globally unique identifier for the asset-profile definition (document) on which the digital asset was issued. * verified_originator_entity_id: This is the identity data of the originator entity (person or organization) in the origin network. This information must be verified by the sender gateway. * verified_beneficiary_entity_id: This is the identity data of the beneficiary entity (person or organization) in the destination network. This information must be verified by the receiver gateway. * originator_pubkey REQUIRED. This is the public key of the asset owner (originator) in the origin network or system. * beneficiary_pubkey REQUIRED. This is the public key of the beneficiary in the destination network. * sender_gateway_network_id REQUIRED. This is the identifier of the origin network or system behind the client. * recipient_gateway_network_id REQUIRED. This is the identifier of the destination network or system behind the server. * client_identity_pubkey REQUIRED. The public key of client who sent this message. * server_identity_pubkey REQUIRED. The public key of server for whom this message is intended. Hargreaves, et al. Expires 21 September 2024 [Page 15] Internet-Draft SATP Core March 2024 * sender_gateway_owner_id: This is the identity information of the owner or operator of the sender gateway. * receiver_gateway_owner_id: This is the identity information of the owner or operator of the recipient gateway. 8.2. Conveyance of Network Capabilities and Parameters This is set of artifacts pertaining to the origin network behind the client (sender gateway) that MAY be communicated to the server (recipient gateway). A server may accept the asset-related claims but reject the transfer request based on parameters of the origin network. Some of these parameters maybe gateway-specific (e.g. chosen signature algorithm), while others are inherent in the origin network (e.g. lock type; average lock duration time; etc.). The network capabilities list is as follows: * sender_gateway_network_id REQUIRED.This is the identifier of the origin network or system behind the client. * signature_algorithm REQUIRED: The digital signature algorithm chosen by the client (sender gateway) for signing claims. * supported_signature_algorithm OPTIONAL: The list of algorithm-id that is supported by the client from which the server MAY select. * Lock_type REQUIRED: faucet, timelock, hashlock, hashtimelock, multi-claim PC, destroy/burn (escrowed cross-claim). * Lock_expiration_time REQUIRED: when will the lock or escrow expire. * Permissions OPTIONAL: list of identities (public-keys or X.509 certificates) that can perform operations on the escrow or lock on the asset in the origin network. * developer_URN OPTIONAL: Assertion of developer / application identity. * credential_profile REQUIRED: Specify type of auth (e.g., SAML, OAuth, X.509). * application_profile OPTIONAL: Vendor or Application specific profile. Hargreaves, et al. Expires 21 September 2024 [Page 16] Internet-Draft SATP Core March 2024 * logging_profile REQUIRED: contains the profile regarding the logging procedure. Default is local store * Access_control_profile REQUIRED: the profile regarding the confidentiality of the log entries being stored. Default is only the gateway that created the logs can access them. * Subsequent calls OPTIONAL: details possible escrow actions. * History OPTIONAL: provides an history of the escrow, in case it has previously been initialized. 8.3. Transfer Proposal Message The purpose of this message is for the client to initiate an asset Transfer and propose the set of claims related to the asset to be transferred. This message must be signed by the client. Depending on the proposal, multiple rounds of communication between the client and the server may occur. This message is sent from the client to the Transfer Initialization Endpoint at the server. The parameters of this message consists of the following: * version REQUIRED: SAT protocol Version (major, minor). * message_type REQUIRED: urn:ietf:satp:msgtype:init-proposal-msg. * session_id REQUIRED: A unique identifier (UUIDv2) chosen by the client to identify the current session. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * transfer_init_claims: The set of artifacts and parameters as the basis for the current transfer. * transfer_init_claims_format OPTIONAL: The format of the transfer initialization claims. * network_capabilities_list REQUIRED: The set of origin network parameters reported by the client to the server. * client_identity_pubkey REQUIRED. The public key of client who sent this message. Hargreaves, et al. Expires 21 September 2024 [Page 17] Internet-Draft SATP Core March 2024 * server_identity_pubkey REQUIRED. The public key of server for whom this message is intended. * multiple_claims_allowed OPTIONAL: true/false. * multiple_cancels_allowed OPTIONAL: true/false. * client signature REQUIRED: The client's signature over the message. 8.4. Transfer Proposal Receipt Message The purpose of this message is for the server to indicate explicit acceptance of the Transfer Initialization Claims in the transfer proposal message. The message must be signed by the server. The message is sent from the server to the Transfer Proposal Endpoint at the client. The parameters of this message consists of the following: * version REQUIRED: SAT protocol Version (major, minor). * message_type REQUIRED: urn:ietf:satp:msgtype:init-receipt-msg * session_id REQUIRED: A unique identifier (UUIDv2) chosen by the client to identify the current session. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * hash_transfer_init_claims REQUIRED: Hash of the Transfer Initialization Claims received in the Transfer Proposal Message. * Timestamp REQUIRED: timestamp referring to when the Initialization Request Message was received. Example: TBD. 8.5. Transfer Proposal Reject and Conditional Reject Message The purpose of this message is for the server to indicate a rejection or conditional rejection of the Transfer Initialization Claims. In the case of a conditional rejection, the server may propose a different set of claims (counter-proposal claims) to the client. Hargreaves, et al. Expires 21 September 2024 [Page 18] Internet-Draft SATP Core March 2024 If the server wishes to indicate a conditional rejection, the server MUST include a counter-proposal set of claims. If the server does not wish to proceed, the server MUST include an empty (blank) counter-proposal. Depending on the proposal and counter-proposal, multiple rounds of communication between the client and the server may occur. The message must be signed by the server. The message is sent from the server to the Transfer Proposal Endpoint at the client. The parameters of this message consists of the following: * version REQUIRED: SAT protocol Version (major, minor). * message_type REQUIRED: rn:ietf:satp:msgtype:init-reject-msg * session_id REQUIRED: A unique identifier (UUIDv2) chosen by the client to identify the current session. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * hash_transfer_init_claims REQUIRED: Hash of the Transfer Initialization Claims received in the Transfer Proposal Message. * transfer_init_counter_claims: The set of artifacts and parameters as the counter-proposal to the client. * Timestamp REQUIRED: timestamp referring to when the Initialization Request Message was received. Example: TBD. 8.6. Transfer Commence Message The purpose of this message is for the client to signal to the server that the client is ready to start the transfer of the digital asset. This message must be signed by the client. This message is sent by the client as a response to the Transfer Proposal Receipt Message previously receuved from the server. This message is sent by the client to the Transfer Commence Endpoint at the server. Hargreaves, et al. Expires 21 September 2024 [Page 19] Internet-Draft SATP Core March 2024 The parameters of this message consists of the following: * message_type REQUIRED. MUST be the value urn:ietf:satp:msgtype:transfer-commence-msg. * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * client_identity_pubkey REQUIRED. The public key of client who sent this message. * server_identity_pubkey REQUIRED. The public key of server for whom this message is intended. * hash_transfer_init_claims REQUIRED: Hash of the Transfer Initialization Claims received in the Transfer Proposal Message. * hash_prev_message REQUIRED. The hash of the last message, in this case the Transfer Proposal Receipt message. * client_transfer_number OPTIONAL. This is the transfer identification number chosen by the client. This number is meaningful only the client. * client_signature REQUIRED. The digital signature of the client. For example, the client makes the following HTTP request using TLS (with extra line breaks for display purposes only): ``` POST /token HTTP/1.1 Host: server.example.com Authorization: Basic awHCaGRSa3F0MzpnWDFmQmF0M2ZG Content-Type: application/x-www-form- urlencoded Hargreaves, et al. Expires 21 September 2024 [Page 20] Internet-Draft SATP Core March 2024 { "message_type": "urn:ietf:satp:msgtype:transfer-commence-msg", "session_id":"9097hkstgkjvVbNH", "originator_pubkey":"zGy89097hkbfgkjvVbNH", "beneficiary_pubkey": "mBGHJjjuijh67yghb", "sender_net_system": "originNETsystem", "recipient_net_system":"recipientNETsystem", "client_identity_pubkey":"fgH654tgeryuryuy", "server_identity_pubkey":"dFgdfgdfgt43tetr535teyrfge4t54334", "transfer_init_claims":"nbvcwertyhgfdsertyhgf2h3v4bd3v21", "hash_prev_message":"DRvfrb654vgreDerverv654nhRbvder4", "client_transfer_number":"ji9876543ewdfgh", "client_signature":"fdw34567uyhgfer45" } ``` 8.7. Commence Response Message (ACK-Commence) The purpose of this message is for the server to indicate agreement to proceed with the asset transfer, based on the artifacts found in the previous Transfer Proposal Message. This message is sent by the server to the Transfer Commence Endpoint at the client. The message must be signed by the server. The parameters of this message consists of the following: * message_type REQUIRED urn:ietf:satp:msgtype:ack-commence-msg * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * client_identity_pubkey REQUIRED. The client for whom this message is intended. * server_identity_pubkey REQUIRED. The server who sent this message. * hash_prev_message REQUIRED.The hash of the last message, in this case the the Transfer Commence Message. * server_transfer_number OPTIONAL. This is the transfer identification number chosen by the server. This number is meaningful only to the server. Hargreaves, et al. Expires 21 September 2024 [Page 21] Internet-Draft SATP Core March 2024 * server_signature REQUIRED. The digital signature of the server. An example of a success response could be as follows: (TBD) 9. Lock Assertion and Receipt (Stage 2) The messages in this stage pertain to the sender gateway providing the recipient gateway with a signed assertion that the asset in the origin network has been locked or disabled and under the control of the sender gateway. In the following, the sender gateway takes the role of the client while the recipient gateway takes the role of the server. The flow follows a request-response model. The client makes a request (POST) to the Lock-Assertion Endpoint at the server. Gateways MUST support the use of the HTTP GET and POST methods defined in RFC 2616 [RFC2616] for the endpoint. Clients MAY use the HTTP GET or POST methods to send messages in this stage to the server. If using the HTTP GET method, the request parameters may be serialized using URI Query String Serialization. (NOTE: Flows occur over TLS. Nonces are not shown). 9.1. Lock Assertion Message The purpose of this message is for the client (sender gateway) to convey a signed claim to the server (receiver gateway) declaring that the asset in question has been locked or escrowed by the client in the origin network (e.g. to prevent double spending). The format of the claim is dependent on the network or system of the client and is outside the scope of this specification. This message is sent from the client to the Lock Assertion Endpoint at the server. The server must validate the claims (payload) in this message prior to the next step. The message must be signed by the client. The parameters of this message consists of the following: * message_type REQUIRED urn:ietf:satp:msgtype:lock-assert-msg. Hargreaves, et al. Expires 21 September 2024 [Page 22] Internet-Draft SATP Core March 2024 * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * client_identity_pubkey REQUIRED. The client who sent this message. * server_identity_pubkey REQUIRED. The server for whom this message is intended. * lock_assertion_claim REQUIRED. The lock assertion claim or statement by the client. * lock_assertion_claim_format REQUIRED. The format of the claim. * lock_assertion_expiration REQUIRED. The duration of time of the lock or escrow upon the asset. * hash_prev_message REQUIRED. The hash of the previous message. * client_transfer_number OPTIONAL. This is the transfer identification number chosen by the client. This number is meaningful only to the client. * client_signature REQUIRED. The digital signature of the client. 9.2. Lock Assertion Receipt Message The purpose of this message is for the server (receiver gateway) to indicate acceptance of the claim(s) in the lock-assertion message delivered by the client (sender gateway) in the previous message. This message is sent from the server to the Assertion Receipt Endpoint at the client. The message must be signed by the server. The parameters of this message consists of the following: * message_type REQUIRED urn:ietf:satp:msgtype:assertion-receipt-msg. * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. Hargreaves, et al. Expires 21 September 2024 [Page 23] Internet-Draft SATP Core March 2024 * client_identity_pubkey REQUIRED. The client for whom this message is intended. * server_identity_pubkey REQUIRED. The server who sent this message. * hash_prev_message REQUIRED. The hash of previous message. * server_transfer_number OPTIONAL. This is the transfer identification number chosen by the server. This number is meaningful only to the server. * server_signature REQUIRED. The digital signature of the server. 10. Commitment Preparation and Finalization (Stage 3) This section describes the transfer commitment agreement between the client (sender gateway) and the server (receiver gateway). This stage must be completed within the time specified in the lock_assertion_expiration value in the lock-assertion message. In the following, the sender gateway takes the role of the client while the recipient gateway takes the role of the server. The flow follows a request-response model. The client makes a request (POST) to the Transfer Commitment endpoint at the server. Gateways MUST support the use of the HTTP GET and POST methods defined in RFC 2616 [RFC2616] for the endpoint. Clients MAY use the HTTP GET or POST methods to send messages in this stage to the server. If using the HTTP GET method, the request parameters maybe serialized using URI Query String Serialization. The client and server may be required to sign certain messages in order to provide standalone proof (for non-repudiation) independent of the secure channel between the client and server. This proof maybe required for audit verifications post-event. (NOTE: Flows occur over TLS. Nonces are not shown). 10.1. Commit Preparation Message (Commit-Prepare) The purpose of this message is for the client to indicate its readiness to begin the commitment of the transfer. Hargreaves, et al. Expires 21 September 2024 [Page 24] Internet-Draft SATP Core March 2024 This message is sent from the client to the Commit Prepare Endpoint at the server. The message must be signed by the client. The parameters of this message consists of the following: * message_type REQUIRED. It MUST be the value urn:ietf:satp:msgtype:commit-prepare-msg * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * client_identity_pubkey REQUIRED. The client who sent this message. * server_identity_pubkey REQUIRED. The server for whom this message is intended. * hash_prev_message REQUIRED. The hash of previous message. * client_transfer_number OPTIONAL. This is the transfer identification number chosen by the client. This number is meaningful only the client. * client_signature REQUIRED. The digital signature of the client. 10.2. Commit Ready Message (Commit-Ready) The purpose The purpose of this message is for the server to indicate to the client that: (i) the server has created (minted) an equivalent asset in the destination network; (ii) that the newly minted asset has been self-assigned to the server; and (iii) that the server is ready to proceed to the next step. This message is sent from the server to the Commit Ready Endpoint at the client. The message must be signed by the server. The parameters of this message consists of the following: * message_type REQUIRED. It MUST be the value urn:ietf:satp:msgtype:commit-ready-msg. Hargreaves, et al. Expires 21 September 2024 [Page 25] Internet-Draft SATP Core March 2024 * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * client_identity_pubkey REQUIRED. The client for whom this message is intended. * server_identity_pubkey REQUIRED. The server who sent this message. * mint_assertion_claims REQUIRED. The mint assertion claim or statement by the server. * mint_assertion_format OPTIONAL. The format of the assertion payload. * hash_prev_message REQUIRED. The hash of previous message. * server_transfer_number OPTIONAL. This is the transfer identification number chosen by the server. This number is meaningful only the server. * server_signature REQUIRED. The digital signature of the server. 10.3. Commit Final Assertion Message (Commit-Final) The purpose of this message is for the client to indicate to the server that the client (sender gateway) has completed the extinguishment (burn) of the asset in the origin network. The message must contain standalone claims related to the extinguishment of the asset by the client. The standalone claim must be signed by the client. This message is sent from the client to the Commit Final Assertion Endpoint at the server. The message must be signed by the server. The parameters of this message consists of the following: * message_type REQUIRED. It MUST be the value urn:ietf:satp:msgtype:commit-final-msg. * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. Hargreaves, et al. Expires 21 September 2024 [Page 26] Internet-Draft SATP Core March 2024 * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * client_identity_pubkey REQUIRED. The client who sent this message. * server_identity_pubkey REQUIRED. The server for whom this message is intended. * burn_assertion_claim REQUIRED. The burn assertion signed claim or statement by the client. * burn_assertion_claim_format OPTIONAL. The format of the claim. * hash_prev_message REQUIRED. The hash of previous message. * client_transfer_number OPTIONAL. This is the transfer identification number chosen by the client. This number is meaningful only the client. * client_signature REQUIRED. The digital signature of the client. 10.4. Commit-Final Acknowledgement Receipt Message (ACK-Final-Receipt) The purpose of this message is to indicate to the client that the server has completed the assignment of the newly minted asset to the intended beneficiary at the destination network. This message is sent from the server to the Commit Final Receipt Endpoint at the client. The message must be signed by the server. The parameters of this message consists of the following: * message_type REQUIRED. It MUST be the value urn:ietf:satp:msgtype:ack-commit-final-msg. * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * client_identity_pubkey REQUIRED. The client for whom this message is intended.. Hargreaves, et al. Expires 21 September 2024 [Page 27] Internet-Draft SATP Core March 2024 * server_identity_pubkey REQUIRED. The server who sent this message. * assignment_assertion_claim REQUIRED. The claim or statement by the server that the asset has been assigned by the server to the intended beneficiary. * assignment_assertion_claim_format OPTIONAL. The format of the claim. * hash_prev_message REQUIRED. The hash of previous message. * server_transfer_number OPTIONAL. This is the transfer identification number chosen by the server. This number is meaningful only the server. * server_signature REQUIRED. The digital signature of the server. 10.5. Transfer Complete Message The purpose of this message is for the client to indicate to the server that the asset transer session (identified by session_id) has been completed and that no further messages are to be expected from the client in regards to this transfer instance. The message closes the first message of Stage 2 (Transfer Commence Message). This message is sent from the client to the Transfer Complete Endpoint at the server. The message must be signed by the client. The parameters of this message consists of the following: * message_type REQUIRED. It MUST be the value urn:ietf:satp:msgtype:commit-transfer-complete-msg. * session_id REQUIRED: A unique identifier (UUIDv2) chosen earlier by client in the Initialization Request Message. * transferContext_id OPTIONAL: An optional identifier (UUIDv2) used to identify the current transfer session at the application layer. * client_identity_pubkey REQUIRED. The client who sent this message. Hargreaves, et al. Expires 21 September 2024 [Page 28] Internet-Draft SATP Core March 2024 * server_identity_pubkey REQUIRED. The server for whom this message is intended. * hash_prev_message REQUIRED. The hash of previous message. * hash_transfer_commence REQUIRED. The hash of the Transfer Commence message at the start of Stage 2. * client_transfer_number OPTIONAL. This is the transfer identification number chosen by the client. This number is meaningful only the client. * client_signature REQUIRED. The digital signature of the client. 11. SATP Session Resumption This section answers the question how can a backup gateway build trust with the counter party gateway to resume the execution of the protocol, in the presence of errors and crashes? Gateways may enter faulty state at any time while execution the protocol. The faulty state can manifest itself by incorrect behavior, leading to gateways emitting alerts and errors. In some instances, gateways may crash. We employ either the primary- backup or self-healing paradigm, meaning that the crashed gateway will eventually be replaced by a functioning one, or recover, respectively. When a crash occurs, we initiate a recovery procedure by the backup gateway or the recovered gateway, as defined in the crash recovery draft [I-D.draft-belchior-satp-gateway-recovery]. In either case, if the recovery happenswithin a time period defined as max_timeout (in Stage 2), the recovered gateway triggers a session resumption. The schema and order of the recovered messages is specified in the crash recovery draft. In the case where there is no answer from the gateway within the specified max_timeout, the counter-party gateway rollbacks the process until that stage. Upon recovery, the crashed gateway learns that the counterparty gateway has initated a rollback, and it proceeds accordingly (by also initating a rollback). Note that rollbacks can also happen in case of unresolved errors. Hargreaves, et al. Expires 21 September 2024 [Page 29] Internet-Draft SATP Core March 2024 The non-crashed gateway that conducts the rollback tries to communicate with the crashed gateway from time to time (self healing) or to contact the backup gateways (primary-backup). In any case, and upon the completion of a rollback, the non-crashed gateway sends a ROLLBACK message to the recovered gateway to notify that a rollback happened. The recovered gateway should answer with ROLLBACK-ACK. Since the self-healing recovery process does not require changes to the protocol (since from the counterparty gateway perspective, the sender gateway is just taking longer than normal; there are no new actions done or logs recorded), we focus on the primary-backup paradigm. 11.1. Primary-Backup Session Resumption Upon a gateway recovering using primary-backup, a new gateway (recovered gateway) takes over the crashed gateway. The counter- party gateway assures that the recovered gateway is legitimate (according to the crash recovery specification). After the recovery, the gateways exchange information about their current view of the protocol, since the crashed gateway may have been in the middle of executing the protocol when it crashed. After that, the gateways agree on the current state of the protocol. 11.2. Recovery Messages We have omitted the logging procedure (only focusing the different messages). As defined in the crash recovery draft [I-D.draft-belchior-satp-gateway-recovery], there are a set of messages that are exchanged between the recovered gateway and counterparty gateway: * RECOVER: when a gateway crashes and recovers, it sends a RECOVER message to the counterparty gateway, informing them of its most recent state. The message contains various parameters such as the session ID, message type, SATP stage, sequence number, a flag indicating if the sender is a backup gateway, the new public key if the sender is a backup, the timestamp of the last known log entry, and the sender's digital signature. * RECOVER-UPDATE: Upon receiving the RECOVER message, the counterparty gateway sends a RECOVER-UPDATE message. This message carries the difference between the log entry corresponding to the received sequence number from the recovered gateway and the latest sequence number (corresponding to the latest log entry). The message includes parameters such as the session ID, message type, Hargreaves, et al. Expires 21 September 2024 [Page 30] Internet-Draft SATP Core March 2024 the hash of the previous message, the list of log messages that the recovered gateway needs to update, and the sender's digital signature. * RECOVER-SUCCESS: The recovered gateway responds with a RECOVER- SUCCESS message if its logs have been successfully updated. If there are inconsistencies detected, the recovered gateway initiates a dispute with a RECOVER-DISPUTE message. The message parameters include session ID, message type, the hash of the previous message, a boolean indicating success, a list of hashes of log entries that were appended to the recovered gateway log, and the sender's digital signature. In case the recovery procedure has failed and a rollback process is needed, the following messages are used: * ROLLBACK: A gateway that initiates a rollback sends a ROLLBACK message. The message parameters include session ID, message type, a boolean indicating success, a list of actions performed to rollback a state (e.g., UNLOCK, BURN), a list of proofs specific to the DLT [SATP], and the sender's digital signature. * ROLLBACK-ACK: Upon successful rollback, the counterparty gateway sends a ROLLBACK-ACK message to the recovered gateway acknowledging that the rollback has been performed successfully. The message parameters are similar to those of the ROLLBACK message. 12. Error Messages SATP SATP distinguishes between application driven closures (terminations) and those caused by errors at the SATP protocol level. The list of errors and desciption can be found in the Appendix. ``` enum { session_closure(1), nonfatal_error (2) fatal_error(3), (255) } AlertLevel; enum { close_notify(0), bad_certificate(42), unsupported_certificate(43), certificate_revoked(44), certificate_expired(45), certificate_unknown(46), illegal_parameter(47), TBD (255) } AlertDescription; struct { AlertLevel level; AlertDescription description; } Alert; ``` Hargreaves, et al. Expires 21 September 2024 [Page 31] Internet-Draft SATP Core March 2024 12.1. Closure Alerts The SATP client and server (gateways) must share knowledge that the transfer connection is ending in order to avoid third party attacks. (a) close_notify: This alert notifies the recipient that the sender gateway will not send any more messages on this transfer connection. Any data received after a closure alert has been received MUST be ignored. (b) user_canceled: This alert notifies the recipient that the sender gateway is canceling the transfer connection for some reason unrelated to a protocol failure. 12.2. Error Alerts When an error is detected by a SATP gateway, the detecting gateway sends a message to its peer. Upon transmission or receipt of a fatal alert message, both gateways MUST immediately close the connection. Whenever a SATP implementation encounters a fatal error condition, it SHOULD send an appropriate fatal alert and MUST close the connection without sending or receiving any additional data. The following error alerts are defined: * connection_error: There is an error in the TLS session establishment (TLS error codes should be reported-up to gateway level) * bad_certificate: The gateway certificate was corrupt, contained signatures, that did not verify correctly, etc. (Some common TLS level errors: unsupported_certificate, certificate_revoked, certificate_expired, certificate_unknown, unknown_ca). * protocol_version_error: The SATP protocol version the peer has attempted to negotiate is recognized but not supported. * (Others TBD) 13. Security Consideration Gateways are of particular interest to attackers because they are a kind of end-to-end pipeline that enable the transferral of digital assets to external networks or systems. Thus, attacking a gateway may be attractive to attackers instead of the network behind a gateway. Hargreaves, et al. Expires 21 September 2024 [Page 32] Internet-Draft SATP Core March 2024 As such, hardware hardening technologies and tamper-resistant crypto- processors (e.g. TPM, Secure Enclaves, SGX) should be considered for implementations of gateways. 14. IANA Consideration (TBD) 15. Appendix A: API1 Considerations In this section we discuss some considerations regarding the interaction between the Application and a Gateway through API1. 15.1. Digital Asset Resource Descriptors Resources are identified by URL [RFC1738]: * Type: application/satres * Access Protocol: SATP Data included in the URL: 15.1.1. Organization Identifier This MAY be a Legal Entity Identifier (LEI) or another identifier linking resource ownership to a real-world entity. Any scheme for identifying gateway owners may be implemented (e.g., LEI directory, closed user group membership, SWIFT BIC, etc.). The developer or application MAY validate the identity with the issuing authority. The identifier is not a trusted identity but MAY be relied upon where trust has been established between the two parties (e.g., in a closed user group). The mechanisms to determine organization identifiers are out of scope for the current specification. 15.1.2. Gateway / Endpoint ID FQDN of the SATP compliant gateway. Required to establish IP connectivity. This MUST resolve to a valid IP address. Hargreaves, et al. Expires 21 September 2024 [Page 33] Internet-Draft SATP Core March 2024 15.1.3. Network or System Identifier Specific to the gateway behind which the target network operates. This field is local to the gateway and is used to direct SATP interactions to the correct underlying network. This value may be alphanumeric or a hexadecimal value. For example: "tradelens-network", "EU-supply-chain". 15.1.4. Network Resource Specifies a resource held on the underlying network. This field must be meaningful to the network in question but is otherwise an arbitrary string. The underlying object it points to may be a network address, data block, transaction ID, alias, etc. or a future object type not yet defined. 15.1.5. Examples The following illustrates using example.com as the endpoint: satpres://example/api.gateway1.com/swift 15.2. Digital Asset Resource Client Descriptors Resources are identified by URN as described below: * The type is new: application/satpclient The URN format does not imply availability of access protocol. Data included in the URN includes the following: 15.2.1. Organization Identifier Legal Entity Identifier (LEI) or other identifier linking resource ownership to a real-world entity. Any scheme for identifying Gateway owners may be implemented (e.g. LEI directory, closed user group membership, BIC, etc.). The Gateway MAY validate the identity with the issuing authority. The identifier is not a trusted identity, but MAY be relied on where trust has been established between the two parties (e.g. in a closed user group). Hargreaves, et al. Expires 21 September 2024 [Page 34] Internet-Draft SATP Core March 2024 15.2.2. Gateway / Endpoint ID Applications which interact with multiple networks can operate in a mode whereby the application connects to its local gateway, which then forwards application traffic to local networks and to remote networks via other SATP gateways. Where this is the case, this field identifies the "home" gateway for this application. This may be required to carry out gateway to gateway handshaking and protocol negotiation, or for the server to look up use case specific data relating to the client. 15.2.3. Organizational Unit The organization unit within the organization that the client (application or developer) belongs to. This assertion should be backed up with authentication via the negotiated protocol. The purpose of this field is to allow gateways to maintain access control mapping between applications and resources that are independent of the authentication and authorization schemes used, supporting future changes and supporting counterparties that operate different schemes. 15.2.4. Name A locally unique (within the OU) identifier, which can identify the application, project, or individual developer responsible for this client connection. This is the most granular unit of access control, and gateways should ensure appropriate identifiers are used for the needs of the application or use case. 15.2.5. Examples The following illustrates using example.com as the endpoint: satpclient:example/api.gatewayserver.example.com/research/luke.riley 15.3. Gateway Level Access Control Gateways can enforce access rules based on standard naming conventions using novel or existing mechanisms such as AuthZ protocols using the resource identifiers above, for example: satpclient:////mybank/api.gatewayserver.mybank.com/lending/ eric.devloper can READ/WRITE Hargreaves, et al. Expires 21 September 2024 [Page 35] Internet-Draft SATP Core March 2024 satpres://example/api.gateway1.com/tradelens AND satpres://example/api.gateway1.com/ripple These rules would allow a client so identified to access resources directly, for example: satpres://example/api.gateway1.com/tradelens/xxxxxADDRESSxxxxx This method allows resource owners to easily grant access to individuals, groups, and organizations. Individual gateway implementations may implement access controls, including subsetting and supersetting of applications or resources according to their own requirements. 15.4. Application Profile Negotiation Where an application relies on specific extensions for operation, these can be represented in an Application Profile. For example, a payments application that tracks payments using a cloud-based API and interacts only with gateways logging messages to that API can establish a resource profile as follows: Application Name: TRACKER X-Tracker_URL: https://api.tracker.com/updates X-Tracking-Policy: Always As gateways implement this functionality, they support the TRACKER application profile, and the application is able to expand its reach by periodically polling for the availability of the profile. This is an intentionally generalized extension mechanism for application or vendor specific functionality. 15.5. Discovery of Digital Asset Resources Applications located outside a network or system SHOULD be able to discover which resources they are authorized to access in a network or system. Resource discovery is handled by the gateway in front of the network. For instance using a GETrequest against the gateway URL with no resource identifier could return a list of URLs available to the requester. This list issubject to the access controls above. Hargreaves, et al. Expires 21 September 2024 [Page 36] Internet-Draft SATP Core March 2024 Gateways MAY allow applications to discover resources they do not have access to. This should be indicated in the free text field, and gateways SHOULD implement a process for applications to request access. Formal specification of supported resource discovery methods is out of scope of this document. 16. Appendix B: API3 Considerations In this section we discuss some considerations regarding the interaction between a gateway and an external resource or service provider through API3. 17. Appendix C: Error Types The following lists the error associated with each message in SATP. (Note: these have been laid out for convenience, and may be grouped together more efficiently later). 17.1. Transfer Commence and Response errors The following are the list of errors related to Transfer Commence and Response: * err_2.1: Badly formed message. * err_2.2: Incorrect parameter. * err_2.3: ACK mismatch. 17.2. Lock Assertion errors The following are the list of errors related to Lock Assertion: * err_2.4.1: Badly formed message: badly formed Claim. * err_2.4.2: Badly formed message: bad signature. * err_2.4.3: Badly formed message: wrong transaction ID. * err_2.4.4: Badly formed message: Mismatch hash values. * err_2.4.5: Expired signing-key certificate. * err_2.4.6: Expired Claim. Hargreaves, et al. Expires 21 September 2024 [Page 37] Internet-Draft SATP Core March 2024 17.3. Lock Assertion Receipt errors The following are the list of errors related to Lock Assertion Receipt: * err_2.6.1: Badly formed message: badly formed Claim. * err_2.6.2: Badly formed message: bad signature. * err_2.6.3: Badly formed message: wrong transaction ID. * err_2.6.4: Badly formed message: Mismatch hash values. * err_2.6.5: Expired signing-key certificate. * err_2.6.6: Expired Claim. 17.4. Commit Preparation errors The following are the list of errors related to Commit Preparation: * err_3.1.1: Badly formed message: wrong transaction ID. * err_3.1.2: Badly formed message: mismatch hash value (i.e. from msg 2.6). * err_3.1.3: Incorrect parameter. * err_3.1.4: Message out of sequence. 17.5. Commit Preparation Acknowledgement errors The following are the list of errors related to Commit Preparation Acknowledgement: * err_3.2.1: Badly formed message: wrong transaction ID. * err_3.2.2: Badly formed message: mismatch hash value. * err_3.2.3: Incorrect parameter. * err_3.2.4: Message out of sequence. 17.6. Commit Ready errors The following are the list of errors related to Commit Ready: * err_3.4.1: Badly formed message: wrong transaction ID. Hargreaves, et al. Expires 21 September 2024 [Page 38] Internet-Draft SATP Core March 2024 * err_3.4.2: Badly formed message: mismatch hash value. * err_3.4.3: Incorrect parameter. * err_3.4.4: Message out of sequence (ACK mismatch). 17.7. Commit Final Assertion errors The following are the list of errors related to Commit Final Assertion: * err_3.6.1: Badly formed message: badly formed Claim. * err_3.6.2: Badly formed message: bad signature. * err_3.6.3: Badly formed message: wrong transaction ID. * err_3.6.4: Badly formed message: Mismatch hash values. * err_3.6.5: Expired signing-key certificate. * err_3.6.6: Expired Claim. 18. References 18.1. Normative References [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [REQ-LEVEL] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . 18.2. Informative References [I-D.draft-belchior-satp-gateway-recovery] Belchior, R., Correia, M., Augusto, A., and T. Hardjono, "Secure Asset Transfer Protocol (SATP) Gateway Crash Recovery Mechanism", Work in Progress, Internet-Draft, draft-belchior-satp-gateway-recovery-01, 29 January 2024, . Hargreaves, et al. Expires 21 September 2024 [Page 39] Internet-Draft SATP Core March 2024 [NIST] Yaga, D., Mell, P., Roby, N., and K. Scarfone, "NIST Blockchain Technology Overview (NISTR-8202)", October 2018, . [RFC5939] Andreasen, F., "Session Description Protocol (SDP) Capability Negotiation", September 2010, . Authors' Addresses Martin Hargreaves Quant Network Email: martin.hargreaves@quant.network Thomas Hardjono MIT Email: hardjono@mit.edu Rafael Belchior INESC-ID, Técnico Lisboa, Blockdaemon Email: rafael.belchior@tecnico.ulisboa.pt Hargreaves, et al. Expires 21 September 2024 [Page 40]