https://irma.app/docs/what-is-irma/ IRMA docs IRMA docs v0.6.1 * Docs * Attribute index * About * Privacy by Design Foundation >Intro Intro * What is IRMA? * Getting started New * Revocation * Randomblind issuance Guides * irma command line tool * irma server * irma server library * IRMA backend packages * IRMA frontend JavaScript packages * IRMA schemes * Session requests * Email address * IRMA app * irmajs JavaScript library API reference * Go libraries * irma server * IRMA frontend packages * irmajs Documentation * Technical overview * Zero-knowledge proofs * Keyshare protocol What is IRMA? IRMA is a set of free and open source software projects implementing the Idemix attribute-based credential scheme, allowing users to safely and securely authenticate themselves as privacy-preserving as the situation permits. Users receive digitally signed attributes from trusted issuer, storing them in their IRMA app, after which the user can selectively disclose attributes to others. Schematically: issuance-flow disclosure-flow Using the issuer's digital signature over the attributes the verifier can verify that the attributes were given to the user in the past, and that they have not been modified since. IRMA session flow A typical IRMA session is depicted schematically below. IRMA session flow Software components: * Requestor backend and frontend: Generally the requestor runs a website with a (JavaScript) frontend in the user's browser, and a backend server. During an IRMA session the frontend displays the IRMA QR that the IRMA app scans. All frontend tasks depicted in the diagram are supported by irma-frontend. * IRMA server: Handles IRMA protocol with the IRMA app for the requestor. * IRMA mobile app: Android, iOS. Explanation of the steps: 1. Usually the session starts by the user performing some action on the website (e.g. clicking on "Log in with IRMA"). 2. The requestor sends its session request (containing the attributes to be disclosed or issued, or message to be signed) to the IRMA server. Depending on its configuration, the IRMA server accepts the session request only if the session request is authentic (e.g. a validly signed session request JWT) from an authorized requestor. 3. The IRMA server accepts the request and assigns a session token (a random string) to it. It returns the contents of the QR code that the frontend must display: the URL to itself and the session token. 4. The frontend (irma-frontend) receives and displays the QR code, which is scanned by the IRMA app. 5. The IRMA app requests the session request from step 1, receiving the attributes to be disclosed or issued, or message to be signed. 6. The IRMA server returns the session request. 7. The IRMA app displays the attributes to be disclosed or issued, or message to be signed, and asks the user if she wants to proceed. 8. The user accepts. 9. The IRMA server performs the IRMA protocol with the IRMA app, issuing new attributes to the user, or receiving and verifying attributes from the user's IRMA app, or receiving and verifying an attribute-based signature made by the user's app. 10. The session status (DONE, CANCELLED, TIMEOUT), along with disclosed and verified attributes or signature depending on the session type, are returned to the requestor. Additional notes: * Which of these tasks are performed by the requestor's backend and which by its frontend differs case by case: + Often the session request is sent to the IRMA server by the requestor's backend, after which the IRMA server's reply in step 2 is forwarded to the frontend which renders it as a QR code. Step 1 can however also be done by irma-frontend, in which case irma-frontend automatically picks up the IRMA server's reply in step 2 and renders the QR code. + Similarly, irma-frontend can be instructed to fetch the session result in step 10, but this can also be done in the backend. In the latter, irma-frontend can fetch a custom result at your backend, if desired. * The IRMA server could be deployed on the same machine as the requestor's backend, but it need not be; possibly it is not even controlled by the requestor. Generally, steps 2/3 and 10 are done with REST HTTP calls to the IRMA server, but in case the irmaserver library is used, these steps are function calls. Alternatively, you could use one of the packages in irma-backend-packages to do these steps with function calls in other programming languages. Session types In an IRMA session, the IRMA mobile app performs one of the following three session types with an IRMA server: * Disclosure sessions: Upon receiving a list of requested attributes from the IRMA server, the app discloses the required attributes to the IRMA server if the app user agrees, after which they are verified by the IRMA server. * Attribute-based signature sessions: Similar to disclosure sessions, but the attributes are attached to a message digitally signed into an attribute-based signature. The attribute-based signature can be verified at any later time, ensuring that the signed message is intact, and that the IRMA attributes attached to it were valid at the time of creation of the attribute-based signature. * Issuance sessions: the IRMA app receives a new set of IRMA attributes including valid issuer signatures from the IRMA server, to use in later disclosure or attribute-based signature sessions. (Possibly the user is asked to disclose some attributes as well, within the same IRMA session, before receiving the new attributes. This is called a combined issuance-disclosure session .) This process is depicted schematically and explained in more detail in the IRMA session flow chapter. For the user, after scanning the QR in his/her IRMA app a disclosure session generally looks like the following. (Attribute-based signature sessions and issuance sessions are identical in terms of their flow (scan qr, provide permission, success screen); only the graphical interface is different.) disclose-permission disclosure-done IRMA servers Various existing software components documented on this website can perform the role of the IRMA server. Apart from exposing an API that is used by the IRMA app during IRMA sessions, each of these components also offer an API with which IRMA sessions can be started and monitored, for use by the requestor: the party wishing to issue attributes to or verify attributes from an IRMA app. The IRMA server handles the IRMA session with the IRMA app for the requestor. Currently the following IRMA servers exist: * The irma server command of the irma binary: a standalone daemon exposing its requestor API as HTTP endpoints. Documentation; API reference. * The irmaserver Go library, exposing a HTTP server that handles IRMA sessions with the IRMA app, and Go functions for starting and managing IRMA sessions. Documentation; API reference. * The now deprecated irma_api_server. About this documentation IRMA uses JSON to pass messages within IRMA sessions. The majority of IRMA is written in Go, and the JSON messages generally correspond to specific Go structs. For example, the GET /session/{token}/result endpoint of the irma server outputs instances of the server.SessionResult. In such cases, a link to the corresponding Go struct will be included. This can tell you what fields you can use or expect. (Note that some structs have custom (un)marshalers. See also the Go documentation on JSON and Go.) Getting started - * IRMA session flow * Session types * IRMA servers * About this documentation IRMA docs Docs What is IRMA?Getting startedTechnical overview Community SlackTwitterGitHub More AboutAttribute indexPrivacy by Design Foundation