add README.md

Signed-off-by: Daniel Golle <daniel@makrotopia.org>
This work was sponsored by WIO (wiowireless.com)

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..7ec5e14
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# ucert
+
+ucert is a signature-chaining wrapper around usign using libubox blob and blobmsg. 
+
+## a few words about security
+ucert inherits all its cryptographic properties from the underlying usign implementation which as such wasn't meant to be used in such a way.
+To maintain a high cryptographic standard, it is likely that further optimization of the signed payload format (reduce known-plaintext by normalization, add salts in case usign doesn't, ...) has to be carried out.
+
+## usage
+```shell
+Usage: ucert <command> <options>
+Commands:
+  -A:                  append signature (needs -c and -x)
+  -D:                  dump (needs -c)
+  -I:                  issue cert and revoker (needs -c and -p and -s)
+  -R:                  process revoker certificate (needs -c and -P)
+  -V:                  verify (needs -c and -p|-P, may have -m)
+Options:
+  -c <file>:           certificate file
+  -m <file>:           message file (verify only)
+  -p <file>:           public key file
+  -P <path>:           public key directory (verify only)
+  -q:                  quiet (do not print verification result, use return code only)
+  -s <file>:           secret key file (issue only)
+  -x <file>:           signature file
+```
+
+### examples
+```shell
+# on airgap system
+# create root keypair (which never leaves airgap)
+usign -G -p capubkey -s caseckey
+# create delegate keypair
+usign -G -p pubkey -s seckey
+# create ca-signed delegate cert (and revoker)
+ucert -I -p pubkey -s caseckey -c newcert
+
+# eg. on buildbot worker
+# got newcert and seckey from airgap
+# sign content
+usign -S -m message.bin -s seckey -x message.bin.sig
+# create cert for message
+cp newcert message.bin.ucrt
+ucert -A -c message.bin.ucrt -x message.bin.sig
+
+# on client
+ucert -V -P /etc/opkg/keys -m message.bin -c message.bin.ucrt && echo message.bin verified successfully
+```