Artefacts Registry

Introduction This memo proposes an API intended to be implemented by Artefact Registries in the context of SATP. A Registry is a component that exposes an API allowing gateways to fetch artefacts related to the SAT protocol ("API3"). Examples of SATP artefacts are network identifiers, entities identifiers, asset profiles, or asset instances. Registries play an important role in maintaining record of artefacts that are important during the Setup Stage of SATP (a.k.a “Stage 0”). Registries are are acting as persistent storage locations for such artefacts. Once registered, artefacts cannot be removed. New versions are appended in the Registry without removing previous versions (append-only principle). Readers are directed first to for a description of the architecture underlying the Registries. All API calls are assumed to run over TLS1.2 or higher, and the endpoints of the registry are associated with a certificate indicating the legal owner (or operator) of the Registry. HTTPS must be used instead of plain HTTP.

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 . 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.

Terminology Please refer to for the terminology used in this document. The artefacts recorded via registries are called Tokenized Asset Records or TARs. Please refer to for more information about TARs.

The Registry API

Overview The Registry API pertains to the interaction between gateways. In such interface was identied as "API3" - see for more details.

The role of the Registry in SATP The three stages of the SATP protocol are described in . Prior to the initiation of SATP the peer gateways may access artefacts related to networks, assets or the gateway themselves. Registries are used to maintain record of such artefacts. Registries are of particular importance in the interactions between the peer gateways during the setup stage (Stage-0) Records stored in a registry are persisted in the form of Tokenized Artefacts Record (TAR). In summary the main concepts of a TAR are as follows:

The Artefact: This is a piece of information containing digitized data or pointing to assets. It can range from configuration data, execution log, network identifier, as well as any form of tangible or intangible asset, such as real estate, art, company shares, or even intellectual property.
The Token: A digital token is created on a network to represent a specific piece of information or an asset.
The Record: The token acts as the immutable record of ownership. It contains vital data about the artefact (metadata), ownership history, and rules for transfer, all secured by a network.

Registry API Message Format, identifiers and Descriptors

Overview This section describes the Registry API message-types, the format of the messages, the format for resource descriptors and other related parameters.

API Digital Signatures and Key Types All API calls must be signed, using JSON Web Signatures mechanism (RFC7515). Registries SHOULD support the algorithms defined in the JSON Web Algorithms (JWA) specification [RFC7518] and key types defined in the JSON Web Key (JWK) specification [RFC7517]. All registries implementing the API must implement at minimal the ECDSA signature algorithm with the P-256 curve and the SHA-256 hash function. Additional signature algorithms and keying parameters may be implemented by the registries. However, these are outside the scope of this specification.

Registry Message Format and Payloads All registry API messages are in JSON format .

Protocol version This refers to the registry API Version, encoded as "major.minor" (separated by a period symbol). The endpoints of the registry should clearly indicate the version of the API. The current version is "1.0" defined in this specification. Implementations not understanding a future option value should return an appropriate error response and cease the negotiation.

Client Credential Types Supported by Registries Registries must support JSON Web Tokens (JWT) [RFC 7519] with OAUth2.0 [RFC6749] as the minimal credential type for authenticating incoming API calls. A registry may support additional credential mechanisms, which may be advertised by the registry through different mechanisms (e.g. config file at a well-known endpoint). However, these mechanisms are out of scope for the current specification.

Registry Supported TLS Schemes Registries must suport TLS1.2 or higher [RFC8448]. The TLS scheme is used by client applications to call the Registry endpoints. Registries must a minimal support the AES-128 in GCM mode with SHA-256 (TLS_AES_128_GCM_SHA256).

Client Offers Other Supported TLS Schemes If a client application wishes to use TLS schemes other then the basic scheme (AES-128 in GCM mode with SHA-256), then the client may choose to send a JSON block containing information regarding the client's supported TLS schemes.

Registry Identifier This is the unique identifier of the registry service. The registry identifier MUST be uniquely bound to its endpoint (e.g. via X.509 certificates). This registry identifier is distinct from the registry operator business identifier (e.g., legal entity identifier (LEI) number). A registry operator may operate multiple registries. Each of the registries MUST be identified by a unique registry identifier. The mechanisms to establish the registry identifier or the operator identifier is outside the scope of this specification.

Signature Algorithms Supported This is a JSON list of digital signature algorithms supported by a registry. Each entry in the list should be either an Algorithm Name value registered in the IANA "JSON Web Signature and Encryption Algorithms" registry established by or be a value that contains a Collision-Resistant Name. All implementations must support a common default of "ES256", which is the ECDSA signature algorithm with the P-256 curve and the SHA-256 hash function.

JSON Canonicalisation Registries must suport JSON Canonicalization .

Overview of API endpoints Registries MUST support the use of the HTTP GET and POST methods defined in RFC 2616 for the endpoint. Clients MAY use the HTTP GET or POST methods to send messages to the registry. 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).

TAR Creation

Call This endpoint stores the input data in the regitry permanent storage and returns a token identifier related to the TAR. The call should return as soon as the input data are persisted in the registry. In case of asynchronous creation of the token identifier associated to the TAR a temporary receipt should be returned. Such receipt should be substituted with the permanent token identifier. This endpoint uses an HTTP POST method Here is an example representation in JSON format:

Return result

Error Message TBD

TAR Read This endpoint retrieves a TAR previously created or updated in the Registry.

Call The parameters of this message consist of the following: * tarid REQUIRED: urn:tar:eip155.444444444500:81d0782847297956410ec1a674e60a78fff14b69

Return result

Error Message TBD

TAR Update Updates the TAR by registering a new version for the specific TARID

Call The parameters of this message consist of the following: * tarid REQUIRED: urn:tar:eip155.444444444500:81d0782847297956410ec1a674e60a78fff14b69

tarBody REQUIRED:

Return result

Error Message TBD

TAR Deletion Archives the TAR

Call The parameters of this message consist of the following: * tarid REQUIRED: urn:tar:eip155.444444444500:81d0782847297956410ec1a674e60a78fff14b69

Return result A success code

Error Message TBD

IANA Consideration The tar namespace might follow a hierachichal structure under the general URN satp namespace, i.e. urn:satp:tar.

Registry API Error Codes TBD

URN Registration URN: Request to be assigned by IANA. Common Name: urn:ietf:satp Registrant Contact: IESG Description: The secure asset transfer protocol (SATP) requires message types, endpoints and parameters to be defined within a unique namespace to prevent collision.

Error Types and Codes This appendix defines the error codes that may be returned in SATP protocol messages.

Protocol Error Codes TBD

Acknowledgements The authors would like to thank the following people for their input and support: Andre, Rafael, Rama.