<-Basic API Go to ToC Workflow Description ->

1 Reference Model

Figure 1 depicts the Reference Model of the MPAI Store.

Figure 1 - Reference Model of the MPAI Store

Figure 1 – Reference Model of the MPAI Store

The MPAI Store is a repository of approved Metadata. It does not hold the Implementations the Metadata names, nor the data in Access that the Metadata names by URI and SHA-256: they are where their Implementers keep them, at the locations the Metadata states. It is the guarantor of the infrastructure: it approves AIM Instance Metadata – what an AIM is, what it takes and produces, where its Implementation is – and says whether an Implementation is the one its Implementer submitted. It issues the AIM Licence of an AIM that has one. It never runs an AIM, and is not addressed by a User Agent at run time.

Implementers submit AIM Instance Metadata, and keep the Implementations where the Metadata states. Controllers obtain the approved Metadata they need, obtain the Implementations from the locations it states, and ask the Store to verify them. A Service of MPAI-MAS builds its own business on approved Metadata: its Applications, their Workflows and their descriptors are its own.

2 Functions

Table 1 – Functions of the MPAI Store

Function Description
Approval Validates submitted AIM Instance Metadata against the AIM Metadata Schema and checks that it is an instance of the AIM Metadata its Header names (Metadata). For a Composite AIM, checks that the AIM Instance Metadata of each Sub-AIM is in the submission or in the Store, since without it the Composite AIM could not be built.
Versions Keeps every published version. Published Metadata is never overwritten: a resubmission is a new version. A Controller learns that a newer version exists from the versions of the Metadata, without obtaining it.
Findings Records, with each version, what it found in the submission – for example, a package the Metadata names that could not be inspected. A finding is signalled; it does not refuse the submission.
Fingerprints Records the fingerprint (SHA-256) of each Implementation the AIM Instance Metadata names, as submitted and approved.
Verification Confirms, on request, that an Implementation is the one approved for that AIM Instance Metadata.

3 Submission

An Implementer submits the AIM Instance Metadata of an Implementation; the Implementations it names stay where the Implementer keeps them. The Store refuses a submission, and says why, where:

  1. it is not a valid JSON instance of the AIM Metadata Schema;
  2. it does not identify the AIM Instance it describes;
  3. its Topology cannot be resolved into Data Types and Port Numbers;
  4. it is not an instance of the AIM Metadata its Header names;
  5. a Sub-AIM it names can be found neither in the submission nor in the Store.

Otherwise the Store publishes it as a new version, with its findings.

The Store authenticates the submitter (STR-4). A Store may do so by a credential that it issues to the Implementer when MPAI approves its registration, which ties the Implementer ID to a key of the Implementer, and by the Implementer’s signature of each submission: made with that key over the canonical form (PTF-JSON-CANON-V1) of the AIM Instance Metadata and sent with it in the header MPAI-Signature. The Store checks the credential and the signature, and keeps them with the version. A Store that authenticates in another way shall say to Implementers what, if anything, they have to keep on their machines (WKF-2).

3.1 The two licences: the Implementer’s to the MPAI Store, the MPAI Store’s to the Entity that runs Controllers

An AIM that is sold is licensed in two steps, each a licence of the AIM Licence Data Type (AIF-LIC, AIM Licence).

  1. The Implementer’s licence to the MPAI Store is the AIMLicence field of the AIM Instance Metadata the Implementer submits. It states what the MPAI Store may grant (Grant, Term, Updates), the sale price that the Implementer proposes (Payment), where its terms are published (TermsURI) and, in Sublicensing, whether the MPAI Store may sublicense the AIM. It is submitted with the AIM Instance Metadata, is covered by the signature of the submission (STR-4) and is published with the AIM Instance Metadata, which is never overwritten (STR-2).
  2. The MPAI Store’s licence to the Entity that runs Controllers is the AIM Licence the MPAI Store issues (MPAI_AIFS_GetLicence, 5.2.5). Its licensee is the holder of a PTF Trust Anchor: an organisation, one owner, or the operator of a service such as one that offers MPAI as a Service (MPAI-MAS). It is a sublicence: it is within the licence of the Implementer, and ParentLicence names the Implementer and the hash of the AIMLicence field it is under.

The price in the AIM Licence is the sale price that the Implementer proposed with the mark-up of the MPAI Store applied, which covers the costs of the MPAI Store. The rule for the mark-up is that of the MPAI Store and is outside MPAI-AIF V3.0. The AIM Licence does not license the users of the licensee: what the operator of a service grants to its own users is outside MPAI-AIF V3.0.

4 Verification

A Controller runs only code it has verified (Controller). Before an AIM is built, the Controller measures its Implementation and the models it needs; for an AIM that executes apart from the Controller, what executes it measures, and reports to the Controller. The fingerprint of an Implementation or of a model is the SHA-256 hash of its file. The Controller sends the fingerprints it calculated to the Store (MPAI_AIFS_VerifyImplementation, 5.2.3), which says whether each is the one it approved, and compares the hashes of the models with those the settings of the AIM state. The fingerprint the Store approved is known to the Store only: it is never given out. Where they differ, the Controller refuses the Module with MPAI_AIF_NOT_TRUSTED. What executes an AIM apart from the Controller reports what it measured to the Controller; the Controller asks the Store and decides. It proves, when it connects, which Implementation it runs (Zero Trust and Profiles).

All archives obtained from the Store shall not leave the Trusted Zone where the API Profile is Basic, and shall not leave Secure Storage where the API Profile is Secure.

5 Store API

All communication with the Store is over HTTPS. The functions of the Store API follow the conventions of the Basic API.

5.1 Called by an Implementer

5.1.1 MPAI_AIFS_SubmitAIM

error_t MPAI_AIFS_SubmitAIM(const char* AIMInstanceMetadata)

Submits the AIM Instance Metadata of an Implementation to the MPAI Store for approval and subsequent availability. The Metadata contains the information about the submitter and the submitted AIM, including its Implementations and its resources. Returns the reasons of a refusal (3), or the version published and its findings. Where the Store authenticates by signature, the submission carries the signature (3).

5.1.2 MPAI_AIFS_CheckImplementer

error_t MPAI_AIFS_CheckImplementer(const char* ImplementerID, int* Result)

Says whether the Store has assigned the Implementer ID (GET /MPAI/Store/Implementer/{id}). MPAI-AIF V3.0 assumes that the Implementer has obtained an Implementer ID from the MPAI Store. The Store refuses AIM Instance Metadata whose Implementer ID it has not assigned.

5.2 Called by a Controller

5.2.1 MPAI_AIFS_RequestAIM

error_t MPAI_AIFS_RequestAIM(const char* AIM_ID)

Requests the list of approved AIM Instance Metadata whose AIM type is AIM_ID – for example, every Implementation of MMC-EDP-V2.5.

5.2.2 MPAI_AIFS_GetAIMMetadata

error_t MPAI_AIFS_GetAIMMetadata(const char* AIM_ID, AIMMetadata_t* metadata)

Retrieves the approved AIM Instance Metadata AIM_ID, used for the selection of an Implementation, the evaluation of resources and the deployment.

5.2.3 MPAI_AIFS_VerifyImplementation

error_t MPAI_AIFS_VerifyImplementation(const char* ImplementationID,
                                       const char* Fingerprint, int* Result)

A Controller sends the fingerprint it calculated of an Implementation or a model it obtained. The Store answers, in Result, whether it is the fingerprint it recorded when it approved that Implementation: Same, Different or NotRecorded. The Store never gives out the fingerprint it recorded.

5.2.4 MPAI_AIFS_GetAndParseArchive

error_t MPAI_AIFS_GetAndParseArchive(const char* filename)

Obtains and parses an archive from the Store. The default format is tar.gz; the options are tar.gz, tar.bz2, tbz, tbz2, tb2, bz2, tar and zip. An archive includes one AIM Instance Metadata file and one or more binary files. The parsing of the JSON Metadata, and the creation of the corresponding data structure, are left to the Implementer.

5.2.5 MPAI_AIFS_GetLicence

error_t MPAI_AIFS_GetLicence(const char* AIM_ID, const char* TrustAnchorID, const char** Licence)

Issues the AIM Licence for the AIM to the holder of the Trust Anchor, signed by the MPAI Store, under the AIMLicence of the Implementer (3.1), at the price with the mark-up of the MPAI Store, and records the payment. The same AIM Licence is returned if it is asked again. A Controller calls it after it has read the AIMLicence offer and its price in the AIM Metadata, and before it obtains the Implementations.

5.2.6 MPAI_AIFS_VerifyLicence

error_t MPAI_AIFS_VerifyLicence(const char* AIMLicenceID, int* Result)

Says whether an AIM Licence is valid and not revoked.

The MPAI Store exposes these functions over HTTPS under the path /MPAI/Store:

  • POST /MPAI/Store/L3 submits AIM Instance Metadata. The Store publishes it with a new version only if it is an instance of its AIM Metadata and every Sub-AIM it names is in the submission or in the Store; otherwise it refuses it, stating the nonconformities found.
  • GET /MPAI/Store/L3?name= returns the latest approved AIM Instance Metadata of an AIM.
  • GET /MPAI/Store/L3/{id}[?version=n] returns one AIM Instance Metadata, its version in the response header MPAI-Store-Version.
  • POST /MPAI/Store/Licence is MPAI_AIFS_GetLicence (body: AIMName, TrustAnchorID and, optionally, ControllerID): it returns the AIM Licence, with 201 the first time and 200, the same one, when it is asked again; GET /MPAI/Store/Licence/{id} returns an AIM Licence, and GET /MPAI/Store/Licence/{id}/status whether it is valid or revoked.
  • POST /MPAI/Store/L3/{id}/verify (body: BinaryName, Fingerprint) is MPAI_AIFS_VerifyImplementation: it returns Same, Different or NotRecorded.
  • GET /MPAI/Store/L3/{id}/versions returns its versions, and GET /MPAI/Store/L3/{id}/findings what the Store found in it.

A Controller obtains the AIM Instance Metadata of a Module and of all its Sub-AIMs through these routes, and keeps what it obtained in its AIM repository (Controller, 3) and uses it, whether or not the Store can be reached. AIM Implementations are obtained from the location their AIM Instance Metadata states, and verified by the Store (5.2.3).

6 Requirements

Table 2 – Requirements of the MPAI Store

# Requirement
STR-1 The MPAI Store shall refuse AIM Instance Metadata that does not validate against the AIM Metadata Schema or is not an instance of the AIM Metadata its Header names.
STR-2 The MPAI Store shall never overwrite published Metadata.
STR-3 The MPAI Store shall record the fingerprint of each Implementation it approves, and verify an Implementation against it on request.
STR-4 The MPAI Store shall authenticate the submitter of Metadata.
STR-5 The MPAI Store shall not run an AIM.
STR-6 The MPAI Store shall give a Controller that obtains an AIM an AIM Licence for it, signed by the Store, and shall not require the Controller to obtain again, or pay again for, what the AIM Licence covers.
STR-7 The MPAI Store shall be able to revoke an AIM Licence, and shall say so when asked for its status.
STR-8 The MPAI Store shall issue an AIM Licence only for an AIM whose AIMLicence allows it to sublicense, only within that AIMLicence, and shall name in it, in ParentLicence, the Implementer and the hash of the AIMLicence it is under.
STR-9 The MPAI Store shall apply its mark-up to the sale price that the Implementer proposed, shall make the resulting price known to a Controller before issuing the AIM Licence, and shall state that price in the AIM Licence.

7 Workflow

This section puts in order the steps that Sections 2 to 5 of this page and the Controller and Execution pages state separately, from the submission of an Implementation to a Module that runs. It adds no requirement. The actors are the Implementer, the MPAI Store, the User Agent and the Controller; the Module is what the Controller builds from the AIM Instance Metadata of the Module and executes.

Table 3 – From an Implementation to a Module that runs

# Actor What happens
1 Implementer Registers with the MPAI Store and receives an Implementer ID.
2 Implementer Places the Implementations of the AIMs of its package, and the models they need, at the locations it chooses, and submits the AIM Instance Metadata of each AIM of the package (MPAI_AIFS_SubmitAIM; POST /MPAI/Store/L3). Each AIM Instance Metadata states the location of its Implementations and, if the AIM is sold, carries the AIMLicence: the Implementer’s licence to the MPAI Store, with the sale price it proposes (3.1). That of a Composite AIM is submitted with those of its Sub-AIMs, unless these are in the Store already.
3 MPAI Store Approves the submission (2 and 3): refuses what is not valid, authenticates the submitter (STR-4), looks for the Implementations at the locations stated – what it cannot inspect it signals as a finding – records the fingerprint of each as submitted and approved, and publishes the AIM Instance Metadata, with its AIMLicence, as a new version (STR-1 to STR-3). It does not run an AIM (STR-5).
4 User Agent Initialises the Controller through the Controller API.
5 User Agent Asks the Controller to start the Module, naming it. The User Agent does not address the MPAI Store.
6 Controller Load. Asks the MPAI Store for the approved AIM Instance Metadata that matches (MPAI_AIFS_RequestAIM; GET /MPAI/Store/L3?name=) and obtains that of the Module and of all its Sub-AIMs, at every depth (GET /MPAI/Store/L3/{id}); where the Store cannot be reached it may use a copy it keeps. Where the AIM has an AIMLicence, reads the offer and the price with the mark-up (STR-9) and asks the Store for the AIM Licence (MPAI_AIFS_GetLicence), which the Store issues under the Implementer’s licence (3.1).
7 Controller Obtains the Implementations and the models the AIM Instance Metadata names from the locations it states – the Controller, or what executes an AIM apart from it.
8 Controller Verify. Before an AIM is built, measures each Implementation and model, sends the fingerprints to the Store (5.2.3), which says whether they are those it approved, and compares the hashes of the models with those the settings of the AIM state (4), and checks the AIM Licence (WKF-15). Where they differ, refuses the Module with MPAI_AIF_NOT_TRUSTED.
9 Controller Build, Place and instantiate, Bind, Execute (Controller, 5, steps 3 to 6). The Module runs and is ready to exchange Messages.
10 User Agent Writes to the boundary Input Ports of the Module and reads its boundary Output Ports by Data Type and Port Number, or binds devices to them, as the execution model of the Module says (Execution).
11 User Agent, Controller The User Agent asks the Controller to stop the Module. The Controller stops the AIMs, revokes the Grants and releases what it placed (Controller, 5, step 7).
12 User Agent Destroys the Controller.

7.1 An individual AIM that completes a Module

An AIM that the AIM Instance Metadata of a Module does not declare is not part of the Module (CTR-1). Adding it changes the AIM Instance Metadata of the Module; it is not a download:

  1. the Implementer of the AIM does steps 1 to 3 for the AIM;
  2. the Implementer of the Module, or of the Composite AIM that is to contain the AIM, submits a new AIM Instance Metadata of the Module that names the AIM among its Sub-AIMs, with its Topology; the Store publishes it as a new version (STR-2);
  3. the Controller obtains the new version by step 6 when it loads the Module. A running Module is not changed: the version takes effect when the Module is started again;
  4. the Controller then does steps 7 and 8 for the AIM.

An AIM that the AIM Instance Metadata of the Module already declares is obtained by steps 7 and 8 alone.

7.2 The User Agent and several Controllers

A Module is used through the User Agent of its AIF, which supplies its inputs and names its outputs; the User Agent is not an AIM. Where there are several Controllers, each does these steps for its own Module, and the Modules exchange Messages through External Ports (Controller, 9).

7.3 What each party shall do

The following is the least that each party shall do for the workflow to reach its goal: that a Controller runs only Implementations that the MPAI Store approved, submitted by Implementers that MPAI approved.

Table 4 – Requirements of the workflow

# Requirement So that
WKF-1 An Implementer shall obtain an Implementer ID from the MPAI Store before it submits AIM Instance Metadata, and shall put it in the Identifier of every AIM Instance Metadata it submits. the Store can tell which Implementer submitted what, and refuse the others.
WKF-2 An Implementer shall identify itself to the MPAI Store in each submission, in the way the Store requires (STR-4). only the Implementer whose ID the AIM Instance Metadata carries can submit it.
WKF-3 An Implementer shall make each Implementation and model that its AIM Instance Metadata names available at the location the AIM Instance Metadata states, to the MPAI Store when it submits and to the Controllers that use the AIM for as long as the AIM Instance Metadata is published. the Store can measure it and a Controller can obtain it.
WKF-4 An Implementer shall not change an Implementation or a model at its location after the MPAI Store has approved it. A changed Implementation shall be submitted as new AIM Instance Metadata. what a Controller obtains is what the Store approved.
WKF-5 The MPAI Store shall assign an Implementer ID only to an Implementer that MPAI has approved, and shall say, when asked (5.1.2), whether it has assigned an ID. only approved Implementers submit.
WKF-6 The MPAI Store shall publish AIM Instance Metadata only if it has authenticated its submitter as the Implementer whose ID it carries (STR-4). a Controller can rely on who published it.
WKF-7 The MPAI Store shall measure each Implementation and model that it can obtain at the location the AIM Instance Metadata states, shall record the fingerprint, and shall signal each that it cannot measure (STR-3). a fingerprint of the Implementation as submitted exists to be verified against.
WKF-8 The MPAI Store shall answer a request to verify a fingerprint with Same, Different or NotRecorded, and shall not disclose the fingerprint it recorded (5.2.3). a Controller can ask the Store but cannot supply its own reference.
WKF-9 A Controller shall obtain the Implementations and models of a Module from the locations stated in the AIM Instance Metadata it obtained from the MPAI Store, shall measure them, and shall ask the Store to verify the fingerprints (5.2.3). it runs only what the Store approved.
WKF-10 A Controller shall not build an AIM for which the MPAI Store has not answered Same (CTR-2). a changed or unknown Implementation does not run.
WKF-11 A Controller shall add no AIM to a running Module. A new version of the AIM Instance Metadata of a Module takes effect when the Module is started again (CTR-1). the Module is what its AIM Instance Metadata declares.
WKF-12 An Implementer that sells an AIM shall state in the AIMLicence of its AIM Instance Metadata what the MPAI Store may grant, the sale price it proposes and whether the MPAI Store may sublicense the AIM (3.1). the MPAI Store holds a licence from the Implementer to sublicense the AIM, and knows the price the Implementer asks.
WKF-13 The MPAI Store shall apply its mark-up to the sale price proposed by the Implementer and shall make the resulting price known to a Controller before it issues the AIM Licence (STR-9). the Entity that runs Controllers knows what it pays, and the costs of the MPAI Store are covered.
WKF-14 The MPAI Store shall issue the AIM Licence to the Entity that runs Controllers only under an AIMLicence that allows it to sublicense, within it, and naming it (STR-8). the right the Entity receives is one that the Implementer gave the MPAI Store.
WKF-15 A Controller shall check, before it builds an AIM that has an AIMLicence, that its AIM Licence is the MPAI Store’s, is for the Entity it runs for, and is under the AIMLicence of the AIM Instance Metadata it obtained (ParentLicence). it runs an AIM only under a licence that follows from the Implementer’s.

What is written on the Implementer’s machine. Nothing in this standard requires an Implementer to write anything on its own machine. Where the means by which a Store authenticates a submitter (WKF-2) needs something to be kept on the Implementer’s machine, that Store shall say so to the Implementer before it asks for it.

<-Basic API Go to ToC Workflow Description ->