# 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 targeting 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.

- When 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 functions 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/]

## Running automatic tests

This should be enough to verify that all the necessary parts are in
place on your system, before getting p11p-daemon running.

    $ sudo apt install softhsm2 gnutls-bin libengine-pkcs11-openssl
    $ make -C tests

## Compiling, configuring and running p11p-daemon

See p11p-daemon/README.md.