<-Conformance Go to ToC Examples ->
1 General
The MPAI-AIF Reference Software is an implementation of MPAI-AIF V3.0. It is not normative: it shows one implementation that conforms with the standard, and where the standard leaves a choice it states the choice made. It implements a User Agent, a Controller with the Controller API, Communication, Storage, AIM Metadata, Execution, Zero Trust over MPAI-PTF, the Security API and the Secure Profile (with the Controller split into a Secure and a Non-Secure Controller), the execution of AIMs apart from the Controller, and the MPAI Store with its Service and an App for Implementers. AIMs of several MPAI Standards run on it. The Reference Software of MPAI-MAS – the MAS App, the MAS Service and their clients – is built on it.
The software is written in C# for .NET 10. The Controller and the Store Service run on Windows and Linux; the browser client runs in any current browser; the desktop clients and the Store App run on Windows.
2 How the parties are realised
Each party of the Reference Model is a program or a library with its own interface, so that a party can run on its own machine:
- the User Agent is a library with clients (desktop, browser). It acquires and presents data through its Physical Layer, interprets a Workflow, and reaches the Controller only through the Controller API, in the same process or over HTTP with a bearer token. It contains no AIM, and a test keeps it so;
- the Controller builds one Module from its AIM Instance Metadata, verifies it, places its AIMs where their Relation says, establishes the Channels and runs the Module by exchange or continuously;
- an AIM executes with the Controller, in its process, or apart from it, as its Relation states; what executes it apart is a program the Controller reaches over a link that it can open with the Trust Protocol;
- the MPAI Store is a service with a REST API over HTTPS, a core library, and an App with which an Implementer submits.
3 Components
Table 1 – Components of the Reference Software
| Component | What it contains |
| AIF/Controller | The Module loader, the life cycle (placement, start, pause, resume, stop at every depth), the executor for the exchange and continuous execution (one executor), status and degradation (ALIVE, DEGRADED, DEAD; OnDegraded and RestartLimit), the time base and the Trace, the record of the boundary, the AIM repository, the check of the AIM Licence, and the verification of Implementations and models; each Topology connection resolved in its own composite, a composite with a pool of its own; Access – the data an AIM needs and does not receive on a Port, obtained, checked against its SHA-256 and given under its Setting, a file, a set of files or an archive, for an operating system and an architecture, updated as new versions (Model_Update), and the drift an AIM reports (Model_Drift); the Trust Authority of a service and the admission of Controllers by its policy. |
| AIF/ControllerApi | The Controller API, as the User Agent depends on it, with and without waiting. |
| AIF/Communication | Channels with the InProcess, Remote and External transports; Port behaviour (Depth, Overflow; a feedback input of Depth 1, DropOldest); several Messages given at one Output Port in one run; payloads by reference within a Controller and inlined at its boundary; External Ports between Controllers, with a payload channel; Bouts – what does not change in a flow of Data said once, signed by its giver and verified by its receiver; Storage: Private Storage of an AIM and of a Module, Shared Storage under rules, the record of the boundary. |
| AIF/Metadata | The reader and checker of AIM Metadata and AIM Instance Metadata: validation against the AIM Metadata Schema and the instance-of check against the AIM Metadata a Header names. |
| AIF/PortData | The codecs of the Data Types that cross a boundary or a link, checked against their schemas. |
| AIF/AimHost | The program that executes AIMs apart from the Controller: it takes them from its Controller, runs them, and proves which Implementation it runs. |
| AIF/Trust, AIF/RootOfTrust | MPAI-PTF: canonical form, signatures, identities, credentials, evidence, the Trust Protocol, the Verification Pipeline, the Trace; a simulated TPM 2.0 as the root of trust of a Controller and of an AIM that executes apart from it, which also gives the Security API its random bytes and seals its secrets to the measurements of the party. |
| AIF/Security | The Security API on a root of trust: Secure Storage, Attestation, key management, key exchange and derivation, MAC, ciphers, authenticated encryption, signatures, asymmetric encryption, random generation. Each caller – an AIM Instance, the Controller, the User Agent – has a handle bound to its identity, the Owner of its keys and Secure Storage areas. A master key drawn from the root of trust is sealed by it to the measurements of the party; persistent keys and Secure Storage areas are kept encrypted and authenticated under it. The Entity Attestation Token is a COSE_Sign1 signed by the identity key of the party, carrying the challenge of the Verifier and the MPAI-PTF Attestation Evidence over the same challenge. |
| AIF/SecureProfile | The Controller of the Secure Profile split in two parts (Zero Trust and Profiles, 6.2): the Secure Controller holds the Controller – and so the Module, whose AIMs execute in its area with the Security API of the party – and is reached over a link; the Non-Secure Controller relays the frames of the User Agent and their replies and reads none of them; the client of the User Agent, MPAI_AIFU_Controller_Initialize_Secure, verifies the token of the Secure Controller and only then agrees with it the key that protects every request end to end. |
| AIF/UserAgent | The Workflow reader and interpreter (with the steps that make the Controller the Trust Authority of a service, admit by, and leave it), the Physical Layer, the device registry, the Controller API client (local and remote, and to a split Controller), and the clients. |
| Store | The MPAI Store: the core (the catalogue of AIM Instance Metadata, the resolution of Topologies, fingerprints of the submitted packages), the Service (REST API; it signs its answers to a verification, and issues AIM Licences that name, by its hash, the AIM Instance Metadata they cover) and the App (the form of an Implementer). |
| AIMs, Apps, MAS | The AIMs of the Standards with their AIM Instance Metadata; the Applications, each a Module and a Workflow; the MAS API Service. |
| schemas, Test | The JSON Schemas of the Data Types and of the Metadata; the automated tests. |
4 What is implemented
Table 2 – Implementation of MPAI-AIF V3.0
| Chapter | Implemented |
| User Agent | Workflow interpretation; the Physical Layer on the desktop and in the browser, acquiring by Qualifier; the Controller API client, local and over HTTP; record and playback; sessions; its own Store, Read, Delete and List on the Shared Storage of its Module. |
| AI Modules | Basic and Composite AIMs to any depth; Ports by Data Type and Port Number; execution of Sub-AIMs apart from the Controller; reports and status; the data of Access, Model_Update and Model_Drift. |
| Controller | One Controller, one Module; start, pause, resume and stop at every depth; OnDegraded and RestartLimit; trust authority over MPAI-PTF (the Controller the Trust Authority of a service, admitting Controllers by its policy); the Controller keeps, after a Module stops, the Implementations it built. |
| Communication | Channels with the InProcess, Remote and External transports; Port behaviour; payloads by reference within a Controller, inlined at its boundary; one time base; External Ports between Controllers; Bouts. |
| Storage | Private Storage of an AIM and of a Module, Shared Storage, rules (category, readers, time, until a date) with a central control, the record of the boundary; in the Secure Profile, the data of a Module sealed by its AIMs with keys of their own. |
| Metadata | AIM Metadata and AIM Instance Metadata read, validated, and checked for the instance-of relation. |
| Execution | The exchange and continuous execution on one executor; Period, Deadline and MaxAge. |
| MPAI Store | Submission, versions, findings, fingerprints and verification of Implementations and models; the check of an Implementer ID; the authentication of the submitter; signed answers to a verification; the AIM Licence, issued by the Store library and the Store Service, naming by its hash the AIM Instance Metadata it covers. Section 5. |
| Zero Trust | Identities and credentials of AIM Instances; code and models verified before they run; trust between a Controller and an AIM that executes apart from it; attestation over a simulated root of trust; the Trace. The Secure Profile: the Controller split into a Secure and a Non-Secure Controller; the User Agent verifies the Attestation of the Secure Controller and its requests are protected end to end; the Secure Controller serves only the User Agents it was given, each signing its first request with its identity key; the AIMs of a Module built from AIM Instance Metadata that declares APIProfile Secure are built only where the party has the Security API, and keep their data sealed; a Module where one is not, or whose Sub-AIMs declare another Profile than their Composite AIM, is refused with MPAI_AIF_FAILED and the reason. |
| Security API | Every function of the page, with its name, in C# (a byte array or a span where the page has a pointer and its size). Not offered (MPAI_AIF_NOT_SUPPORTED): DES and DH keys and FFDH, PURE_EDDSA, the salt (label) of RSA_OAEP, a GCM nonce other than 12 bytes, XTS on data that is not a whole number of blocks; SHA-3 and ChaCha20-Poly1305 where the platform does not have them. |
5 The MPAI Store and the workflow
Table 3 follows the workflow of MPAI-GME Operation, Section 8, and says what the Reference Software does at each step.
Table 3 – The workflow in the Reference Software
| # | Step | In the Reference Software |
| 1 | The Implementer registers | The Store Service serves a page, /MPAI/Store/Register. It gives the Implementer an Implementer ID and a registration code, shown once. ID 1 is MPAI’s own. |
| 2 | The Implementer submits | The Store App (or any HTTPS client) posts the AIM Instance Metadata to POST /MPAI/Store/L3, with the Implementer ID in its Identifier and the Implementer’s signature in the header MPAI-Signature. |
| 3 | The Store approves | The Service refuses an Implementer ID it has not assigned or MPAI has not approved, and a submission that is unsigned, signed by another key or changed after it was signed. It validates the whole AIM Instance Metadata against the AIM Metadata Schema, resolves its Topology, looks for the Sub-AIMs, and checks it against the AIM Metadata its Header names. It looks for the package at the location stated, records the SHA-256 of the Implementation (for a package in its packages folder), and publishes the AIM Instance Metadata as a new version with its findings. It keeps every version and the record of who submitted it. |
| 4, 5 | The User Agent initialises the Controller and starts the Module | The Controller API, in the process or over HTTP. |
| 6 | The Controller loads the Metadata | The Controller reads the AIM Instance Metadata of the Module and of its Sub-AIMs from a folder it keeps; a client of the Store (GET /MPAI/Store/L3) fills it, and a copy kept is used when the Store cannot be reached. |
| 7 | The Controller obtains the Implementations | The Controller reads the AIMLicence offer, if the AIM Metadata has one, and obtains the AIM Licence from the Store (MPAI_AIFS_GetLicence, POST /MPAI/Store/Licence). It then obtains the Implementations from the location the AIM Instance Metadata states (a file or an https address) into its AIM repository, which it consults before it asks again. |
| 8 | The Controller verifies | The Controller measures the package it obtained (every file of the package at the location the AIM Instance Metadata states, by the method of MPAI-GME Operation, 5) and sends the fingerprint to the Store (POST /MPAI/Store/L3/{id}/verify), which answers Same, Different or NotRecorded, signed with its key over the question and a nonce of the Controller; it never gives the fingerprint out. What executes an AIM apart from the Controller measures and reports what it measured; the Controller asks the Store. The Controller refuses the Module with NOT_TRUSTED unless the answer is Same. |
| 9 | The Controller builds and runs the Module | It resolves the Topology into connections of AIM, Data Type and Port Number, places each AIM where its Relation says, admits it through the Trust interface, establishes the Channels and binds the handles. |
| 10, 11, 12 | Use, stop, destroy | The Controller API. |
What the Store App writes on the Implementer’s machine. In the folder of the App, %LOCALAPPDATA%\MPAI\StoreApp, the Implementer ID (implementer-id.txt) and the Implementer’s private key (implementer-<ID>.key), which never leaves the computer. The key is the Reference Software’s way of authenticating the submitter (WKF-2); another Store may authenticate in another way.
6 Not implemented
Not implemented are, among others: the PointToPoint and Bus transports; Grants per Channel end; a Deployment Controller; a Controller managing Controllers; a hardware root of trust (the root of trust is the simulated TPM 2.0); the measurement by the Store of an Implementation that is not a package (a .zip at an https address, or a package in its own packages folder). An Implementer cannot yet submit a fingerprint of its own with its AIM Instance Metadata (MPAI-GME Operation, 4). In the Secure Profile: the Secure Controller as a program of its own (in the tests and in the AIH-HSP demonstration it is reached over a loopback link in the same process); a monotonic counter of the root of trust for the replay protection of Secure Storage (the versions of the areas are kept in a sealed index, which an attacker able to replace the whole folder could roll back); keys generated and held by the root of trust (they are generated by the Security API and kept under the sealed master key); secrets that remain readable after the code of the party is changed by an approved update (the master key is sealed to the measurements as they are).
7 Verification
The Reference Software is verified by automated tests, among them:
- every AIM Instance Metadata loaded, validated and checked against its AIM Metadata;
- Modules run by exchange and continuously, with loops, degradation and restarts;
- Sub-AIMs executing apart from the Controller, in another process, under the one Controller;
- Storage under rules, the record of a boundary and its playback;
- the Store Service on a local port: registration, approval, signed submission, refusal of what is unsigned, altered or from an unknown Implementer, recording and verification of fingerprints;
- the AIM Licence over HTTPS: issued by the Store Service under the Implementer’s offer at the price with the Store’s mark-up, the same one when it is asked again, its status and its revocation, and a Controller that builds from it;
- an Implementer, the Store and a Controller each on its own, the Controller obtaining over HTTP and verifying through the Store, and refusing an Implementation changed after it was approved;
- the Applications of MPAI-MAS run end to end, by several clients at once.
- the Security API: each function gives what the platform’s cryptography gives for the same inputs, and XTS the IEEE 1619 vector; only the Owner uses a key or a Secure Storage area; keys and areas survive a restart and do not open with other code measured; an altered or replayed Secure Storage area is refused; the Entity Attestation Token proves the party and its code over the challenge of the Verifier, and a wrong challenge, key or code is refused;
- the Controller of the Secure Profile split: the Module answers through the Non-Secure Controller as it answers directly, the Non-Secure Controller sees none of its data, and a replayed or altered request, a session the Non-Secure Controller tries to open itself, a party or code the User Agent does not expect, are refused;
- the Secure Implementations of AIH-HSP (the AIM Instance Metadata 1AIH-*-V1.1-I02): the Health Back End and the Health Front End through the split Controller, with nothing of the End User in clear in what is relayed or kept, and the AIH-HSP demonstration in both Profiles, each Controller on a root of trust of its own.
- Access: data obtained, checked against its SHA-256, given under its Setting, refused when changed, updated as a new version; the drift an AIM reports;
- between Controllers: a Controller the Trust Authority of a service, admitting others by its policy and refusing what it does not admit; External Ports; Bouts signed, verified, and refused when altered;
8 Access to the code
Please send an email to the MPAI Secretariat to access the code.