# p11p design

## 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).
- Run on reasonable Linux and BSD systems.
- Somewhat isolating (and potentially constraining) the running of
  vendor 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? p11-kit-client.so uses
  libffi and its own serialisation code (rpc-message.c),
  both of which might be unnecessarily complex, but for a PoC might
  be a good choice.
- 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 child, `p11p-helper`, is an executable program using
  the Cryptoki API, implemented in C (or possibly another language
  that can dlopen and call into the vendor solib).
- 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

#### Supported PKCS #11 mechanisms

TBD

## Configuration

TODO

## External dependencies

TODO

## External documentation

- [OASIS PKCS 11 TC](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=pkcs11)