keystore.md
#  Keystore
**Authors(s):**
- [whyrusleeping](github.com/whyrusleeping)
- [Hector Sanjuan](github.com/hsanjuan)
**Abstract**
This spec provides definitions and operations for the keystore feature in IPFS.
# Table of Contents
- [Goals](#goals)
- [Planned Implementation](#planned-implementation)
- [Key storage](#key-storage)
- [Interface](#interface)
- [Code changes and additions](#code-changes-and-additions)
- [Structures](#structures)
## Goals
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
### Key storage
Storage layout and format is defined in the [`repository_fs`](repository_fs.md) part of the spec.
### Interface
#### ipfs key
```
USAGE
ipfs key - Create and list IPNS name keypairs
ipfs key
'ipfs key gen' generates a new keypair for usage with IPNS and 'ipfs name
publish'.
> ipfs key gen --type=rsa --size=2048 mykey
> ipfs name publish --key=mykey QmSomeHash
'ipfs key list' lists the available keys.
> ipfs key list
self
mykey
SUBCOMMANDS
ipfs key export <name> - Export a keypair
ipfs key gen <name> - Create a new keypair
ipfs key import <name> <key> - Import a key and prints imported key id
ipfs key list - List all local keypairs.
ipfs key rename <name> <newName> - Rename a keypair.
ipfs key rm <name>... - Remove a keypair.
ipfs key rotate - Rotates the IPFS identity.
For more information about each command, use:
'ipfs key <subcmd> --help'
```
#### ipfs crypt
**NOTE:** as of 2023 Q4, `ipfs crypt` commands are not implemented yet.
```
ipfs crypt - Perform cryptographic operations using ipfs keypairs
SUBCOMMANDS:
ipfs crypt sign <data> - Generates a signature for the given data with a specified key
ipfs crypt verify <data> <sig> - Verify that the given data and signature match
ipfs crypt encrypt <data> - Encrypt the given data
ipfs crypt decrypt <data> - Decrypt the given data
DESCRIPTION:
`ipfs crypt` is a command used to perform various cryptographic operations
using ipfs keypairs, including: signing, verifying, encrypting and decrypting.
```
#### Some subcommands:
##### ipfs key Gen
```
USAGE
ipfs key gen <name> - Create a new keypair
SYNOPSIS
ipfs key gen [--type=<type> | -t] [--size=<size> | -s]
[--ipns-base=<ipns-base>] [--] <name>
ARGUMENTS
<name> - name of key to create
OPTIONS
-t, --type string - type of the key to create: rsa, ed25519. Default:
ed25519.
-s, --size int - size of the key to generate.
--ipns-base string - Encoding used for keys: Can either be a multibase
encoded CID or a base58btc encoded multihash. Takes
{b58mh|base36|k|base32|b...}. Default: base36.
```
* * *
##### Key Send
```
USAGE
ipfs key - Create and list IPNS name keypairs
SYNOPSIS
ipfs key
DESCRIPTION
'ipfs key gen' generates a new keypair for usage with IPNS and 'ipfs name
publish'.
> ipfs key gen --type=rsa --size=2048 mykey
> ipfs name publish --key=mykey QmSomeHash
'ipfs key list' lists the available keys.
> ipfs key list
self
mykey
SUBCOMMANDS
ipfs key export <name> - Export a keypair
ipfs key gen <name> - Create a new keypair
ipfs key import <name> <key> - Import a key and prints imported key id
ipfs key list - List all local keypairs.
ipfs key rename <name> <newName> - Rename a keypair.
ipfs key rm <name>... - Remove a keypair.
ipfs key rotate - Rotates the IPFS identity.
For more information about each command, use:
'ipfs key <subcmd> --help'
```
##### Comments:
Ensure that the user knows the implications of sending a key.
* * *
##### Crypt Encrypt
```
ipfs crypt encrypt <data> - Encrypt the given data with a specified key
ARGUMENTS:
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
DESCRIPTION:
'ipfs crypt encrypt' is a command used to encypt data so that only holders of a certain
key can read it.
```
##### Comments:
This should probably just operate on raw data and not on DAGs.
* * *
##### Other Interface Changes
We will also need to make additions to support keys in other commands, these changes are as follows:
- `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
- `ipfs block put`
- Support for a `-encrypt-key` option, for encrypting the block before hashing and storing
- `ipfs object put`
- 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 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)
}
```
Note: Never store passwords as strings, strings cannot be zeroed out after they are used.
using a byte array allows you to write zeroes over the memory so that the users password
does not linger in memory.
#### Unixfs
- new node types, 'encrypted' and 'signed', probably shouldn't be in unixfs, just understood by it
- 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
#### 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
- DagBuilderParams should have extra parameters to accommodate creating a DBH that encrypts the blocks
#### New 'Encrypt' package
Should contain code for crypto operations on dags.
Encryption of dags should work by first generating a symmetric key, and using
that key to encrypt all the data. That key should then be encrypted with the
public key chosen and stored in the Encrypted DAG structure.
Note: One option is to simply add it to the key interface.
### Structures
Some tentative mockups (in json) of the new DAG structures for signing and encrypting
Signed DAG:
```
{
"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",
}
}
```
