Docs

Author: gabriel

.vuepress/config.js

@@ -34,6 +34,11 @@ module.exports = {
         path: "/docs/restapi/",
         children: ["/docs/restapi/user", "/docs/restapi/sigchain"]
       },
+      {
+        title: "Library",
+        collapsable: false,
+        children: ["/docs/lib/encrypt", "/docs/lib/packages"]
+      },
       {
         title: "Specs",
         collapsable: false,
@@ -51,7 +56,7 @@ module.exports = {
       {
         title: "Other",
         collapsable: true,
-        children: ["/docs/building", "/docs/service", "/docs/packages"]
+        children: ["/docs/building", "/docs/service"]
       }
     ]
   }

README.md

@@ -2,24 +2,24 @@
 title: keys.pub - Tools to help manage cryptographic keys
 ---
 
-# keys.pub
+<img src="./logo.png" width="280"/>
 
 ::: warning
 This project is in development and has not been audited. Don't use for anything important yet.
 :::
 
 ## Install
 
-- [Install Command Line](docs/cli/install.md)
-- [Install Desktop](docs/desktop/install.md) (includes command line)
+- [Install Command Line](/docs/cli/install.md)
+- [Install Desktop](/docs/desktop/install.md) (includes command line)
 
 ## Introduction
 
-keys.pub hosts a set of tools to help manage cryptographic keys. This includes a [software library](/docs/lib/), a [command line utility](/docs/cli/), [a desktop app](/docs/desktop/install.md), and a [REST API](docs/restapi/).
+keys.pub hosts a set of tools to help manage cryptographic keys. This includes a [software library](/docs/lib/), a [command line utility](/docs/cli/), [a desktop app](/docs/desktop/install.md), and a [REST API](/docs/restapi/).
 
 The default key is a [Curve25519 key (EdX25519)](/docs/specs/keys.md) capable of signing and encryption.
 Using this key, you can create a [sigchain](/docs/specs/sigchain.md) (an ordered sequence of signed statements).
-You can [link a key to an identity](docs/specs/user.md) on Github or Twitter, etc, by publishing a signed statement on that service and in a sigchain on keys.pub.
+You can [link a key to an identity](/docs/specs/user.md) on Github or Twitter, etc, by publishing a signed statement on that service and in a sigchain on keys.pub.
 
 You can [search for keys](docs/restapi/user.md#search) by user name and service (Github or Twitter, etc), or lookup a user for a key identifier.
 

docs/cli/encrypt.md

@@ -4,20 +4,23 @@
 
 Encrypt text to armored msg.enc (from stdin).
 
+Specify a key id or user name@service as recipients.
+
 ```shell
 > echo -n "My secret 🤓" |  keys encrypt -armor \
--signer kex1mnseg28xu6g3j4wur7hqwk8ag3fu3pmr2t5lync26xmgff0dtryqupf80c \
+-signer gabriel@github \
 -recipient kex1ts0qw8fwkvle2f2xsqumetmr9ev5ppx22rl5hnycen68sanjzl7qnta629 \
--recipient kex1mnseg28xu6g3j4wur7hqwk8ag3fu3pmr2t5lync26xmgff0dtryqupf80c > msg.enc
+-recipient gabriel@github > msg.enc
 ```
 
 Encrypt image.png to image.png.enc (using -in and -out).
 
+Signer is optional, if unspecified, is anonymous.
+
 ```shell
 > keys encrypt \
--signer kex1mnseg28xu6g3j4wur7hqwk8ag3fu3pmr2t5lync26xmgff0dtryqupf80c \
 -recipient kex1ts0qw8fwkvle2f2xsqumetmr9ev5ppx22rl5hnycen68sanjzl7qnta629 \
--recipient kex1mnseg28xu6g3j4wur7hqwk8ag3fu3pmr2t5lync26xmgff0dtryqupf80c \
+-recipient gabriel@github \
 -in image.png -out image.png.enc
 ```
 

docs/desktop/install.md

@@ -6,7 +6,7 @@ macOS only, other platforms coming soon.
 
 ## macOS
 
-To install via [homebrew](https://brew.sh/) casks:
+To install via [homebrew](https://brew.sh/) cask:
 
 ```shell
 brew tap keys-pub/tap

docs/lib/README.md

@@ -0,0 +1,53 @@
+# Encrypt
+
+The following example describes how to:
+
+- Initialize and setup/unlock a Keyring
+- Create a Keystore
+- Configure Saltpack
+- Generate an EdX25519 key
+- Encrypt to recipients using Saltpack
+
+```go
+import (
+    "github.com/keys-pub/keys"
+    "github.com/keys-pub/keys/keyring"
+    "github.com/keys-pub/keys/saltpack"
+)
+
+...
+
+// Create a Keyring.
+kr, err := keyring.NewKeyring("MyApp")
+// Setup/unlock the Keyring using a password.
+if err := keyring.UnlockWithPassword(kr, "alicepassword"); err != nil {
+    log.Fatal(err)
+}
+// Alternatively, you can use an in memory (ephemeral) Keyring for testing:
+// kr, err := keyring.NewMem()
+
+// Create a Keystore (backed by the Keyring).
+ks := keys.NewKeystore(kr)
+
+// Configure saltpack format.
+sp := saltpack.NewSaltpack(ks)
+sp.SetArmored(true)
+
+// Create an EdX25519 key and save it to the Keystore.
+alice := keys.GenerateEdX25519Key()
+if err := ks.SaveEdX25519Key(alice); err != nil {
+    log.Fatal(err)
+}
+
+bobID := keys.ID("kex1yy7amjzd5ld3k0uphvyetlz2vd8yy3fky64dut9jdf9qh852f0nsxjgv0m")
+message := []byte("hi bob")
+
+// Encrypt using Saltpack from alice to bob (include alice as a recipient too).
+encrypted, err := sp.Encrypt(message, alice.X25519Key(), bobID, alice.ID())
+if err != nil {
+    log.Fatal(err)
+}
+
+fmt.Printf("Encrypted: %s\n", string(encrypted))
+
+```

docs/lib/encrypt.md

@@ -0,0 +1,11 @@
+# Packages
+
+- [github.com/keys-pub/keys](https://godoc.org/github.com/keys-pub/keys): The core package, defines keys, stores, sigchain, signed statements and users.
+- [github.com/keys-pub/keys/keyring](https://godoc.org/github.com/keys-pub/keys/keyring): Securely store keys on macOS, Windows and Linux.
+- [github.com/keys-pub/keys/saltpack](https://godoc.org/github.com/keys-pub/keys/saltpack): Saltpack integration.
+
+The [github.com/keys-pub/keysd](https://github.com/keys-pub/keysd) repository is for services, utilities, clients, etc and includes:
+
+- [github.com/keys-pub/keysd/service](https://godoc.org/github.com/keys-pub/keysd/service): Service (gRPC), and command line client.
+- [github.com/keys-pub/keysd/http/client](https://godoc.org/github.com/keys-pub/keysd/http/client): Client REST API.
+- [github.com/keys-pub/keysd/http/server](https://godoc.org/github.com/keys-pub/keysd/http/server): Server REST API.

docs/lib/packages.md

@@ -0,0 +1,3 @@
+# Sign
+
+// TODO