diff options
Diffstat (limited to 'p11p.md')
| -rw-r--r-- | p11p.md | 112 |
1 files changed, 112 insertions, 0 deletions
@@ -0,0 +1,112 @@ +# p11p -- PKCS #11 proxy performing failover and load balancing + +p11p is a shared library and a daemon, both running on the same host +as a Cryptoki application, intercepting the communication with a +cryptographic device (typically a HSM) with the goal of dealing with +error handling and load balancing between devices. + +ASCII art time! + + +------------------------------------=--------------+ + | PC/server/laptop | + | | + | +----------------------------+ | + | | application (process) | +---------------+ | + | | | | p11p-daemon | | + | | +------------------------+ | | | | + | | | p11p-client.so (solib) |--->| +-----------+ | | + | | +------------------------+ | | | 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. + + Could be accomplished by providing proxying / forwarding of PKCS #11 + sessions to a system with access to a PKCS #11 aware cryptographic + device. + +## Functionality + + + +## Inspiration + +- [p11-kit https://github.com/p11-glue/p11-kit/] + +## 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). +- All run on reasonable Linux and BSD systems. +- Somewhat isolating (and potentially constraining) the running of + token 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? It uses libffi (virtual.c) + and its own serialisation code (rpc-message.c), both of which sounds + unnecessary unsafe, but for a PoC might be good enough. +- 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 children, `p11p-helper`, are executable programs using + the Cryptoki API, implemented in C. +- 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 mechanisms + +TBD + +## Use cases + +- Migrating from one kind of HSM to another kind of HSM. + + +## NOTES + +- apt install p11-kit libp11-dev + +## External dependencies + +TBD + +## External documentation + +- [OASIS PKCS 11 TC](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=pkcs11) |