Secure Asset Transfer Protocol (SATP) Core
draft-ietf-satp-core-06
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
|---|---|---|---|
| Authors | Martin Hargreaves , Thomas Hardjono , Rafael Belchior , Venkatraman Ramakrishna | ||
| Last updated | 2024-10-04 (Latest revision 2024-09-11) | ||
| Replaces | draft-hargreaves-sat-core | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Reviews |
HTTPDIR Early Review due 2024-02-28
Requested
|
||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | WG Document | |
| Associated WG milestone |
|
||
| Document shepherd | (None) | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Yes | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-satp-core-06
Secure Asset Transfer Protocol M. Hargreaves
Internet-Draft Quant Network
Intended status: Informational T. Hardjono
Expires: 7 April 2025 MIT
R. Belchior
INESC-ID, Técnico Lisboa, Blockdaemon
V. Ramakrishna
IBM
4 October 2024
Secure Asset Transfer Protocol (SATP) Core
draft-ietf-satp-core-06
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, each representing their corresponding digital asset
networks. 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.
Hargreaves, et al. Expires 7 April 2025 [Page 1]
Internet-Draft SATP Core October 2024
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/.
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 7 April 2025.
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. Stages of the Protocol . . . . . . . . . . . . . . . . . 6
4.4. Gateway Cryptographic Keys . . . . . . . . . . . . . . . 7
5. SATP Message Format, identifiers and Descriptors . . . . . . 7
5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8
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. Transfer-Context ID: . . . . . . . . . . . . . . . . 9
5.2.5. Session ID: . . . . . . . . . . . . . . . . . . . . . 10
5.2.6. Sequence Number: . . . . . . . . . . . . . . . . . . 10
5.2.7. Gateway Credential Type . . . . . . . . . . . . . . . 10
5.2.8. Gateway Credential . . . . . . . . . . . . . . . . . 10
5.2.9. Payload Hash . . . . . . . . . . . . . . . . . . . . 10
Hargreaves, et al. Expires 7 April 2025 [Page 2]
Internet-Draft SATP Core October 2024
5.2.10. Signature Algorithms Supported . . . . . . . . . . . 10
5.2.11. Message Signature . . . . . . . . . . . . . . . . . . 10
5.2.12. Lock assertion Claims and Format . . . . . . . . . . 10
5.3. Negotiation of Security Protocols and Parameters . . . . 11
5.3.1. TLS Secure Channel Establishment . . . . . . . . . . 11
5.3.2. Client offers supported credential schemes . . . . . 11
5.3.3. Server selects supported credential scheme . . . . . 11
5.3.4. Client asserts or proves identity . . . . . . . . . . 11
5.3.5. Sequence numbers initialized . . . . . . . . . . . . 11
5.3.6. Messages can now be exchanged . . . . . . . . . . . . 12
5.4. Asset Profile Identification . . . . . . . . . . . . . . 12
6. Overview of Message Flows . . . . . . . . . . . . . . . . . . 12
7. Identity and Asset Verification Stage (Stage 0) . . . . . . . 13
8. Transfer Initiation Stage (Stage 1) . . . . . . . . . . . . . 14
8.1. Transfer Initialization Claims . . . . . . . . . . . . . 14
8.2. Conveyance of Gateway and Network Capabilities . . . . . 16
8.3. Transfer Proposal Message . . . . . . . . . . . . . . . . 17
8.4. Transfer Proposal Receipt Message . . . . . . . . . . . . 19
8.5. Transfer Proposal Reject Message . . . . . . . . . . . . 20
8.6. Transfer Commence Message . . . . . . . . . . . . . . . . 21
8.7. Commence Response Message (ACK-Commence) . . . . . . . . 22
9. Lock Assertion Stage (Stage 2) . . . . . . . . . . . . . . . 22
9.1. Lock Assertion Message . . . . . . . . . . . . . . . . . 23
9.2. Lock Assertion Receipt Message . . . . . . . . . . . . . 23
10. Commitment Preparation and Finalization (Stage 3) . . . . . . 24
10.1. Commit Preparation Message (Commit-Prepare) . . . . . . 25
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 . . . . . . . . . . . . . . . 27
11. SATP Session Resumption . . . . . . . . . . . . . . . . . . . 28
11.1. Primary-Backup Session Resumption . . . . . . . . . . . 29
11.2. Recovery Messages . . . . . . . . . . . . . . . . . . . 29
12. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 30
12.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 31
12.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 31
13. Security Consideration . . . . . . . . . . . . . . . . . . . 32
14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . 32
15. Appendix: Error Types . . . . . . . . . . . . . . . . . . . . 32
15.1. Transfer Commence and Response errors . . . . . . . . . 32
15.2. Lock Assertion errors . . . . . . . . . . . . . . . . . 32
15.3. Lock Assertion Receipt errors . . . . . . . . . . . . . 33
15.4. Commit Preparation errors . . . . . . . . . . . . . . . 33
15.5. Commit Preparation Acknowledgement errors . . . . . . . 33
15.6. Commit Ready errors . . . . . . . . . . . . . . . . . . 34
15.7. Commit Final Assertion errors . . . . . . . . . . . . . 34
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
Hargreaves, et al. Expires 7 April 2025 [Page 3]
Internet-Draft SATP Core October 2024
16.1. Normative References . . . . . . . . . . . . . . . . . . 34
16.2. Informative References . . . . . . . . . . . . . . . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35
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 asset network to a destination asset
network. Readers are directed first to [ARCH] for a description of
the architecture underlying the current protocol.
Both the origin and destination asset networks are assumed to be
opaque in the sense that the interior construct 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 asset network and is re-generated (minted) at the
destination asset 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 asset networks in a consistent state
(that the asset is located in one system/network only at any time).
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) asset 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.
Hargreaves, et al. Expires 7 April 2025 [Page 4]
Internet-Draft SATP Core October 2024
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, some
borrowed from [NIST]:
* Digital asset: digital representation of a value or of a right
that is able to be transferred and stored electronically using
distributed ledger technology or similar technology [MICA].
* Asset network: A monolithic system or a set of distributed systems
that manage digital assets.
* 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 7 April 2025 [Page 5]
Internet-Draft SATP Core October 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 asset network or
system).
In the remainder of this document, for brevity of description the
term “asset network” will often be shorted to "network".
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 [SATP-ARCH].
+----------+ +----------+ | Client | | Off-net | ------ | (App) | |
Resource | | +----------+ +----------+ | | | API3 | | |
+----------+ | | ^ | V | | +---------+ | 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 [SATP-ARCH]. 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).
4.3. Stages of the Protocol
The SAT protocol defines three (3) stages for a unidirectional asset
transfer. These stages occur following the transfer set-up.
Hargreaves, et al. Expires 7 April 2025 [Page 6]
Internet-Draft SATP Core October 2024
* Transfer Initiation stage (Stage-1): These flows deal 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 stage (Stage-2): These flows deal with the
conveyance of signed assertions from the sender gateway to the
receiver gateway regarding the locked status of an asset at the
origin asset network.
* Commitment Preparation and Finalization stage (Stage-3): These
flows deal with the asset transfer and commitment establishment
between two gateways.
In order to clarify discussion, the interactions between the peer
gateways prior to transfer initiation stage is referred to as the
setup stage (Stage-0), which is outside the scope of the current
specification.
The Stage-1, Stage-2 and Stage-3 flows will be discussed below.
4.4. Gateway Cryptographic Keys
SATP recognizes the following cryptographic keys which are intended
for distinct purposes within the different stages of the protocol.
* Gateway signature public key-pair: This is the key-pair utilized
by a gateway to digitally sign assertions and receipts.
* Gateway secure channel establishment public key-pair: This is the
key-pair utilized by peer gateways to establish a secure channel
(e.g. TLS) for a transfer session.
* Gateway device-identity public key pair: This is the key-pair that
identifies the unique hardware device underlying a gateway.
* Gateway owner-identity public key pair: This is the key-pair that
identifies the owner (e.g. legal entity) who is the legal owner of
a gateway.
5. SATP Message Format, identifiers and Descriptors
Hargreaves, et al. Expires 7 April 2025 [Page 7]
Internet-Draft SATP Core October 2024
5.1. Overview
This section describes the SATP message-types, the format of the
messages exchanged between two gateways, the format for resource
descriptors and other related parameters.
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-proposal-msg: This is the transfer proposal message from
the sender gateway carrying the set of proposed parameters for the
transfer.
* proposal-receipt-msg: This is the signed receipt message
indicating acceptance of the proposal by the receiver gateway.
* proposal-reject-msg: This is an explicit reject message from the
receiver gateway, indicating a rejection of the proposal and an
immediate session termination.
* 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.
Hargreaves, et al. Expires 7 April 2025 [Page 8]
Internet-Draft SATP Core October 2024
* 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.
* 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 (e.g. UUIDv4) 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. Transfer-Context ID:
This is the unique immutable identifier (e.g. UUIDv4) representing
the application layer context of a single unidirectional transfer.
The method to generate the transfer-context ID is outside the scope
of the current document.
The transfer-context may be a complex data structure that contains
all information related to a SATP execution instance. Examples of
information contained in a transfer-context may include identifiers
of sessions, gateways, networks or assets related to the specific
SATP execution instance.
Hargreaves, et al. Expires 7 April 2025 [Page 9]
Internet-Draft SATP Core October 2024
5.2.5. Session ID:
This is the unique identifier (e.g. UUIDv4) representing a session
between two gateways handling a single unidirectional transfer. This
may be derived from the Transfer-Context ID at the application level.
There may be several session IDs related to a SATP execution
instance. Only one Session ID may be active for a given SATP
execution instance. Session IDs may be stored in the transfer-
context for audit trail purposes.
5.2.6. Sequence Number:
This is a monotonically increasing counter value uniquely
representing a message from a session. This can be utilized to
assist the peer gateways when they are processing multiple
simultaneous unrelated transfers.
5.2.7. Gateway Credential Type
This is the type of authentication mechanism supported by the gateway
(e.g. SAML, OAuth, X.509)
5.2.8. Gateway Credential
This payload is the actual credential of the gateway (token,
certificate, string, etc.).
5.2.9. Payload Hash
This is the hash of the current message payload.
5.2.10. 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.11. Message Signature
This payload is the actual the ECDSA signature portion over a
message.
5.2.12. Lock assertion Claims and Format
This is the format of the set of claims regarding the state of the
asset in the origin network. The claims are network-dependent in the
sense that different asset networks or systems may utilize a
different asset locking (disablement) mechanism.
Hargreaves, et al. Expires 7 April 2025 [Page 10]
Internet-Draft SATP Core October 2024
5.3. Negotiation of Security Protocols and Parameters
The peer gateways in SATP must establish a TLS session between them
prior to starting the transfer initiation stage (Stage-0). The TLS
session continues until the transfer is completed at the end of the
commitment establishment stage (Stage-3).
In the following, the sender gateway is referred to as the client
while the received gateway as the server.
5.3.1. TLS Secure Channel Establishment
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
The client sends a JSON block containing the supported 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.
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 (receiver 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.
Hargreaves, et al. Expires 7 April 2025 [Page 11]
Internet-Draft SATP Core October 2024
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
[ARCH], with the preparatory stage denoted as Stage-0. How the tasks
are achieved in Stage-0 is out of scope for the current
specification.
The Stage-1 flows pertains to the initialization of the transfer
between the two gateways.
After both gateways agree to commence the transfer at the start of
Stage-2, the sender gateway G1 must deliver a signed assertion that
it has performed the correct lock (burn) on the asset in origin
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 destination network (NW2).
The Stage-3 flows commits gateways G1 and G2 to the burn and mint in
Stage-2. The sender gateway G1 must make the lock on the asset in
origin network NW1 to be permanent (burn). The receiver gateway G2
must assign (mint) the asset in the destination network NW2 to the
correct beneficiary.
The reader is directed to [ARCH] for further discussion of this
model.
App1 NW1 G1 G2 NW2 App2
..|.....|............|......................|............|.....|..
| | | Stage 1 | | | | | | | | | | | (1.1)|--Transf. Proposal
Hargreaves, et al. Expires 7 April 2025 [Page 12]
Internet-Draft SATP Core October 2024
-->| | | | | | | | | | | |<--Proposal
Receipt---|(1.2) | | | | | | | | | | (1.3)|<--Transf.
Commence-->| | | | | | | | | | | |<--- ACK Commence
--->|(1.4) | | | | | | | |
..|.....|............|......................|............|.....|..
| | | Stage
2 | | | | | | | | | | |<---Lock----|(2.1) | | | | | | | | | | |
(2.2)|--- Lock-Assertion--->| | | | | | | | | | | |
(2.3)|----Bcast-->| | | | | | | | | | |<--Assertion
Receipt--|(2.4) | | | | | | | |
..|.....|............|......................|............|.....|..
| | | 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-->| | |
..|.....|............|......................|............|.....|..
7. Identity and Asset Verification Stage (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:
* Verification of the gateway signature public key: The sender
gateway and receiver gateway must validate their respective
signature public keys that will later be used to sign assertions
and claims. This may include validating the X509 certificates of
these keys.
* 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 [RFC9334] 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.
Hargreaves, et al. Expires 7 April 2025 [Page 13]
Internet-Draft SATP Core October 2024
* 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. The reader is directed
to [ARCH] for further discussion regarding Stage-0.
8. Transfer Initiation Stage (Stage 1)
This section describes the transfer initiation stage, where the
sender gateway and the receiver gateway prepare for the start of the
asset transfer.
The sender gateway proposes the set of transfer parameters and asset-
related artifacts for the transfer to the receiver gateway. These
are contained in the Transfer Initiation Claims.
If the receiver gateway accepts the proposal, it returns a signed
receipt message for the proposal indicating it agrees to proceed to
the next stage. If the receiver gateway rejects any parameters or
artifacts in the proposal, it can provide a counteroffer to the
sender gateway by responding with a proposal reject message carrying
alternative parameters.
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.
(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:
* digitalAssetId REQUIRED: This is the globally unique identifier
for the digital asset located in the origin network.
Hargreaves, et al. Expires 7 April 2025 [Page 14]
Internet-Draft SATP Core October 2024
* assetProfileId REQUIRED: This is the globally unique identifier
for the asset-profile definition (document) on which the digital
asset was issued.
* verifiedOriginatorEntityId REQUIRED: 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.
* verifiedBeneficiaryEntityId REQUIRED: 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.
* originatorPubkey REQUIRED. This is the public key of the asset
owner (originator) in the origin network or system.
* beneficiaryPubkey REQUIRED. This is the public key of the
beneficiary in the destination network.
* senderGatewaySignaturePublicKey REQUIRED. This is the public key
of the key-pair used by the sender gateway to sign assertions and
receipts.
* receiverGatewaySignaturePublicKey REQUIRED. This is the public
key of the key-pair used by the recevier gateway to sign
assertions and receipts.
* senderGatewayId OPTIONAL. This is the identifier of the sender
gateway.
* recipientGatewayId OPTIONAL. This is the identifier of the
receiver gateway.
* senderGatewayNetworkId REQUIRED. This is the identifier of the
origin network or system behind the client.
* recipientGatewayNetworkId REQUIRED. This is the identifier of the
destination network or system behind the server.
* senderGatewayDeviceIdentityPubkey OPTIONAL. The device public key
of the sender gateway (client).
* receiverGatewayDeviceIdentityPubkey OPTIONAL. The device public
key of the receiver gateway
* senderGatewayOwnerId OPTIONAL: This is the identity information of
the owner or operator of the sender gateway.
Hargreaves, et al. Expires 7 April 2025 [Page 15]
Internet-Draft SATP Core October 2024
* receiverGatewayOwnerId OPTIONAL: This is the identity information
of the owner or operator of the recipient gateway.
Here is an example representation in JSON format:
json { "digitalAssetId": "2c949e3c-5edb-4a2c-9ef4-20de64b9960d",
"assetProfileId": "38561", "verifiedOriginatorEntityId": "CN=Alice,
OU=Example Org Unit, O=Example, L=New York, C=US",
"verifiedBeneficiaryEntityId": "CN=Bob, OU=Case Org Unit, O=Case,
L=San Francisco, C=US", "originatorPubkey":
"0304b9f34d3898b27f85b3d88fa069a879abe14db5060dde466dd1e4a31ff75e44",
"beneficiaryPubkey":
"02a7bc058e1c6f3a79601d046069c9b6d0cb8ea5afc99e6074a5997284756fc9ae",
"senderGatewaySignaturePublicKey":
"02a7bc058e1c6f3a79601d046069c9b6d0cb8ea5afc99e6074a5997284756fc9ae",
"receiverGatewaySignaturePublicKey":
"0243b12ada6515ada3bf99a7da32e84f00383b5765fd7701528e660449ba5ef260",
"senderGatewayId": "GW1", "recipientGatewayId": "GW2",
"senderGatewayNetworkId": "1", "recipientGatewayNetworkId": "43114",
"senderGatewayDeviceIdentityPubkey":
"0245785e34b4a7b457dd4683a297ea3d78bab35f8b2583df55d9df8c69604d0e73",
"receiverGatewayDeviceIdentityPubkey":
"03763f0bc48ff154cff45ea533a9d8a94349d65a45573e4de6ad6495b6e834312b",
"senderGatewayOwnerId": "CN=GatewayOps, OU=GatewayOps Systems,
O=GatewayOps LTD, L=Austin, C=US", "receiverGatewayOwnerId":
"CN=BridgeSolutions, OU=BridgeSolutions Engineering,
O=BridgeSolutions LTD, L=Austin, C=US" }
8.2. Conveyance of Gateway and Network Capabilities
This is set of parameters pertaining to the origin network and the
destination network, and the technical capabilities supported by the
peer gateways.
Some of network-specific parameters regarding the origin network may
be relevant for a receiver gateways to evaluate its ability to
process the proposed transfer.
For example, the average duration of time of a lock to be held by a
sender gateway may inform the receiver gateway about delay
expectations.
The network capabilities list is as follows:
* gatewayDefaultSignatureAlgorithm REQUIRED: The default digital
signature algorithm (algorithm-id) used by a gateway to sign
claims.
Hargreaves, et al. Expires 7 April 2025 [Page 16]
Internet-Draft SATP Core October 2024
* gatewaySupportedSignatureAlgorithms OPTIONAL: The list of other
digital signature algorithm (algorithm-id) supported by a gateway
to sign claims
* networkLockType REQUIRED: The default locking mechanism used by a
network. These can be (i) timelock, (ii) hashlock, (iii)
hashtimelock, and so on (TBD).
* networkLockExpirationTime REQUIRED: The duration of time (in
seconds) for a lock to expire in the network.
* gatewayCredentialProfile REQUIRED: Specify type of auth (e.g.,
SAML, OAuth, X.509).
* gatewayLoggingProfile REQUIRED: contains the profile regarding the
logging procedure. Default is local store
* gatewayAccessControlProfile REQUIRED: the profile regarding the
confidentiality of the log entries being stored. Default is only
the gateway that created the logs can access them.
Here is an example representation in JSON format:
json { "gatewayDefaultSignatureAlgorithm": "ECDSA",
"gatewaySupportedSignatureAlgorithms": ["ECDSA", "RSA"],
"networkLockType": "HASH_TIME_LOCK", "networkLockExpirationTime":
120, "gatewayCredentialProfile": "OAUTH", "gatewayLoggingProfile":
"LOCAL_STORE", "gatewayAccessControlProfile": "RBAC" }
8.3. Transfer Proposal Message
The purpose of this message is for the sender gateway as the client
to initiate an asset transfer session with the receiver gateway as
the server.
The client transmits a proposal message that carries the claims
related to the asset to be transferred. This message must be signed
by the client.
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).
* messageType REQUIRED: urn:ietf:satp:msgtype:transfer-proposal-msg
.
Hargreaves, et al. Expires 7 April 2025 [Page 17]
Internet-Draft SATP Core October 2024
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen by
the client to identify the current session.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* transferInitClaims REQUIRED: The set of artifacts and parameters
as the basis for the current transfer.
* transferInitClaimsFormat REQUIRED: The format of the transfer
initialization claims.
* networkCapabilitiesList REQUIRED: The set of origin network
parameters reported by the client to the server.
* multipleClaimsAllowed OPTIONAL: true/false.
* multipleCancelsAllowed OPTIONAL: true/false.
* clientSignature REQUIRED: The client's signature over the message.
Here is an example of the message request body:
json { "version": "1.0", "messageType":
"urn:ietf:satp:msgtype:transfer-proposal-msg", "sessionId":
"d66a567c-11f2-4729-a0e9-17ce1faf47c1", "transferContextId":
"89e04e71-bba2-4363-933c-262f42ec07a0", "transferInitClaims": {
"digitalAssetId": "2c949e3c-5edb-4a2c-9ef4-20de64b9960d",
"assetProfileId": "38561", "verifiedOriginatorEntityId": "CN=Alice,
OU=Example Org Unit, O=Example, L=New York, C=US",
"verifiedBeneficiaryEntityId": "CN=Bob, OU=Case Org Unit, O=Case,
L=San Francisco, C=US", "originatorPubkey":
"0304b9f34d3898b27f85b3d88fa069a879abe14db5060dde466dd1e4a31ff75e44",
"beneficiaryPubkey":
"02a7bc058e1c6f3a79601d046069c9b6d0cb8ea5afc99e6074a5997284756fc9ae",
"senderGatewaySignaturePublicKey":
"02a7bc058e1c6f3a79601d046069c9b6d0cb8ea5afc99e6074a5997284756fc9ae",
"receiverGatewaySignaturePublicKey":
"0243b12ada6515ada3bf99a7da32e84f00383b5765fd7701528e660449ba5ef260",
"senderGatewayId": "GW1", "recipientGatewayId": "GW2",
"senderGatewayNetworkId": "1", "recipientGatewayNetworkId": "43114",
"senderGatewayDeviceIdentityPubkey":
"0245785e34b4a7b457dd4683a297ea3d78bab35f8b2583df55d9df8c69604d0e73",
"receiverGatewayDeviceIdentityPubkey":
"03763f0bc48ff154cff45ea533a9d8a94349d65a45573e4de6ad6495b6e834312b",
"senderGatewayOwnerId": "CN=GatewayOps, OU=GatewayOps Systems,
O=GatewayOps LTD, L=Austin, C=US", "receiverGatewayOwnerId":
Hargreaves, et al. Expires 7 April 2025 [Page 18]
Internet-Draft SATP Core October 2024
"CN=BridgeSolutions, OU=BridgeSolutions Engineering,
O=BridgeSolutions LTD, L=Austin, C=US" }, "transferInitClaimsFormat":
"JSON", "networkCapabilitiesList": [], // TODO: is the network
capabilities list the same as the conveyance of network capabilities,
or more? "multipleClaimsAllowed":false, "multipleCancelsAllowed":
false, "clientSignature": "428848dcc8bf7d2a9aa81a06a2a316f0b0b5e65eb7
e1af9aa36a7028414b88ec584375281508254be946e32da6edbea6b4c794cd50c8307
53f9b134def087470de4df82000094000000004f564c2054657374204d65737361676
5c001a0ff92315970206155d9ffa29deb57d71b4aa51ebd9bbe1e8033df5452203530
3c323b869475d4e7549304f88883a" }
8.4. Transfer Proposal Receipt Message
The purpose of this message is for the server to indicate explicit
acceptance of the parameters in the claims part of 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).
* messageType REQUIRED: urn:ietf:satp:msgtype:proposal-receipt-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen by
the client to identify the current session.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* hashTransferInitClaims 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.
Here is an example of the message request body:
Hargreaves, et al. Expires 7 April 2025 [Page 19]
Internet-Draft SATP Core October 2024
json { "version": "1.0", "messageType":
"urn:ietf:satp:msgtype:proposal-receipt-msg", "sessionId": "d66a567c-
11f2-4729-a0e9-17ce1faf47c1", "transferContextId":
"89e04e71-bba2-4363-933c-262f42ec07a0", "hashTransferInitClaims":
"154dfaf0406038641e7e59509febf41d9d5d80f367db96198690151f4758ca6e",
"timestamp": "2024-10-03T12:02+00Z" // TODO: shouldn't we have a
signature field? Or would we solely rely on the TLS sig? }
8.5. Transfer Proposal Reject Message
The purpose of this message is for the server to indicate explicit
rejection of the Transfer Initialization Claims in the transfer
proposal message. A reject message is taken to mean an immediate
termination of the session.
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).
* messageType REQUIRED: urn:ietf:satp:msgtype:proposal-reject-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen by
the client to identify the current session.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* hashTransferInitClaims 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.
Here is an example of the message request body:
json { "version": "1.0", "messageType":
"urn:ietf:satp:msgtype:proposal-reject-msg", "sessionId": "d66a567c-
11f2-4729-a0e9-17ce1faf47c1", "transferContextId":
"89e04e71-bba2-4363-933c-262f42ec07a0", "hashTransferInitClaims":
"154dfaf0406038641e7e59509febf41d9d5d80f367db96198690151f4758ca6e",
"timestamp": "2024-10-03T12:02+00Z" // TODO: shouldn't we have a
signature field? Or would we solely rely on the TLS sig? }
Hargreaves, et al. Expires 7 April 2025 [Page 20]
Internet-Draft SATP Core October 2024
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 received from the server.
This message is sent by the client to the Transfer Commence Endpoint
at the server.
The parameters of this message consists of the following:
* messageType REQUIRED. MUST be the value
urn:ietf:satp:msgtype:transfer-commence-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by the client in the Initialization Request Message.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* hashTransferInitClaims REQUIRED: Hash of the Transfer
Initialization Claims in the Transfer Proposal message.
* hashPrevMessage REQUIRED. The hash of the last message, in this
case the Transfer Proposal Receipt message.
* clientSignature REQUIRED. The digital signature of the client.
For example, the client makes the following HTTP request using TLS:
json { "messageType": "urn:ietf:satp:msgtype:transfer-commence-msg",
"sessionId": "d66a567c-11f2-4729-a0e9-17ce1faf47c1",
"transferContextId": "89e04e71-bba2-4363-933c-262f42ec07a0",
"hashTransferInitClaims":
"154dfaf0406038641e7e59509febf41d9d5d80f367db96198690151f4758ca6e",
"hashPrevMessage":
"0b0aecc2680e0d8a86bece6b54c454fba67068799484f477cdf2f87e6541db66",
"clientSignature": "9b134def087470de4df82000094000000004f564c2508254b
e946e32da6edbea6b4c794cd50c830753f054657374204d657373616765c001a0ff92
315970206155d9ffa29deb57d71b4aa51ebd9bbe1e8033df5452203530428848dcc8b
f7d2a9aa81a04b88ec5843752813c323b869475d4e7549304f88883a6a2a316f0b0b5
e65eb7e1af9aa36a702841" }
Hargreaves, et al. Expires 7 April 2025 [Page 21]
Internet-Draft SATP Core October 2024
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 consist of the following:
* messageType REQUIRED urn:ietf:satp:msgtype:ack-commence-msg
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by client in the Initialization Request Message.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* hashPrevMessage REQUIRED.The hash of the last message, in this
case the the Transfer Commence Message.
* serverSignature REQUIRED. The digital signature of the server.
An example of a success response could be as follows: (TBD).
9. Lock Assertion Stage (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 asset 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.
Hargreaves, et al. Expires 7 April 2025 [Page 22]
Internet-Draft SATP Core October 2024
(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:
* messageType REQUIRED urn:ietf:satp:msgtype:lock-assert-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by client in the Initialization Request Message.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* 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.
* hashPrevMessage REQUIRED. The hash of the previous message.
* clientSignature 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.
Hargreaves, et al. Expires 7 April 2025 [Page 23]
Internet-Draft SATP Core October 2024
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:
* messageType REQUIRED urn:ietf:satp:msgtype:assertion-receipt-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by client in the Initialization Request Message.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* hashPrevMessage REQUIRED. The hash of previous message.
* serverSignature 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).
Hargreaves, et al. Expires 7 April 2025 [Page 24]
Internet-Draft SATP Core October 2024
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.
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:
* messageType REQUIRED. It MUST be the value
urn:ietf:satp:msgtype:commit-prepare-msg
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by client in the Initialization Request Message.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* hashPrevMessage REQUIRED. The hash of previous message.
* clientSignature 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:
* messageType REQUIRED. It MUST be the value
urn:ietf:satp:msgtype:commit-ready-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by client in the Initialization Request Message.
Hargreaves, et al. Expires 7 April 2025 [Page 25]
Internet-Draft SATP Core October 2024
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* mintAssertionClaims REQUIRED. The mint assertion claim or
statement by the server.
* mintAssertionFormat OPTIONAL. The format of the assertion
payload.
* hashPrevMessage REQUIRED. The hash of previous message.
* serverSignature 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:
* messageType REQUIRED. It MUST be the value
urn:ietf:satp:msgtype:commit-final-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by client in the Initialization Request Message.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* burnAssertionClaim REQUIRED. The burn assertion signed claim or
statement by the client.
* burnAssertionClaimFormat OPTIONAL. The format of the claim.
* hashPrevMessage REQUIRED. The hash of previous message.
Hargreaves, et al. Expires 7 April 2025 [Page 26]
Internet-Draft SATP Core October 2024
* clientSignature 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:
* messageType REQUIRED. It MUST be the value
urn:ietf:satp:msgtype:ack-commit-final-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by client in the Initialization Request Message.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* assignmentAssertionClaim REQUIRED. The claim or statement by the
server that the asset has been assigned by the server to the
intended beneficiary.
* assignmentAssertionClaimFormat OPTIONAL. The format of the claim.
* hashPrevMessage REQUIRED. The hash of previous message.
* serverSignature 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 sessionId) 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.
Hargreaves, et al. Expires 7 April 2025 [Page 27]
Internet-Draft SATP Core October 2024
The message must be signed by the client.
The parameters of this message consists of the following:
* messageType REQUIRED. It MUST be the value
urn:ietf:satp:msgtype:commit-transfer-complete-msg.
* sessionId REQUIRED: A unique identifier (e.g. UUIDv4) chosen
earlier by client in the Initialization Request Message.
* transferContextId REQUIRED: A unique identifier (e.g. UUIDv4)
used to identify the current transfer session at the application
layer.
* hashPrevMessage REQUIRED. The hash of previous message.
* hashTransferCommence REQUIRED. The hash of the Transfer Commence
message at the start of Stage 2.
* clientSignature 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.
Hargreaves, et al. Expires 7 April 2025 [Page 28]
Internet-Draft SATP Core October 2024
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.
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.
Hargreaves, et al. Expires 7 April 2025 [Page 29]
Internet-Draft SATP Core October 2024
* 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,
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 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 { sessionClosure(1), nonfatalError (2) fatalError(3), (255)
} AlertLevel;
enum { closeNotify(0), badCertificate(42),
unsupportedCertificate(43), certificateRevoked(44),
certificateExpired(45), certificateUnknown(46), illegalParameter(47),
TBD (255) } AlertDescription;
Hargreaves, et al. Expires 7 April 2025 [Page 30]
Internet-Draft SATP Core October 2024
struct { AlertLevel level; AlertDescription description; } Alert; ```
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) closeNotify: 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) userCanceled: 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:
* connectionError: There is an error in the TLS session
establishment (TLS error codes should be reported-up to gateway
level)
* badCertificate: 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).
* protocolVersionError: The SATP protocol version the peer has
attempted to negotiate is recognized but not supported.
* (Others TBD)
Hargreaves, et al. Expires 7 April 2025 [Page 31]
Internet-Draft SATP Core October 2024
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.
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: 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).
15.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.
15.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.
Hargreaves, et al. Expires 7 April 2025 [Page 32]
Internet-Draft SATP Core October 2024
* err_2.4.6: Expired Claim.
15.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.
15.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.
15.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.
Hargreaves, et al. Expires 7 April 2025 [Page 33]
Internet-Draft SATP Core October 2024
15.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.
* 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).
15.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.
16. References
16.1. Normative References
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/rfc/rfc7519>.
[REQ-LEVEL]
Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
16.2. Informative References
Hargreaves, et al. Expires 7 April 2025 [Page 34]
Internet-Draft SATP Core October 2024
[ARCH] Hardjono, T., Hargreaves, M., Smith, N., and V.
Ramakrishna, "Secure Asset Transfer (SAT) Interoperability
Architecture", June 2024,
<https://datatracker.ietf.org/doc/draft-ietf-satp-
architecture/>.
[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-02, 22 July 2024,
<https://datatracker.ietf.org/doc/html/draft-belchior-
satp-gateway-recovery-02>.
[MICA] European Commission, "EU Directive on Markets in Crypto-
Assets Regulation (MiCA)", June 2023,
<https://www.esma.europa.eu/esmas-activities/digital-
finance-and-innovation/markets-crypto-assets-regulation-
mica>.
[NIST] Yaga, D., Mell, P., Roby, N., and K. Scarfone, "NIST
Blockchain Technology Overview (NISTR-8202)", October
2018, <https://doi.org/10.6028/NIST.IR.8202>.
[RFC5939] Andreasen, F., "Session Description Protocol (SDP)
Capability Negotiation", September 2010,
<https://www.rfc-editor.org/info/rfc5939>.
[RFC9334] Birkholz, H., Thaler, D., Richardson, M., Smith, N., and
W. Pan, "Remote Attestation Procedures Architecture
(RATS)", January 2023,
<https://www.rfc-editor.org/info/rfc9334>.
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 7 April 2025 [Page 35]
Internet-Draft SATP Core October 2024
Venkatraman Ramakrishna
IBM
Email: vramakr2@in.ibm.com
Hargreaves, et al. Expires 7 April 2025 [Page 36]