Permalink
Browse files

Initial work on specs for public consumtion based on internal documen…

…tation and latest code.
  • Loading branch information...
pelle committed Nov 25, 2017
0 parents commit 05f355c73f7489f5b308c246750f7ae5838d103c
@@ -0,0 +1 @@
.DS_Store
@@ -0,0 +1,54 @@
# Uport Specs
Uport is a platform for user centric identity and communication. The platform currently consists of our mobile app, ethereum smart contracts and number of open protocols for signed messages and message flow.
## Identities
An identity in Uport is really just someone or something that can sign data or transactions and also receive signed data about itself.
An identity has:
- An Identifier in the form of an [MNID](https://github.com/uport-project/mnid)
- A signing key
- A public key stored on the [Uport Registry](https://github.com/uport-project/uport-registry)
An identity can:
- Sign JWTs (JSON Web Tokens)
- Authenticate themselves to a third party
- Disclose private information about themselves
- Receive requests for disclosure about themselves
- Receive and store signed third party verifications about themselves
- Sign Ethereum transactions
### Identities created using the Uport Mobile App
Currently most Uport users manage their identities through their mobile app. Identities created today consist of an instance of the [Proxy](https://github.com/uport-project/uport-identity/blob/develop/contracts/Proxy.sol) smart contract deployed on a supported ethereum compatible blockchain.
## Request Flows
A request will typically be signed by a client app and sent to mobile app using this generic request flow:
![Generic Uport Request Flow](./flows/generic.png)
### [More about request flows]((./flows/index.md))
## Off-chain Messages
Most request and responses are performed Off-chain in a private manner between the different parties to a flow.
Most Off-chain messages consist of signed JWTs (JSON Web Tokens) as defined in [RFC 7519](https://tools.ietf.org/html/rfc7519). Signatures are verified using our simple Uport PKI (see later in this document).
### [More about Off-chain Messages]((./messages/index.md))
## On-chain Transactions
Ethereum transactions can be requested to be signed by the mobile app
## Uport PKI
Uport implements a simple yet general purpose decentralized PKI system making it easy to create and verify offchain JWT messages.
### Identity Document
### Register Identity Document
### Lookup Identity Document
@@ -0,0 +1,16 @@
@startuml
!include ../uportskin.plantuml
title Desktop Browser dApp to Uport Mobile Request Flow
participant ClientApp
participant MessagingServer
participant UportMobile
actor Owner
ClientApp -> Owner : Show QR code containing request
Owner -> UportMobile: Scans QR code
UportMobile -> Owner : Authorize Request?
Owner -> UportMobile: Allow/Disallow
UportMobile -> MessagingServer: Send response
MessagingServer -> ClientApp: Receive Response
@enduml
BIN +24.2 KB flows/desktopdapp.png
Binary file not shown.
@@ -0,0 +1,17 @@
@startuml
!include ../uportskin.plantuml
title Desktop Web Server App to Uport Mobile Request Flow
participant ClientBackEnd
participant ClientFrontEnd
participant UportMobile
actor Owner
ClientFrontEnd <- ClientBackEnd : Create Signed Request
ClientFrontEnd -> Owner : Show QR code containing request
Owner -> UportMobile: Scans QR code
UportMobile -> Owner : Authorize Request?
Owner -> UportMobile: Allow/Disallow
UportMobile -> ClientBackEnd: Send response
ClientBackEnd -> ClientFrontEnd: Handle response
@enduml
Binary file not shown.
@@ -0,0 +1,13 @@
@startuml
!include ../uportskin.plantuml
title Uport Generic Request Flow
participant ClientApp
participant UportMobile
actor Owner
ClientApp -> UportMobile : Signed Request (JWT)
UportMobile -> Owner : Authorize Request?
Owner -> UportMobile: Allow/Disallow
UportMobile -> ClientApp: Response
@enduml
BIN +17.4 KB flows/generic.png
Binary file not shown.
@@ -0,0 +1,31 @@
# Uport Request Flows
A request will typically be signed by a client app and sent to mobile app using this generic request flow:
![Generic Uport Request Flow](./generic.png)
## Specific Application flows
- [Selective Disclosure Flow](./selectivedisclosure.md)
- Send Verification Flow
- Ethereum Transaction Request Flow
## Different Request flows depending on client application type
### Mobile Request Flow
In the case of a mobile app or a web app running in a mobile web browser the request looks like this in more detail:
![Mobile Request Flow](./mobile.png)
### Desktop Browser Serverless Flow
For web apps running in a desktop browser with no server backing the flow request flow looks like this:
![Desktop Serverless App Flow](./desktopdapp.png)
### Desktop Browser Server Backed Flow
For web apps running in a desktop browser with no server backing the flow request flow looks like this:
![Desktop Server Backed Flow](./desktopserverapp.png)
@@ -0,0 +1,13 @@
@startuml
!include ../uportskin.plantuml
title Mobile App or Browser to Uport Mobile Request Flow
participant ClientApp
participant UportMobile
actor Owner
ClientApp -> UportMobile : Open URL containing request
UportMobile -> Owner : Authorize Request?
Owner -> UportMobile: Allow/Disallow
UportMobile -> ClientApp: Open URL containg callback url and Response
@enduml
BIN +20.2 KB flows/mobile.png
Binary file not shown.
@@ -0,0 +1,32 @@
# Selective Disclosure Flow
A client application can request various information from the user.
The following shows the basic flow:
![Selective Disclosure Flow](./selectivedisclosure.png)
## Endpoint
The request should be sent to one of the following URLs:
- `me.uport:me`
- `https://id.uport.me/me`
## Send Request
Create a valid signed or unsigned [Selective Disclosure Request](../messages/sharereq.md) and send it to the Uport mobile app.
Signed example:
`me.uport:me?requestToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJp...`
Unsigned example:
`me.uport:me?callback_url=https://mysite.com/callback&label=My%20Site`
## Client Callback
The client app MUST include a URL where the response is returned from the user. This can be a https url or a custom app url which receives the response.
A sucessfull response is returned as a [Selective Disclosure Response](../messages/shareresp.md) as the `access_token` param appended to a url fragment. If the callback requires the response as a HTTP POST, it is sent as a JSON POST request to the callback url instead.
@@ -0,0 +1,13 @@
@startuml
!include ../uportskin.plantuml
title Uport Selective Disclosure Flow
participant ClientApp
participant UportMobile
actor Owner
ClientApp -> UportMobile : Selective Disclosure Request
UportMobile -> Owner : Authorize Request?
Owner -> UportMobile: Allow/Disallow
UportMobile -> ClientApp: Selective Disclosure Response
@enduml
Binary file not shown.
No changes.
No changes.
@@ -0,0 +1,66 @@
# Off-chain Messages
Most request and responses are performed Off-chain in a private manner between the different parties to a flow.
## JSON Web Token
Most Off-chain messages consist of signed JWTs (JSON Web Tokens) as defined in [RFC 7519](https://tools.ietf.org/html/rfc7519).
### Requirements
We currently only support signatures using the [secp256k1 ECDSA curve](https://en.bitcoin.it/wiki/Secp256k1), which is the same as used by both Bitcoin and Ethereum.
#### JOSE Header
The [JOSE header](https://tools.ietf.org/html/rfc7519#section-5) indicates the signing algorithm used in the JWT. This MUST contain the following:
```json
{"typ": "JWT", "alg": "ES256K"}
```
#### Attributes
The JWT spec calls these claims, but we use the term claims for identity specific claims. So in this document we will call these standard JWT "claims" "attributes"
Name | Description | Required
---- | ----------- | --------
[`iss`](https://tools.ietf.org/html/rfc7519#section-4.1.1) | The [MNID](https://github.com/uport-project/mnid) of the signing identity| yes
[`sub`](https://tools.ietf.org/html/rfc7519#section-4.1.2) | The [MNID](https://github.com/uport-project/mnid) of the subject of the JWT| no
[`aud`](https://tools.ietf.org/html/rfc7519#section-4.1.3) | The [MNID](https://github.com/uport-project/mnid) or URL of the audience of the JWT. Our libraries or app will not accept any JWT that has someone else as the audience| no
[`iat`](https://tools.ietf.org/html/rfc7519#section-4.1.6) | The time of issuance | yes
[`exp`](https://tools.ietf.org/html/rfc7519#section-4.1.4) | Expiration time of JWT | no
Non Standard attributes:
Name | Description | Required
---- | ----------- | --------
`callback` | Callback URL for returning the response to a request | no
`type` | Type of Message | no
### Signature Verification
Each Uport compatible must be signed using an secp256k1 curve. The public key is resolved for the `iss` using the [Uport PKI](../pki/index.md).
## Unsigned Requests
Many apps that run 100% in the browser do not have a secure way of signing a request. Therefore we provide unsigned versions of certain requests.
### Standard Unsigned Parameters
There are certain standardized parameters that are provided using HTTP query params in the request. Some of these are based on parameters in the [OAuth 2.0 RFC 6749 Spec](https://tools.ietf.org/html/rfc6749):
Name | Description | Required
---- | ----------- | --------
`client_id` | The [MNID](https://github.com/uport-project/mnid) of the requesting identity | no
`callback_url` | The URL that receives the response | no
`callback_type` | Valid values `post` or `redirect`. Determines if callback should be sent as a HTTP POST or open the link (`redirect`). If unspecified the mobile app will attempt to pick the correct one| no
`label` | Plain text name of client to be displayed to user | no
## Message types
There are several standard message types that the Uport mobile app knows how to handle or create:
- **[Selective Disclosure Request](./sharereq.md)** for asking private data from a user
- **[Selective Disclosure Response](./shareresp.md)** signed by the app as a response to a Selective Disclosure Request
- **Verification** - signed claim by one party about another party
- **Ethereum Transaction Request**
@@ -0,0 +1,51 @@
# Selective Disclosure Request
The Selective Disclosure Request is created by a client app and sent to a users mobile app during the [Selective Disclosure Flow](../flows/selectivedisclosure.md).
The request can be either signed or unsigned.
## Endpoint
The request should be sent to one of the following URLs:
- `me.uport:me`
- `https://id.uport.me/me`
## Signed Request
A JWT using the standard [Uport JWT Requirements](./index.md) is sent to the endpoint using the `requestToken` query parameter. Eg:
`me.uport:me?requestToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJp...`
#### Attributes
The following attributes of the JWT are supported:
Name | Description | Required
---- | ----------- | --------
`type` | MUST have the value `shareReq` | yes
[`iss`](https://tools.ietf.org/html/rfc7519#section-4.1.1) | The [MNID](https://github.com/uport-project/mnid) of the signing identity| yes
[`iat`](https://tools.ietf.org/html/rfc7519#section-4.1.6) | The time of issuance | yes
[`exp`](https://tools.ietf.org/html/rfc7519#section-4.1.4) | Expiration time of JWT | no
`callback` | Callback URL for returning the response to a request | no
`net` | network id of ethereum chain of identity eg. `0x4` for `rinkeby` | no
`requested` | The self signed claims requested from a user. Array of claim types for self signed claims eg: `["name", "email"]` | no
`verified` | The verified claims requested from a user. Array of claim types for self signed claims eg: `["name", "email"]` | no
`permissions` | An array of permissions asked for. Currently only supported is `notifications` | no
## Unsigned Requests
To perform an unsigned selective disclosure request append the request parameters as URL encoded query parameters to one of the above endpoints and open it. Eg.:
`me.uport:me?callback_url=https://mysite.com/callback&label=My%20Site`
The following
Name | Description | Required
---- | ----------- | --------
`callback_url` | The URL that receives the response | yes
`callback_type` | Valid values `post` or `redirect`. Determines if callback should be sent as a HTTP POST or open the link (`redirect`). If unspecified the mobile app will attempt to pick the correct one| no
`client_id` | The [MNID](https://github.com/uport-project/mnid) of the requesting identity | no
`label` | Plain text name of client to be displayed to user | no
`network_id` | network id of ethereum chain of identity eg. `0x4` for `rinkeby` | no
@@ -0,0 +1,22 @@
# Selective Disclosure Response
The Selective Disclosure Response is created by a users mobile app as a response to a [Selective Disclosure Request](./sharereq.md) during the [Selective Disclosure Flow](../flows/selectivedisclosure.md).
The response is always signed and returned to the callback url requested in the request.
#### Attributes
The following attributes of the JWT are supported:
Name | Description | Required
---- | ----------- | --------
`type` | MUST have the value `shareResp` | yes
[`iss`](https://tools.ietf.org/html/rfc7519#section-4.1.1) | The [MNID](https://github.com/uport-project/mnid) of the signing identity| yes
[`aud`](https://tools.ietf.org/html/rfc7519#section-4.1.3) | The [MNID](https://github.com/uport-project/mnid) of the requester or the callback url if this was created as a response to an unsigned request | yes
[`iat`](https://tools.ietf.org/html/rfc7519#section-4.1.6) | The time of issuance | yes
[`exp`](https://tools.ietf.org/html/rfc7519#section-4.1.4) | Expiration time of JWT | yes
`req`| The original JWT encoded Selective Disclosure Request | yes for responses to signed requests
`nad`| The [MNID](https://github.com/uport-project/mnid) of the ethereum account requested if different from the `iss` | no
`own` | The self signed claims requested from a user. Object of claim types for self signed claims eg: `{"name":"Carol Crypteau", "email":"carol@sample.com"}` | no
`verified` | Array of requested verification JWTs | no
`capabilities` | An array of JWT tokens giving client app the permissions requested. Currently a token allowing them to send push notifications | no
@@ -0,0 +1,3 @@
# Ethereum Transaction Request
TODO
@@ -0,0 +1,3 @@
# Verifications
TODO
@@ -0,0 +1,27 @@
skinparam roundcorner 10
skinparam BoxPadding 10
skinparam headerFontColor #6959DB
skinparam headerFontSize 18
skinparam sequence {
ArrowColor #6959DB
GroupBackgroundColor #6959DB
GroupBorderColor #EDECFF
GroupHeaderFontColor #ffffff
BoxBorderColor #6959DB
BoxBackgroundColor #EDECFF
BoxPadding 10
ParticipantBorderColor #6959DB
ParticipantBackgroundColor #ffffff
ParticipantPadding 10
ActorBorderColor #6959DB
ActorBackgroundColor #ffffff
EntityBorderColor #6959DB
EntityBackgroundColor #ffffff
DatabaseBorderColor #6959DB
DatabaseBackgroundColor #ffffff
LifeLineBorderColor #878787
}

0 comments on commit 05f355c

Please sign in to comment.