Proximity Sharing
This guide shows you how to present an mdoc credential, such as a mobile driving licence (mDL), to a nearby verifier, also called a reader. You review what the reader requests, choose an eligible credential, and approve or decline sharing.
This guide covers the walt.id Compose Multiplatform wallet on Android and iOS and the native SwiftUI wallet on iOS.
Prerequisites
Before you begin, ensure you have:
- A walt.id mobile wallet app — See Try the Demo for downloads, or follow the source build guide.
- An eligible mdoc in the wallet — The credential must match the requested document type and required fields, with its associated holder key available on the device. SD-JWT VCs and W3C VCs use other presentation flows.
- A compatible reader — Use a second device running a reader app, or a computer for the web reader.
- Device access — Enable the radios and grant the permissions requested by the wallet. NFC requires compatible hardware and, on iOS, an eligible device and an app signed with Apple's managed host-card emulation (HCE) entitlements.
How the Connection Works
Engagement starts the connection: the reader scans a QR code displayed by the wallet, or you bring the devices together for NFC. Transfer carries the request and response. An NFC tap can start a Bluetooth transfer; it does not necessarily mean the credential travels over NFC.
Loading diagram...
The QR code provides connection information, not your credential data. The exchange uses a local encrypted connection; credential issuance and any configured online trust or status services may still need internet access. Proximity sharing is separate from URL-based OpenID4VP and the browser/OS Digital Credentials API.
| Connection | Android | iOS |
|---|---|---|
| QR → Bluetooth Low Energy | Supported with Bluetooth access. | Supported with Bluetooth access. |
| NFC → Bluetooth | Requires NFC host-card emulation and Bluetooth access. | Requires NFC eligibility, HCE entitlements, and Bluetooth access. |
| NFC → direct NFC transfer | Requires NFC host-card emulation. Keep the devices together. | Requires NFC eligibility and HCE entitlements. The system sheet can require review followed by reconnection. |
| Wi-Fi Aware transfer | Available on eligible Android 13+ devices with compatible hardware and permissions; independent reader testing is still pending. | Unavailable. |
Only connections available on your device are offered. Reader support also varies; see the compatibility overview.
Share From the App
- Open Present in person and follow any permission or radio prompts.
- Choose Show QR code and let the reader scan it, or choose Hold near the reader and bring the devices together. If QR is the only available method, it opens directly. On iOS, NFC opens the system presentation sheet.
- Review the reader's identity and trust result, requested data, and any stated purpose or retention intent. When several credentials match a requested document, choose one and review the selected fields.
- Approve or decline. Complete device authentication if prompted. If the app asks you to reconnect after approval, start a fresh request on the reader and follow the wallet's instructions.
- Check the result on both devices. Connection details shows how the exchange started and which connection carried the data.
The wallet's completion screen records what it sent; the reader determines whether it accepts and trusts the credential. Start a fresh sharing session after cancellation or failure.
Configure Reader Trust
Reader authentication lets the wallet check who signed a request. Your trust policy determines whether that reader is accepted. This is separate from the reader trusting the issuer of your credential.
| Material | Configure In | Purpose |
|---|---|---|
| Public Reader CA certificate | Wallet | Trust the reader signing the request. |
Reader private key, certificate, and chain, often a password-protected .p12 | Reader only | Sign the reader's request. |
| Public credential issuer IACA certificate | Reader | Trust the credential issuer. |
For testing, the demo apps allow anonymous or untrusted readers by default, while still asking for your consent. To require an authenticated, trusted reader:
- Configure a signing identity on the reader using its official instructions, and obtain the matching public Reader CA through a trusted channel.
- In the wallet's Settings → Credential Sharing → Reader Authentication, select Import Reader CA or trust bundle. Import the public PEM/DER certificate or a supported walt.id JSON trust bundle, check its details and fingerprint, and confirm.
- Select Require a trusted reader and start a new sharing session. An unsigned reader, or a reader without a trusted certificate chain, is rejected.
- Configure the credential issuer's public IACA on the reader so it can trust the credentials you present.
Import only public trust material into the wallet. A reader's .p12 contains its signing identity and belongs on the reader. Its import passphrase is the export password chosen when the file was created, not your wallet PIN.
Trust is configured separately in each wallet app. Even when untrusted readers are allowed, the wallet rejects invalid reader authentication and readers known to be revoked. Importing a CA does not repair an invalid reader certificate or automatically configure online revocation checks.
Optional Sharing Settings
Connection and approval preferences are under Settings → Credential Sharing → Nearby sharing. Automatic uses the available connection methods by default. The app remembers changes for later presentations.
- Bluetooth transfer restricts transfer to Bluetooth, using QR or NFC engagement. Use it for readers that mishandle multiple advertised transports.
- Wi-Fi Aware requires compatible Android hardware and a reader supporting that method.
- NFCv2 profiles select a provisional NFC engagement mode and require a compatible reader. They are separate from conventional NFC sharing and are not needed for normal QR or NFC-to-Bluetooth use.
Prepare a Share Before Reconnecting
With Ask each time, you review each incoming request. Prepare sharing instead collects a request from an authenticated, trusted reader without sending credentials. After that connection closes, review the request and choose Approve and get ready. Start a fresh request on the reader and reconnect to send the approved data.
The approval lasts 60 seconds and works once. A different reader or changed request requires fresh review. This flow also allows review outside the iOS NFC system sheet when it prevents interaction with the wallet.
Reader Compatibility
Use this overview to choose a reader and connection. Follow the reader's official documentation for installation and general setup; expand its notes for wallet-specific configuration and limitations.
| Reader | Connection | Reader Authentication | Compatibility |
|---|---|---|---|
| Multipaz Identity Reader | QR or NFC → Bluetooth | Custom signing identity | Compatible; QR transport-selection workaround below. |
| EUDI Proximity Verifier (Android) | QR → Bluetooth GATT | Unsigned requests | Compatible with the wallet's permissive reader policy. |
| Multipaz TestApp | QR → Bluetooth; direct NFC / NFCv2 | Signed requests | Compatible after reader-side fixes; official builds have limitations below. |
| Stelau Web Verifier | QR → Bluetooth GATT | Configurable signing identity | Compatible after reader-side fixes; iOS discovery can be intermittent. |
The listed Bluetooth flows cover Android and both iOS wallet apps; direct NFC support varies as detailed below. Wi-Fi Aware compatibility has not yet been verified with these readers. Compatibility notes apply to the versions referenced below.
Multipaz Identity Reader
Setup and Compatibility Details
Use the official reader-key generation and PKCS#12 instructions to create a signing identity. Import the .p12 into the reader's Reader identity settings and its public Reader CA into the wallet. Add your credential issuer's IACA under the reader's trusted issuers.
Choose an mDL request matching your credential, such as Age Over 18 for age and portrait data. Scan the wallet's QR, or use Hold to Wallet for NFC engagement.
Compatibility note: the reader can select direct NFC from a QR advertising several transports, then fail before requesting data. If you encounter this, select Bluetooth transfer in the wallet's Nearby sharing settings and start a fresh session. This is a transport-selection issue, not certificate rejection.
QR/Bluetooth and conventional NFC-to-Bluetooth work with the official app, including signed requests with a compatible custom identity. NFCv2 and Wi-Fi Aware are not established paths for this reader.
Version reference: Android 0.4.0-pre.3.22549ee (build 45), upstream source 22549ee.
EUDI Proximity Verifier
Setup and Compatibility Details
Follow the official application and proximity-flow instructions, using the walt.id wallet's Present in person → Show QR code in place of the EUDI Wallet steps. Choose an mDL request matching the fields in your credential.
The referenced reader version sends unsigned requests. Use Allow anonymous or untrusted readers in the wallet for these exchanges; Require a trusted reader rejects them. Importing a Reader CA cannot authenticate an unsigned request. Prepared sharing requires a signing reader.
For issuer trust, follow the application configuration guide. The referenced release bundles EUDI test issuer roots; adding your issuer's IACA requires source configuration and a rebuild.
QR/Bluetooth GATT works with Android and iOS wallets. The referenced iOS verifier is UI-only; use the Android verifier. Its L2CAP setting has no effect, and NFC and Wi-Fi Aware are not established paths.
Version reference: official Android 2026.05.6 release, build 6, upstream source c59e184.
Multipaz TestApp
Setup and Compatibility Details
Use the official applications page for APKs and the project documentation for source and build information.
Official-build limitations: in the referenced version, reader certificates can have invalid serial numbers or excessive validity periods, conventional NFC selection can fail before transfer, and portrait decoding can crash the result screen. NFCv2 exchanges can succeed, but these issues prevent reliable use of the complete signed/direct-NFC flow.
After correcting those reader issues, the wallet is compatible with signed QR/Bluetooth, conventional direct NFC on Android, and NFCv2 direct sharing on Android and iOS. This does not mean the referenced official APK includes the fixes. Intermittent NFC failures and repeated requests on a retained connection remain limitations.
For a reader version that addresses these issues:
- Import its public reader CA into the wallet. The app exposes it under Trusted verifiers → Multipaz TestApp, in the certificate's Basic Information → Type field. Separately add your credential issuer's IACA to the reader's trusted issuers.
- Choose an mDL request, enable request signing, and include a portrait if your credential contains one. Turn off Observe Mode polling frames and the option to keep the connection open for multiple requests.
- For conventional direct NFC, enable NFC Data Transfer, disable BLE and automatic transport selection in the reader's NFC Negotiated Handover settings, and use the wallet's Automatic profile.
- For NFCv2 direct transfer, choose the reader's NFCv2-only action and the wallet's NFCv2 direct profile. Keep the devices together and follow any review-and-reconnect prompt on iOS.
An update does not regenerate an existing invalid certificate; use a fresh test profile or device. Bundled test CAs are for synthetic testing, and the reader still needs your credential issuer's IACA to trust the result.
Version reference: official 0.101.0-pre.38.3fd9b168, upstream source 3fd9b168.
Stelau mdoc Web Verifier
Setup and Compatibility Details
Follow the official usage guide for browser requirements, QR scanning, Bluetooth permissions, request selection, and issuer trust.
Reader limitations: in the referenced version, missing Bluetooth notification subscriptions can stall the exchange, and an empty optional request field can cause validation to fail. After correcting those issues, the wallet is compatible with signed QR/Bluetooth GATT exchanges. Android exchanges work with trusted readers; iOS exchanges can succeed, but Bluetooth discovery and repeated attempts are unreliable. This does not establish that the public deployment includes the fixes.
For a version that addresses these issues, configure the reader certificate chain and PKCS#8 private key under Reader Authentication, and import its public Reader CA into the wallet. Add the credential issuer's IACA under Issuer Certificate Management. Then follow the official QR flow and select the wallet in the browser's Bluetooth picker.
Use test keys and a dedicated test browser profile: the reader stores its signing identity in browser local storage. This browser path provides Bluetooth GATT, not NFC, L2CAP, or Wi-Fi Aware.
Version reference: public deployment checked on 9 September 2026 using desktop Chrome on macOS; upstream source f2ef877c inspected for the issues above.
Troubleshooting
- The reader cannot connect: Check device permissions, radios, and the reader's compatibility notes, then start a fresh wallet session and reader scan. For interrupted NFC attempts, separate the devices and restart the sharing flow.
- The reader is rejected: Check request signing, the matching Reader CA, and the certificate's validity. An unsigned reader cannot be used with Require a trusted reader.
- No credential can be shared: Check the requested document type and fields, credential validity, and holder-key availability.
- The wallet completes but the reader reports an untrusted issuer: Configure the credential issuer's IACA on the reader, independently of Reader CA configuration in the wallet.
Next Steps
- Receive an mdoc first — Receiving Credentials via OID4VCI.
- Present remotely over OID4VP — Presenting Credentials via OID4VP.
- Configure reader trust — Security.
Further Reading
- Try the Demo — Install a sample wallet and test with Portal2.
- Mobile Wallet Getting Started — SDK overview.
- mdoc and mDL — Credential formats and presentation concepts.
For SDK integration and implementation details:
- Mobile Wallet SDK proximity guide — Kotlin session, trust, and consent integration.
- Swift WalletSDK proximity guide — Native iOS integration.
- Shared proximity engine — Protocol, session, and request handling.
- Mobile proximity transports — Android and iOS transport support and integration boundaries.