docs: ongoing organization
This commit is contained in:
Zach Ramsay
Ethan Buchman
parent
ef65ff7b22
commit
670f833233
|
|
@ -1,96 +0,0 @@
|
|||
## Design Document
|
||||
|
||||
### Object-Capability Model
|
||||
|
||||
When thinking about security, it's good to start with a specific threat model. Our threat model is the following:
|
||||
|
||||
> We want to assume a thriving ecosystem of Cosmos-SDK modules that are easy to compose into a blockchain application. Some of these modules will be faulty or malicious.
|
||||
|
||||
The Cosmos-SDK is designed to address this threat by being the foundation of an object capability system.
|
||||
|
||||
```
|
||||
The structural properties of object capability systems favor
|
||||
modularity in code design and ensure reliable encapsulation in
|
||||
code implementation.
|
||||
|
||||
These structural properties facilitate the analysis of some
|
||||
security properties of an object-capability program or operating
|
||||
system. Some of these — in particular, information flow properties
|
||||
— can be analyzed at the level of object references and
|
||||
connectivity, independent of any knowledge or analysis of the code
|
||||
that determines the behavior of the objects. As a consequence,
|
||||
these security properties can be established and maintained in the
|
||||
presence of new objects that contain unknown and possibly
|
||||
malicious code.
|
||||
|
||||
These structural properties stem from the two rules governing
|
||||
access to existing objects:
|
||||
|
||||
1) An object A can send a message to B only if object A holds a
|
||||
reference to B.
|
||||
|
||||
2) An object A can obtain a reference to C only
|
||||
if object A receives a message containing a reference to C. As a
|
||||
consequence of these two rules, an object can obtain a reference
|
||||
to another object only through a preexisting chain of references.
|
||||
In short, "Only connectivity begets connectivity."
|
||||
|
||||
- https://en.wikipedia.org/wiki/Object-capability_model
|
||||
```
|
||||
|
||||
Strictly speaking, Golang does not implement object capabilities completely, because of several issues:
|
||||
|
||||
* pervasive ability to import primitive modules (e.g. "unsafe", "os")
|
||||
* pervasive ability to override module vars https://github.com/golang/go/issues/23161
|
||||
* data-race vulnerability where 2+ goroutines can create illegal interface values
|
||||
|
||||
The first is easy to catch by auditing imports and using a proper dependency version control system like Glide. The second and third are unfortunate but it can be audited with some cost.
|
||||
|
||||
Perhaps [Go2 will implement the object capability model](https://github.com/golang/go/issues/23157).
|
||||
|
||||
### What does it look like?
|
||||
|
||||
Only reveal what is necessary to get the work done.
|
||||
|
||||
For example, the following code snippet violates the object capabilities principle:
|
||||
|
||||
```golang
|
||||
type AppAccount struct {...}
|
||||
var account := &AppAccount{
|
||||
Address: pub.Address(),
|
||||
Coins: sdk.Coins{{"ATM", 100}},
|
||||
}
|
||||
var sumValue := externalModule.ComputeSumValue(account)
|
||||
```
|
||||
|
||||
The method "ComputeSumValue" implies a pure function, yet the implied capability of accepting a pointer value is the capability to modify that value. The preferred method signature should take a copy instead.
|
||||
|
||||
```golang
|
||||
var sumValue := externalModule.ComputeSumValue(*account)
|
||||
```
|
||||
|
||||
In the Cosmos SDK, you can see the application of this principle in the basecoin examples folder.
|
||||
|
||||
```golang
|
||||
// File: cosmos-sdk/examples/basecoin/app/init_handlers.go
|
||||
package app
|
||||
|
||||
import (
|
||||
"github.com/cosmos/cosmos-sdk/x/bank"
|
||||
"github.com/cosmos/cosmos-sdk/x/sketchy"
|
||||
)
|
||||
|
||||
func (app *BasecoinApp) initRouterHandlers() {
|
||||
|
||||
// All handlers must be added here.
|
||||
// The order matters.
|
||||
app.router.AddRoute("bank", bank.NewHandler(app.accountMapper))
|
||||
app.router.AddRoute("sketchy", sketchy.NewHandler())
|
||||
}
|
||||
```
|
||||
|
||||
In the Basecoin example, the sketchy handler isn't provided an account mapper, which does provide the bank handler with the capability (in conjunction with the context of a transaction run).
|
||||
|
||||
### More Resources
|
||||
|
||||
* Read the [Cosmos SDK Guide](./guide.md).
|
||||
|
|
@ -19,7 +19,6 @@ SDK
|
|||
|
||||
sdk/overview.rst
|
||||
sdk/install.rst
|
||||
sdk/key-management.rst
|
||||
sdk/roles-and-multi-sig.rst
|
||||
|
||||
Basecoin
|
||||
|
|
@ -40,6 +39,7 @@ Staking Module
|
|||
:maxdepth: 2
|
||||
|
||||
staking/intro.rst
|
||||
staking/key-management.rst
|
||||
staking/local-testnet.rst
|
||||
staking/public-testnet.rst
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,206 @@
|
|||
Key Management
|
||||
==============
|
||||
|
||||
Here we explain a bit how to work with your keys, using the
|
||||
``basecli keys`` subcommand. Note that because ``basecli`` is
|
||||
an implementation of the Cosmmos SDK, other implementations, such
|
||||
as ``gaia`` will have a compatible set of tooling.
|
||||
|
||||
**Note:** This keys tooling is not considered production ready and is
|
||||
for dev only.
|
||||
|
||||
We'll look at what you can do using the six sub-commands of
|
||||
``basecli keys``:
|
||||
|
||||
::
|
||||
|
||||
new
|
||||
list
|
||||
get
|
||||
delete
|
||||
recover
|
||||
update
|
||||
|
||||
Create keys
|
||||
-----------
|
||||
|
||||
``basecli keys new`` has two inputs (name, password) and two outputs
|
||||
(address, seed).
|
||||
|
||||
First, we name our key:
|
||||
|
||||
.. code:: shelldown
|
||||
|
||||
basecli keys new alice
|
||||
|
||||
This will prompt (10 character minimum) password entry which must be
|
||||
re-typed. You'll see:
|
||||
|
||||
::
|
||||
|
||||
Enter a passphrase:
|
||||
Repeat the passphrase:
|
||||
alice A159C96AE911F68913E715ED889D211C02EC7D70
|
||||
**Important** write this seed phrase in a safe place.
|
||||
It is the only way to recover your account if you ever forget your password.
|
||||
|
||||
pelican amateur empower assist awkward claim brave process cliff save album pigeon intact asset
|
||||
|
||||
which shows the address of your key named ``alice``, and its recovery
|
||||
seed. We'll use these shortly.
|
||||
|
||||
Adding the ``--output json`` flag to the above command would give this
|
||||
output:
|
||||
|
||||
::
|
||||
|
||||
Enter a passphrase:
|
||||
Repeat the passphrase:
|
||||
{
|
||||
"key": {
|
||||
"name": "alice",
|
||||
"address": "A159C96AE911F68913E715ED889D211C02EC7D70",
|
||||
"pubkey": {
|
||||
"type": "ed25519",
|
||||
"data": "4BF22554B0F0BF2181187E5E5456E3BF3D96DB4C416A91F07F03A9C36F712B77"
|
||||
}
|
||||
},
|
||||
"seed": "pelican amateur empower assist awkward claim brave process cliff save album pigeon intact asset"
|
||||
}
|
||||
|
||||
To avoid the prompt, it's possible to pipe the password into the
|
||||
command, e.g.:
|
||||
|
||||
::
|
||||
|
||||
echo 1234567890 | basecli keys new fred --output json
|
||||
|
||||
After trying each of the three ways to create a key, look at them, use:
|
||||
|
||||
::
|
||||
|
||||
basecli keys list
|
||||
|
||||
to list all the keys:
|
||||
|
||||
::
|
||||
|
||||
All keys:
|
||||
alice 6FEA9C99E2565B44FCC3C539A293A1378CDA7609
|
||||
bob A159C96AE911F68913E715ED889D211C02EC7D70
|
||||
charlie 784D623E0C15DE79043C126FA6449B68311339E5
|
||||
|
||||
Again, we can use the ``--output json`` flag:
|
||||
|
||||
::
|
||||
|
||||
[
|
||||
{
|
||||
"name": "alice",
|
||||
"address": "6FEA9C99E2565B44FCC3C539A293A1378CDA7609",
|
||||
"pubkey": {
|
||||
"type": "ed25519",
|
||||
"data": "878B297F1E863CC30CAD71E04A8B3C23DB71C18F449F39E35B954EDB2276D32D"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "bob",
|
||||
"address": "A159C96AE911F68913E715ED889D211C02EC7D70",
|
||||
"pubkey": {
|
||||
"type": "ed25519",
|
||||
"data": "2127CAAB96C08E3042C5B33C8B5A820079AAE8DD50642DCFCC1E8B74821B2BB9"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "charlie",
|
||||
"address": "784D623E0C15DE79043C126FA6449B68311339E5",
|
||||
"pubkey": {
|
||||
"type": "ed25519",
|
||||
"data": "4BF22554B0F0BF2181187E5E5456E3BF3D96DB4C416A91F07F03A9C36F712B77"
|
||||
}
|
||||
},
|
||||
]
|
||||
|
||||
to get machine readable output.
|
||||
|
||||
If we want information about one specific key, then:
|
||||
|
||||
::
|
||||
|
||||
basecli keys get charlie --output json
|
||||
|
||||
will, for example, return the info for only the "charlie" key returned
|
||||
from the previous ``basecoin keys list`` command.
|
||||
|
||||
The keys tooling can support different types of keys with a flag:
|
||||
|
||||
::
|
||||
|
||||
basecli keys new bit --type secp256k1
|
||||
|
||||
and you'll see the difference in the ``"type": field from``\ basecli
|
||||
keys get\`
|
||||
|
||||
Before moving on, let's set an enviroment variable to make
|
||||
``--output json`` the default.
|
||||
|
||||
Either run or put in your ``~/.bash_profile`` the following line:
|
||||
|
||||
::
|
||||
|
||||
export BC_OUTPUT=json
|
||||
|
||||
Recover a key
|
||||
-------------
|
||||
|
||||
Let's say, for whatever reason, you lose a key or forget the password.
|
||||
On creation, you were given a seed. We'll use it to recover a lost key.
|
||||
|
||||
First, let's simulate the loss by deleting a key:
|
||||
|
||||
::
|
||||
|
||||
basecli keys delete alice
|
||||
|
||||
which prompts for your current password, now rendered obsolete, and
|
||||
gives a warning message. The only way you can recover your key now is
|
||||
using the 12 word seed given on initial creation of the key. Let's try
|
||||
it:
|
||||
|
||||
::
|
||||
|
||||
basecli keys recover alice-again
|
||||
|
||||
which prompts for a new password then the seed:
|
||||
|
||||
::
|
||||
|
||||
Enter the new passphrase:
|
||||
Enter your recovery seed phrase:
|
||||
strike alien praise vendor term left market practice junior better deputy divert front calm
|
||||
alice-again CBF5D9CE6DDCC32806162979495D07B851C53451
|
||||
|
||||
and voila! You've recovered your key. Note that the seed can be typed
|
||||
out, pasted in, or piped into the command alongside the password.
|
||||
|
||||
To change the password of a key, we can:
|
||||
|
||||
::
|
||||
|
||||
basecli keys update alice-again
|
||||
|
||||
and follow the prompts.
|
||||
|
||||
That covers most features of the keys sub command.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<!-- use later in a test script, or more advance tutorial?
|
||||
SEED=$(echo 1234567890 | basecli keys new fred -o json | jq .seed | tr -d \")
|
||||
echo $SEED
|
||||
(echo qwertyuiop; echo $SEED stamp) | basecli keys recover oops
|
||||
(echo qwertyuiop; echo $SEED) | basecli keys recover derf
|
||||
basecli keys get fred -o json
|
||||
basecli keys get derf -o json
|
||||
```
|
||||
-->
|
||||
Loading…
Reference in New Issue