Skip to main content

Getting started

This page helps you pick the right Yivi protocol for your use case, and points you to the setup guide for that path. Before you start, install the Yivi app (Android, iOS) on your phone.

Choose your protocol​

Yivi is a crypto agile wallet: it speaks both Yivi's own privacy-preserving IRMA protocol and the EUDI-aligned OpenID4VP / OpenID4VCI standards. Which one to use depends on what matters most for your use case.

Verification (asking users for attributes)​

Use caseRecommended protocol
Privacy-preserving scenarios — age verification, digital voting, anonymous attestations, attribute-based signatures, anything where sessions must not be linkable to the same userIRMA — Idemix gives you issuer unlinkability and relying-party unlinkability out of the box. OpenID4VP does not support attribute-based signatures.
Maximum interoperability — accepting credentials from any EUDI-compliant wallet, or integrating with EU/national identity ecosystemsOpenID4VP — standards-based, carries SD-JWT VCs that any EUDI wallet can produce

Issuance (giving users attributes)​

Use caseRecommended protocol
Privacy-preserving issuance — you want issuer unlinkability, or you need to issue Idemix attributes alongside SD-JWT VCsIRMA — the IRMA protocol supports both Idemix and SD-JWT VC issuance with the privacy properties Yivi is known for
Maximum interoperability — issue credentials that any EUDI wallet (not just Yivi) can receiveOpenID4VCI — standards-based, produces SD-JWT VCs other EUDI wallets understand
tip

Issuance and disclosure are decoupled. Yivi is crypto agile: the IRMA protocol can issue multiple credential formats side by side — both Idemix and SD-JWT VC — from a single issuer setup. Once they are in the wallet, Idemix credentials are disclosed over IRMA and SD-JWT VCs over OpenID4VP, so users can hold credentials of both formats in one wallet at the same time.

Starting points​

Pick the section that matches your protocol of choice:

Verifying over IRMA​

This walkthrough uses the following components:

  • irma server, a server that verifies or issues IRMA attributes to Yivi apps.
  • yivi-frontend, a JavaScript library for drawing the Yivi QR in your website and handling the IRMA session with the irma server.

If you want to compile from source instead of using prebuilt binaries, follow the build prerequisites documented in the upstream repositories: the irmago README for the irma server, and the yivi-frontend-packages README for yivi-frontend.

Installing irma server​

You can install the yivi command line tool in the following three ways.

  • Download prebuilt binary from GitHub. Choose the binary for your OS and architecture (most likely amd64).
  • Rename the file to /usr/local/bin/yivi to have it available in your PATH.

Running irma server​

After installing the yivi binary, start the server (with increased verbosity but otherwise default configuration):

yivi irma server -v

Configuration​

Run yivi irma server -h to see configuration options. In order to verify your configuration, run yivi irma server check -v. General documentation can be found on the irma server page, API documentation of HTTP endpoints can be found on the api irma server page.

Perform a command line IRMA session​

Given:

  1. a running IRMA server (see above)
  2. the Yivi app with developer mode turned on
  3. the devices with the Yivi app and IRMA server on the same network

you can perform a first IRMA session using your server on the command line as follows:

yivi irma session --server http://localhost:8088 --disclose pbdf.pbdf.irmatube.type

IRMATube attributes are available on the YiviTube demo page. This will print a QR that you can scan with your Yivi app, and the attribute contents after they have been received and verified by the server. yivi irma session can also perform issuance sessions and attribute-based signature sessions. If you pass -v it logs the session request JSON that it sends to your irma server.

Installing an example webpage for yivi-frontend​

Download the yivi-frontend-packages source code, as zip from GitHub, or using git:

git clone https://github.com/privacybydesign/yivi-frontend-packages && cd yivi-frontend-packages

Examples for the browser and for Node.js are included in the examples folder. In this guide we will use the yivi-frontend example for browsers to realize the example webpage. This example has to be installed first.

cd examples/browser/yivi-frontend/
npm install
npm run build

Perform browser IRMA session​

(Re)start your irma server, configuring it such that it statically hosts the yivi-frontend example webpage we just built with the commands below. Change ~ to the actual folder you have downloaded yivi-frontend-packages to.

yivi irma server -v --static-path ~/yivi-frontend-packages/examples/browser/yivi-frontend

A webpage demoing IRMA attribute issuance verification should now be available at http://localhost:8088.

note

Open the browser console and the console running irma server to see various log messages and possibly error messages as the IRMA session proceeds.

Example configuration and IRMA session​

Generally, your IRMA server runs in your backend alongside a server application serving your frontend (website), with which the Yivi app user is interacting. Your server application starts and manages sessions at your IRMA server to verify or issue attributes (for example, when the user wants to log in). This can be set up as follows.

Configure irma server​

In production, it is generally best to authenticate incoming session requests from your application. The following is an example production configuration file (in YAML) for the irma server (start with yivi irma server -c /path/to/config.yml) that will accept session requests if they include a Authorization: mysecrettoken HTTP header.

config.yml
production: true

port: 443
url: "https://example.com/irma/"
tls_cert: "/etc/letsencrypt/live/example.com/fullchain.pem"
tls_privkey: "/etc/letsencrypt/live/example.com/privkey.pem"

no_auth: false
requestors:
  myapp:
    auth_method: "token"
    key: "mysecrettoken"
  • You may want to restrict permissions to verify or issue specific attributes, globally or per requestor.
  • The server can be made into a daemon on most Linux systems using a systemd unit file.
  • Another common setup is to have a reverse proxy between the IRMA server and the internet, which handles TLS instead and forwards traffic on https://example.com/irma/ to the IRMA server.

Perform a session​

Assuming your application runs on the same server as the IRMA server, your application can now start a session at your IRMA server as follows (using curl as example):

curl https://example.com/session \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: mysecrettoken" \
  -d '{
        "@context": "https://irma.app/ld/request/disclosure/v2",
        "disclose": [[["irma-demo.MijnOverheid.ageLower.over18"]]]
      }'

This will output something like the following:

{
  "token": "X7LU5Q8Jhig0330gjYUO",
  "sessionPtr": {"u": "https://example.com/irma/t1nXs4ZduyhvAeAAlB77","irmaqr": "disclosing"},
  "frontendRequest":{"authorization":"X9XeI0gJG2HZv4hZ1WkP","minProtocolVersion":"1.0","maxProtocolVersion":"1.1"}
}

Instead of managing sessions with HTTP requests as shown here, for certain languages (currently Go and JavaScript) it is also possible to include an IRMA library and manage sessions using function invocations.

Issuing over IRMA​

The IRMA quickstart above mostly focuses on verifying — receiving IRMA attributes from Yivi apps and establishing their authenticity. Issuing attributes to Yivi apps can be done with the same software and largely similar flows, but is more involved, because the identity of prospective issuers needs to be verified and the contents and structure of the credentials to be issued needs to be established. This process is documented in the issuer guide.

For experimenting and demoing, however, it is possible to issue any of the existing credentials within the irma-demo scheme. For example, if the requestors block in the YAML example configuration of the IRMA server above would include permission to issue irma-demo attributes, as follows:

requestors:
  myapp:
    auth_method: "token"
    key: "mysecrettoken"
    issue_perms:
      - "irma-demo.*"

Then an issuance session for the credential used in the example disclosure session above can be started at the IRMA server as follows:

curl https://example.com/session \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: mysecrettoken" \
  -d '{
        "@context": "https://irma.app/ld/request/issuance/v2",
        "credentials": [
          {
            "credential": "irma-demo.MijnOverheid.ageLower",
            "attributes": {
              "over12": "yes",
              "over16": "yes",
              "over18": "yes",
              "over21": "no"
            }
          }
        ]
      }'

To issue a demo credential of your own not already present in the irma-demo scheme, see the issuer guide. To issue SD-JWT VCs over the IRMA protocol (so they can later be disclosed over OpenID4VP), see Issuing SD-JWT VC over IRMA.

Verifying over OpenID4VP​

OpenID4VP carries SD-JWT VCs and is the right choice when you want the broadest interoperability with the EUDI ecosystem. The full path is:

  1. Read the OpenID4VP Introduction for an overview of the protocol and what Yivi currently supports.
  2. Apply for a verifier certificate via the Yivi portal and Yivi support — every verifier needs an X.509 certificate on the Yivi Trust List before it can request attributes.
  3. Build your DCQL queries and authorization requests following Disclosing SD-JWT VCs over OpenID4VP.
  4. Wire up your frontend using the Verifier Integration Guide, which walks through a working end-to-end example based on the openid4vp-demo-frontend reference repository.

Issuing over OpenID4VCI​

OpenID4VCI is the standards-based path to issuing SD-JWT VCs into Yivi (and any other EUDI-compliant wallet).

Private Beta

OpenID4VCI issuance is currently in private beta. Reach out to Yivi support if you would like to participate. If you are an existing Yivi issuer and want something operational today, prefer Issuing over IRMA instead.

To get started:

  1. Read the OpenID4VCI Introduction for an overview of the pre-authorized code flow and what's in scope for the private beta.
  2. Follow the Issuer Integration Guide for credential offer creation, the optional tx_code step, and polling for issuance completion. The code samples mirror the openid4vp-demo-frontend reference repository.