What is Yivi?

Yivi is a set of open source software project 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 Yivi app, after which the user can selectively disclose attributes to others.

Yivi's roots lie within Radboud University. Back in the day, its code name was IRMA, which stands for "I Reveal My Attributes." IRMA was later rebranded as Yivi, but many technical dependencies, such as the protocol and repositories, continue to bear the name IRMA.

Schematically:

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.

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 Yivi app scans. All frontend tasks depicted in the diagram are supported by yivi-frontend.
• IRMA server: Handles IRMA protocol with the Yivi app for the requestor.
• Yivi 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 (yivi-frontend) receives and displays the QR code, which is scanned by the Yivi app.
5. The Yivi 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 Yivi 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 Yivi app, issuing new attributes to the user, or receiving and verifying attributes from the user's Yivi 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 yivi-frontend, in which case yivi-frontend automatically picks up the IRMA server's reply in step 2 and renders the QR code.
  • Similarly, yivi-frontend can be instructed to fetch the session result in step 10, but this can also be done in the backend. In the latter, yivi-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 Yivi 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 Yivi 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 Yivi 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.)

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 Yivi 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 Yivi app. The IRMA server handles the IRMA session with the Yivi 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 Yivi 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.)