1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
# 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
|
