Developer's Guide for iOS 

The IDEMIA Verify SDK - iOS v1.4.0 is intended for developers who want to verify mobile driver's licenses (mDL) within their mobile apps. This guide outlines the necessary steps to configure and use a minimum viable project to verify a mDL.

Prerequisites 

Skills required 

The integration tasks requires developers with knowledge of:

• iOS frameworks built in Xcode 11.0 or higher
• Swift 5.0 or higher
• macOS 10.14 or higher

External libraries required 

• SwCrypt - pod 'SwCrypt'
• SwiftCBOR - pod 'SwiftCBOR'
• DLParser - pod 'DLParser', '~> 3.0'

For optical inspection 

• Add BiometricSDK.framework
• Add BiometricSDKAlgorithmPlugin_F5_4_LOW75.framework
• pod 'IDZSwiftCommonCrypto', '~> 0.13.0',
  => true
• pod 'SwiftBytes', '~> 0.6.0'
• pod "OpenSSL-Universal",
  => 'https://github.com/krzyzanowskim/OpenSSL.git',
  => 'master'

For line code 

Download the Verify framework from the mi-artifactory: https://mi-artifactory.otlabs.fr/artifactory/verify-sdk-ios-release/com/idemia/idverify/ios/.

• Add LineCodeVerify.framework

For the Line Code SDK integration, please refer to the Line Code SDK Documentation.

Resources required 

The tools required for integration on a Macintosh are:

• Xcode 11.0 or above
• iOS SDK tools: release 11 or above (preferably latest version)
• Physical iOS device (simulator is not supported)

SDK implementation 

The required permissions in the app info.plist file are:

• Privacy - Bluetooth Always Usage Description
• Privacy - Bluetooth Peripheral Usage Description
• Privacy - Camera Usage Description

Design considerations 

User permissions 

Your iOS app must handle user permissions to protect the resources on the target mobile device. Specifically, check that the app permissions are granted by the user. If the required permissions are not granted, the SDK will throw an exception or error and may even crash.

The following permission are required:

• Camera permission: for the QR code scan

• Bluetooth permission: for BLE data transfer

How to create your own app 

To create your own app, follow the steps below.

1. Add the Verify.framework file to your project by pasting the following file in folder at path: /verify-ios-tester-app/src/xcode/VerifyTesterApp/VerifyTesterApp/Frameworks/Verify.framework.

2. Download the Verify framework and tester app from the mi-artifactory: https://mi-artifactory.otlabs.fr/artifactory/verify-sdk-ios-release/com/idemia/idverify/ios/

3. Link Verify.framework to your project by dragging and dropping on Project Settings (General > Frameworks, Libraries, and Embedded Content).

Add pods

• pod 'DLParser', '~> 3.0'
• pod 'SwCrypt'
• pod 'SwiftCBOR'
• pod 'PPpdf417', '~> 7.2.0'

For optical inspection

• Add BiometricSDK.framework
• Add BiometricSDKAlgorithmPlugin_F5_4_LOW75.framework
• pod 'IDZSwiftCommonCrypto', '~> 0.13.0',
  => true
• pod 'SwiftBytes', '~> 0.6.0'
• pod 'OpenSSL-Universal'

For line code

• Add LineCodeVerify.framework

For the IDEMIA Line Code SDK - iOS integration, please refer to the Line Code SDK Documentation.

3. Call IDVerifyTerminal.getClient and initialize the IDVerifyTerminal shared object in the AppDelegate.swift file.

   Swift
   1//Only for Optical Inspection
   2let license = BioSDKLicense(lkmsURL:serverEndpointUrl, lkmsProfileId: profileID, lkmsApiKey: apiKey)

   Note:

   • Minimum threshold for the BioTemplate authentication score (Optical Inspection use case) is 3500 by default.
   • Internet connection is required for 1st time transaction of Optical Inspection for attributes retrieval. The Mobile ID credential is downloaded from server only once and will not be downloaded again until either expired or app is reinstalled/data cleared.
   • By default no logs shall be visible on logcat from the SDK. Use enableDebug(true) for debugging purpose only if needed and toggle it to false for production release.

   Swift
   1let config = Configs.Builder()
   2    .enableDebug(isDebuggable: isDebuggable)
   3    .setBioSDKLicense(bioSDKLicense: license) //Optional: required only if you're to use Optical Inspection
   4    .build()
   5
   6sharedVSDKClient = IDVerifyTerminal.getClient(configs: config)

Obtain a LKMS license

Please contact our support team to get an LKMS license for your app. You can skip this step if your app doesn't intend to use "Optical Inspection" feature of the IDEMIA Mobile ID Verify App.

4. Scan the QR or PDF417 codes.

   Swift
   1/**
   2 * Response callback for parse engagement QR code data or PDF417 raw data from physical or **Mobile ID** credential holder
   3 */
   4  //MARK:  parsed QRCode
   5  func parsedDataForQRCode(trimmedQRCode: String){
   6      DispatchQueue.global(qos: .default).asyncAfter(deadline: .now() + 0.2) {
   7          let config = self.formAndReturnAppConfigsParamForAPI(qrString: trimmedQRCode)
   8          sharedVSDKClient?.initDeviceEngagement(apiConfig: config, responseCallback: self)
   9
   10      }
   11  }
   12
   13  //MARK:  parsed 2DBarCode
   14  func parsedDataFor2DBarCode(trimmedQRCode: String){
   15      DispatchQueue.global(qos: .default).asyncAfter(deadline: .now() + 0.2) {
   16          let config = self.formAndReturnAppConfigsParamForAPI(qrString: trimmedQRCode)
   17          sharedVSDKClient?.parsePDF417(apiConfig: config, responseCallback: self)
   18      }
   19  }
   20
   21  // Returns ApiConfigs with all the parameters
   22  func formAndReturnAppConfigsParamForAPI(qrString qr: String?) -> ApiConfigs? {
   23      guard let tempQRString = qr else {
   24          return nil
   25      }
   26      // Build app configs
   27      let apiConfigs = ApiConfigs.ConfigBuilder()
   28          .withData(inputData:tempQRString)
   29          .setAgeOverNN(age: pickedAge)
   30          .build()
   31      return apiConfigs
   32  }

5. Handle the response result after scanning the QR code or 2D barcode. After scanning the QR code successfully, you will get the result in onSuccess.

   Swift
   1func onSuccess(response: Any?){
   2  }
   3  func onError(error: VerifyError){
   4
   5  }

6. Send a request to the Mobile ID App to get the license details.

   The sendRequest() method will return the response from the user's Mobile ID credential. If it's received it successfully, then all the attributes of the Mobile ID App response appear in the view controller.

   Swift
   1// Set 'appConfig' as follows if you want to use all attributes as optional parameters
   2var dataItems = getMandatoryParams()
   3dataItems.append(contentsOf: getOptionalParams())
   4
   5let apiConfigs = AppConfigs.MIDRequestBuilder()
   6            .addParam(listParams: dataItems)
   7            .build()

   Swift
   1// Set 'appConfig' as follows if you want to use only the suggested attributes as optional parameters
   2var dataItems = getOptionalParams() let apiConfigs =
   3AppConfigs.MIDRequestBuilder() .addParam(listParams: paramsList, useDefaults:
   4true) .build()

   Swift
   1//Send the request by using `appConfig` which you set earlier
   2sharedVSDKClient?.sendRequest(apiConfig: apiConfigs, responseCallback: self)
   3}

   Swift
   1// send request using new namespace and paramList support
   2
   3func sendrequest(){
   4
   5    var aamvaParamsList = [MIDRequestParam]()
   6    var namespaceParamList = [String: [MIDRequestParam]]()
   7    var isoParamsList = [MIDRequestParam]()
   8    isoParamsList.append(MIDRequestParam(paramName: MIDParamConstants.GIVEN_NAME))
   9    isoParamsList.append(MIDRequestParam(paramName: MIDParamConstants.FAMILY_NAME))
   10    isoParamsList.append(MIDRequestParam(paramName: MIDParamConstants.RESIDENT_ADDRESS))
   11    isoParamsList.append(MIDRequestParam(paramName: MIDParamConstants.RESIDENT_CITY))
   12    isoParamsList.append(MIDRequestParam(paramName: MIDParamConstants.RESIDENT_CITY))
   13
   14    namespaceParamList[MIDParamConstants.DOCTYPE_ORG_AAMVA_US] = aamvaParamsList
   15    namespaceParamList[MIDParamConstants.NAMESPACE_18013_5 ] = isoParamsList
   16
   17    let apiConfigs = ApiConfigs.MIDRequestBuilder()
   18        .version(version: MIDParamConstants.REQUEST_VERSION)
   19        .addDocType(docType: "my.cusom.docType.custom1") //example docType1
   20
   21        //1. add
   22        .addParams(namespaceParamList)
   23        // add again to test if duplicates are removed
   24        .addParams(MIDParamConstants.NAMESPACE_18013_5,isoParamsList)
   25        //2. add more params one by one with custom namespce
   26        .addParam(MIDParamConstants.NAMESPACE_18013_5,MIDRequestParam(paramName: "custom_param1"))
   27        .addParam("my.custom.namespace",MIDRequestParam(paramName: "custom_param1"))
   28
   29        .addParam("my.custom.namespace",MIDRequestParam(paramName: "custom_param2"))
   30        .addParam("my.custom.namespace",MIDRequestParam(paramName: "custom_param3"))
   31        //duplicates will be removed
   32        .addParam("my.custom.namespace",MIDRequestParam(paramName: "custom_param1"))
   33        .addParam("my.custom.namespace",MIDRequestParam(paramName: "custom_param3"))
   34        //3. or add a custom namespace like this
   35        .addParams("my.custom.namespace2", [
   36            MIDRequestParam(paramName: "custom_param_nm21"),
   37            MIDRequestParam(paramName: "custom_param_nm22"),
   38            MIDRequestParam(paramName: "custom_param_nm23"),
   39            MIDRequestParam(paramName: "custom_param_nm21") ]//duplicate
   40    )
   41
   42        .buildDoc()  //build doctype1
   43        .addDocType(docType: "my.cusom.docType.custom2") //example docType2
   44        .addParams("my.custom.namespace2", [
   45            MIDRequestParam(paramName: "custom_param_nm21"),
   46            MIDRequestParam(paramName: "custom_param_nm22"),
   47            MIDRequestParam(paramName: "custom_param_nm23"),
   48            MIDRequestParam(paramName: "custom_param_nm21") ]//duplicate
   49    )
   50        .buildDoc() //build doctype2
   51
   52        .build()
   53
   54    //call sendRequest API
   55    sharedVSDKClient?.sendRequest(apiConfig: apiConfigs, responseCallback: self)
   56    // 3. Read request params supplied from app and make the request structure accordingly.
   57
   58}

7. Callback for the sendRequest IDEMIA Verify SDK - iOS API to receive and display the response data from the Mobile ID App.

   Swift
   1/**
   2    * Request callback for the `sendRequest` SDK API to receive and display the response data from the mDL.
   3    */
   4
   5   func onSuccess(response: Any?){
   6   }
   7   func onError(error: VerifyError){
   8   }
   9   func onRequestCanceled(response: Any?){
   10   }
   11   func onProgress(totalBytesRecived: Int){
   12   }
   13   func onRequestSent(status: Bool?){
   14   }
   15   func currentBLEStatus(currentState: TransferState){
   16   }

8. You can cancel the transaction at any time by calling the cancelRequest() method.

   Swift
   1sharedVSDKClient?.cancelRequest(responseCallback: self,cancellationReason: .CANCELED_BY_USER)

9. Get the SDK version by calling it directly with class name.

   Swift
   1IDVerifyTerminal.version

Updates and additions 

• Added optional method withImage added in ApiConfigs.ConfigBuilder for initDeviceEngagement which takes the captured device screenshot image (while scanning the compact QR code) for BioTemplate authentication
• Added optional method setBioSDKLicense is added in Configs.Builder to supply the LKMS license detail to the IDEMIA Verify SDK - iOS.
• Added model class OIDLDataModel, which encapsulates the attributes list and corresponding security checks for the Optical Inspection QR code result
• Added the new model class OpticalInspectionAuth to return security checks related to Optical Inspection.

Request parameters 

Expected results 

Expected results (PDF417 scan) 

Expected results (Optical Inspection) 

Error codes 

Test samples 

Line code sample 

Optical inspection sample 

PDF417 sample 

QR + BLE sample 

Note: The below screenshot is only for device engagement QR code testing. The full QR code + BLE scenario will only work with real device with the IDEMIA Mobile ID App.