Wouter Ensink

A few months ago, we announced our plans to become an EUDI wallet while still retaining our original privacy-by-design technology.

Since that announcement, we've come a long way, and today it's time to announce the release of the first major step towards true crypto agility: the support for the OpenID4VP protocol and the SD-JWT VC credential format in the Yivi app. In this blog, we'll dive into how we did this and what it means for you.

EUDI Technology​

The EUDI Wallet ecosystem consists of many moving parts, but the most fundamental pieces are a set of credential formats and protocols. For web technology, it uses the OpenID4VCI protocol for credential issuance and the OpenID4VP protocol for disclosures. The credential formats consist of SD-JWT VC, W3C VC, and ISO mDL/mdoc.

For Yivi to become an EUDI compatible wallet, it must have support for these formats and protocols.

We can't do all of these at the same time, so we had to make a choice to start with one credential format and one protocol.

For the credential format the choice was simple: SD-JWT VC is the most used, easiest to implement and has an open standard.

The choice for a protocol was a bit harder. Since a single protocol can only either issue or verify, we knew we would get into the situation where we would either have credentials without being able to share them, or we would be able to share them without being able to actually obtain them. A classic chicken and egg problem.

To get around this problem, we decided to start with OpenID4VP for disclosures and extend our existing IRMA protocol to be able to issue SD-JWT VCs in addition to our existing Idemix format.

A nice additional benefit for this is that we can stick close to our existing scheme for now, which makes adapting the app a much more gradual process.

Our choice to start from scratch​

While there are existing libraries with implementations of the EUDI specifications, we ultimately decided to roll our own implementation. There are a couple of reasons for this, but the most notable is that integrating a ready-made solution into the Yivi code base would be very challenging.

Our code base for the app currently consists of two major components: irmaclient and irmamobile. The first is the client implementation of the IRMA protocol, written in Go. The second is the Flutter app that presents a cross-platform user interface.

We considered using the existing EUDI reference implementations developed by the EU, but ultimately decided not to use them. They weren't cross-platform, and the code base was scattered across many different packages, making a fork pretty much unworkable if needed.

Rolling our own meant we could make it exactly the way our crypto-agile approach requires while at the same time building a much more detailed knowledge of our core technologies.

This is why we ended up extending irmago with EUDI code.

Using the EUDI verifier server as a reference​

In order to be sure our OpenID4VP and SD-JWT VC implementations would be compatible with the spec, we would need an existing verifier to test against. We decided to opt for the EUDI reference implementation since it was open source, easy to set up, and has a high chance of being used in the ecosystem.

We run it both on https://verifier.openid4vc.staging.yivi.app as well as in the Docker Compose configuration used during irmago integration tests.

OpenID4VP: A new protocol​

Since its inception, Yivi has been built around a very specific set of technologies: the Idemix credential format and the IRMA protocol. So far, this has worked out very well, but it also means it was not designed with multiple formats and protocols in mind.

Adding a protocol means adapting a significant section of the existing Yivi code base.

Our strategy for this was to build a shell around the existing irmaclient code and build a new client side by side with the existing IRMA client inside of this shell. We kept the API that irmamobile uses to talk to irmaclient as unchanged as possible to prevent making too many changes at once.

Inside of this shell, we started building an OpenID4VP client. This client is compatible with the existing interfaces that the app relies on for handling session interactions. As long as we stick to our current scheme, this will work well, but it will need a significant refactor when we eventually accept credentials outside of our scheme.

When a new session URL is received by the client, it will forward it either to the existing IRMA client or the new OpenID4VP client based on the type of session.

SD-JWT VC: A new credential format​

SD-JWT VC is quite a simple and straightforward credential format, but it's relatively new and still changes from time to time, so an up-to-date implementation in Go was not available.

Issuing SD-JWT VC over the IRMA protocol​

Since we wouldn't be able to develop both OpenID4VP and OpenID4VCI at the same time, we knew we would end up in a situation where either we could issue SD-JWT VC credentials but had no way to disclose them, or we would be able to disclose them but had no way to issue them. A classic chicken and egg problem.

The solution we came up with was to extend the IRMA protocol to allow it to also issue SD-JWT VCs.

As of today, issuers will be able to start issuing their credentials as defined in our scheme both in the classic Idemix format as well as the new SD-JWT VC format using the latest version of the irma server.

In order to be able to do this, they need to obtain a new X.509 certificate that's on our new Trust List.

Key binding & salts: A major limitation​

In order to prove a credential instance belongs to a user, SD-JWT uses a system called "key binding". Here, the wallet provides an asymmetric public key to the issuer, who puts it into the credential. During disclosure, the wallet uses its corresponding private key to sign a JWT containing the hash over the credential and some parameters provided by the verifier to prove they own the private key corresponding to the public key inside of the credential.

This is quite a nice system, but it has one major flaw: disclosing a credential multiple times means showing the same public key multiple times. This breaks one of the pillars Yivi was originally built on: multi-show unlinkability.

The only way to (kind of) solve this without moving entirely to Zero-Knowledge Proofs (like Yivi originally uses) is to issue multiple instances of the same credential at the same time and discard an instance after it has been used once.

This has far-reaching consequences for the user experience, which is something we'll talk about next.

The Yivi app​

For our users, not a lot will change in terms of how the Yivi app works. This is intentional, as we wanted to stay close to our easy-to-understand interface. The issuance and disclosure flows, including the ability to do issuance during disclosure, remain unchanged.

One thing we did change is the way credential cards look. This has to do with the fact that SD-JWT VCs come in batches of instances (as discussed above), and these instances are removed after a single use. If you received 10 instances, you can share them only 10 times. We struggled with this because the implications for the UX are quite significant.

As you might know, Yivi's own Idemix credentials are infinitely shareable until they expire based on time. Issuing the same credential in SD-JWT means that the app possesses one format that can be shared infinitely and another format that can only be shared X times.

This leaves us in a situation where a credential can be in a state of both valid and "out of stock," depending on which format is requested.

We don't want to bother our users with this, but in one way or another, we'll have to.

After a lot of consideration, we decided to show the instance count in the UI. It now shows up next to the expiry date. If it's Idemix only, we show "unlimited"; if an SD-JWT is present, we show the remaining number of disclosures.

When the credential is close to its usage limit, we show this to the user with a button to reobtain the credential, just like we do with regular time-based expiry.

This leaves us with only two UX downsides:

1. The app shows there are 0 credential instances left, but Idemix can still be shared
2. The app doesn't show a decreased number after SD-JWT is shared

Becoming an SD-JWT VC issuer​

If you're already an issuer using an IRMA server in the Yivi ecosystem, you can become an SD-JWT VC issuer with some minor modifications. First of all, you'll need to obtain an X.509 certificate that is on our Trust List.

This certificate is on an issuer basis, as defined in our scheme. This means you can use it to issue the same credentials you already can with your existing Idemix private key.

After you obtained a certificate, you need to upgrade your IRMA server to version 0.19 or higher. More details on how to set it up can be found in the SD-JWT VC Issuance guide.

Becoming an OpenID4VP verifier​

We are compatible with a subset of the OpenID4VP standard version 1.0. In this section, we'll specify what is possible for you and how you can use Yivi with OpenID4VP and SD-JWT.

Verifier certificate​

Before you're allowed to request any attributes, you must possess a valid verifier certificate that is on the Yivi Trust List. You can obtain one via the Yivi portal.

The certificate contains a JSON value that has some metadata in it, like the organization information, permitted attributes, and a logo. It is tied to the hostname where the verifier server runs (so the URL the app has to contact for a session).

More details about what features we support and how to set it up can be found in our documentation (coming soon).

Next up: OpenID4VCI​

Now that OpenID4VP is done, our journey to become a crypto-agile EUDI-compatible wallet has officially started. Our next step is to implement the issuance side of the system: the OpenID4VCI protocol.

Wrap up​

As we've seen today, Yivi is well on its way to becoming crypto-agile. For more information about our roadmap, see our Crypto Agile Introduction.

One of the main goals for Yivi is to become the worlds most user friendly identity wallet. We've already done a lot to help this cause, like allowing the user to directly start issuing missing credentials while they're trying to dislose so they stay in the flow.

In this blog we'll look ahead at some of the plans we have for the near future to improve the user experience.

Our four values for UX​

To keep our goals clear and keep an eye on the usefulness of new features, we've written down our main values for the UX. These values are:

• Accessible
• Understandable
• Trustworthy
• Beautiful

Accessible means that we're committed to making Yivi a good experience for everyone.

Understandable means that Yivi should feel familiar and usable to everyone.

Trustworthy is not just about using the most reliable protocols. It's also about conveying that to the user and letting them feel like they can trust Yivi, issuers and verifiers. Things that fall into this category are imagery, colors and clear explanations.

Beautiful is not as important as the others, but the eye wants something too. Things like consistent color, fonts and styling combined with fluid animations is what gives Yivi just that extra touch.

Our plans for the near future​

There are four UX improvements that we want to work on over the next couple of months:

• Getting compliant with European Accessibility Act
• QR code scanner button on the login page
• Easier card organisation and navigation
• Brand extensions

Let's have a look at each of them.

Getting compliant with European Accessibility Act (EAA)​

The EAA is a directive that aims to improve the functioning of the internal market for accessible products and services, by removing barriers created by divergent rules in member states of the European Union.

It applies to products and services that have been identified as being most important to people with disabilities. Yivi aims to be one of those products and therefore should comply with this act.

For digital products, like Yivi, this means having to comply with the Web Content Accessibility Guide (WCAG) version 2.1 level AA.

Requirements include:

• Big enough touch targets
• Big enough contrast ratios
• Support for screen readers
• Alt text for visual media
• Support for large text
• And more

A complete overview can be found here.

We plan to adhere to these standards by assessing our current state and make improvements accordingly. Recently we've improved our screen reader support by adding better descriptions and hiding some distracting items from the screen reader with this pull request.

Automatic tests will be introduced to make sure our Flutter code adhears to the touch target and contrast ratio requirements set by WCAG.

We encourage users to let us know what they think and how we can improve the experience for them.

QR code scanner button on login page​

For Yivi to be understandable it helps to feel familiar to some degree. Lots of banking apps, at least in The Netherlands, have a quickly accessible QR code scanner button on the login page that users can press even before entering their pin. The pin code then needs to be entered to confirm the action the user wants to take based on the scanned QR code. For banking apps that would most likely be transfering money.

Our plan is for Yivi to also support this flow. The user can quickly scan a QR code by pressing the button on the login page and then enter the pin afterwards to continue with the issuance or disclosure.

Progress on this feature can be followed here.

Easier card organisation and navigation​

We've received feedback from some of our users that the navigation and organisation of the cards inside the wallet is not optimal. Right now there's just a list of cards, categorized based on the Category field in the scheme and nothing more. There's no way to sort, organize or navigate these cards.

When a user has just a few credentials this is not a big issue, but when the list grows larger, finding the card you're looking for becomes harder and harder.

To solve this problem, we're planning to make the list editable and add search functionality. Editable means the user will be able to select, move and delete credentials.

Sorting based on time and name is also something we're looking at, but it's important to not let that interfere too much with custom ordering.

Brand extensions​

To build a level of trust, imagery and branding is important. As of now, credentials inside the Yivi app are plain, white cards with a name and a small logo for the issuer. To feel more authentic, it would be nice if issuers had more control over what their card will look like. The credential containing your ID information could for example look like your actual ID card.

We do need to consider what this means for usability, as the cards will most likely be taller than they are now and that could make the list a lot longer.

The card image itself could contain some of your personal data in the form of some kind of SVG template. We need to keep in mind that not all of your data may fit on the card itself and not everyone will be able to read those details from the image itself.

As for the technology, we're considering using the SD-JWT VC SVG template system as a basis.

We would like to get feedback from our issuers to see if this is something they would want, and if so, what features they'd want out of it.

Closing up​

So that's it for now. We'd love to hear from you about what you think about these plans and what other features you'd like to see in Yivi.

Authentication and identification are critical components of digital services. This can be done with Yivi, our privacy-friendly ID-Wallet. It provides multiple options for verifying user identities. However, a significant challenge in implementing Yivi is the identifier used for authentication. Government and healthcare organizations can use the BSN (Burger Service Nummer), but private entities must explore alternative options. Below, we discuss potential authentication methods using Yivi, their advantages, and their limitations.

Authentication and Activation Using BRP Data​

For registration purposes organizations often need a set of data to match the user to their own administration, this is often done by matching on data from the Dutch Personal Records Database (BRP). The data in the BRP is of such quality that it can be trusted to be correct. The challenge often is that the data of the user in the administration of verifing organization is not of the same quality. Resulting in the proces that when a user discloses its BRP information to an organization it sometimes results in a dropout. These dropsouts are a problem, because it blocks the user from identifying and thereby registering or authenticating itself. To circumvent this problem organizations often choose to either: request more data from the user, for instance an contractnumber or change the data in their adminstration to match the data from the BRP so that in a next match the user is matched correctly.

Governmental and/or Health care organizations can simply use the identifying BSN from the BRP to match a user to their administration. We often see that only the BSN is requested from the user and that the BSN is then used to call the BRP for name and address details. We are not a fan of that approach, because we think that the amount of backchannel communication about users should be reduced and that the user should be in control of what personal data is being shared with which organizaiton.

Pros​

• In most cases, unique identification is achievable.
• High quality data for registration purposes.
• No unique identifier available for non governmental/health care organizations.
• BRP data can be used to increase data quality in the administration of organizations.

Cons​

• Dropouts require additional data or manual processes which may negatively influence the user experience.
• No unique identifier is available for private sector.
• Name and/or address scans can have negative effects on performance.

Attribute Index of Municipality​

Below is the attribute index of the BRP disclosed by the municipality.

Adding email address or phone number​

In addition to BRP data organizations may want to request users to disclose their email address and/or phonenumber. It's a common practice for authentication purposes to have the email address as a unique identifier of the user. The same goes for phone number, while it has to be said that phone numbers are more often transfered to other users, especially in a business setting. In that sense an email address is more stable. In the context of registration and authentication Yivi supports the combination of multiple data sources being disclosed, this can be done with the so called condiscon feature. Verifing organizations can make a composition of attributes that they request the user to disclose. In the context of registration/identification organizations may want to compose the following session request:

{
  "@context": "https://irma.app/ld/request/disclosure/v2",
  "disclose": [
    [
      [ "pbdf.pbdf.email" ],
      [ "pbdf.pbdf.mobilenumber" ]
    ],
    [
        "pbdf.gemeente.personalData.firstnames",
        "pbdf.gemeente.personalData.familyname",
        "pbdf.gemeente.personalData.fullname",
        "pbdf.gemeente.personalData.surname",
        "pbdf.gemeente.address.street",
        "pbdf.gemeente.address.houseNumber",
        "pbdf.gemeente.address.zipcode",
        "pbdf.gemeente.address.city"   
    ]
  ]
}

In this example we request users to disclose either their email address or phone number and their name and address details, which are often required in a registration process. Once the identifying data has been added to the administration of the verifying organization a subsequent authentication request might look like this:

{
  "@context": "https://irma.app/ld/request/disclosure/v2",
  "disclose": [
    [
      [ "pbdf.pbdf.email" ],
      [ "pbdf.pbdf.mobilenumber" ]
    ]
  ]
}

There is no need to request the user's personal data for authentication purposes once the organization has stored the identifier which can be the phone number or the email address.

Pros​

• Having a separate registration and subsequent authentication flow is a well known practise in the field. It's a familiar user experience.
• Working with identifiers reduces the amount of potential login failures to nearly zero, causing practically no dropouts.

Cons​

• Disclosing data from multiple sources may result in a more complex user experience when the user does not have the data already issued at their Yivi app.

Issuing a unique identifier to the Wallet​

Organizations can enhance user authentication by issuing a unique identifier, such as a membership card, directly to users’ Yivi wallets. This approach allows users to authenticate seamlessly without repeatedly disclosing sensitive personal data. The unique identifier can be tied to an internal identifier known only to the organization, ensuring a smooth authentication experience while maintaining user privacy.

This process can be facilitated using chained Yivi sessions. Users first disclose the necessary information for registration. If any mismatches arise that prevent automatic registration, additional identifying information, such as a contract number, can be requested to complete the registration. Once a user is successfully registered, the organization can issue a Yivi credential containing the unique identifier, which can be used for subsequent authentications.

A notable example of this implementation is PubHubs, where users are issued a club membership credential that allows seamless authentication for entry and participation.

Pros​

• Provides a privacy-preserving authentication method without requiring repeated data disclosures.
• Reduces user friction in subsequent login attempts.
• Can be tied to existing internal identifiers within the organization.
• Enables a high level of security with minimal backchannel verification.

Cons​

• Chained Yivi sessions are not yet widely supported by many identity brokers such as Signicat and Ver.iD.
• Having organization specific credentials in a Wallet and using them on a subsequent authentication is not a well-known user experience yet.

Authentication Using the Yivi Wallet Instance Identifier​

Every Yivi wallet instance is associated with a unique app-ID, which is issued by the Yivi keyshare server. This identifier provides an alternative authentication mechanism that does not rely on personal attributes.

Organizations can use the app-ID as a pseudonymous identifier to authenticate users across sessions. This method provides a straightforward way to recognize returning users without requesting sensitive personal data. However, the app-ID has limitations that make it less suitable for long-term authentication.

Pros​

• Functions as a pseudonymized identifier for users, maintaining privacy.
• Enables quick and easy authentication without requiring additional attributes to be issued.

Cons​

• The app-ID is not unique across different devices or installations. For example, an iOS and an Android installation of the same user will generate distinct appid values.

Final Thoughts​

Each authentication method using Yivi presents unique strengths and challenges. The choice depends on factors such as regulatory compliance, infrastructure readiness, and user experience. Organizations must carefully assess their needs and available resources before implementing an authentication solution with Yivi.

Hey everyone!

As we approach the end of 2024, our team is working hard to deliver as much progress on the project as possible. In keeping with our commitment to the community, we’re excited to share some of the improvements we’ve been working on. A lot of work has been put into getting a production grade hosting environment, but next to that we also delivered on some other areas.