Learn how to build an iOS application that can verify an mDoc presented via a proximity workflow

Create a new project

Please follow the detailed instructions to Create a new XCode Project and add your organisation’s identifier.

Unzip the dependencies file

1. Unzip the MobileCredentialVerifierSDK-*version*.xcframework.zip file.
2. Drag the MobileCredentialVerifierSDK-*version*.xcframework folder into your project.
3. Configure MobileCredentialVerifierSDK.xcframework to Embed & sign.

See Add existing files and folders for detailed instructions.

This should result in the the following framework being added to your project:

Add Bluetooth permissions

The SDK requires access to the mobile device Bluetooth capabilities as part of the proximity presentation workflow. Configure these permissions in the Info tab of the Application target:

Run the application

Select Run and make sure the application launches with a “Hello, world!” text in the middle of the display, as shown in the following image:

Create the application structure

1. Open the ContentView file in your new project and replace any existing code with the following:

   Swift

   import SwiftUI
   import MobileCredentialVerifierSDK
    
   struct ContentView: View {
       @ObservedObject var viewModel: VerifierViewModel = VerifierViewModel()
       // Verify mDocs - Step 4.4: Add the isPresentingResponseView variable
    
       var body: some View {
           NavigationStack {
               VStack(spacing: 20) {
                   // Manage certificates - Step 1.2: Add Certificate Management button
                   // Verify mDocs - Step 2.5: Add Scan QR Code button
                   // Verify mDocs - Step 4.3: Add View Response button
               }
               // Manage certificates - Step 1.3: Add navigation destination logic
           }
       }
        // Verify mDocs - Step 2.4: Create QRScannerView
   }
    
   class VerifierViewModel: ObservableObject {
       // Initialise SDK - Step 2.1: Add MobileCredentialVerifier var
       // Verify mDocs - Step 1.1: Create MobileCredentialRequest instance
       // Verify mDocs - Step 1.2: Create receivedDocuments variable
    
       init() {
         do {
               // Initialise SDK - Step 2.2: Initialise MobileCredentialVerifier SDK
    
         }
         catch {
             print(error.localizedDescription)
         }
       }
    
       // Verify mDocs - Step 3.1: Create setupProximityPresentationSession
       // Verify mDocs - Step 3.2: Create sendDeviceRequest function
   }
    
   // Manage certificates - Step 1.1: Create CertificateManagementView view
   // Verify mDocs - Step 4.1: Create MobileCredentialClaimListView view
   // Verify mDocs - Step 4.2: Create PresentationResponseView
   This will serve as the basic structure for your application. We will copy and paste different code snippets into specific locations in this codebase to achieve the different functionalities. These locations are indicated by comments that reference both the section and the step.

Initialise the MobileCredentialVerifier class

1. Add the following code after the // Initialise SDK - Step 2.1: Add MobileCredentialVerifier var comment to create a variable that holds the mobileCredentialVerifier instance:

    var mobileCredentialVerifier: MobileCredentialVerifier

2. Add the following code after the // Initialise SDK - Step 2.2: Initialise MobileCredentialVerifier SDK comment to initialise the SDK and create a new instance in the MobileCredentialVerifier variable:

   Swift

       mobileCredentialVerifier = MobileCredentialVerifier.shared
       try mobileCredentialVerifier.initialise()

3. Run the app to make sure it compiles properly.

Create the Certificate Management view

1. Add the following code under the // Manage certificates - Step 1.1: Create CertificateManagementView view to create a new view where the user will manage certificates in the app.

   Swift

   struct CertificateManagementView: View {
       // Certificate Management ViewModel will handle the logic
       @ObservedObject var viewModel = CertificateManagementViewModel()
       // This var holds a pem string of a certificate to be added
       @State var certificateString = ""
    
       var body: some View {
           Form {
               Section(
                   header: Text("IACA Certificate").font(.headline),
                   footer: HStack {
                       Spacer()
                       Button("Add", action: {
                           // Manage Certificates - Step 2.6: Call addCertificate function
                       })
                       Spacer().frame(width: 30)
                       Button("Clear", action: {
                           certificateString = ""
                       })
                       .foregroundColor(.red)
                       .contentShape(Rectangle())
                       .frame(alignment: .trailing)
                   }
               ) {
                   TextField("IACA certificate string", text: $certificateString)
               }
    
               Section(
                   header: Text("Stored Certificates").font(.headline)
               ) {
                   // Manage Certificates - Step 2.4: Display retrieved certificates
               }
           }
           .navigationBarTitle("Certificate Setting")
           .onAppear {
               // Manage Certificates - Step 2.3: Call getCertificates function
           }
       }
   }
    
   class CertificateManagementViewModel: ObservableObject {
    
       // Manage Certificates - Step 2.1: Add certificates variable
       // Manage Certificates - Step 2.2: Create getCertificates function
       // Manage Certificates - Step 2.5: Create addCertificate function
       // Manage Certificates - Step 2.7: Create removeCertificate function
   }

2. Add the following code under the // Manage certificates - Step 1.2: Add Certificate Management button comment to add a new button for the user to select to navigate to the new CertificateManagementView:

   Swift

   NavigationLink("Certificate Management", value: "CertificateManagement")
       .font(.headline)
       .foregroundColor(.blue)
       .padding()
       .background(Color.gray.opacity(0.2))
       .cornerRadius(10)

3. Add the following code under the // Manage certificates - Step 1.3: Add navigation destination logic comment to create the logic that associates the button with the correct view:

   Swift

   .navigationDestination(for: String.self) { value in
       switch value {
       case "CertificateManagement":
           CertificateManagementView(viewModel: CertificateManagementViewModel())
       // Verify mDocs - Step 2.6: Add QR code view destination
       // Verify mDocs - Step 4.6: Add Response view destination
       default:
           EmptyView()
       }
   }

4. Run the app and select the Certificate Management button. You should see a result similar to the following:

As the user selects the Certificate Management button they are navigated to the new CertificateManagement view where they can see controls that would enable them to add, view and remove certificates. We will build these capabilities into the controls in the next step.

Add Certificate Management functionalities

Currently our CertificateManagementView view has no functionalities. Let’s fix this by adding the capabilities to add, view and remove certificates.

1. Add the following code under the // Manage Certificates - Step 2.1: Add certificates variable comment to add a new certificates variable that will hold the certificates added to the application:

   Swift

       @Published var certificates: [TrustedCertificate] = []
       let mobileCredentialVerifier = MobileCredentialVerifier.shared

2. Add the following code under the // Manage Certificates - Step 2.2: Create getCertificates function comment to create a new getCertificates function that calls the SDK getTrustedIssuerCertificates and enables the application to retrieve all certificates and display them to the user:

   Swift

       func getCertificates() {
           do {
               let fetchedCertificates = try mobileCredentialVerifier.getTrustedIssuerCertificates()
               // Updating the UI from the main thread
               DispatchQueue.main.async {
                   self.certificates = fetchedCertificates
               }
           } catch {
               print(error.localizedDescription)
           }
       }

3. Add the following code under the // Manage Certificates - Step 2.3: Call getCertificates function comment to call the new getCertificates function from within the CertificateManagementView once the view is loaded:

   Swift

       viewModel.getCertificates()

4. Add the following code under the // Manage Certificates - Step 2.4: Display retrieved certificates comment to iterate over retrieved certificates and display them to the user:

   Swift

           ForEach(viewModel.certificates, id: \.id) { certificate in
           Text("\(certificate.pem)")
               .frame(maxHeight: 100)
               // Manage Certificates - Step 2.8: Call removeCertificate function
   }

5. Add the following code under the // Manage Certificates - Step 2.5: Create addCertificate function comment to create a new addCertificate function that calls the SDK addTrustedIssuerCertificates and enables the application to accept a string parameter and use it to add a new certificate:

   Swift

       func addCertificate(_ certificate: String) {
           Task {
               do {
                   _ = try await mobileCredentialVerifier.addTrustedIssuerCertificates(certificates: [certificate])
                   self.getCertificates()
               }
               catch {
                   print(error.localizedDescription)
               }
           }
       }

6. Add the following code under the // Manage Certificates - Step 2.6: Call addCertificate function comment to call the new addCertificate function from within the CertificateManagementView once the user provides a string (which is stored in the certificateString variable) and selects the Add button:

   Swift

       viewModel.addCertificate(certificateString)

7. Add the following code under the // Manage Certificates - Step 2.7: Create removeCertificate function comment to create a new removeCertificate function that calls the SDK deleteTrustedIssuerCertificate and enables the application to remove a selected certificate:

   Swift

       func removeCertificate(_ certificateID: String) {
           do {
               try mobileCredentialVerifier.deleteTrustedIssuerCertificate(certificateId: certificateID)
               // Refresh the certificates list after deletion
               self.getCertificates()
           } catch {
               print(error.localizedDescription)
           }
       }

8. Add the following code under the // Manage Certificates - Step 2.8: Call removeCertificate function comment to call the new removeCertificate function from within the CertificateManagementView once the user performs a swipe action on an individual certificate:

   Swift

   		.swipeActions(edge: .trailing) {
   	Button(role:. destructive) {
   		viewModel.removeCertificate(certificate.id)
   	} label: {
   		Image(systemName: "trash")
   	}
   }

9. Run the app and perform the following instructions:

   1. Select the Manage Certificates button.

   2. Copy and paste the following text into the IACA Certificate text box.

      MIICYzCCAgmgAwIBAgIKXhjLoCkLWBxREDAKBggqhkjOPQQDAjA4MQswCQYDVQQG
      EwJBVTEpMCcGA1UEAwwgbW9udGNsaWZmLWRtdi5tYXR0cmxhYnMuY29tIElBQ0Ew
      HhcNMjQwMTE4MjMxNDE4WhcNMzQwMTE1MjMxNDE4WjA4MQswCQYDVQQGEwJBVTEp
      MCcGA1UEAwwgbW9udGNsaWZmLWRtdi5tYXR0cmxhYnMuY29tIElBQ0EwWTATBgcq
      hkjOPQIBBggqhkjOPQMBBwNCAASBnqobOh8baMW7mpSZaQMawj6wgM5e5nPd6HXp
      dB8eUVPlCMKribQ7XiiLU96rib/yQLH2k1CUeZmEjxoEi42xo4H6MIH3MBIGA1Ud
      EwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBRFZwEOI9yq
      232NG+OzNQzFKa/LxDAuBgNVHRIEJzAlhiNodHRwczovL21vbnRjbGlmZi1kbXYu
      bWF0dHJsYWJzLmNvbTCBgQYDVR0fBHoweDB2oHSgcoZwaHR0cHM6Ly9tb250Y2xp
      ZmYtZG12LnZpaS5hdTAxLm1hdHRyLmdsb2JhbC92Mi9jcmVkZW50aWFscy9tb2Jp
      bGUvaWFjYXMvMjk0YmExYmMtOTFhMS00MjJmLThhMTctY2IwODU0NWY0ODYwL2Ny
      bDAKBggqhkjOPQQDAgNIADBFAiAlZYQP95lGzVJfCykhcpCzpQ2LWE/AbjTGkcGI
      SNsu7gIhAJfP54a2hXz4YiQN4qJERlORjyL1Ru9M0/dtQppohFm6

3. Select the Add button. The new certificate should appear in the STORED CERTIFICATES area.

4. Swipe left across the new certificate and select the Delete icon to remove it.

You should get a result similar to the following:

1. When the user selects the Certificate Management button they are navigated to the CertificateManagement view.
2. When the user adds the text and selects the Add button a new certificate is added and displayed in the STORED CERTIFICATES area.
3. When the user swipes left and selects the Delete icon the certificate is removed.

Create a presentation request

As a verifier, you can select what information you request for verification. Our application implements this by creating a MobileCredentialRequest instance to define the required information, and a new variable to hold the response from the wallet application.

1. Add the following code under the Verify mDocs - Step 1.1: Create MobileCredentialRequest instance comment to define what information to request from the wallet application user:

   Swift

       let mobileCredentialRequest = MobileCredentialRequest(
           docType: "org.iso.18013.5.1.mDL",
           namespaces: [
               "org.iso.18013.5.1":  [
                   "family_name": false,
                   "given_name": false,
                   "birth_date": false
               ]
           ]
       )

   This object details:

   • The requested credential type (e.g. org.iso.18013.5.1.mDL).
   • The claims required for verification (e.g. family_name).
   • The requested namespace (e.g. org.iso.18013.5.1).
   • Whether or not the verifier intends to persist the claim value (true/false).

   For the verification to be successful, the presented credential must include the referenced claim against the specific namespace defined in the request. Our example requests the birth_date under the org.iso.18013.5.1 namespace. If a wallet responds to this request with a credential that includes a birth_date but rather under the org.iso.18013.5.1.US namespace, the claim will not be verified.

2. Add the following code under the Verify mDocs - Step 1.2: Create receivedDocuments variable to create a new receivedDocuments variable that will hold the response from the wallet application:

   Swift

       @Published var receivedDocuments: [MobileCredentialPresentation] = []

Now your application has an existing request to share, and a variable to hold any incoming responses. We can now proceed to build the capabilities to send the request and handle the response.

Scan and process a QR code

As defined in ISO 18130-5, a proximity presentation workflow is always initiated by the holder (wallet application user), who must create a QR code for the verifier to scan in order to initiate the device engagement phase.

This means that your verifier application must be able to scan and process this QR code. For ease of implementation, we will use a third party framework to achieve this.

1. Add camera usage permissions to the app target:

   

2. Add the CodeScanner library via Swift Package Manager.

   

3. Create a new swift file named QRScannerView and add the following code into it to implement the QR scanning capability:

   Swift

   import SwiftUI
   import CodeScanner
    
   struct QRScannerView: View {
    
       private let completionHandler: (String) -> Void
    
       init(completion: @escaping (String) -> Void) {
           completionHandler = completion
       }
    
       var body: some View {
           CodeScannerView(codeTypes: [.qr]) { result in
               switch result {
               case .failure(let error):
                   print(error.localizedDescription)
               case .success(let result):
                   print(result.string)
                   completionHandler(result.string)
               }
           }
       }
   }

4. Back in the ContentView file, add the following code under the // Verify mDocs - Step 2.4: Create QRScannerView to create a new app view that the user will use to scan a QR code:

   Swift

       var codeScannerView: some View {
           QRScannerView(
               completion: { string in
                   // Verify mDocs - Step 3.3: Pass string from QR code to presentation session
                   // Verify mDocs - Step 4.5: Change isPresentingResponseView to true
               }
           )
       }

5. Add the following code under the // Verify mDocs - Step 2.5: Add Scan QR Code button to add a new button for the user to select to navigate to the new QRScannerView:

   Swift

   NavigationLink("Scan QR Code", value: "ScanQRCode")
       .font(.headline)
       .foregroundColor(.blue)
       .padding()
       .background(Color.gray.opacity(0.2))
       .cornerRadius(10)

6. Add the following code under the // Verify mDocs - Step 2.6: Add QR code view destination comment to create the logic that associates the button with the correct view:

   Swift

       case "ScanQRCode":
           codeScannerView

7. Run the app and select the Scan QR Code button. You should be navigated to the new QRScannerView where you can use the camera to scan a QR code.

Now we will build the logic that handles this QR code to establish a secure connection with the wallet application.

Exchange presentation request and response

Once the verifier has scanned the QR code presented by the wallet application, your application must retrieve the information from that QR code and use it to establish a secure connection between the verifier and holder devices.

The verifier then uses this secure connection to send a presentation request to which the holder wallet application responds with a presentation response. The SDK then verifies any mDocs included in the response and stored the verification results in a variable.

To achieve this, your application must use the SDK’s createProximityPresentationSession function that takes a string retrieved from the QR code and uses it to establish a proximity presentation session with the wallet application and initiate the presentation workflow.

1. Add the following code under the // Verify mDocs - Step 3.1: Create setupProximityPresentationSession to create a new setupProximityPresentationSession function that:

   1. Retrieves the string from the QR code.
   2. Establishes a secure connection with the wallet application by creating a proximityPresentationSession instance.
   3. Sends a presentation request by calling the sendDeviceRequest function:
   Swift

       func setupProximityPresentationSession(_ string: String) {
           Task {
               do {
                   let _ = try await mobileCredentialVerifier.createProximityPresentationSession(
                       encodedDeviceEngagementString: string,
                       onSessionTerminated: { _ in print("Session Terminated") }
                   )
                   sendDeviceRequest()
               } catch {
                   print(error.localizedDescription)
               }
           }
       }

2. Add the following code under the // Verify mDocs - Step 3.2: Create sendDeviceRequest function comment to create a new sendDeviceRequest function. This function calls the existing proximityPresentationSession instance requestMobileCredentials function, which:

   1. Accepts an array of MobileCredentialRequests.
   2. Sends the requests to the wallet application.
   3. Receives a response from the wallet application.
   4. Verifies any mDocs included in the response.
   5. Stores the verification results in the receivedDocuments variable:
   Swift

       func sendDeviceRequest() {
        Task { @MainActor in
            do {
    
                // Refresh the list of received documents
                if !receivedDocuments.isEmpty {
                    receivedDocuments = []
                }
    
                // Find the existing proximity presentation session.
                let presentationSession = try? mobileCredentialVerifier.getCurrentProximityPresentationSession()
    
                // Request mDocs
                let deviceResponse = try await presentationSession?.requestMobileCredentials(
                    request: [mobileCredentialRequest]
                )
    
                // Assign new values from the response
                receivedDocuments = deviceResponse?.credentials ?? []
                // Terminate session after response is received (optional)
                await presentationSession?.terminateSession()
            } catch {
                print(error)
                receivedDocuments = []
            }
        }
    }

3. Add the following code under the // Verify mDocs - Step 3.3: Pass string from QR code to presentation session comment to pass the string retrieved from the scanned QR code to the presentation session function:

   Swift

   viewModel.setupProximityPresentationSession(string)

Now that we have the verification results stored, you can implement different business logics to handle the results.

For this tutorial, we will only display these results to the verifier app user, individually indicating the verification status of each claim included in the request.

Display verification results

We will now create a new view that is automatically displayed when verification results are available.

1. Add the following code under the // Verify mDocs - Step 4.1: Create MobileCredentialClaimListView view comment to create a new MobileCredentialClaimListView view that parses all claims from the presented mDocs and displays them to the verifier app user:

   Swift

   struct MobileCredentialClaimListView: View {
       let claims: [MobileCredentialDataTypes.NameSpace: [MobileCredentialDataTypes.ElementID: Any]]
       var body: some View {
           Form {
               ForEach(claims.keys.sorted(), id: \.self) { namespace in
                   Section(header: Text(namespace).font(.title2)) {
                       ForEach(claims[namespace]!.sorted(by: { $0.key < $1.key }), id: \.key) { key, value in
                           HStack {
                               Text(key)
                               Spacer()
                               Text(String(describing: value))
                           }
                       }
                   }
               }
           }
       }
   }

2. Add the following code under the // Verify mDocs - Step 4.2: Create PresentationResponseView comment to create a new PresentationResponseView view that displays verified and failed claims as soon as the receivedDocuments variable is not empty:

   Swift

   struct PresentationResponseView: View {
       @Binding var receivedDocuments: [MobileCredentialPresentation]
    
       var body: some View {
           if receivedDocuments.isEmpty {
               VStack(spacing: 40) {
                   Text("Waiting for response...")
                       .font(.title3)
                   ProgressView()
                       .progressViewStyle(.circular)
                       .scaleEffect(2)
               }
           } else {
               Text("Verified claims").font(.title3.bold())
    
               ForEach(receivedDocuments, id: \.docType) { doc in
                   MobileCredentialClaimListView(claims: doc.claims ?? [:])
               }
    
               Text("Failed claims").font(.title3.bold())
               ForEach(receivedDocuments, id: \.docType) { doc in
                   MobileCredentialClaimListView(claims: doc.claimErrors ?? [:])
               }
               .padding(10)
           }
       }
   }

3. Add the following code under the // Verify mDocs - Step 4.3: Add View Response button comment to add a new View Response button that the user can use to manually navigate to the new PresentationResponseView view if required:

   Swift

   NavigationLink("View Response", value: "ViewResponse")
       .font(.headline)
       .foregroundColor(.blue)
       .padding()
       .background(Color.gray.opacity(0.2))
       .cornerRadius(10)
       .navigationTitle("Main Menu")
       .navigationBarTitleDisplayMode(.inline)
       .navigationDestination(isPresented: $isPresentingResponseView) {
           PresentationResponseView(receivedDocuments: $viewModel.receivedDocuments)
       }
       .navigationDestination(for: String.self) { value in
           switch value {
           case "CertificateManagement":
               CertificateManagementView(viewModel: CertificateManagementViewModel())
           case "ScanQRCode":
               codeScannerView
           case "ViewResponse":
               PresentationResponseView(receivedDocuments: $viewModel.receivedDocuments)
           default:
               EmptyView()
           }
       }

4. Add the following code under the // Verify mDocs - Step 4.4: Add the isPresentingResponseView variable comment to add a new isPresentingResponseView variable that is used to indicate whether or not the response view should be displayed.

   Swift

   @State private var isPresentingResponseView = false

5. Add the following code under the // Verify mDocs - Step 4.5: Change isPresentingResponseView to true comment to change the isPresentingResponseView variable to true, indicating the verifier app should navigate to the PresentationResponseView view.

   Swift

   isPresentingResponseView = true

6. Add the following code under the // Verify mDocs - Step 4.6: Add Response view destination comment to create the logic that associates the button with the correct view:

   Swift

       case "ViewResponse":
           PresentationResponseView(receivedDocuments: $viewModel.receivedDocuments)