diff --git a/docs/design.md b/docs/design.md deleted file mode 100644 index 1bb9964d76..0000000000 --- a/docs/design.md +++ /dev/null @@ -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). diff --git a/docs/index.rst b/docs/index.rst index 62a3f62b59..99adb156e3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/staking/key-management.rst b/docs/staking/key-management.rst new file mode 100644 index 0000000000..0e7522cc6c --- /dev/null +++ b/docs/staking/key-management.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 + +