BWS access schema

gistfile1.md

BWS Access Control

There are 3 tiers of access control

1. Access is controlled at the server

All requests to an existing wallet must be signed by a private key and are verified by the server. All copayers have a always valid private key, m/1/1, and can generate more with restricted access thru the grantAccess removeAccess API.

Extra access keys pairs are always derived from the extended master private key using m/1/x.

2. Tx Proposals and rejections are verified by copayers.

In order to generate a (unsigned) tx proposals and tx proposal rejections, copayers must sign them with the m/2/1 key.

This prevent the server for tampering or generating txs proposals.

Currently this key never changes, although in the future a mechanism for revoking m/2/1 in favor of m/2/x could be possible. This would need to be safely communicated to all copayers by the server.

3. TX Signatures are verified by the bitcoin network

Finally in order to generate valid outgoing transaction, the inputs signatures are needed. This are produced by keys derived from m/42/* according to BIP45.

Revoking m/42/* is not currently possible but there could be a mechanism to inform the server that certain branch is obsolete and wallet output should be created using a new one. This would be outside BIP45 scope.

Information Needed to Access a BWS Wallet

In other access any wallet functionality a copayer or agent needs:

A valid wallet's access key pair, with the appropriate access level that grant access to the function he is trying to execute

• (optional) the private key m/2/1 to sign tx proposals
• (optional) the xpriv key to sign transactions

Granting Access

If a copayer wants to grant access to an agent, he need to:

1. Generate a new access key pair at the server by using the grantAccess API call
2. Give the resulting priv key to the agent among with priv key m/2/1 (if the agent will be allowed to propose / reject txs) and xpriv key (m/42) (if it will be allowed to sign transactions). All this info should be packed in a single string for convenience: bws-agent-access:XXXXXXX

Revoking access

Currently revoking access is only possible at tier 1), buy using the revokeAccess API key. Note that migrating to a new BWS instance would revoke all outstanding extra accesses.

API

reqSigningKey = `m/1/1`; // Can't be revoked.

// extraAccesses: `m/2/x/y`;

grantAccess (index, permissionTable, name, function(err) {
});

revokeAccess (index, function(err) {
});

// Revoke all
revokeAllAccesses (function(err) {
});

// List access permission
listAccesses(function(err, accesses) {
});

// List log of access
[...]

Permission Table

 readBalance: true,
 readHistory: true,
 proposeTransactions: true,
 rejectTransactions: true,
 createAddresses: true,

or API fn names directly.

Request header

x-identity: f(pubkey)
x-signature: f(privkey, request)