All you need to know about uPort Identity management

13 min readFeb 6, 2019

Overview

1.1 Identity within blockchain vs Blockchain for identity

Identity within blockchain: Identity with private keys are required to interact with blockchain.

Challenges:

Key management /recovery : if you lose your private key, you lose your identity
Non-Persistent identity : having much wallets (Mist, Metamask…)
Authenticating the user / KYC
User friendly interface / UX : copying/pasting addresses, making mistake..
uPort → Blockchain for identity : The idea behind uPort is that the critical problem of keeping private keys can be bypassed by the blockchain. To do so, uPort uses the blockchain as an identity certification authority where a smart contract represents the digital identity of a user while allowing the revocation and replacement of that user’s keys.

uPort identities can take many forms: individuals, devices, entities, or institutions. Uport identities are self-sovereign, meaning they are fully owned and controlled by the creator, and don’t rely on centralized third-parties for creation or validation.

A core function of a uPort identity is that it can digitally sign and verify a claim, action, or transaction.

Challenges:

Identity ownership
Data ownership : Data are owned by companies (Google,..)
Reputation fragmentation
Password management

1.2 uPort features

Identity rooted in Ethereum Blockchain
Passwordless sign in ( Scan QR code )
Simplified user centric key management
Binding digital signatures
User reputation system
Identity verification
Browser to mobile app communication (notification from Ethereum DApps)
Private chain support
User Data Storage is Off-Chain to Combat Permanence (within the uPort mobile app) so applications cannot simply read the public blockchain to discover information about an identity. Instead, they must ask for a user’s private information directly.

The uPort Wallet application provides a simple consent interface for dapps to request private data from users, and users can approve or reject this request. This interface is called Selective Disclosure Request, and it gives users complete control over their identity data.

uPort fit very well into companies ‘verification processes of their customers’ (Know Your Customer — KYC) identity. These processes stem from compliance obligations with state laws. Authentication by uPort therefore makes it possible to register Ethereum applications in the legal requirements of the real world.

1.3 Proposed Use Cases

A self-sovereign identity system will have many use cases, here a few of them are presented:

uPort allows end-users to:

own and control their personal identity, reputation, data, and digital assets;
securely and selectively disclose their data to counterparties; access digital services without using passwords;
digitally sign claims, transactions, and documents;
control and send value on a blockchain;
interact with decentralized applications and smart contracts;
encrypt messages and data.
uPort allows enterprises to:
establish a corporate identity;
easily onboard new customers and employees;
establish an improved and transitive Know-Your-Customer process;
build secure access-controlled environments with less friction for employees;
reduce liability by not holding sensitive customer information;
increase compliance; maintain a network of vendors; establish role-specific, actor-agnostic identities (i.e. CTO) with specific permissions.

Clients

Applications that can interact with the uPort platform:

1- uPort Mobile Wallet : Secure mobile wallet for end users to create their identity, manage their data, and approve requests.

2- uPort App Manager :Web client for developers to manage the uPort identity of their applications.

3- uPort JS Client :JavaScript client for developers to interact with the uPort Platform. Can create identities, handle messages, execute signatures, and more.

Architecture

The uPort architecture includes three main elements:

Smart contracts certifying the identity of the user and containing the logic that lets the user recover their identity if their mobile device is lost
A mobile application that holds the user’s keys and lets him communicate with the smart contract (sign transaction). The key is held in the secure enclave of his device and accessed via local biometric authentication whenever the key is used to sign. The key remains on the device and there is no means of exporting the private key off the device.
Developer libraries are how third party app developers would integrate support for uPort into their apps

3.1 Smart contracts

The uPort identifier is a 20-byte hexadecimal string that acts as a globally unique, persistent identifier. This identifier is defined as the address of an Ethereum smart contract known as a Proxy contract.

The Proxy contract can relay transactions and it is through this mechanism that the identity interacts with other smart contracts on the Ethereum blockchain. When the user wants to identify and interact with a particular application smart contract, they send a transaction through the Proxy contract, via a Controller contract, which contains the main access control logic. The Proxy contract then forwards this transaction to the application smart contract.

This architecture allows the application to view the Proxy contract address as the interacting entity. The Proxy contract thus introduces a layer of indirection between the user’s private key — stored on their mobile device — and the application smart contract.

The purpose of having a Proxy contract as the core identifier is that it allows the user to replace their private key while maintaining a persistent identifier. If the user’s uPort identifier instead was the public key corresponding to their private key, they would lose control over their identifier if they were to lose the device where the private key is held.

Identity recovery : What happens if the phone is lost or broken?

In the case of device loss, uPort allows the user to associate a new public key through the intervention of a quorum of trusted people. These trusted people are user-defined and can be individuals, such as chosen friends and family members, or institutions, like banks and credit unions. They are known as recovery delegates.

User have an existing recovery network stored in his controller contract (Recovery addresses)
He get a new phone
He tells his recovery network about his new public device key
2 or 3 recovery contracts confirm his new device key to the controller contract
The controller contract updates user’s public key
The identity is recovered

The recovery delegates control a Recovery contract to specify a new user address for the Controller Contract.

Off-chain data storage :

uPort can be used for non-blockchain identity-related use cases. This is achieved by cryptographically binding an external data structure to the uPort identifier using a Registry contract. The Registry contract contains a mapping from a uPort identifier to an IPFS hash. IPFS is a decentralized system for storing, linking and transporting data. The hash guarantees the integrity of the data structure, and the cryptographic binding to the identifier is defined by smart contract access control: only the uPort proxy is authorized to update the Registry contract.

The data structure corresponding to the IPFS hash can contain profile information like Name, Profile picture, etc. It can also contain data such as public keys in order to support a decentralized public key infrastructure. The data structure used is a collection of JSON schemas. Each JSON schema can be digitally signed with a private key to create a JSON Web Token. This token can then be used as an off-chain attestation.

An attestation is a very general structure. It can be used as proof that a certain identity makes a claim about another identity. It can also be a self-signed certificate stating that a public key belongs to a specific identity. Furthermore, an attestation can be used to provide a two-way link to a service like Twitter, allowing the user to leverage their existing social network.

Selective disclosure adds a layer of privacy to uPort by allowing the user to encrypt some or all attributes by default and choose who to share the data with. The system relies on each uPort identity having a public encryption key. The disclosure of an attribute works by having the user encrypt an attribute with a symmetric encryption key. This key is then individually encrypted using the public encryption key of each identity that is allowed to read this attribute.

Once associated with a personal data storage solution, uPort will allow its users to choose which service accesses which data and possibly revoke that access at any time.

The interaction in the blockchain opens the possibility for users to cash in their data and thus at least cover transaction costs.

Smart contracts’ interactions :

Proxy Contract :

Forward an Ethereum transaction to an external address
Swap out the owner for a different one

Controller contract :

The user address can forward transactions to the Proxy Contract
The user address can relinquish control of the Proxy Contract to a new Controller Contract (timelocked*)
The user address can replace itself with a new user address (timelocked)
The recovery address can replace the user address with a new address.

* meaning they take a certain amount of time to go into effect after they are requested.

This extra security measure gives the user additional time to recover their account using the recovery address in the event they have had their key stolen, and is under attack by a malicious entity.

Registry Contract : maintain cryptographic bindings between a uPort identity and an off-chain data structure (IPFS, etc).

Recovery Quorum Contract :

A recovery delegate can sign a vote to change the user address — which goes into effect after more than half of the recovery delegates have voted for the change.
The user address can add/remove a recovery delegate (timelocked). This implies that an attacker who compromises the user’s device key can replace recovery delegates with her own and take full control over the identity. However since the interaction is timelocked, existing recovery delegates have a grace period where they can replace the user key as well as and/or block the addition and removal of recovery delegates, which would effectively thwart the attack.

IPFS hash is linking to a structure containing the user’s attributes, profile data and attestations

3.2 Mobile Application

Interacting with a dApp:

1. “Connect”: Provide the uPort identifier to the dapp. The desktop version of these apps show a QR code, and scanning this QR code with the mobile version of the app will log the user in.

2. “Verify/validate/authorize” an interaction: Signing a transaction with the private key. When the user needs to confirm an interaction with the blockchain (i.e. sign a transaction) another QR code is shown. The user scans this code and is presented by a confirmation screen where they can confirm the interaction using their fingerprint.

If a dapp is run in a mobile browser the interaction model is slightly different. Instead of displaying a QR code the dapp will instead ask to launch the uPort app. The user will then be redirected to the uPort app where they can either authorize the release of their identifier or sign a transaction. Once the action is taken the user is taken back to the mobile browser for continued interaction with the dapp.

An identity has:

An Identifier in the form of an MNID*
A signing key
A public key stored on the uPort Registry

*MNID (Multi Network Identifier) is a way to interact with multiple chains, on Ethereum or elsewhere in order to prevent monetary loss.

3.3 Librairies

uPort Connect: Enables web applications to communicate with uPort Wallet. Desktop web applications transport messages via QR codes and push notifications, while mobile web applications use applinks.
uPort Identity: Provides a library of uPort identity code including identities, identity managers, and more.
uPort Credentials: Makes it easy to generate JWT Statements, including request tokens and credentials. This is currently wrapped in the uPort JS library.
uPort JWT: Makes it easy to verify signatures against the uPort PKI. This is currently wrapped in the uPort JS library.
uPort Mobile SDK: Native mobile libraries for uPort-enabled mobile applications. Coming soon.

Central services

Chasqui (Messaging server)

Chasqui is in charge of communication from a desktop-based decentralized application frontend to and from the mobile app.

Note that the Chasqui server is not used when the decentralized application is run in a mobile browser.

Connecting steps:

A uPort user will initially connect to a dapp by scanning the “connect with uPort” QR code which contains a session ID.
The dapp frontend will then poll the Chasqui server for a uPort identifier posted to the session ID.
The mobile app will post the identifier and this is then immediately picked up by the dapp frontend.

Sending transactions’ steps :

The dapp will poll the Chasqui server for a transaction hash.
Once the transaction hash has been posted the dapp can immediately show that a transaction has been sent and update the UI accordingly.

Sensui (Fueling server)

Sensui helps new users of Ethereum overcome the initial hurdle of needing to purchase Ether to pay the fees needed to use the network. Sensui works to alleviate this problem by paying the gas fees for the user, permitting the user to create a new uPort and get up and running immediately.

The Sensui server works by utilizing the account based infrastructure of the Ethereum network. Suppose a user wants to send a transaction but they have no Ether in their sending account :

The user signs the transaction as they normally would, then sends the signed transaction to the Sensui server.
The server verifies that the sending account does not have enough Ether to pay for the gas, sends enough Ether to the account to pay the fees, and finally sends the user-signed transaction to the network.

Infura Ethereum RPC

The Ethereum RPC endpoint provider, Infura, allows uPort to communicate with the Ethereum network through the standard RPC interface that Infura provides. This allows the use of the uPort mobile app until there are mature mobile light-clients available for Ethereum.

Infura IPFS

Infura also allows the uPort mobile app to connect to an IPFS node that allows for communication with the IPFS network

Detailed workflows

Signing transactions :

Browser displays QR code with randomly generated sessionID in a URI
Browser starts polling chasqui using the sessionId to check if Mobile has posted the transaction hash.
If mobile-to-mobile, this follows the mobile interaction pattern (using URIs & JWTs instead of Chasqui shown in diagram A)
Mobile scans QR code, displays card asking the user to sign a transaction. A system dialog (Touch ID / Face ID / Device PIN) is shown in order to access the device key.
If user consents: Mobile fetches the transaction data from the URL, as well as the sessionId, then signs the transaction data with the device key.
Device sends the signed tx to sensui.uport.me. Sensui wraps the signed tx in its own transaction and sends the wrapped tx to a relay contract via rinkeby.infura.io.
Infura sends the tx hash back to Sensui, which passes it to the mobile app. Mobile posts the transaction hash to chasqui using the sessionId.
Browser grabs the transaction hash from Chasqui, removes QR code from UI, and updates UI accordingly
The relay contract confirms the original signed tx hasn’t been tampered with, then forwards the entire wrapped tx through the controller contract to the proxy.
Proxy contract forwards the tx to its intended destination, gas paid for by Sensui.

Requesting Credentials:

Browser displays QR code with URI
Browser starts polling Chasqui using the sessionId to check if Mobile has posted the address & any other info required by the 3rd party app.
Mobile scans QR code, displays card asking the user to share their address (and, optionally, other relevant data)
If user consents: Mobile grabs sessionId from URI, posts address & data to the Chasqui API using the sessionId
Browser grabs the address & data from Chasqui, removes QR code from UI

Attesting Credentials:

Browser displays a QR code (if desktop) or loads a URI that opens the uPort app (if mobile) to initiate the login / share data flow outlined in requesting credentials
After the user scans (on desktop) or consents to open the app (on mobile), the app displays a card asking the user to share their data. This will always contain the user’s address and may contain a push token as well as any other data the app chooses to request.
If user consents, mobile app posts the address (and maybe also a push token or other data) via Chasqui (if desktop) or encoded in a JWT appended to a URI (if mobile)
Browser grabs the address & data from Chasqui or the URL and removes QR code from UI.
When the app is ready to send an attestation (maybe they completed a background check, maybe the user sent funds, maybe the user shared a piece of personal data), the app encodes the relevant data in a JWT and signs it.

If push is enabled:

6a. This attestation token is sent along with the user’s push token to pututu,

7a. Pututu checks the signature in the push token against the user’s public key in IPFS, then forwards the attestation token.

8a. The user receives a push notification, which opens the app to a card asking if they want to accept the attestation.

If push is not enabled:

6b. The attestation token is encoded in a QR code (if desktop) or a URI (if mobile) and the user is told to scan or open the uPort app.

7b. After the user scans (desktop) or consents to open the app (mobile), the app displays a card asking if the user wants to accept the attestation

Weaknesses and future enhancements :

All recovery delegates of a user is publicly available on the blockchain. This could pose a security risk since an attacker could decide to attack a user’s delegates in order to compromise their identity.

The data stored temporarily on the Chasqui server is not encrypted at the moment which can be a privacy concern. The intention is to make all communications over this server end-to-end encrypted so that the server only stores encrypted information.

The Sensui server will in the future employ a more sophisticated architecture to pay fees for the user, which will involve smart contract logic built into the Controller Contract.