# p11p-daemon is a PKCS #11 proxy

## Installing dependencies

### p11-kit

	$ sudo apt install p11-kit

Or, if your p11-kit package is too old (<0.23.15):

    $ sudo apt install pkg-config libffi-dev
    $ curl -LO https://github.com/p11-glue/p11-kit/releases/download/0.23.16.1/p11-kit-0.23.16.1.tar.gz
    $ curl -LO https://github.com/p11-glue/p11-kit/releases/download/0.23.16.1/p11-kit-0.23.16.1.tar.gz.sig
    $ gpg --verify p11-kit-0.23.16.1.tar.gz.sig
    $ tar xf p11-kit-0.23.16.1.tar.gz && cd p11-kit
    $ ./configure --without-libtasn1
    $ make all check
    $ sudo make install

### Erlang/OTP 19

Ideally, your OS distribution has Erlang/OTP 19 or newer:

    $ sudo apt install erlang

An alternative -- which hurts because how would you verify kerl --
would be:

    $ curl -LO https://raw.githubusercontent.com/kerl/kerl/master/kerl
    $ : pray that you got the right bits!
    $ chmod +x kerl
    $ sudo apt install libncurses5-dev
    $ ./kerl build 19.2
    $ mkdir ~/kerl
    $ ./kerl install 19.2 ~/kerl/19.2
    $ . ~/kerl/19.2/activate

## Compiling p11p-daemon

If you don't have rebar3 installed, install it. See
https://www.rebar3.org/docs/ .

If you don't have rebar3 in PATH, add it.

Example:

    $ export PATH=$PATH:~/.cache/rebar3/bin

Compile:

    $ make

## Configuring p11p-daemon

Edit config/sys.config to define virtual tokens.

A PKCS #11 application ("client"), connecting to p11p-daemon performs
PKCS #11 operations on a virtual token. Each virtual token represents
one or more physical cryptographic devices with a PKCS #11 interface
("tokens").

Each virtual token has a name, a mode and a list of PKCS #11 modules,
i.e. shared libraries.

### vtoken name

A string identifying a virtual token. This name is reflected in the
name of the socket used by the client to connect to p11p-daemon.

### vtoken modules

A list of PKCS #11 modules backing the virtual token.

Each entry in this list has a name, a path to the shared library to
load and, optionally, an environment to run it in. The environment can
be used to pass configuration to the module.

### vtoken mode

The mode of a virtual token determines some of its behaviour with
reagard to choosing which token to satisfy a client request.

#### failover

In failover mode, the virtual token will use the first token in the
list of tokens until that token fails and then switch to the next in
the list.

Failover mode has one parameter specifying the number of seconds (?)
to wait for a token to respond before giving up and decide that the
token has failed.

#### balance

In balance mode, the virtual token will balance client requests over
all configured tokens in accordance with its configuration parameter.

Balance mode has one parameter, a list of invocation counts.  An
invocation count is an integer specifying how many times a token
should be invoked before moving to the next in the list. The first
integer in the list corresponds to the first token, the second integer
to the second token, and so on.

The default invocation count is one.

## Running p11p-daemon

To start p11p-daemon, running in the background and logging to files
under _build/default/rel/p11p/log/:

    $ make start

A socket per configured token, /run/user/$EUID/p11p/$TOKEN-$PID, is
made available and can now be used by a client. Example usage using
p11tool:

    $ P11_KIT_SERVER_ADDRESS=unix:path=/run/user/1000/p11p/vtoken0-26585 P11_KIT_DEBUG=none p11tool --provider /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so --list-tokens
    Token 0:
        URL: pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=b4a861d362dbd386;token=mytoken
        Label: mytoken
        Type: Generic token
        Manufacturer: SoftHSM project
        Model: SoftHSM v2
        Serial: b4a861d362dbd386
        Module: (null)

To stop p11p-daemon:

    $ make stop

## Debugging p11p-daemon

To start an Erlang shell running the p11p application:

    $ make shell

Quit by entering "q()." in the Erlang shell.

## Known bugs and limitations

- Multiple p11 applications using the same vtoken in a given
  p11p-daemon will result in undefined behaviour.

  TODO: Make this work, or prohibit it by rejecting a second user of
  the same vtoken.

## Hacking

### Layout in src

Terms used: p11 apps, servers, clients, proxy apps, virtual tokens and
physical tokens.

- p11 apps are PKCS #11 applications, not part of p11p-daemon, running
  in their own processes and connecting to a unix socket set up by a
  p11p-daemon server.

- Servers, implemented in p11p_server, proxy PKCS #11 requests and
  responses between a p11 app and a p11p-daemon client.

- Clients, implemented in p11p_client, proxy PKCS #11 requests and
  responses between p11p-daemon servers and a physical token, with the
  help of a proxy app.

- Proxy aps are considered part of p11p-daemon but run in separate
  unix processes, loading vendor.so at startup and talking to a
  physical token. Proxy apps are run by p11p-daemon clients.

- Virtual tokens are p11p-daemon objects representing a group of
  physical tokens.

- Phsyical tokens are p11 devices, not part of p11p-daemon, associated
  with a p11p-daemon proxy app.

The modules are:
- p11p_app.erl -- The application starts the main supervisor,
  p11p_sup.

- p11p_sup.erl -- The main supervisor starts the the server
  supervisor, the config server, and the manager.

- p11p_manager.erl -- The manager of clients and virtual
  tokens. Spawning clients when needed, facilitating failover and load
  balancing.

- p11p_server_sup.erl -- The server supervisor starts one server per
  configured token.

- p11p_server.erl -- A server, binding to a unix socket and proxying
  p11 requests and rsponses between a connecting p11 app and a client.

- p11p_client.erl -- A client, forking and executing proxy apps and
  proxying p11 requests and responses between a proxy app and a
  server.

- p11p_config.erl -- The config server reads the configuration file(s)
  and is used by any module needing configuration.

## Contact

  linus+p11p@sunet.se