The DistributedIDClient class supplies all of the methods and data structures necessary for interacting with the ShoCard services.

To instantiate the DistributedIDClient class, use either of these calls, depending on whether or not you want to register a message handler at the same time:

new DistributedIdClient.Builder(ApplicationInstance applicationInstance).build();

or

new DistributedIdClient.Builder(ApplicationInstance applicationInstance, MessageHandler messageHandler).build();

Methods

updateApplicationInstance

void updateApplicationInstanceId(String tokenIdOrWebCallbackURL)

The updateApplicationInstance method is typically used by mobile applications to update the device token ID to receive push notifications, or by server applications to update the callback URL.

Parameters

Parameter Description
tokenIdOrWebCallbackURL The push token (for mobile apps), or the callback URL (for server applications).

shareData

void shareData(UUID applicationInstanceId, String message, Challenge challenge, List<Share> shares)

Use the shareData method to send data from one ShoCard application instance to another trusted ShoCard application instance.

Parameters

Parameter Description
applicationInstance The UUID for the ApplicationInstance object.
message (Optional) A string containing a brief message to be displayed to the recipient. Although there’s no specific limit on the size of the message, there is an overall limit of of 10 Mb for the entire payload (message + challenge + data).
challenge (Optional) A Challenge object to create a new session or share data without a session. An existing session can be passed on from any previous call.
data An array of Share objects. The Share object groups data and associated claims.

createSelfClaim

Claim createSelfClaim(Map<String, String> data)

Use the createSelfClaim method to create a self-asserted Claim for any personally identifiable information (PII) presented by the user. This call is intended to create a proof on behalf of the user that they own the data, have certified it for later verification, and for creation of a claim by a third party.

Parameters

Parameter Description
data A map of key and value pairs for the claim.

createClaim

Claim createClaim(UUID subjectId, String message, Challenge challenge, Map<String, String> data), Claim referenceClaim

Use the createClaim method to create a Claim for a third-party. This method takes an optional, self-asserted Claim as a reference to the applicationInstanceId for which this Claim is being created. The applicationInstanceId receiving the Claim is passed in the subjectId parameter.

Parameters

Parameter Description
subjectId The UUID for the applicationInstanceId object for which the claim is being created.
message (Optional) A string containing a brief message that’s passed to the client application. Although there’s no specific limit on the size of the message, there is an overall limit of of 10 Mb for the entire payload (message + challenge + data).
challenge (Optional) A Challenge object to create a new session or share data without a session. An existing session can be passed on from any previous call.
data A map of key and value pairs for the claim.
referenceClaim (Optional) A self-asserted Claim object to use as a reference to the applicationInstanceId object for which this claim is being created.

verifyData

void verifyData(List<Share> data)

Use the verifyData method to verify a list of Share objects. This method verifies the data read from the claims passed in the Share objects. Returns a list of DidException objects if the verification fails.

Parameters

Parameter Description
data A list of Share objects containing the claims.

requestShare

void requestShare(recipientId<Entity> toDistributed ID, Challenge challenge, List<String> requestedKeys)

Use the requestShare method to request data from another ShoCard application instance. You can pass the keys for the application in requestedKeys.

Parameters

Parameter Description
recipientId The UUID for the applicationInstanceId object for which the claim is being created.
message (Optional) A string containing a brief message that’s passed to the client application. Although there’s no specific limit on the size of the message, there is an overall limit of of 10 Mb for the entire payload (message + challenge + data).
challenge (Optional) A Challenge object to create a new session or share data without a session. An existing session can be passed on from any previous call.
requestedKeys (Optional) A list of strings containing the keys for the client application.

expireClaim

void expireClaim(ClaimReference claimReference, Instant expiryTimestamp, String message, Challenge challenge)

Use the expireClaim method to revoke or expire a claim. This method results in the notification handler being called by the client SDK (the client expireClaimReceived method).

Parameters

Parameter Description
claimReference The Claim object that’s to be revoked or expired.
expiryTimestamp An Instant object used to revoke a claim instantly (using a time before the current time).
message (Optional) A string containing a brief message that’s passed to the client application. Although there’s no specific limit on the size of the message, there is an overall limit of of 10 Mb for the entire payload (message + challenge + data).
challenge (Optional) A Challenge object to create a new session or share data without a session. An existing session can be passed on from any previous call.

processMessages

void processMessages(MessageHandler messageHandler)

or

void processMessages()

The processMessages method processes the messages sent to the client, and if specified, calls the associated MessageHandler instance. When registered mobile applications receive a push notification, call this method to handle the messages associated with the notification type.

Parameters

Parameter Description
messageHandler The MessageHandler object containing the messages to be processed.

handleShare

void handleShare(UUID senderId, String message, Challenge challenge, List<Share> share, List<DidException> errors)

Use the handleShare method when the ShoCard application instance receives a message containing some data and a claim from another ShoCard application instance. The received data will be in a secure envelope signed by the sender. The SDK will verify the data and claim in the Share objects received. If the verification fails, a list of errors will be passed in errors.

Parameters

Parameter Description
senderId The UUID for the ApplicationInstance object where the claim was sending the message.
message A string containing a brief message that’s passed to the receiving application instance. Although there’s no specific limit on the size of the message, there is an overall limit of of 10 Mb for the entire payload (message + challenge + data).
challenge (Optional) A Challenge object to create a new session or share data without a session. An existing session can be passed on from any previous call.
share A List of Share objects containing the data and claims.
errors A List of DidException objects containing the error or errors when verification of the Share objects fails.

handleClaim

void handleClaim(UUID senderId, String message, Challenge challenge, Claim claim, List<DidException> errors)

Use the handleClaim method when the notification contains a message indicating that a client created a claim for the ApplicationInstance. This method is the counterpart to the createClaim method. When the claim is created, a notification is sent to the receiving ApplicationInstance.

The SDK will verify the data in the received Claim using the public key of the issuer. It will also check if the claim has been revoked. If this verification fails, The SDK will pass the list of DidException objects in errors.

Parameters

Parameter Description
senderId The UUID of the ApplicationInstance object where the claim was created.
message A string containing a brief message that’s passed to the receiving application instance. Although there’s no specific limit on the size of the message, there is an overall limit of of 10 Mb for the entire payload (message + challenge + data).
challenge (Optional) A Challenge object to create a new session or share data without a session. An existing session can be passed on from any previous call.
claim A List of Claim objects containing the data and claims.
errors A List of DidException objects containing the error or errors when verification of the Share objects fails.

handleExpiredClaim

void handleExpiredClaim(UUID senderId, String message, Challenge challenge, ClaimReference claimReference, List<DidException> errors)

Use the handleExpiredClaim method when a notification contains a message indicating that a claim belonging to this application instance was cancelled by the application instance that created the claim. This method is the counterpart to the cancelClaim method.

When a ShoCard application instance calls the cancelClaim method, a new claim is created, cancelling an existing claim. The SDK will verify the signatures for the cancelled claim and forward the list of DidException objects in errors if verification fails.

Parameters

Parameter Description
senderId The UUID of the ApplicationInstance object where the claim was expired.
message A string containing a brief message indicating a claim was cancelled. Although there’s no specific limit on the size of the message, there is an overall limit of of 10 Mb for the entire payload (message + challenge + data).
challenge (Optional) A Challenge object to create a new session or share data without a session. An existing session can be passed on from any previous call.
claimReference A Claim object containing the data and claim.
errors A list of DidException objects containing the error or errors when verification of the Share objects fails.

handleShareRequest

void handleShareRequest(UUID senderId, String message, Challenge challenge, List<String> requestedKeys)

Use the handleShareRequest when the notification contains a message from another ShoCard application instance requesting the recipient to share data. This method is the counterpart to the requestShare method. When a sender application instance initiates a requestShare call, it converts to a shareRequestReceived call on the recipient’s end.

Parameters

Parameter Description
senderId The UUID for the ApplicationInstance object from which the message to share data is sent.
message (Optional) A string containing a brief message that’s passed to the client application. Although there’s no specific limit on the size of the message, there is an overall limit of of 10 Mb for the entire payload (message + challenge + data).
challenge (Optional) A Challenge object to create a new session or share data without a session. An existing session can be passed on from any previous call.
requestedKeys (Optional) A list of strings containing the keys for the client application.

void handleException(DIDException error)

Parameters

Parameter Description
error The DIDException object containing the error information.

Use the handleException method when the SDK is unable to retrieve a message or fails to process the retrieved message. The SDK passes the DIDException object to the sending application instance.