RFC - Full Wallet Lifecycle #18
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
In accordance with our RFC process, as of today this can be considered in Final Comment Period with a disposition of merge |
DavidBurkett
approved these changes
Aug 20, 2019
quentinlesceller
approved these changes
Aug 20, 2019
text/0000-full-wallet-lifecycle.md
Outdated
|
|
||
| Given that the Wallet's Owner API needs to deal with sensitive data such as passwords and seed phrases, the API will be enhanced with a new ECDH and Token-based security model, the primary goals of which are to: | ||
|
|
||
| * Ensure sensitive data such as passwords or seed phrases are always end-to-end encrypted between the client and Owner API server, regardless of what higher-level protocols are used during the exchange. |
There was a problem hiding this comment.
Missing "the" in front of Owner API server?
text/0000-full-wallet-lifecycle.md
Outdated
| * Minimize the potential for damage that can be done by a third party listening on the exchange between a wallet client and its corresponding server. | ||
| * Ensure that sensitive data such as passwords or seed phrases are not resident in server-side memory any longer than they absolutely need to be. | ||
|
|
||
| Note that this mode of operation is primarly intended for use over the JSON-RPC API, which supports many different architectural possiblities. Clients that link libraries directly and keep all sensitive data in the same process would see less benefit from this scheme, and an alternative model which doesn't encrypt any sensitive data is provided. Further, authors of existing wallets will need time to consider and/or implement the added complexity needed on the client-side to support ECDH and encryption. It's therefore proposed that the Owner API initially provide the new "SecureAPI" mode as an optional feature, with wallet authors strongly encouraged to make use of it. Support for the "InsecureAPI" model can be maintained indefinitely for directly-linked wallets, and for the JSON-RPC API until a cut-off release at some point in the future. |
There was a problem hiding this comment.
Note that this mode of operation is primarly intended
Not English native but isn't it primarily?
Also
architectural possiblities
architectural possibilities.
Missing "s" at:
It's therefore proposed that the Owner API initially provide
text/0000-full-wallet-lifecycle.md
Outdated
|
|
||
|  | ||
|
|
||
| Once `init_api_secure` is called the API will assume that subsequent API requests will be encrypted with the shared secret, and that that all subsequent API calls (other than `open_wallet`) will be accompanied with a valid encrypted token derived during the call to the `open_wallet` function. This assumption will remain until the server process exits or a call to a corresponding `close_api_secure` function is called. |
There was a problem hiding this comment.
Missing comma after "Once init_api_secure is called". Not sure about the need for a comma before the ", and that that all".
text/0000-full-wallet-lifecycle.md
Outdated
|
|
||
| ##### Legacy support | ||
|
|
||
| If `init_api_secure` is not called, the mode of operation for the JSON-RPC API will be assumed to work as currently, i.e. requests and responses are unencrypted, the wallet stores its full seed in-memory between requests and the providing of a Token with each request is not requred. However, the new lifecycle functions described in this RFC, which deal with highly sensitive data such as passwords and master keys, will not be available via the JSON-RPC API unless `init_api_secure` has been called. This setup should allow existing wallets to continue working as-is until a cutoff release for legacy mode is determined. |
There was a problem hiding this comment.
providing of a Token with each request is not requred
providing of a token with each request is not required.
text/0000-full-wallet-lifecycle.md
Outdated
|
|
||
| #### Opening a Wallet in SecureAPI Mode | ||
|
|
||
| Opening a wallet in SecureAPI mode consists of encrypting a request to `open_wallet` (which contains the wallet password) with the shared secret `s`. The request is decrypted in the JSON-RPC layer, and the password is used in the wallet backend to unlock the wallet master seed. The master seed is stored XORed against a randomly-generated token T, which is returned to the client in an encrypted response for inclusion in all further API calls. T is valid for the lifetime of the process, or until a corresponding call to `close_wallet`. |
There was a problem hiding this comment.
The request is decrypted in the JSON-RPC layer, and the password
Unnecessary comma?
process, or until a corresponding call to
close_wallet.
Same comment.
text/0000-full-wallet-lifecycle.md
Outdated
|
|
||
| ### Directly Linked Wallets | ||
|
|
||
| Wallets that link the wallet API directly will not be required to encrypt parameters, as there would be little benefit to doing so within a single process. However, for consistency they will be expected to store and supply a token to each API call. The modified workflow for a linked wallet is outlined below: |
There was a problem hiding this comment.
However, for consistency they...
However, for consistency, they...
text/0000-full-wallet-lifecycle.md
Outdated
|  | ||
|  | ||
|
|
||
| 'Legacy' support will not be provided for directly-linked wallets on release of the features described in this RFC. Is is expected wallet authors will need to update their code to store and supply the token with each request. |
There was a problem hiding this comment.
Is is expected wallet authors
It is expected wallet authors
text/0000-full-wallet-lifecycle.md
Outdated
|
|
||
| The functions as shown here are for illustrative purposes, and their signatures will change during implementation. | ||
|
|
||
| * `OwnerAPI::init_api_secure(pubkey: Secp256k1Point) -> Result<pubkey: Secp256K1Point, Error> |
There was a problem hiding this comment.
Missing ` at the end of the line.
text/0000-full-wallet-lifecycle.md
Outdated
|
|
||
| Although this document doesn't attempt to outline implementation, a few notes to consider for the implementor: | ||
|
|
||
| * Currently, the code that deals with wallet initialization and seed management sits outside the wallet APIs, in the `impls` crate, (denoting they're implementation specific). The implementation should attempt to refactor traits from these hard implementations into a new interface, similar to the existing WalletBackend and NodeClient interfaces (WalletLifecycleManager, for instance). The implementation within `impls` will then become an implementation of that trait, and can be substituted by wallet authors with their own implementations. |
There was a problem hiding this comment.
(WalletLifecycleManager, for instance)
Why comma here?
trait, and can
Same
text/0000-full-wallet-lifecycle.md
Outdated
| - The 'name' parameter is included for future use as in `open_wallet` above. | ||
| * `OwnerAPI::open_wallet(name: Option<String>, password: String) -> Result<t:Token, libwallet::Error>` | ||
| - Opens a wallet and sets it as the 'active' wallet. All further API commands will be performed against this wallet. | ||
| - 'Opens' the wallet seed in memory, stored XORd against a new token. The token is to be returned to the client for use in all further API calls. |
|
Thanks! Comments noted and doc updated. |
4 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Replaces #11 (for git reasons, conversation in previous issue is still valid)
Adds detailed description of potential security model and sequence diagrams demonstrating.
Link to rendered doc
Tracking issue: mimblewimble/grin-wallet#212