Link Contract Instantiation Steps

XDI Connections

Version 1

October 9, 2014

Contents

Introduction

Related Specifications

Terminology

Requirements

Link Contract Instantiation Steps

Requests and Responses

Connection Request Pattern

Connection Request Response Message Pattern

Connection Invitation Request

Connection Invitation Response

Examples

Examples of How Messages Differ Based on Who Constructs Them, Who Initiates Them

Example Case 1 (RA-constructed, RA-initiated connection request):

Example Case 2 (RA-constructed, AA-initiated connection request):

Example Case 3 (AA-constructed, RA-initiated connection invitation):

Example Case 4a (AA-constructed and AA-initiated connection request to itself):

Example Case 4b (AA-constructed, AA-initiated connect invite to RA):

Using Connection Invitations, Requests and Resulting Link Contracts

RA Sends Connection request to AA

AA Writes Link Contract Instance to RA (under Requester LC authority)

Standard XDI Message Pattern After a Link Contract Has Been Instantiated (i.e., End-State)

AA Sends Connection Invitation Request to RA

Introduction

To meet the security and privacy requirements of XDI-based systems acting for different authorities, the XDI protocol enables systems to precisely describe access and usage rights to the data they control. In order for these rights to be enforced uniformly by the all XDI authorities to which they are granted, XDI authorization is described in XDI itself. This includes the ability to express any policy governing authorization and for policies to reference data, variables, relations, and other statements in the relevant XDI graphs. XDI’s primary policy building blocks are a protocol for message operations, a policy expression syntax (using Boolean constructs) and the link contract. The link contract is an access control mechanism designed to work equally well in either a centralized, or distributed (peer to peer) model.

XDI Connections are the building blocks for establishing policy-based, privileged relationships between peer graphs. Using XDI connections, peer graph authorities can request the instantiation of link contracts to enable access to other graphs. Peer authorities can also invite others to form connections with their graphs.

Related Specifications

The XDI Policy Specification defines the link contract and policy expression patterns used for XDI connections.

The XDI Bindings Specification enables both direct communications between native XDI endpoints and the conveyance of XDI messages through people’s browsers.

The XDI Message Specification enables access operations, which are evaluated against policies. Policy instantiation also requires message flows.

The XDI Cryptography Profiles Specification can be used to add integrity and auditable to XDI Policy operations.

Terminology

XDI connections relies on the following definitions and patternsfrom XDI Policy: XDI policy, authorizing authority (AA), requesting authority (RA), XDI community authority (XCA), operational policies, usage policies, conditional policy expressions, other policy variables, XDI message, link contract, link contract instance, link contract template, community link contract, requester link contract.

XDI connections defines the following additional terms:

Link contract instantiation:The process of creating a link contract instance from a template, and all preceding steps for the XDI authorities to agree on one XDI connection.

XDI connection: A uni-directional component of a relationship between two or more XDI authorities, manifested by a link contract instance. XDI connection is essentially synonymous with the term link contract.

XDI connection request: An XDI message triggering link contract instantiation, providing a template and requesting a link contract instance.

XDI connection invitation: The inverse of the connection request, in which an authority invites another to send it a connection request. In the connection invitation, the XDI authority may publishes a template it is willing to accept. If accepted, the connection invitation will result in a connection request.

XDI peer relationship: A set of related connections (TBD).

XDI connection manager: Software that end users use to create connections.

XDI service endpoint: The software controlling a peer graph, and containing an authorization manager service for link contract instantiation.

XDI user agent: The component used by a person to interact with web sites or other artifacts publishing XDI connection requests and connection invitations, e.g. connection manager UI or purpose-built API.

Requirements

XDI connections must support establishment of relationships between peer graphs. These relationships may consist of one or more uni-directional connections between two or more peer graph authorities.

XDI ConnectionsFlow Requirements

XDI connections must support the necessary protocol and behavioral building blocks to allow a flexible process of inviting, requesting, approving or pre-approving connections among multiple authorities.

Requesting connections: An entity must be able to request a connection, i.e. invoke a link contract instantiation. It must be possible for an entity create a link contract template to allow a common form of connection requests to be automatically generated for multiple parties. A connection request may also be used to pre-approve a connection request when it is received from another party. This will cause link contract instantiation to complete without manual intervention.

Inviting connections: An entity must be able to invite one or many other entities to request a connection to its graph. A connection invitation may also be used to pre-approve sending a connection request to anothergraph.

Link Contract Instantiation Requirements

XDI connections must support a flexible process of link contract instantiation that allows different kinds of access rights to graphs and different ways of establishing access; for example, access may only be needed on a one-off basis, it may need to be available only for emergencies, or it be needed persistently.

Link contract instantiation must allow for peer authorities to use the patterns defined in XDI policy to instantiate connections, or link contracts, in the following ways:

Automated approval or denial of a connection request by an AA (i.e., no user intervention required).
Manual approval or denial of a connection request by an authorizing authority (AA). User intervention is required. Either an AA or an RA needs to be able to require an explicit approval or consent by the user. Note that this might require a decision on the link contract to be deferred[DB1].
Delegated authority for approval. A typical use case would be parental approval, doctor/student, teacher/student.

Link contract instantiation also MUST allow for two types of initiation:

AA initiated. Example: user (as AA) clicks on an a XDI connect button on a web page or within an app.
RA initiated. Example: the XDI endpoint for a user’s friend (as RA) sends the user’s XDI endpoint an XDI contact request.

Link contract instantiation MUST also allow for:

The AA to store a copy of the link contract instance.
The RA to store a copy of the link contract instance.
The RA to request that the AA store a copy of the link contract instance in the RA’s graph (e.g. to manage subscriptions), which the AA can also later update.
Algorithmically determined addresses for some link contract structures, enabling them to be flexible for many usage patterns as well as portable.

Link Contract Instantiation Steps

Link contract instantiation requires the following steps:

The AA selects one or more community link contracts and writes them into its own XDI graph.
The RA selects a link contract template (or writes its own) and uses it to either:
Publish a connection request message in an artifact such as a web link or a button (for an AA initiated link contract) or
Send a connection request message directly to the XDI endpoint for an AA (for an RA initiated link contract).
The AA’s XDI endpoint approves, denies or defers to the user or the user’s delegate the RA’s connection request, and generates a connection response.
If approved, the AA writes the link contract instance to:
Its own XDI graph.
If requested, to the RA’s XDI graph under the RA’s requestor contract.

Connections requests and responses are exchanged in steps 2, 3 and 4. In steps 1 and 2 some preparation occurs where AA’s and RA’s create community link contracts, or link contract templates that will facilitate connections.

Connection Authorization

The community link contract referenced in the connection request message can be used (together with any other policy expressions the AA has created) to authorize the request.

Community link contracts may define

-Acceptable templates

-Policy expressions that can be used to automatically accept or reject requests

-AA-configurable policies, such as deferred request processing or additional policy expressions with screening criteria created by the user

A connection request can be pre-authorized by creating a connection invitation for a specific RA or any RA that matches a policy expression.

Requests and Responses

Both connection requests and invitations protocols include botha request and response message. Optionally, the AA may also initiate message to write the link contract instance created for the connection to the RA’s graph under a requester link contract. These protocols must conform to the following abstract patterns for which examples are provided at the end of this specification.

TBD: Would it make it easier for these requests to be processed in the messages contained a “message type” parameter? They are awfully hard for the human eye (and command parsers?) to decode

Connection Request Pattern

RAM-IDAA--> ## Message from RA to AA
RAM-ID$do/{$do}/TA<T-ID>{$do} ## request LC per template T-ID
RAM-ID$do/(AA/XCA)XCA<C-ID>$do ## under community LC[DB2]

Where XCA is the XDI community authority, M-ID is a message id, T-ID is a link contract template ID, and C-ID is a community link contract ID.

Note: An RA can place a connection request in a link, a UI, or API artifact so that any AA can trigger the request to itself. In such cases, the RA doesn’t know the AA identifier in advance. The RA should substitute the variable expression “{$to}” wherever “AA” appears in the above patternfor the request syntax to be used in such artifacts. The variable will be replaced with the AA’s identifier when the request is triggered.

Optional parameters:

RA<M-IDAA<signature-context> ## digital signature over message

RA<M-IDAA$expires$t/&/&/UTC-time ## request must be discarded if not done by $t

Additional operations can also be added to the connection request, for example, to retrieve the link contract instance requested, or to $get or $set data in the permitted graph once the link contract exists.

Connection Request Response Message Pattern

Desirable to return indication of

Success

Deferral

Rejected

Other error

On success return the address of the LC[DB3]

(AA/RA)T-ID$do[DB4]

On failure return

TBD[DB5]

Use of requester link contract

Note: need to determine whether this is mandatory or optional

AAM-ID-->$do/$set/(AA/RA)T-ID# authz: requester LC for AA/RR and T-ID

AAM-ID-->/$do/(RA/$from)T-ID # write the LC instance identifying the T-D

(AA/RA)T-ID/$do/operation/object-graph # write the LC instance

Connection Invitation Request

AAM-ID/$is()/(RA) # message from AA to RA

AAM-ID/$do/(RA/XCA)XCAC-ID$do # referencing community LC for the connection invitation

AAM-ID/$is$do/(AA/<XCA)XCAC-ID$do # referencing AA’s community LC for the connection request to be sent[DB6]

AAM-ID$do/$is{$do}/TAT-ID{$do} # referencing desired LC template ID[DB7]

Where XCA is the XDI community authority, M-ID is a message id, T-ID is a link contract template ID, and C-ID is a community link contract ID.

Note: An AA can place a connection invitation in a link, a UI, or API artifact so that any RA can trigger the request to itself. In such cases, the AA doesn’t know the RA identifier in advance. The AA should substitute the variable expression “{$from}” wherever “RA” appears in the above pattern for the request syntax to be used in such artifacts. The variable will be replaced with the RA’s identifier when the request is triggered.

Optional parameters:

AA<M-IDRA<signature-context> ## digital signature over message

AA<M-IDRA$expires$t/&/&/UTC-time ## invitation is not valid unless taken by $t

Connection Invitation Response

Desirable to return indication of

Deferred[DB8]

Accepted

Rejected

Other error

Examples

Examples of How Messages Differ Based on Who Constructs Them, Who Initiates Them

Message patterns vary slightly with the different scenarios from the grid above. The following examples include connect invites and connection requests, showing the directionality of the messages and the use variable substitution when required for the AA or RR identifiers.

RA-initiated / AA-initiated
RA-constructed
RA-selected? / (1) The RA user agent constructs and delivers an XDI connection request directly to AA’s XDI endpoint.
Example: Acme(RA) use their Connection Manager to request that Alice(AA) share something with them. / (2) The AA user agent obtains a copy of RA’s XDI connection request and delivers it to AA’s XDI endpoint.
Example: Alice(AA) clicks on the XDI connection request button at Acme(RA)’s website to share something with them.
AA-constructed
RA-selected? / (3) The RA user agent obtains a copy of AA’s XDI connect invite and delivers it to RA’s XDI endpoint.
Example: Alice(RA) clicks on the XDI connect invite button of Bob’s cloud card to request that Bob(AA) share something. / (4.a) The AA user agent constructs and delivers an XDI connection request directly to AA’s XDI endpoint.
Example: Alice(AA) decides to give Bob or ACME access to her graph and invokes the connection request through her connection manager to create the link contract.
OR
(4.b) The AA user agent constructs and delivers an XDI connect invite directly to RA’s XDI endpoint.
Example: Alice(AA) uses her Connection Manager to publish a connect invite intended for Bob, ACME or other parties (RAs).

Example Case 1 (RA-constructed, RA-initiated connection request):

Person invokes connection manager to send connection request to a peer (both AA and RA known in advance)

+ra[$msg]@0/$is()/(=aa) ## message from ra to aa +ra[$msg]@0/$do/(=aa/+ca)+ca#community$do ## use this community contract
+ra[$msg]@0$do/{$do}/+ta#something{$do} ## give me an LC per this template
+ra[$msg]@0<$sig&/&/"..." ## here is my signature
+ra[$msg]@0<$sig>/$is#/$sha$256$rsa$2048

---

(=aa/+ra)+ta#something$do ## Result LCI address: same for all examples

Example Case 2 (RA-constructed, AA-initiated connection request):

Person’s user agent acquires a connection request button, AA not known in advanced. {$to} used for the AA is the only difference from previous example.

+ra[$msg]@0/$is()/({$to}) ## message from ra to aa
=aa[$msg]@0/$do/(=ra/+ca)+ca#community$do ## use this community LC to RA

+ra[$msg]@0/$do/({$to}/+ca)+ca#community$do ## use this community LC to AA
+ra[$msg]@0$do/{$do}/+ta#something{$do}## variable aa - give me LC
+ra[$msg]@0<$sig&/&/"..."## here is my signature
+ra[$msg]@0<$sig>/$is#/$sha$256$rsa$2048

+ra[$msg]@1$do/$get/=aa<#email>## variable aa - give me LC

Example Case 3 (AA-constructed, RA-initiated connection invitation):

AA constructs this connection invitation, the RA user agent delivers it to the the RA endpoint. The RA’s identifier will be substituted for the $from variable

=aa[$msg]@0/$is()/({$to})## message from aa to ra
=aa[$msg]@0/$do/({$to}/+ca)+ca#community$do## use this community contract
=aa[$msg]@0/$is{$do}/+ta#something{$do} ## aa may connect under this template
=aa[$msg]@0<$sig&/&/"..." ## here is aa signature
=aa[$msg]@0<$sig>/$is#/$sha$256$rsa$2048

=aa[$msg]@1/$is$get/=aa[$card]!:uuid:1234 ## aa may connect under this template

Example Case 4a (AA-constructed and AA-initiated connection request to itself):

AA user agent constructs this connection request and delivers it to the AA endpoint, generally to grant an RA access as part of a pre-existing relationship (e.g. Forever connection pair).

=aa[$msg]@0/$is()/(=aa) ## message from aa to aa
=aa[$msg]@0/$do/(=aa/+ca)+ca#community$do ## using community contract
=aa[$msg]@0$do/{$do}/+ta#something{$do} ## create LC under this template
=aa[$msg]@0<$sig&/&/"..." ## here is my aa signature
=aa[$msg]@0<$sig>/$is#/$sha$256$rsa$2048

Example Case 4b (AA-constructed, AA-initiated connect invite to RA):

AA constructs this connect invite and delivers it to the RA endpoint.

=aa[$msg]@0/$is()/(=ra) ## message from aa to ra
=aa[$msg]@0/$do/(=ra/+ca)+ca#community$do ## I use this community contract
=aa[$msg]@0$do/$is{$do}/+ta#something{$do} ## may accept connect req through this template
=aa[$msg]@0<$sig&/&/"..." ## here is my signature
=aa[$msg]@0<$sig>/$is#/$sha$256$rsa$2048

Using Connection Invitations, Requests and Resulting Link Contracts

RA Sends Connection request to AA

This example shows a two-part XDI message where part 1 (@0 in the message collection) requests link contract instantiation and part 2 (@1 in the message collection) requests some data permissioned by that new link contract. This illustrates how a single XDI message envelope could both request a new link contract and return data authorized by that contract.

Part 1 (AA Initiated)

=ra[$msg]@0/$is()/({$to})
=ra[$msg]@0$do/{$do}/(=ra)=ra#newsletter{$do}
=ra[$msg]@0<$sig&/&/”...”
=ra[$msg]@0/$do/(=aa/+ca)+ca#community$do

Part 1 (RA Initiated)

=ra[$msg]@0/$is()/(=aa)
=ra[$msg]@0$do/{$do}/(=ra)=ra#newsletter{$do}
=ra[$msg]@0<$sig&/&/”...”
=ra[$msg]@0/$do/(=aa/+ca)+ca#community$do

Part 2: Using the Link Contract

=ra[$msg]@1/$is()/({$to})
=ra[$msg]@1$do/$get/{$to}<#email>
=ra[$msg]@1<$sig&/&/”...”
=ra[$msg]@1/$do/({$to}/=ra)=ra#newsletter$do

(=aa/+ca)(+ca#community$do$if/$true)+ca/#member/{$from}

AA Writes Link Contract Instance to RA (under Requester LC authority)

=aa[$msg]!:uuid:1234$do/$set/(=aa/=ra)=ra#newsletter$do
=aa[$msg]!:uuid:1234<$sig&/&/”...”
=aa[$msg]!:uuid:1234/$do/(=ra/$from)=ra#newsletter$do
(=aa/=ra)=ra#newsletter$do/$get/=aa<#email>

Standard XDI Message Pattern After a Link Contract Has Been Instantiated (i.e., End-State)

=ra[$msg]!:uuid:1234$/$is()/(=aa)
=ra[$msg]!:uuid:1234$do/$get/=aa<#email>
=ra[$msg]!:uuid:1234<$sig&/&/”...”
=ra[$msg]!:uuid:1234/$do/(=aa/=ra)=ra#newsletter$do

AA Sends Connection Invitation Request to RA

This is an example XDI Connection Invitation from an AA to an RA which results in the RA sending an XDI Connection request to the AA.

=aa[$msg]@0/$is()/({$to})
=aa[$msg]@0/$do/(=ra/+ca)+ca#community$do

=aa[$msg]@0/is$do/(=aa/+ca)+ca#community$do
=aa[$msg]@0$do/$is{$do}/+respect#forever{$do}
=aa[$msg]@0<$sig&/&/"..."
=aa[$msg]@0<$sig>/$is#/$sha$256$rsa$2048

The referenced link contract template could be:

+respect#forever{$do}/$get/{$to}{$card}

This will result in an XDI Connection request from the RA to the AA

=ra[$msg]@0/$is()/(=aa)
=ra[$msg]@0$do/{$do}/+respect#forever{$do}
=ra[$msg]@0<$sig&/&/"..."
=ra[$msg]@0<$sig>/$is#/$sha$256$rsa$2048

[DB1]proposal for handling this in an email from dan blum to the TC on 10/1/14

[DB2]is the community LC mandatory?

[DB3]If requester link contracts were mandatory, this is superfluous

If requester link contracts are not mandatory, this may be insufficient because RA (probably) cannot retrieve LC instance later

[DB4]General issue with response messages not binge correlated adequately (either by specified session management or by specified request id) with the requests that generated them

Another is that with some use cases, a message may be sent to an entity in response to a request message that self-delivered through a browser flow

[DB5]Error messages need to be better defined

[DB6]Temporary note: could replace $is$do with $connect$do for better readability

[DB7]Temporary note: and replace $do/$is({$do} with $do/$invite$connect

[DB8]Note that the deferred response is required because XDI does not support asynchronous messaging yet. The request / response depends on the http binding, being part of the same http connection

Same comments made for the connection request response above reply

Many issues with this