SDK for iOS 

Introduction 

The IDEMIA Verify SDK for iOS provides customers with the resources to customize the SDK to their preferred user-experience and integrate it within an existing mobile application. The IDEMIA Mobile ID Verify App works in conjunction with the IDEMIA Mobile ID App allowing verifiers to authenticate the user's physical ID or digital credential (i.e., drivers license or identity card).

You can use the iOS SDK to:

• **Create and design your preferred user-experience and UI while leveraging the IDEMIA Verify functionalities **

  You can build a custom mobile application that implements your user-experience design and leverages all of the SDK functionalities allowing you to apply your branding and preferred user flow. Maintain complete control over the display and functionality of the application.

• **Embed IDEMIA Verify into an existing application **

  You can automatically integrate an existing mobile application with IDEMIA by adding the SDK frameworks, which removes the need to use and maintain an additional application to leverage the Mobile ID's functionalities.

Get started 

Skills required 

The integration tasks require developers to have knowledge of:

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

Resources required 

The tools required for integration on macOS are:

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

Other requirements

External Libraries

• SwCrypt: pod 'SwCrypt', '~> 5.1.3'
• SwiftCBOR: pod 'SwiftCBOR', '~> 0.4.3'
• DLParser: pod 'DLParser', '~> 3.0'

Optical Inspection Requirements

• pod 'BiometricSDK-face/Framework', '~> 4.23.1'
• pod 'BiometricSDK-face/Plugins/FaceCaptureNormal', '~> 4.23.1'
• pod 'BiometricSDK-face/Algorithms/F5_4_LOW75', '~> 4.23.1'
• pod 'IDZSwiftCommonCrypto', '~> 0.13.0',
  => true
• pod 'SwiftBytes', '~> 0.6.0'
• pod "OpenSSL-Universal", '~> 1.1.180*'

User permission 

When designing your app,consider that your iOS app must handle user permissions to protect the resources on the target mobile device. Specifically, you must verify 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 user permission are required:

• Camera permission for the QR code scan
• Bluetooth permission for the BLE data transfer

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

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

Create your own app 

If you already have access for Mi-Artifactory, download the sample app: https://mi-artifactory.otlabs.fr/artifactory/verify-sdk-ios-release/com/idemia/idverify/ios/2.3.0/Sample/2.3.0-sample-ios.zip

To create your own app, you must add the following SDK libraries to your project. You can add these libraries manually as shown in Option A, or through CocoaPods as shown in Option B.

Add SDK libraries 

The Podfile specifies the dependencies of each user target, and the SDK pods are used to declare a specific dependency. The target scopes the pod dependencies to specific targets in your Xcode project.

Required pods

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

Requirements for optical inspection only

• pod 'BiometricSDK-face/Framework', '~> 4.23.1'
• pod 'BiometricSDK-face/Plugins/FaceCaptureNormal', '~> 4.23.1'
• pod 'BiometricSDK-face/Algorithms/F5_4_LOW75', '~> 4.23.1'
• pod 'IDZSwiftCommonCrypto', '~> 0.13.0',
  => true
• pod 'SwiftBytes', '~> 0.6.0'
• pod 'OpenSSL-Universal', '~> 1.1.180'

Note: You only need to add the SDK libraries for Optical Inspection if you plan to use the Optical Inspection feature.

Option A: Import SDK manually

The manual method allows you to import the SDK files using Verify.framework using the steps below:

1. Add the Verify.framework file to your project by pasting this file in project folder at path: /verify-ios-tester-app/src/xcode/VerifyTesterApp/VerifyTesterApp/Frameworks/Verify.framework.
2. Download the Verify.framework and TesterApp 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 it on Project Settings (General > Frameworks, Libraries, and Embedded Content).

Option B: Import SDK through CocoaPods

Alternatively, the CocoaPods method allows you import the SDK files using CocoaPods (along with cocoapods-artplugin) using these steps.

1. If you don't already have CocoaPods with the Artifactory tool, install it by running the following command as shown in the snippet:

   Swift
   1gem install cocoapods-art

2. The plugin uses authentication that is specified in a standard .netrc file, as shown in the snippet:

   Swift
   1machine mi-artifactory.otlabs.fr
   2login ##USERNAME##
   3password ##PASSWORD##

3. Once set, add our repository to your CocoaPod's dependency management system as shown in the snippet:

   Swift
   1pod repo-art add verify-sdk-ios-release "https://mi-artifactory.otlabs.fr/artifactory/api/pods/verify-sdk-ios-release"

4. At the top of your project Podfile add the lines shown in the snippet:

   Swift
   1plugin 'cocoapods-art', :sources => [
   2   'verify-sdk-ios-release', # so it could resolve dependencies for Verify
   3    'master', # so it could resolve dependencies from master repo (the
   4main one)
   5    'smartsdk' # so it could resolve BiometricSDK depdendency
   6]

5. Add the Verify SDK in your Podfile in one of its pod's version, as shown in the snippet:

   Swift
   1pod 'Verify', '~> 2.3.0.910' # Verify SDK

6. Now install as shown in the snippet:

   Swift
   1pod install

   NOTE: If you are already using our repository, and you cannot resolve some dependency, try to update the specs:

   Swift
   1pod repo-art update verify-sdk-ios-release

Obtain an LKMS license 

You can skip this step if you do not intend to use the Optical Inspection feature in the Verify App.

1. Contact the IDEMIA support team to get an LKMS license for your app.

2. Scan the QR or PDF417 codes as shown in the snippet:

   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  }

3. After scanning the QR or 2D barcode successfully, you will get the result response in onSuccess as shown in the snippet:

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

4. Send a request to the Mobile ID App to get the license details as shown in the snippet.:

   Swift
   Language not specified
   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()

5. Use the sendRequest() method to return the response from the user's Mobile ID credential as shown in the snippet:

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

6. If the sendRequest() method is received successfully, then all the attributes of the Mobile ID App response will appear in the view controller as shown in the snippet:

   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. Request the callback for the sendRequest SDK API to receive and display the response data from the Mobile ID App as shown in the snippet:

   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 as shown in the snippet:

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

9. You can get the SDK version by calling it directly with the class name as shown in the snippet:

   Swift
   1IDVerifyTerminal.version

10. Added new configuration setReaderAuthInfo for reader authentication; here is a sample code snippet:

Swift
1let apiConfigs = ApiConfigs.MIDRequestBuilder()
2    .version(version: MIDParamConstants.REQUEST_VERSION)
3    .addDocType(docType: "org.iso.18013.5.1.mDL")
4    .addParams(namespaceParamList)
5    .buildDoc()
6    .setReaderAuthInfo(readerAuthSignerCallback: self.callbackReceiverVC, signingAlgo: .ALGO_SHA256WITHECDSA)
7    .withData(inputData: MOCK_QR_CODE_DATA_N1938)
8    .build()

11. Added new protocol ReaderAuthSignerCallback for reader authentication callback; here is a sample code snippet of implementation:

Swift
1extension ViewController: ReaderAuthSignerCallback {
2    func doSignItemRequest(readerAuthenticationBytes: Data, docType: String) -> ReaderAuthSign? {
3        //Generating Public Private KeyPair
4        let keyPairDict = try? ECUtils.generateKeyPair()
5        let privateKey = keyPairDict?["private"]
6
7        //Generating Signature
8        let signedDataSignature = (try? EncyptionDecryption.createSignature(privateKey: privateKey, dataToSign: readerAuthenticationBytes, algorithm: .ecdsaSignatureDigestX962SHA256)) ?? Data()
9
10        //returning Signature and Certificate
11        return ReaderAuthSign(signature: signedDataSignature, x509Certificate: x509CertSample.bytes.getData())
12        }
13}

12. Call loadCertificates() API to load IACA certificates from given path. This step is necessary for a successful transaction since Verify SDK will validate the mDL response against the certificates from supplied path.

Swift
1sharedVSDKClient?.loadCertificates(path: "CERTIFICATEDIRECTORY_NAME", responseCallback: self())
2
3    func onSuccess(response: Any?){
4        print("Certificate load success \(response)")
5    }
6
7    func onError(error: Any?){
8        print(error)
9      }

Test and production apps 

The Verify SDK allows you to create a test app with the steps below. You can also use these steps to create your production application by changing the target definition in your Podfile to your Xcode production project.

1. Open your terminal and type the command "cd project_path" (the path to the project file where .xcodeproj file is located) and press .

2. Type the command "pod init" and press .

3. Go to the finder and open the pod file (in the same place where your .xcodeproj file is located).

4. Type the following in podfile under your target. In our case, the target is VerifyIDTestApp; change it according to your target in podfile and add the snippet shown:

   Language not specified
   1target 'VerifyIDTestApp' do
   2  use_frameworks!
   3  pod 'Verify', '~> 2.3.0.910'
   4
   5  target 'VerifyIDTestAppTests' do
   6    inherit! :search_paths
   7    # Pods for testing
   8  end
   9
   10  target 'VerifyIDTestAppUITests' do
   11    # Pods for testing
   12  end

5. Type the command “pod install” and then press .

6. Open .xcworkspace (i.e., at the same place where your .xcodeproj file is located).

7. Call IDVerifyTerminal.getClient and initialize the IDVerifyTerminal shared object in the AppDelegate.swift file as shown in the snippet:

   Language not specified
   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
   6 sharedVSDKClient = IDVerifyTerminal.getClient(configs: config)

8. If you are using Optical Inspection, you must obtain an LKMS license first. Then add the following license snippet only if you are using Optical Inspection:

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

   Notes:

   • The minimum threshold for the BioTemplate authentication score (Optical Inspection use case) is 3500 by default.
   • Internet connection is required for the first time transaction of Optical Inspection for attributes retrieval. The Mobile ID credential is downloaded from the server only once, and will not be downloaded again until it is either expired or the app is reinstalled and the data is cleared.
   • By default no logs shall be visible on the logcat from the SDK.

9. Use enableDebug(true) for debugging purposes only if needed, and toggle it to false for production release as shown in the snippet:

   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)

Request parameters 

The following table provides a list of user attributes that can be called by the SDK.

Expected results 

QR code 

The following table provides a list of user attributes captured in the QR code that can be called by the SDK.

PDF417 scan 

The following table provides a list of user attributes captured in the PDF417 scan that can be called by the SDK.

Optical inspection 

Additions and updates 

isIssuingCountryMatchWithDS : check issuing_country matches with countryName element in the subject field within the DS certificate isIssuingJurisdictionMatchWithDS : check issuing_jurisdiction matches with stateOrProvinceName element in the subject field within the DS certificate

Notes:

• IDEMIA has many IACA certificates added to our SDK, so we must categorize these certificates, such as Production, Demo, UAT, in our SDK. This allows the Verify App integrator to know which certificate matches pertain to which environment at any time during a transaction.
• A certificate validation match is performed with the Mobile ID credential, and a certification tag is created for every certificate. This flag is used used in the Verify SDK to distinguish between different purposes of the certifications, leading to indicators in the Verify App results screen that some Mobile IDs credentials are “Not for Official Use”. If a certificate is not in production, then it is not meant for official use.
• A popup/updated UI on the Verify App displays whether the Mobile ID credential is applicable for official use or not, based on the matched IACA certificate. Currently, for integrators this provides additional information for IACA certificate matching.
• The classification of these SDK certificates is shown in this link: https://idemiadigitallabs.atlassian.net/wiki/spaces/MI/pages/478052581/IACA+Certificates

Error codes 

This table contains the list of data error codes, messages, descriptions, and actions required.

Test samples 

Optical inspection sample 

The following screen shows the optical inspection feature results.

PDF417 sample 

The following screen shows a PDF417 scan from the Mobile ID App or a physical driver's license.

QR + BLE sample 

The following screen shows a scan of QR code in the IDEMIA Mobile ID App.

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