We supply the Ping wallet app, a native app for iOS and Android devices, as a reference wallet app. Service endpoints, however, must be built and customized by issuers. A common way to build these services is by embedding the PingOne for Individuals Server SDK (Java) in a service. This enables the service to participate in our Personal Identity framework, and interact with compatible wallet apps that implements our SDK interfaces.

Such compatible wallet apps utilizes our PingOne for Individuals Server SDK, just as a service endpoint might, though designed for native mobile applications.

PingOne for Individuals Server SDK overview

PingOne for Individuals Server SDK flow between endpoint web service, PingOne, and a mobile device

Implemented in a service endpoint, the PingOne for Individuals Server SDK enables a service to create a QR code with instructions for a compatible wallet app to scan, and establish communications with the service. The QR code includes a unique shocardID that identifies the service that created the QR Code. You’ll use the shocardID to establish encrypted data communication. The QR code can also include other data, such as a request for information. This data is contained in a JSON structure. Each QR code also maintains a unique ss_id, a challenge request created by the server that must be signed by the compatible wallet app to establish a communication session. The server can then index a receiving request using the supplied ss_id.

After the compatible wallet app scans the QR code, it can create a secure envelope on the device that includes the ss_id, the requested information, and the compatible wallet app’s own shocardID. This data is then signed by the private key of the mobile device user in the compatible wallet app, and encrypted with the public key of the service. The PingOne for Individuals Server SDK supplies the interfaces to the Personal Identity platform to retrieve the registered public key for any valid shocardID presented.

The ID Routing service receives the secure envelope, although it is unable to view any of the content. However, it does have the shocardID of the recipient, in this case, the service endpoint. The ID Routing service routes the encrypted packet to the service endpoint, and the service uses the PingOne for Individuals Server SDK to decrypt and validate the content of the secure envelope, and its recipient. The service can then process the information it received.

All communication between any two applications is done in a manner similar to this, and remember, an application can be a compatible wallet app or a service endpoint.

Creating verifiable credentials

When a service receives user information from a compatible wallet app, it can store the user’s shocardID for future reference and communication. The service sends messages using the user’s shocardID through the PingOne for Individuals Server SDK. The messages are routed using the ID Routing service, and sent to the wallet app using push notifications. The ID Routing service also maintains a mailbox of messages, so even if a push notification is not received by the app (or ignored), when the user returns to the app, the messages can be retrieved and processed.

PingOne for Individuals verifiable credential examples

The service endpoint can create any credential it finds appropriate for the user. Each credential can contain a graphic display in SVG format, along with any set of key-value pairs. For example, a bank may issue a credential to a user that contains the following information:

bankName = “bxFinance”
accountNumber = “123456789accountCreateDate = “June 21, 2021accountType = “checking”

The service endpoint can then create a certification of this credential data using the PingOne for Individuals Server SDK. Using this process, a verifiable claim is created. In the PingOne for Individuals Server SDK, the key is hashed along with a salt. The value is also hashed with a different salt, and signed with the private key of the service endpoint maintained in the PingOne for Individuals Server SDK. This is repeated for all four key-value pairs in the example above, and placed in a JSON structure. The JSON is also hashed and signed using the same private key. The resulting structure along with the signature is hashed, and then sent to the ID Registration service so it can be registered in a smart contract on the blockchain.

The ID Registration service acts as a proxy to create the smart contract for the user authorized by the user’s private key signing the claim. This smart contract is maintained in the blockchain.

Using the ID Routing service, the PingOne for Individuals Server SDK on the service endpoint then sends back to the user in a secure envelope:

Using a compatible wallet app on their mobile device, the user can now share with any other application or service this new credential (or any individual key-value pairs), along with the verifiable proof of the information received from the service endpoint.

Code samples

You’ll find a current PingOne for Individuals Server SDK code sample at https://github.com/pingidentity/pingone-for-individuals-server-sdk.