1 files changed, 69 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..04bb9b3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# p11p -- PKCS #11 proxy performing failover and load balancing
+
+p11p is a shared library, a daemon and a helper program, all running
+on the same host as a PKCS #11 ("Cryptoki") application, intercepting
+the communication with a cryptographic device (typically an HSM) with
+the goal of dealing with error handling and load balancing between
+devices.
+
+    +------------------------------------------------+
+    | PC/server/laptop                               |
+    |                                                |
+    | +--------------------+                         |
+    | | application*       |  +--------------------+ |
+    | |                    |  | p11p-daemon*       | |
+    | | +----------------+ |  |                    | |
+    | | | p11p-client.so |--->| +---------------+  | |
+    | | +----------------+ |  | | p11p-helper*  |  | |
+    | +--------------------+  | |               |  | |
+    |                         | | +-----------+ |  | |
+    |                         | | | vendor.so | |  | |
+    |                         | | +-----------+ |  | |
+    |                         | +----|----------+  | |
+    |                         |      |             | |
+    |                         +------|-------------+ |
+    +--------------------------------|---------------+
+                                     v
+                                   +-----+
+                                   | HSM |
+                                   +-----+
+
+## Goals
+
+* Detect when a Cryptoki library operation fails and retry the
+  operation, possibly on another cryptographic device.
+
+* Provide failover and load balancing between cryptographic devices.
+
+* Put some ground between a Cryptoki application and a Cryptoki
+  library.
+
+## Non-goals
+
+* Take control over the TCP session between a Cryptoki application and
+  a cryptographic device.
+
+  This could be accomplished by providing proxying / forwarding of
+  PKCS #11 sessions to a remote system with more local access to the
+  cryptographic device.
+
+## Use cases
+
+- When vendor library is not so great at TCP and the network between
+  the host running the application and the cryptographic device is
+  messing with TCP sessions, catch the failure (f.ex. by timing out)
+  and retry the operation behind the back of the application.
+
+- Migrating from one kind of HSM to another kind of HSM. p11p-daemon
+  can be configured to use more than one HSM. As long as they provide
+  the same funtcions using the same key(s), p11p-daemon can provide
+  fallback functionality for certain operations between different HSM's
+  from different vendors.
+
+## Inspiration
+
+- [p11-kit https://github.com/p11-glue/p11-kit/]
+
+## Compiling, configuring and running p11p-daemon
+
+See p11p-daemon/README.md.