add a system description

1 files changed, 37 insertions, 4 deletions

diff --git a/p11proxy.md b/p11proxy.md
index cf291b6..0f97adb 100644
--- a/p11proxy.md
+++ b/p11proxy.md
@@ -12,7 +12,7 @@ ASCII art time!
 	|                                                   |
 	| +----------------------------+                    |
 	| | application (process)      |  +---------------+ |
-	| |                            |  | p11pd         | |
+	| |                            |  | p11p-daemon   | |
 	| | +------------------------+ |  |               | |
 	| | | p11p-client.so (solib) |--->| +-----------+ | |
 	| | +------------------------+ |  | | vendor.so | | |
@@ -51,9 +51,42 @@ ASCII art time!
 
 - [p11-kit https://github.com/p11-glue/p11-kit/]
 
-## Specification
-
-
+## Overview and design criterias
+
+    User application --(dlopen)-->
+    p11p-client.so --(<our-protocol>-over-unix-socket)-->
+    p11p-daemon --(fork+exec, stdin/stdout)-->
+    p11p-helper --(dlopen)-->
+	$vendor.so --(vendor-specific)-->
+	PKCS #11 token
+
+- Typical sequence of events
+  - User application dlopens `p11p-client.so` as a "Cryptoki library"
+  - `p11p-client.so` connects to `p11p-daemon` running on the same
+    system, over a unix socket (AF_UNIX).
+  - `p11p-daemon` forks a process and executes `p11p-helper`
+  - `p11p-helper` dlopens the appropriate Cryptoki library from
+    $vendor and forwards the Cryptoki calls there
+
+- The daemon, `p11p-daemon`, handles both load balancing and failover,
+  according to configuration per (set of) token(s).
+- All run on reasonable Linux and BSD systems.
+- Somewhat isolating (and potentially constraining) the running of
+  token solibs by forking before loading them.
+- The Cryptoki stub library, `p11p-client.so`, is implemented in
+  C. TBD: Use code from p11-kit for this? It uses libffi (virtual.c)
+  and its own serialisation code (rpc-message.c), both of which sounds
+  unnecessary unsafe, but for a PoC might be good enough.
+- The daemon, `p11p-daemon`, is implemented in something not too
+  crazy, like Erlang or Rust, taking the deployment story into
+  account -- being self-contained is a worthwhile goal.
+- The daemon children, `p11p-helper`, are executable programs using
+  the Cryptoki API, implemented in C.
+- Wire protocol between `p11p-client.so` and `p11p-daemon` is TBD but
+  should be designed for simple parsing in C. It runs over an AF_UNIX
+  socket and needs only serialisation of Cryptoki calls -- no
+  addressing and minimal framing (like a message length). TBD:
+  Serialise (using Trunnel) and use an end-of-record sequence instead?
 
 ### PKCS #11