Connect Your SELF

The CYS (Connect Your SELF) process enables secure authentication using a challenge-response paradigm, similar to credential requests, but without requesting any credentials. Instead, the user's SELF agent receives a challenge, signs it, and returns the response to prove control over their identity.

note

Ensure that Keymaster is installed, initialized, and started as described in the Keymaster installation documentation before implementing the CYS flow.

CYS Flow Overview

1. Initiate Challenge: The relying party creates a challenge using the Keymaster SDK and provides a callback endpoint for the response.
2. User Receives Challenge: The user's SELF agent receives the challenge and signs it using their private key.
3. Submit Response: The signed challenge is sent back to the relying party via the callback endpoint.
4. Verify Response: The relying party verifies the signature to confirm the user's identity.

Key Differences from Credential Requests

• No credentials are requested or exchanged.
• The process is focused solely on authentication via challenge-response.

Examples

Refer to the code samples below for implementation details.

Create a CYS Challenge

Node.js

const challengeData = {
  challenge: {
    callback: "<YOUR_RESPONSE_API_ENDPOINT>",
  },
};

const challenge = await Keymaster.createChallenge(challengeData);
return challenge;

Java

Map<String, Object> challenge = new HashMap<>();
challenge.put("callback", "<YOUR_RESPONSE_API_ENDPOINT>");

String challengeDid = keymaster.createChallenge(challenge);
return challengeDid;

Handle, Decrypt, and Verify Challenge Response

Node.js

const verifyResponse = async (responseDID: string, options?: any) => {
  const { retries = 5, delay = 2000 } = options || {};

  const response: ChallengeResponse = await Keymaster.verifyResponse(
    responseDID,
    {
      retries,
      delay,
    }
  );
};

Java

public Map<String, Object> verifyResponse(Keymaster keymaster, String responseDID, Map<String, Object> options) {
  CreateResponseOptions verifyOptions = new CreateResponseOptions();
  verifyOptions.retries = options != null && options.get("retries") instanceof Number
      ? ((Number) options.get("retries")).intValue()
      : 5;
  verifyOptions.delay = options != null && options.get("delay") instanceof Number
      ? ((Number) options.get("delay")).intValue()
      : 2000;

  return keymaster.verifyResponse(responseDID, verifyOptions);
}

At this point you now have the DID of the user who completed the CYS flow and can grant access to the user or perform other actions based on the authenticated identity.