Trustee Setup Protocol¶

Objective: Provide the messages and data formats so an identity owner can choose, update, remove trustees and their delegated capabilities.

Assumptions¶

An identity owner selects a connection to become a trustee
Trustees can be granted various capabilities by identity owners
1. Safeguarding a recovery share. This will be the most common
2. Revoke an authorized agent on behalf of an identity owner
3. Provision a new agent on behalf of an identity owner
4. Be an administrator for managing identity owner agents
Trustees agree to any new specified capabilities before any action is taken
Trustees will safeguard recovery shares. Their app will encrypt the share and not expose it to anyone else
Trustees authenticate out-of-band an identity owner when a recovery event occurs
The Trustees' app should only send a recovery share to an identity owner after they have been authenticated
All messages will use a standard DIDComm Envelope.

Messages and Structures¶

Messages are formatted as JSON. All binary encodings use base64url. All messages include the following fields:

version \<string>: The semantic version of the message data format.
type \<string>: The message type.

CAPABILTY_OFFER¶

Informs a connection that the identity owner wishes to make them a trustee. The message includes information about what capabilities the identity owner has chosen to grant a trustee and how long the offer is valid. This message adds the following fields

expires \<string>: 64-bit unsigned big-endian integer. The number of seconds elapsed between January 1, 1970 UTC and the time the offer will expire if no request message is received. This value is purely informative.\ capabilities \<list[string]>: A list of capabilities that the trustee will be granted. They can include

RECOVERY_SHARE: The trustee will be given a recovery share
REVOKE_AUTHZ: The trustee can revoke agents
PROVISION_AUTHZ: The trustee can provision new agents
ADMIN_AUTHZ: The trustee is an administrator of agents

{
  "version": "0.1",
  "type": "CAPABILITY_OFFER",
  "capabilities": ["RECOVERY_SHARE", "REVOKE_AUTHZ", "PROVISION_AUTHZ"]
  "expires": 1517428815
}

CAPABILTY_REQUEST¶

Sent to an identity owner in response to a TRUSTEE_OFFER message. The message includes includes information for which capabilities the trustee has agreed. This message adds the following fields

for_id \<string>: The nonce sent in the TRUSTEE_OFFER message.\ capabilities \<object[string,string]>: A name value object that contains the trustee's response for each privilege.\ authorizationKeys \<list[string]>: The public keys that the trustee will use to verify her actions with the authz policy registry on behalf of the identity owner.

{
  "version": "0.1",
  "type": "CAPABILITY_REQUEST",
  "authorizationKeys": ["Rtna123KPuQWEcxzbNMjkb"]
  "capabilities": ["RECOVERY_SHARE", "REVOKE_AUTHZ"]
}

CAPABILITY_RESPONSE¶

Sends the identity owner policy address and/or recovery data and metadata to a recovery trustee. A trustee should send a confirmation message that this message was received.

address \<string>: The identity owner's policy address. Only required if the trustee has a key in the authz policy registry.\ share \<object>: The actual recovery share data in the format given in the next section. Only required if the trustee has the RECOVERY_SHARE privilege.

{
  "version": "0.1",
  "type": "CAPABILITY_RESPONSE",
  "address": "b3AFkei98bf3R2s"
  "share": {
    ...
  }
}

TRUST_PING¶

Authenticates a party to the identity owner for out of band communication.

challenge \<object>: A message that a party should respond to so the identity owner can be authenticated. Contains a question field for the other party to answer and a list of valid_responses.

{
  "version": "0.1",
  "type": "TRUST_PING",
  "challenge": {
    ...
  }
}

challenge will look like the example below but allows for future changes as needed.\ question \<string>: The question for the other party to answer.\ valid_responses \<list[string]>: A list of valid responses that the party can give in return.

{
    "question": "Are you on a call with CULedger?",
    "valid_responses": ["Yes", "No"]
}

TRUST_PONG¶

The response message for the TRUST_PING message.

  "version": "0.1",
  "type": "TRUST_PONG",
  "answer": {
    "answerValue": "Yes"
  }

KEY_HEARTBEAT_REQUEST¶

Future_Work: Verifies a trustee/agent has and is using the public keys that were given to the identity owner. These keys

authorizationKeys \<list[string]>: Public keys the identity owner knows that belong to the trustee/agent.

{
  "version": "0.1",
  "type": "KEY_HEARTBEAT_REQUEST",
  "authorizationKeys": ["Rtna123KPuQWEcxzbNMjkb"]
}

KEY_HEARTBEAT_RESPONSE¶

Future_Work: The updated keys sent back from the trustee/agent

RECOVERY_SHARE_RESPONSE¶

Future_Work: After an identity owner receives a challenge from a trustee, an application prompts her to complete the challenge. This message contains her response.

for_id \<string>: The nonce sent in the RECOVERY_SHARE_CHALLENGE message.\ response \<object>: The response from the identity owner.

{
  "version": "0.1",
  "type": "RECOVERY_SHARE_RESPONSE",
  "response": {
    ...
  }
}

response will look like the example below but allows for future changes as needed.

{
  "pin": "3qA5h7"
}

Recovery shares are formatted in JSON with the following fields:

version \<string>: The semantic version of the recovery share data format.
source_did: The identity owner DID that sent this share to the trustee
tag \<string>: A value used to verify that all the shares are for the same secret. The identity owner compares this to every share to make sure they are the same.
shareValue \<string>: The share binary value.
hint \<object>: Hint data that contains the following fields:
1. trustees \<list[string]>: A list of all the recovery trustee names associated with this share. These names are only significant to the identity owner. Helps to aid in recovery by providing some metadata for the identity owner and the application.
2. threshold \<integer>: The minimum number of shares needed to recover the key. Helps to aid in recovery by providing some metadata for the identity owner and the application.

{
  "version": "0.1",
  "source_did": "did:sov:asbdfa32135"
  "tag": "ze4152Bsxo90",
  "shareValue": "abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ123456789"
  "hint": {
    "theshold": 3,
    "trustees": ["Mike L", "Lovesh", "Corin", "Devin", "Drummond"]
  }
}