Verifying a Person’s Id from Your Utility Utilizing Samsung Pockets’s App2App SDK

Digital id verification has change into a rising subject within the present technological panorama. Samsung Pockets permits Samsung Galaxy gadget customers to securely register their state-issued US driver’s license of their gadget, letting them use it as a cell driver’s license (mDL). By means of the “Confirm with Pockets” (VWW) performance, Samsung Pockets supplies Android builders with the power to authenticate a consumer’s id straight from their utility by using the consumer’s registered mDL on the gadget. The implementation of the performance is predicated on and is absolutely compliant with the ISO 18013-5 normal. On this article, we discover the entire technique of implementing Confirm with Pockets in an Android utility.

Stipulations

As a way to full the duties on this article and implement a whole pattern utility for verifying a consumer’s id, you want the next:

1. Legitimate US driver’s license or state ID
2. US area Samsung Galaxy gadget with mDL help
3. Full the Samsung Pockets Associate onboarding course of

Understanding the Confirm with Pockets course of

Samsung Pockets gives a local Relying Celebration (RP) SDK for Android functions. RP SDK is an App2App SDK designed for enabling Samsung Pockets’s mDL service in on-line use circumstances. By integrating this SDK, you may leverage the VWW performance inside their functions.

In your utility, you have to create a JSON object for outlining the request and a JSON payload for the Relying Celebration card. Then, you may make the most of the RP SDK to create a legitimate mDoc request utilizing the offered info. Lastly, the request must be despatched to the Samsung Pockets utility.

In response, Samsung Pockets sends an encrypted response again to the applying, which comprises the requested info in a CBOR encoded format. The applying can then decode the offered knowledge and use it as vital. Check with the ISO 18013-5 normal, AAMVA mDL tips and the Samsung Pockets documentation for a greater understanding of the VWW course of.

Implementing the Confirm with Pockets Performance in Your Android Utility

The method of implementing VWW in an Android utility consists of making a Relying Celebration card for Samsung Pockets, downloading and integrating the RP SDK into the Android utility and implementing the mandatory features within the Android utility for finishing the verification course of.

Making a Relying Celebration Pockets Card Template within the Samsung Pockets Companions Portal

As a way to implement and use the VWW performance, you want a pockets card of the Relying Celebration kind for this goal.
To create a Relying Celebration pockets card template:

1. Go to the Samsung Pockets Companions Portal.
2. Choose Pockets Card > Create Pockets Playing cards.
3. From Pockets Card Templates, choose Relying Celebration.
4. Choose the relevant Service Location and Authentication Issuer from the Superior setting part. Ensure to pick out the right values for the cardboard, in any other case the verification course of might not work.

Determine 1: Making a Relying Celebration card for VWW

Integrating the RP SDK in an Android Utility

As soon as the Relying Celebration card template has been created, we are able to obtain and combine the RP SDK to work with the Android utility.

Step 1: Obtain the RP SDK for Android
To obtain the RP SDK:

1. Obtain the ZIP file containing the most recent RP SDK launch AAR file from Samsung Pockets Code Sources on the Samsung Developer web site.
2. Extract the AAR file from the downloaded ZIP file.
3. Copy and paste the downloaded rp-sdk-x.xx-release.aar file inside a brand new listing within the Android Studio venture (for instance, libs).

Step 2: Add Android Manifest Permissions

To implement the Confirm with Pockets performance, the applying wants each the Web entry permission and the power to question the put in Samsung Pockets utility. To offer the applying with these permissions, open the AndroidManifest.xml file within the Android Studio venture and add the next strains:

Step 3: Add Gradle Dependencies
Within the utility’s construct.gradle file, load the RP SDK AAR file and the mandatory extra dependencies for utilizing the SDK, as follows:

// Load RP SDK AAR file
implementation(information("libs/rp-sdk-1.05-release.aar"))

//CBOR decoding dependencies
implementation("com.upokecenter:cbor:4.0.1")
implementation("com.augustcellars.cose:cose-java:1.1.0")

// Different dependencies
implementation("com.google.code.gson:gson:2.11.0")
implementation("org.bouncycastle:bcprov-jdk15to18:1.66")
implementation("com.nimbusds:nimbus-jose-jwt:9.37.3")
implementation("io.reactivex.rxjava2:rxjava:2.2.21")
implementation("io.reactivex.rxjava2:rxkotlin:2.4.0")
implementation("io.reactivex.rxjava2:rxandroid:2.1.1")
implementation("com.squareup.okhttp3:okhttp:4.11.0")

After these steps, the RP SDK is prepared to be used in your Android utility.

Configuring the Android Utility for Confirm with Pockets

Subsequent, we have to full the implementation of the Confirm with Pockets performance in your Android utility.

Step 1: Construct a Card Payload for the Relying Celebration Card

First, we have to create a request payload for the Relying Celebration card following the specification.

personal enjoyable buildApp2AppPayload(): String {
    return PAYLOAD
        .substitute("{refId}", UUID.randomUUID().toString())
        .substitute("{createdAt}", System.currentTimeMillis().toString())
        .substitute("{updatedAt}", System.currentTimeMillis().toString())
}

personal val PAYLOAD = """
    {
      "card": {
        "kind": "relyingparty",
        "knowledge": [
          {
            "createdAt": {createdAt},
            "updatedAt": {updatedAt},
            "language": "en",
            "refId": "{refId}",
            "attributes": {
              "clientPackageName": "com.ahsan.verifyappsample",
              "clientType": "app",
              "fontColor": "#ffffff",
              "logoImage": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png",
              "logoImage.darkUrl": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png",
              "logoImage.lightUrl": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png",
              "providerName": "Samsung Verification Sample"
            }
          }
        ]
      }
    }
""".trimIndent()

Step 2: Construct the AppLink

The AppLink is a tokenized URL that’s much like the CData tokens used for Samsung Pockets playing cards. The Samsung Pockets RP SDK features a operate to generate the AppLink utilizing the payload and the associate credentials (personal key, public key, associate ID, card ID, certificates ID, and so on.).

To construct the AppLink, you may merely name the rpClientApis.buildAppLink() operate with the required parameters:

val rpClientApis = RpClientApis(this)

val appLink = rpClientApis.buildAppLink(
    partnerId = PARTNER_ID,
    cardId = CARD_ID,
    payload = buildApp2AppPayload(),
    samsungPublicKey = SAMSUNG_CERTIFICATE,
    partnerPublicKey = PARTNER_CERTIFICATE,
    partnerPrivateKey = PARTNER_PRIVATE_KEY,
    partnerCertificateId = CERTIFICATE_ID,
    isStagingServer = true
)

Step 3: Construct the Request Knowledge

Lastly, as soon as the AppLink creation is full, we are able to ship the verification request utilizing the RP SDK.

Earlier than sending the request, we have to specify precisely which info we want to retrieve. For this goal, we have to create a JSON doc following the ISO 18013-5 specification and specify the fields we want to retrieve within the response. It’s attainable to request for the next fields within the request knowledge below the “org.iso.18013.5.1” namespace:

• portrait
• family_name
• given_name
• document_number
• age_in_years
• resident_address
• birth_date
• issue_date
• expiry_date
• intercourse
• top
• weight_range
• weight
• eye_colour
• hair_colour
• organ_donor
• driving_privileges
• veteran

Moreover, it’s also attainable to request for the next 3 fields, below the “org.iso.18013.5.1.aamva” namespace:

• domestic_driving_privileges
• DHS_compliance
• EDL_credential

In our instance, we solely attempt to retrieve the next 4 fields: family_name, age_in_years, issue_date, and expiry_date. Within the following code instance, we construct the request string accordingly:

val requestData = """
    {
      "docType": "org.iso.18013.5.1.mDL",
      "nameSpaces": {
        "org.iso.18013.5.1": {
          "family_name": true,
          "age_in_years": true,
          "issue_date": true,
          "expiry_date": true
        }
      }
    }
""".trimIndent()

Step 4: Create the OnResponseListener Class

When utilizing the VWW RP SDK, it’s essential to create a listener class for each sending the request and for receiving and processing the response from the mDoc server.
For our instance, let’s create an empty placeholder OnResponseListener class which extends the RP SDK’s OnResponseListener class.

class OnResponseListener(personal val requestData: String)
: RpClientApis.OnResponseListener{
    override enjoyable onGetMdocRequestData(deviceEngagementBytes: ByteArray): ByteArray? {
        TODO("Not but carried out")
    }

    override enjoyable onMdocResponse(encryptedResponseBytes: ByteArray) {
        TODO("Not but carried out")
    }

    override enjoyable onMdocResponseFailed(exception: Exception) {
        Log.e(TAG, "Response processing failed", exception)
    }
}

Initiating the Verification Request

To provoke the id verification course of, we have to set up a safe session and ship a structured request to the Samsung Pockets utility. We will use the beforehand created OnResponseListener class for this goal.

Step 1: Outline the onGetMdocRequestData() Operate for Sending the Request Knowledge

Contained in the onGetMdocRequestData() operate, we have to do 2 issues for establishing a safe encrypted session:

1. Generate an elliptic curve key pair
2. Construct session institution bytes following the ISO-18013-5 specification.

As soon as the important thing pair is generated, we are able to use this key pair, the gadget engagement bytes, and the beforehand created request knowledge for constructing the encrypted session institution bytes. The gadget engagement bytes are offered routinely contained in the onGetMdocRequestData() operate by the RP shopper SDK.

personal val secureRepository = SecureRepository()

override enjoyable onGetMdocRequestData(deviceEngagementBytes: ByteArray): ByteArray? {
    val keyPair = secureRepository.generateEcKeyPair()
    val encryptedSessionEstablishmentBytes = secureRepository.buildSessionEstablishment(requestData, deviceEngagementBytes, keyPair)
    return encryptedSessionEstablishmentBytes!!
}

For additional info relating to producing the important thing pair and constructing the session institution bytes, verify the offered pattern code.

Step 2: Provoke a Verification Request with the AppLink

As soon as the onGetMdocRequestData() operate is prepared, we are able to use the request() operate to provoke the verification request.

val sessionId = UUID.randomUUID().toString()
val WALLET_PACKAGE = "com.samsung.android.spay"

rpClientApis.request(
    WALLET_PACKAGE,
    sessionId,
    appLink,
    OnResponseListener(requestData)
)

Processing the Request Response

As soon as the mDoc request has been despatched and processed efficiently, the applying ought to obtain a ByteArray as response within the onMdocResponse() operate contained in the listener class. This ByteArray is an encrypted JSON object. As soon as decrypted, the response ought to appear to be the next:

{
  "paperwork": [
    {
      "issuerSigned": {
        "nameSpaces": {
          "org.iso.18013.5.1": [
            "pGhkaWdlc3RJRBkU-mZyYW5kb21UaGNkNGduZDl5Z2I1cTRjaDV4ZnpxZWxlbWVudElkZW50aWZpZXJrZXhwaXJ5X2RhdGVsZWxlbWVudFZhbHVlwHQyMDMxLTExLTIxVDA3OjAwOjAwWg",
            "pGhkaWdlc3RJRBknbWZyYW5kb21Udjg1NmsydzIzZzQ3OHk5cTQ0aHJxZWxlbWVudElkZW50aWZpZXJsYWdlX2luX3llYXJzbGVsZW1lbnRWYWx1ZRgr",
            "pGhkaWdlc3RJRBlvWWZyYW5kb21UbnRtdnJ5OXlucXcyZjY2bmp2NXRxZWxlbWVudElkZW50aWZpZXJqaXNzdWVfZGF0ZWxlbGVtZW50VmFsdWXAdDIwMjMtMTEtMDhUMDc6MDA6MDBa",
            "pGhkaWdlc3RJRBnXQWZyYW5kb21UOXJqd2NydjZ6cXpqZm1xajNkcnhxZWxlbWVudElkZW50aWZpZXJrZmFtaWx5X25hbWVsZWxlbWVudFZhbHVlZUFoc2Fu"
          ]
        },
        "issuerAuth": [
          "dCBa",
          {
            "33": "..."
          },
          "...",
          "..."
        ]
      },
      "deviceSigned": {…},
      "docType": "org.iso.18013.5.1.mDL"
    }
  ],
  "model": "1.0",
  "standing": 0
}

The values contained in the org.iso.18013.5.1 JSON Array are the data we requested, within the CBOR (Concise Binary Object Illustration) format.

For instance, if we decode the worth: “pGhkaWdlc3RJRBlvWWZyYW5kb21UbnRtdnJ5OXlucXcyZjY2bmp2NXRxZWxlbWVudElkZW50aWZpZXJqaXNzdWVfZGF0ZWxlbGVtZW50VmFsdWXAdDIwMjMtMTEtMDhUMDc6MDA6MDBa”, we discover that this CBOR object comprises the issue_date discipline and its worth is 2023-11-08T07:00:00.000Z. Equally, each worth offered within the array is a CBOR object that may be decoded utilizing CBOR decoders to discover a key-value pair containing the requested info.

We will now obtain the mDoc response within the onMdocResponse() operate and decode it to retrieve the ultimate requested values:

override enjoyable onMdocResponse(encryptedResponseBytes: ByteArray) {
    val plainResponse = secureRepository.decryptMdocResponse(encryptedResponseBytes)
    Log.i(TAG, "plainResponse=${plainResponse?.toPrettyJson()}")
    val mDocContent = Mdoc18013Utils.parseMdocResponse(plainResponse!!)
    mDocContent.forEach { (key, worth) ->
        Log.i(TAG, "$key: $worth")
    }
}

Right here, secureRepository.decryptMdocResponse() performs the decryption operation and converts the encrypted bytes right into a plain JSON response. Afterwards, the Mdoc18013Utils.parseMdocResponse() operate takes the plain response and decodes every CBOR-encoded component contained within the org.iso.18013.5.1 array and returns these values in a simplified dictionary of key-value pairs. When you want to study extra about these features, you may take a look at the offered pattern code.

With this step, the pattern utility’s implementation of Confirm with Pockets is full. Now you can construct and run the applying. Within the pattern utility, as soon as the consumer clicks the “Confirm with Samsung Pockets” button, the VWW process is initiated. As soon as the consumer confirms that they want to share their info, the applying will obtain the requested details about the consumer.

Determine 2: Full the verification course of utilizing VWW

Conclusion

On this article, we’ve explored how one can combine the Confirm with Pockets RP SDK straight into your utility and use it to confirm the consumer’s id. Be happy to combine the RP SDK in your personal utility and check the Confirm with Samsung Pockets course of as effectively. When you have any additional queries relating to this course of, be at liberty to achieve out to us by the Samsung Builders Discussion board.

1. ISO/IEC 18013-5:2021 – Private identification — ISO-compliant driving licence — Half 5: Cellular driving licence (mDL) utility
2. Cellular Driver License – American Affiliation of Motor Automobile Directors – AAMVA
3. RP SDK obtain hyperlink
4. Confirm with Pockets API Tips
5. Relying Celebration Card Specs
6. Pattern Code Obtain Hyperlink