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
- Safeguarding a recovery share. This will be the most common
- Revoke an authorized agent on behalf of an identity owner
- Provision a new agent on behalf of an identity owner
- 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 Message Packaging.
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