Keystore: bring keystore spec more up to date

hsanjuan · hsanjuan · commit 16b5ec43f287 · 2020-03-27T13:40:39.000+01:00
This makes the parts that have been implemented from the keystore spec be
reflected on the spec the way that they actually work. Focuses on:

* How keys are named and stored on disk (REPO_FS)
* What the current interface is (KEYSTORE)
diff --git a/KEYSTORE.md b/KEYSTORE.md
@@ -2,39 +2,33 @@
 
 **Authors(s):**
 - [whyrusleeping](github.com/whyrusleeping)
+- [Hector Sanjuan](github.com/hsanjuan)
 
 * * *
 
 **Abstract**
 
-TODO
+This spec provides definitions and operations for the keystore feature in IPFS.
 
 # Table of Contents
 
 TODO
 
 ## Goals:
 
-To have a secure, simple and user-friendly way of storing and managing keypairs
+To have a secure, simple and user-friendly way of storing and managing keys
 for use by ipfs. As well as the ability to share these keys, encrypt, decrypt,
 sign and verify data.
 
 ## Planned Implementation
-### Storage
 
-Keys will be stored in a directory named `keys` under the `$IPFS_PATH`
-directory. Each named keypair will be stored across two files, the private key
-in `$NAME` and the public key in `$NAME.pub`. They will be encoded in PEM (or
-similar) format, and optionally password encrypted. Upon starting the ipfs daemon,
-keys will be lazily loaded as needed. If a given key is password protected, the user
-should be prompted for the password at the time of loading the key. The `$IPFS_PATH/keys`
-directory should be readable only be the owner, with unix permissions of `700`. Keys
-in the directory should be readonly, by the owner `400`.
+### Key storage
+
+Storage layout and format is defined in the [`REPO_FS`](REPO_FS.md) part of the spec.
 
 ### Interface
-Several additions and modifications will need to be made to the ipfs toolchain to
-accomodate the changes. First, the creation of two subcommands `ipfs key` and
-`ipfs crypt`:
+
+#### ipfs key
 
 ```
 
@@ -45,11 +39,11 @@ SUBCOMMANDS:
     ipfs key gen                  - Generates a new named ipfs keypair
     ipfs key list                 - Lists out all local keypairs
     ipfs key info <key>           - Get information about a given key
-	ipfs key rm	<key>             - Delete a given key from your keystore
-	ipfs key rename <key> <name>  - Renames a given key
-	ipfs key show <key>			  - Print out a given key
+    ipfs key rm     <key>             - Delete a given key from your keystore
+    ipfs key rename <key> <name>  - Renames a given key
+    ipfs key show <key>               - Print out a given key
 
-	ipfs key send <key> <peer>    - Shares a specified private key with the given peer
+    ipfs key send <key> <peer>    - Shares a specified private key with the given peer
 
     Use 'ipfs key <subcmd> --help' for more information about each command.
 
@@ -59,9 +53,10 @@ DESCRIPTION:
 
 ```
 
-```
+#### ipfs crypt
 
-	ipfs crypt - Perform cryptographic operations using ipfs keypairs
+```
+    ipfs crypt - Perform cryptographic operations using ipfs keypairs
 
 SUBCOMMANDS:
 
@@ -72,33 +67,27 @@ SUBCOMMANDS:
 
 DESCRIPTION:
 
-	`ipfs crypt` is a command used to perform various cryptographic operations
-	using ipfs keypairs, including: signing, verifying, encrypting and decrypting.
+    `ipfs crypt` is a command used to perform various cryptographic operations
+    using ipfs keypairs, including: signing, verifying, encrypting and decrypting.
 ```
 
 #### Some subcommands:
 
-##### Key Gen
-```
+##### ipfs key Gen
 
-    ipfs key gen - Generate a new ipfs keypair
 
-OPTIONS:
+```
+    ipfs key gen <name> - Generate a new ipfs keypair
 
-	-t, -type		string		- Specify the type and size of key to generate (i.e. rsa-4096)
-	-p, -passphrase string		- Passphrase for encrypting the private key on disk
-	-n, -name		string		- Specify a name for the key
+OPTIONS:
+    -t, -type       string         - Specify the type and size of key to generate (i.e. rsa)
+    -s. -size       int            - Size of the key to generate
+    -p, -passphrase string         - Passphrase for encrypting the private key on disk
 
 DESCRIPTION:
 
     'ipfs key gen' is a command used to generate new keypairs.
-	If any options are not given, the command will go into interactive mode and prompt
-	the user for the missing fields.
-
 ```
-##### Comments:
-
-Similar to ssh's `ssh-keygen` with the `-t` option and interactive prompts.
 
 * * *
 
@@ -109,18 +98,18 @@ Similar to ssh's `ssh-keygen` with the `-t` option and interactive prompts.
 
 OPTIONS:
 
-	-y, -yes		bool		- Yes to the prompt
+    -y, -yes        bool        - Yes to the prompt
 
 DESCRIPTION:
 
     'ipfs key send' is a command used to share keypairs with other trusted users.
 
-	It will first look up the peer specified and print out their information and
-	prompt the user "are you sure? [y/n]" before sending the keypair. The target
-	peer must be online and dialable in order for the key to be sent.
+    It will first look up the peer specified and print out their information and
+    prompt the user "are you sure? [y/n]" before sending the keypair. The target
+    peer must be online and dialable in order for the key to be sent.
 
-	Note: while it is still managed through the keystore, ipfs will prevent you from
-			sharing your nodes private key with anyone else.
+    Note: while it is still managed through the keystore, ipfs will prevent you from
+            sharing your nodes private key with anyone else.
 
 ```
 
@@ -137,19 +126,19 @@ Ensure that the user knows the implications of sending a key.
 
 ARGUMENTS:
 
-	data						- The filename of the data to be encrypted ("-" for stdin)
+    data                        - The filename of the data to be encrypted ("-" for stdin)
 
 OPTIONS:
 
-	-k, -key		string		- The name of the key to use for encryption (default: localkey)
-	-o, -output		string		- The name of the output file (default: stdout)
-	-c, -cipher     string		- The cipher to use for the operation
-	-m, -mode		string		- The block cipher mode to use for the operation
+    -k, -key        string        - The name of the key to use for encryption (default: localkey)
+    -o, -output     string        - The name of the output file (default: stdout)
+    -c, -cipher     string        - The cipher to use for the operation
+    -m, -mode       string        - The block cipher mode to use for the operation
 
 DESCRIPTION:
 
     'ipfs crypt encrypt' is a command used to encypt data so that only holders of a certain
-	key can read it.
+    key can read it.
 
 ```
 
@@ -165,8 +154,8 @@ We will also need to make additions to support keys in other commands, these cha
 
 - `ipfs add`
     - Support for a `-encrypt-key` option, for block encrypting the file being added with the key
-		- also adds an 'encrypted' node above the root unixfs node
-	- Support for a `-sign-key` option to attach a signature node above the root unixfs node
+        - also adds an 'encrypted' node above the root unixfs node
+    - Support for a `-sign-key` option to attach a signature node above the root unixfs node
 
 - `ipfs block put`
     - Support for a `-encrypt-key` option, for encrypting the block before hashing and storing
@@ -175,28 +164,30 @@ We will also need to make additions to support keys in other commands, these cha
     - Support for a `-encrypt-key` option, for encrypting the object before hashing and storing
 
 - `ipfs name publish`
-	- Support for a `-key` option to select which keyspace to publish to
-
-### Code Changes/Additions
-An outline of which packages or submodules will be affected.
-
-#### Repo
-
-- add `keystore` concept to repo, load/store keys securely
-- needs to understand PEM (or $CHOSEN_FORMAT) encoding
-
-Expected Interface: (very wip)
-
-```
-type KeyStore interface {
-	// Get a key from the cache
-	GetKey(name string) (ci.PrivKey, error)
-
-	// Save a new key into the cache, and write to disk
-	StoreKey(name string, key ci.PrivKey) error
-
-	// LoadKey reads the key from its file on disk, and stores it in the cache
-	LoadKey(name string, password []byte) error
+    - Support for a `-key` option to select which keyspace to publish to
+
+### Code changes and additions
+
+This sections outlines code organization around this feature.
+
+#### Keystore package
+
+The fsrepo carries a `keystore` that can be used to load/store keys. The keystore is implemented following this interface:
+
+```go
+// Keystore provides a key management interface
+type Keystore interface {
+	// Has returns whether or not a key exist in the Keystore
+	Has(string) (bool, error)
+	// Put stores a key in the Keystore, if a key with the same name already exists, returns ErrKeyExists
+	Put(string, ci.PrivKey) error
+	// Get retrieves a key from the Keystore if it exists, and returns ErrNoSuchKey
+	// otherwise.
+	Get(string) (ci.PrivKey, error)
+	// Delete removes a key from the Keystore
+	Delete(string) error
+	// List returns a list of key identifier
+	List() ([]string, error)
 }
 ```
 
@@ -210,13 +201,13 @@ does not linger in memory.
 - if new node types are not unixfs nodes, special consideration must be given to the interop
 
 - DagReader needs to be able to access keystore to seamlessly stream encrypted data we have keys for
-	- also needs to be able to verify signatures
+    - also needs to be able to verify signatures
 
 #### Importer
 
 - DagBuilderHelper needs to be able to encrypt blocks
-	- Dag Nodes should be generated like normal, then encrypted, and their parents should
-		link to the hash of the encrypted node
+    - Dag Nodes should be generated like normal, then encrypted, and their parents should
+        link to the hash of the encrypted node
 - DagBuilderParams should have extra parameters to acommodate creating a DBH that encrypts the blocks
 
 #### New 'Encrypt' package
@@ -235,33 +226,33 @@ Some tenative mockups (in json) of the new DAG structures for signing and encryp
 Signed DAG:
 ```
 {
-	"Links" : [
-		{
-			"Name":"@content",
-			"Hash":"QmTheContent",
-		}
-	],
-	"Data": protobuf{
-		"Type":"Signed DAG",
-		"Signature": "thesignature",
-		"PubKeyID": "QmPubKeyHash",
-	}
+    "Links" : [
+        {
+            "Name":"@content",
+            "Hash":"QmTheContent",
+        }
+    ],
+    "Data": protobuf{
+        "Type":"Signed DAG",
+        "Signature": "thesignature",
+        "PubKeyID": "QmPubKeyHash",
+    }
 }
 ```
 
 Encrypted DAG:
 ```
 {
-	"Links" : [
-		{
-			"Name":"@content",
-			"Hash":"QmRawEncryptedDag",
-		}
-	],
-	"Data": protobuf{
-		"Type":"Encrypted DAG",
-		"PubKeyID": "QmPubKeyHash",
-		"Key": "ephemeral symmetric key, encrypted with public key",
-	}
+    "Links" : [
+        {
+            "Name":"@content",
+            "Hash":"QmRawEncryptedDag",
+        }
+    ],
+    "Data": protobuf{
+        "Type":"Encrypted DAG",
+        "PubKeyID": "QmPubKeyHash",
+        "Key": "ephemeral symmetric key, encrypted with public key",
+    }
 }
 ```
diff --git a/REPO.md b/REPO.md
@@ -37,7 +37,7 @@ The Repo stores a collection of [IPLD](https://github.com/ipld/specs#readme) obj
 
 - **config** - node configuration and settings
 - **datastore** - content stored locally, and indexing data
-- **keys** - cryptographic keys, including node's identity
+- **keystore** - cryptographic keys, including node's identity
 - **hooks** - scripts to run at predefined times (not yet implemented)
 
 Note that the IPLD objects a repo stores are divided into:
@@ -73,17 +73,11 @@ The name "datastore" comes from [go-datastore](https://github.com/jbenet/go-data
 
 This makes it easy to change properties or performance characteristics of a repo without an entirely new implementation.
 
-### keys (state)
+### keystore
 
-A Repo typically holds the keys a node has access to, for signing and for encryption. This includes:
+A Repo typically holds the keys a node has access to, for signing and for encryption.
 
-- a special (private, public) key pair that defines the node's identity
-- (private, public) key pairs
-- symmetric keys
-
-Some repos MAY support key-agent delegation, instead of storing the keys directly.
-
-Keys are structured using the [multikey](https://github.com/jbenet/multikey) format, and are part of the [keychain](../keychain) datastructure. This means all keys are IPLD objects, and that they link to all the data needed to make sense of them, including parent keys, identities, and certificates.
+Details on operation and storage of the keystore can be found in [`REPO_FS.md`](REPO_FS.md) and [`KEYSTORE.md`](KEYSTORE.md).
 
 ### config (state)
 
diff --git a/REPO_FS.md b/REPO_FS.md
@@ -2,7 +2,8 @@
 
 **Author(s)**:
 - [Juan Benet](github.com/jbenet)
-
+- [David Dias](github.com/daviddias)
+- [Hector Sanjuan](github.com/hsanjuan)
 * * *
 
 **Abstract**
@@ -32,9 +33,8 @@ This spec defines `fs-repo` version `1`, its formats, and semantics.
 │       └── aa      <--- N tiers
 ├── config          <--- config file (json or toml)
 ├── hooks/          <--- hook scripts
-├── keys/           <--- cryptographic keys
-│   ├── id.pri      <--- identity private key
-│   └── id.pub      <--- identity public key
+├── keystore/       <--- cryptographic keys
+│   ├── key_b32name <--- private key with base32-encoded name
 ├── datastore/      <--- datastore
 ├── logs/           <--- 1 or more files (log rotate)
 │   └── events.log  <--- can be tailed
@@ -116,18 +116,28 @@ Currently available hooks:
 none
 ```
 
-### keys/
+### keystore/
 
 
-The `keys` directory holds all the keys the node has access to. The keys
-are named with their hash, and an extension describing what type of key
-they are. The only specially-named key is `id.{pub, sec}`
+The `keystore` directory holds additional private keys that the node has
+access to (the public keys can be derived from them).
 
-```
-<key>.pub is a public key
-<key>.pri is a private key
-<key>.sym is a symmetric secret key
-```
+The keystore repository should have `0700` permissions (readable, writable by
+the owner only).
+
+The key files are named as `key_base32encodedNameNoPadding` where `key_` is a
+fixed prefix followed by a base32 encoded identifier, **without padding and
+downcased**. The identifier usually corresponds to a human-friendly name given
+by the user.
+
+The key files should have '0400' permissions (read-only, by the owner only).
+
+The `self` key identifier is reserved for the peer's main key, and therefore key named
+`key_onswyzq` is allowed in this folder.
+
+The key files themselves contain a serialized representation of the keys as
+defined in the
+[libp2p specification](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#keys).
 
 ### datastore/
 
