oid4vcwallet/dev.idfoundry.oid4vcwallet/WalletConfiguration

WalletConfiguration

@Serializable

data class WalletConfiguration(val clientID: String = "", val redirectURI: String = "", val issuerRoots: String = "", val verifierRoots: String = "", val registrarRoots: String = "", val mdocReaderRoots: String = "", val mdocReaderRequireEKU: Boolean = false, val requireTrustedMdocReader: Boolean = false, val requireSignedDCAPIRequests: Boolean = false, val development: Boolean = false, val developmentRoots: String = "", val locales: List<String> = defaultLocales(), val batchSize: Int = 0, val requestRefresh: Boolean = false, val copyPolicy: WalletConfiguration.CopyPolicy = CopyPolicy.PER_PRESENTATION, val tlsPins: Map<String, List<String>> = emptyMap(), val issuanceProfile: WalletConfiguration.IssuanceProfile = IssuanceProfile.OPENID4VCI, val proximityDeviceAuth: WalletConfiguration.ProximityDeviceAuth = ProximityDeviceAuth.SIGNATURE, val verifierRequireEKU: String = "", val registrarRequireEKU: String = "", val statusIssuers: Map<String, List<String>> = emptyMap(), val requireIssuerName: Boolean = false, val issuerMetadataRoots: String = "", val requireSignedIssuerMetadata: Boolean = false, val requireIssuerMetadataName: Boolean = false, val maxIssuerMetadataAgeSeconds: Long = 0)(source)

NewWallet's configuration.

Constructors

WalletConfiguration

constructor(clientID: String = "", redirectURI: String = "", issuerRoots: String = "", verifierRoots: String = "", registrarRoots: String = "", mdocReaderRoots: String = "", mdocReaderRequireEKU: Boolean = false, requireTrustedMdocReader: Boolean = false, requireSignedDCAPIRequests: Boolean = false, development: Boolean = false, developmentRoots: String = "", locales: List<String> = defaultLocales(), batchSize: Int = 0, requestRefresh: Boolean = false, copyPolicy: WalletConfiguration.CopyPolicy = CopyPolicy.PER_PRESENTATION, tlsPins: Map<String, List<String>> = emptyMap(), issuanceProfile: WalletConfiguration.IssuanceProfile = IssuanceProfile.OPENID4VCI, proximityDeviceAuth: WalletConfiguration.ProximityDeviceAuth = ProximityDeviceAuth.SIGNATURE, verifierRequireEKU: String = "", registrarRequireEKU: String = "", statusIssuers: Map<String, List<String>> = emptyMap(), requireIssuerName: Boolean = false, issuerMetadataRoots: String = "", requireSignedIssuerMetadata: Boolean = false, requireIssuerMetadataName: Boolean = false, maxIssuerMetadataAgeSeconds: Long = 0)

Types

Companion

object Companion

The configuration's defaults.

CopyPolicy

@Serializable

enum CopyPolicy : Enum<WalletConfiguration.CopyPolicy>

Which copy of a credential a presentation uses (OpenID4VCI 1.0: "a unique Credential per presentation or per Verifier").

IssuanceProfile

@Serializable

enum IssuanceProfile : Enum<WalletConfiguration.IssuanceProfile>

The profile issuance follows.

ProximityDeviceAuth

@Serializable

enum ProximityDeviceAuth : Enum<WalletConfiguration.ProximityDeviceAuth>

How an in-person response authenticates the mdoc (ISO/IEC 18013-5 §9.1.3).

Properties

batchSize

@SerialName(value = "batch_size")

val batchSize: Int

How many copies of each credential to request when an issuer offers batches, each bound to its own key, so each presentation can use one no Verifier has seen. 0 means the SDK's default (5); it's capped at the issuer's batch size.

callbackScheme

val callbackScheme: String?

The scheme of redirectURI: the scheme the authorization's redirect comes back on.

clientID

@SerialName(value = "client_id")

val clientID: String

The wallet's registration with Authorization Servers: empty for a wallet with no WalletProvider, receiving credentials only from pre-authorized codes redeemed with no client authentication.

copyPolicy

@SerialName(value = "copy_policy")

val copyPolicy: WalletConfiguration.CopyPolicy

Which copy of a credential a presentation uses.

development

val development: Boolean

Relaxes what production requires, for a wallet talking to services on a development machine. Never ship an app with it set. It lets issuers, Authorization Servers, Verifiers and status lists be on loopback addresses, over http there too; with developmentRoots, makes requests through an ordinary HTTPS client, without the hardened one's refusal of private network addresses; and skips the production checks on receiving credentials: durable stores and keys, and the random source.

developmentRoots

@SerialName(value = "development_roots")

val developmentRoots: String

PEM certificates the wallet's HTTPS requests trust besides the system's: a development service's own CA (Go reads only Android's system CA files, so a CA installed on the device doesn't reach it). Only with development.

issuanceProfile

@SerialName(value = "issuance_profile")

val issuanceProfile: WalletConfiguration.IssuanceProfile

The profile issuance follows.

issuerMetadataRoots

@SerialName(value = "issuer_metadata_roots")

val issuerMetadataRoots: String

PEM certificates: the trust anchors for signed Credential Issuer Metadata. With them, signed metadata is asked for and verified.

issuerRoots

@SerialName(value = "issuer_roots")

val issuerRoots: String

PEM certificates: the trust anchors for issuers' credentials, and for Verifiers' requests.

locales

@EncodeDefault

val locales: List<String>

The holder's preferred languages (BCP 47, most preferred first), for issuers' display metadata. The device's languages are the usual choice, and the default.

maxIssuerMetadataAgeSeconds

@SerialName(value = "max_issuer_metadata_age_seconds")

val maxIssuerMetadataAgeSeconds: Long

Refuses signed metadata signed longer ago than this many seconds; 0 doesn't limit it.

mdocReaderRequireEKU

@SerialName(value = "mdoc_reader_require_eku")

val mdocReaderRequireEKU: Boolean

Recognizes only reader certificates with the ISO/IEC 18013-5 reader authentication extended key usage (1.0.18013.5.1.6), so a certificate issued for another role under mdocReaderRoots isn't taken for a reader's.

mdocReaderRoots

@SerialName(value = "mdoc_reader_roots")

val mdocReaderRoots: String

PEM certificates: the mdoc readers recognized when one signs an org-iso-mdoc request (MdocPresentation.Request.reader). Empty: every such request is shown by its origin.

proximityDeviceAuth

@SerialName(value = "proximity_device_auth")

val proximityDeviceAuth: WalletConfiguration.ProximityDeviceAuth

How an in-person response authenticates the mdoc. ProximityDeviceAuth.MAC_PREFERRED needs a key store that is also a KeyAgreement.

redirectURI

@SerialName(value = "redirect_uri")

val redirectURI: String

Where the issuer's pages send the holder back to: a private-use URI the app receives. Empty for a wallet that receives only pre-authorized codes.

registrarRequireEKU

@SerialName(value = "registrar_require_eku")

val registrarRequireEKU: String

A dotted object identifier: recognizes only registrar certificates under registrarRoots with that extended key usage. Outside development, required when registrarRoots shares a trust anchor with another role's roots.

registrarRoots

@SerialName(value = "registrar_roots")

val registrarRoots: String

PEM certificates: the registrars whose registrations of Verifiers the wallet checks (Presentation.Verifier.registration). Empty: registrations are ignored.

requestRefresh

@SerialName(value = "request_refresh")

val requestRefresh: Boolean

Asks Authorization Servers for a refresh token, so Wallet.refreshCredential can later replace a credential's copies without the holder. The server must allow the wallet the offline_access scope, or the authorization fails.

requireIssuerMetadataName

@SerialName(value = "require_issuer_metadata_name")

val requireIssuerMetadataName: Boolean

Refuses signed metadata whose certificate doesn't name the issuer.

requireIssuerName

@SerialName(value = "require_issuer_name")

val requireIssuerName: Boolean

Refuses a received SD-JWT VC whose iss its signing certificate doesn't name. SD-JWT VC doesn't require them to correspond: set it where issuerRoots certify several issuers.

requireSignedDCAPIRequests

@SerialName(value = "require_signed_dcapi_requests")

val requireSignedDCAPIRequests: Boolean

Refuses an unsigned OpenID4VP request over the Digital Credentials API: Wallet.startDCAPIPresentation throws untrustedVerifier, before the holder sees it. Its only identity is the origin the platform reports; HAIP requires a wallet to support unsigned requests, so set it only where every Verifier must be one verifierRoots accepts.

requireSignedIssuerMetadata

@SerialName(value = "require_signed_issuer_metadata")

val requireSignedIssuerMetadata: Boolean

Refuses an issuer whose metadata isn't signed under issuerMetadataRoots, before the holder signs in or enters a code.

requireTrustedMdocReader

@SerialName(value = "require_trusted_mdoc_reader")

val requireTrustedMdocReader: Boolean

Refuses an org-iso-mdoc request no recognized reader signed: Wallet.startMdocPresentation throws untrustedVerifier, and nothing is shown to the holder. Needs mdocReaderRoots.

statusIssuers

@SerialName(value = "status_issuers")

val statusIssuers: Map<String, List<String>>

The Status Issuers that may sign a credential issuer's status lists on its behalf: credential issuer (an SD-JWT VC's iss) → Status Issuer identifiers, each recognized by a certificate under issuerRoots naming it. Without it, Wallet.checkStatus accepts only a status list the issuer signed itself.

tlsPins

@SerialName(value = "tls_pins")

val tlsPins: Map<String, List<String>>

Pins hosts' certificates for the wallet's own HTTPS requests: host → base64 SHA-256 digests of a certificate's SubjectPublicKeyInfo, one of which a certificate in the verified chain must have, or the request fails as tlsPin before anything is sent. A host is a name, or *. and one, matching any name a label below it; not an IP address. Pins add to certificate verification, never replace it: pin a CA's key, so a leaf renewal doesn't break the app, and keep a backup pin. They cover the requests the SDK makes (issuers, Authorization Servers, Verifiers, status lists), not the app's own, such as to its Wallet Provider: pin that client yourself (OkHttp's CertificatePinner, or a network security configuration).

verifierRequireEKU

@SerialName(value = "verifier_require_eku")

val verifierRequireEKU: String

A dotted object identifier: recognizes only Verifier certificates under verifierRoots with that extended key usage, the one your ecosystem marks its Verifiers' certificates with. Outside development, required when verifierRoots shares a trust anchor with another role's roots.

verifierRoots

@SerialName(value = "verifier_roots")

val verifierRoots: String

PEM certificates: the trust anchors for Verifiers' requests.