From: Daniel Golle <daniel@makrotopia.org>
Date: Thu, 7 Jun 2018 21:44:57 +0000 (+0200)
Subject: add README.md
X-Git-Url: https://git.librecmc.org/?p=oweals%2Fucert.git;a=commitdiff_plain;h=4ec94878f661ef482e94f62fb9a03b251ea21363

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
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
+```