notes

1 files changed, 41 insertions, 21 deletions

diff --git a/p11p.md b/p11p.md
index aaff8ba..e2642ea 100644
--- a/p11p.md
+++ b/p11p.md
@@ -1,3 +1,5 @@
+TOOD: split this file into README.md, doc/design.md, doc/config.md.
+
 # p11p -- PKCS #11 proxy performing failover and load balancing
 
 p11p is a shared library and a daemon, both running on the same host
@@ -100,8 +102,8 @@ TBD
 
 - When vendor library is not so great at TCP and the network between
   the host running the application and the cryptographic device is
-  killing TCP sessions, catch the failure (f.ex. by timing out) and
-  retry the operation behind the back of the application.
+  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
@@ -109,35 +111,46 @@ TBD
   fall back functionality between different HSM's from different
   vendors.
 
-
 ## configuration
 
-## configuration
+All of PKCS11.CONF(5), from p11-kit, plus the following module
+configuration fields.
+
+- in-group: The name of a group that this module is part of. Each
+  group name mentioned in any module configuration will result in a
+  virtual token being created, named TBD.
 
-    <name> = [a-z]+[a-z0-9_]*
-    <names> = <name>[,<names>]
-    <endpoint> = unix:<path> | tcp:<dns-name>[:<integer>]
+  A virtual token has one or more backing modules, determined by the
+  modules that list the name of the virtual token in 'in-group'. The
+  order of the backing modules is influenced by setting
+  'priority'. The backing module at the top of the list is the current
+  backing module at start-up.
 
-### config common to Client and Server sections
-    Name = <name>
-    Address = <endpoint>
+  The current backing module changes to the next in the list of
+  backing modules when a PKCS #11 request fails to respond within
+  'timeout' a number of times equal to 'retries'. To configure a load
+  balancing virtual token, set 'timeout' to a non-zero value and set
+  'retries' to zero (the default).
 
-### client config
-    [Client]
-    Mode = proxy | forward
+  A virtual token is used as any ordinary token and will be forwarding
+  PKCS #11 calls and responses to and from its current active module.
 
-    [Server]
+  By default, a module is not part of any group.
 
+- timeout: An integer denoting the timeout in seconds for a PKCS #11
+  request. A timeout of zero means that there is no timeout. The
+  default timeout value is zero.
 
-### server config
-    [Server]
-    Mode = proxy | forward
+- retries: The number of retries after a timeout that this module will
+  have before it's being reloaded. Reloading of a module that is part
+  of a group (a backing module) makes the virtual token switch to the
+  next backing module in its list. The default retries value is zero.
 
-    [Client]
+- env: NAME=value is set in the environment of the process loading the
+  module.
 
-    [Token]
-    SOPath = <path>
-    Groups = <names>
+- chroot: A path in which the process loading the module will chrooted
+  to prior to loading the module.
 
 
 ## NOTES
@@ -150,3 +163,10 @@ TBD
 ## External documentation
 
 - [OASIS PKCS 11 TC](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=pkcs11)
+
+# README
+
+## Building
+
+echo $PATH | egrep -q rebar3 || export PATH=$PATH:~/.cache/rebar3/bin
+make