How to manage trusted issuers

Overview

Before your wallet accepts a credential, it needs to know that the credential comes from an issuer it trusts. For mDocs, trust in an issuer is established by validating the issuer's Issuing Authority Certificate Authority (IACA) certificate. This guide explains how the Holder SDK handles issuer trust during credential claiming, and how to manage the list of issuers your wallet trusts.

Prerequisites

This guide builds on the Credential Claiming tutorial, where the trust behavior is configured during SDK initialization. It is recommended to complete that tutorial first.

How the SDK decides which issuers to trust

The SDK's behavior is controlled by the autoTrustMobileCredentialIaca option in the CredentialIssuanceConfiguration you pass when initializing the SDK. This option controls how the SDK handles issuer IACA certificates during credential claiming.

• autoTrustMobileCredentialIaca: true: The SDK automatically downloads and trusts the issuer's IACA certificate when claiming a credential. This lets your wallet claim credentials from any issuer without pre-configuring a trusted issuer list. It is convenient for development and for open ecosystems, but it means your wallet does not restrict which issuers it accepts credentials from.
• autoTrustMobileCredentialIaca: false: The SDK only accepts credentials from issuers whose IACA certificates have already been added to the SDK's trusted issuers list. Credentials from any other issuer are rejected. This gives you explicit control over which issuers your wallet trusts, at the cost of managing the trusted issuer list yourself.

For production wallets that should only accept credentials from a known set of issuers (for example, a specific jurisdiction or set of credential types), set autoTrustMobileCredentialIaca to false and manage the trusted issuer list explicitly, as described below.

Managing the trusted issuer list

When autoTrustMobileCredentialIaca is false, you add the IACA certificates of the issuers you trust using the SDK's addTrustedIssuerCertificates method. Only credentials from issuers whose IACA certificates are in this list pass validation.

try await mobileCredentialHolder.addTrustedIssuerCertificates(certificates: iacaCertificates)

Refer to the SDK reference for the exact signature on each platform:

• iOS: addTrustedIssuerCertificates
• Android SDK reference
• React Native SDK reference

Configure this list based on the jurisdictions and credential types your wallet supports. You obtain each issuer's IACA certificate from the issuer as part of onboarding. For background on IACA certificates and where they sit in the issuance trust model, see Issuing Authority Certificate Authority (IACA).

Which approach should you use?

• Use autoTrustMobileCredentialIaca: true while developing, or when your wallet is intended to accept credentials from any issuer in an open ecosystem.
• Use autoTrustMobileCredentialIaca: false with an explicitly managed trusted issuer list when your wallet must only accept credentials from a known, curated set of issuers.