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

Digital id verification has develop into a rising matter 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 cellular driver’s license (mDL). Via the “Confirm with Pockets” (VWW) performance, Samsung Pockets offers Android builders with the flexibility to authenticate a consumer’s id instantly from their software 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 whole technique of implementing Confirm with Pockets in an Android software.

Conditions

With a purpose to full the duties on this article and implement a whole pattern software 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 assist
3. Full the Samsung Pockets Companion onboarding course of

Understanding the Confirm with Pockets course of

Samsung Pockets presents a local Relying Occasion (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’ll be able to leverage the VWW performance inside their functions.

In your software, it’s essential create a JSON object for outlining the request and a JSON payload for the Relying Occasion card. Then, you’ll be able to make the most of the RP SDK to create a legitimate mDoc request utilizing the supplied info. Lastly, the request must be despatched to the Samsung Pockets software.

In response, Samsung Pockets sends an encrypted response again to the appliance, which incorporates the requested info in a CBOR encoded format. The applying can then decode the supplied information and use it as needed. Discuss with the ISO 18013-5 normal, AAMVA mDL pointers and the Samsung Pockets documentation for a greater understanding of the VWW course of.

Implementing the Confirm with Pockets Performance in Your Android Software

The method of implementing VWW in an Android software contains making a Relying Occasion card for Samsung Pockets, downloading and integrating the RP SDK into the Android software and implementing the required capabilities within the Android software for finishing the verification course of.

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

With a purpose to implement and use the VWW performance, you want a pockets card of the Relying Occasion kind for this function.
To create a Relying Occasion 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 Occasion.
4. Choose the relevant Service Location and Authentication Issuer from the Superior setting part. Be sure that 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 Occasion card for VWW

Integrating the RP SDK in an Android Software

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

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 Assets 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 challenge (for instance, libs).

Step 2: Add Android Manifest Permissions

To implement the Confirm with Pockets performance, the appliance wants each the Web entry permission and the flexibility to question the put in Samsung Pockets software. To supply the appliance with these permissions, open the AndroidManifest.xml file within the Android Studio challenge and add the next strains:

Step 3: Add Gradle Dependencies
Within the software’s construct.gradle file, load the RP SDK AAR file and the required 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 software.

Configuring the Android Software for Confirm with Pockets

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

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

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

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

personal val PAYLOAD = """
    {
      "card": {
        "kind": "relyingparty",
        "information": [
          {
            "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 just 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 accomplice credentials (personal key, public key, accomplice ID, card ID, certificates ID, and so forth.).

To construct the AppLink, you’ll be able to 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 Information

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 function, 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 information 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
• peak
• weight_range
• weight
• eye_colour
• hair_colour
• organ_donor
• driving_privileges
• veteran

Moreover, it is usually 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 applied")
    }

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

    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 software. We will use the beforehand created OnResponseListener class for this function.

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

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 information for constructing the encrypted session institution bytes. The gadget engagement bytes are supplied mechanically contained in the onGetMdocRequestData() operate by the RP consumer 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 concerning producing the important thing pair and constructing the session institution bytes, test the supplied 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 appliance 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 like 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 knowledge we requested, within the CBOR (Concise Binary Object Illustration) format.

For instance, if we decode the worth: “pGhkaWdlc3RJRBlvWWZyYW5kb21UbnRtdnJ5OXlucXcyZjY2bmp2NXRxZWxlbWVudElkZW50aWZpZXJqaXNzdWVfZGF0ZWxlbGVtZW50VmFsdWXAdDIwMjMtMTEtMDhUMDc6MDA6MDBa”, we discover that this CBOR object incorporates the issue_date subject and its worth is 2023-11-08T07:00:00.000Z. Equally, each worth supplied 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 factor contained within the org.iso.18013.5.1 array and returns these values in a simplified dictionary of key-value pairs. For those who want to study extra about these capabilities, you’ll be able to try the supplied pattern code.

With this step, the pattern software’s implementation of Confirm with Pockets is full. Now you can construct and run the appliance. Within the pattern software, 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 appliance will obtain the requested details about the consumer.

Determine 2: Full the verification course of utilizing VWW

Conclusion

On this article, we’ve got explored how one can combine the Confirm with Pockets RP SDK instantly into your software and use it to confirm the consumer’s id. Be at liberty to combine the RP SDK in your individual software and take a look at the Confirm with Samsung Pockets course of as properly. When you’ve got any additional queries concerning this course of, be at liberty to achieve out to us via the Samsung Builders Discussion board.

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