Fix broken footnote references
[cacert-codedocs.git] / source / signer.rst
1 ===================
2 The Signer Protocol
3 ===================
4
5 Communication with the signer is performed via a serial connection. That
6 connection has to be established by the client before speaking the protocol
7 defined here.
8
9 .. _signer-request-data-format:
10
11 Signer request data format specification
12 ========================================
13
14 Protocol request data is encoded in the following format:
15
16 .. table:: signer request message format
17
18 ======= ==============================================================
19 Byte Data
20 ======= ==============================================================
21 0-2 length of header + data in network byte order
22 3-5 length of header network byte order
23 6-14 action specific header
24 15-17 length of first action specific content in network byte order
25 18-N fist action specific content string
26 N+1-N+3 length of second action specific content in network byte order
27 N+4-M second action specific content string
28 M+1-M+3 lenght of third action specific content in network byte order
29 M+4-End third action specific content string
30 ======= ==============================================================
31
32 Due to the length encoding in 3 bytes the messages can have a maximum length
33 of 8\ :sup:`3` = 2\ :sup:`24` Bytes which is around 16 MiB.
34
35 General request header format
36 -----------------------------
37
38 Every protocol request header (bytes 3-12 of protocol request message) follows
39 the same 9 byte structure. The content of bytes 3-8 are protocol action
40 specific.
41
42 .. table:: general request header format
43
44 ==== ===========================
45 Byte Value
46 ==== ===========================
47 0 Version (``0x01``)
48 1 Action
49 2 System (used crypto system)
50 3 8 bits root
51 4 8 bits configuration
52 5 8 bits parameter
53 6-7 16 bits parameter
54 8 8 bits parameter
55 ==== ===========================
56
57 .. _signer-nul-request-format:
58
59 Format of NUL requests
60 ----------------------
61
62 NUL requests are sent at the end of each iteration in
63 :ref:`client.pl <commmodule-client-pl>`'s main loop.
64
65 .. table:: NUL request header format
66
67 ==== ==================
68 Byte Value
69 ==== ==================
70 0 Version (``0x01``)
71 1 Action (``0x00``)
72 2 System (``0x00``)
73 3 ``0x00``
74 4 ``0x00``
75 5 ``0x00``
76 6-7 ``0x0000``
77 8 ``0x00``
78 ==== ==================
79
80 **NUL Request Payload:**
81
82 - GMT timestamp in %m%d%H%M%Y.%S format
83 - ""
84 - ""
85
86 .. note::
87
88 The timestamp sent with the NUL request is used to create a
89 script to synchronize the time on the signer using :program:`date` and
90 :program:`hwclock`.
91
92 .. _signer-x509-request-format:
93
94 Format of X.509 signing request messages
95 ----------------------------------------
96
97 X.509 signing request messages are sent in
98 :ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
99 certificate.
100
101 .. table:: X.509 certificate signing request header format
102
103 ==== ===================================================================
104 Byte Value
105 ==== ===================================================================
106 0 Version (``0x01``)
107 1 Action (``0x01``)
108 2 System (``0x01`` for X.509)
109 3 Root (see table :ref:`table-cert-roots`)
110 4 Profile (see table :ref:`table-cert-profiles`)
111 5 Message Digest Id (see table :ref:`table-md-ids`)
112 6-7 Days in big-endian format
113 8 Key type [#unused-server]_
114 ==== ===================================================================
115
116 The key type is stored in the column *keytype* of the certificate request
117 table which is one of
118
119 - *domaincerts*
120 - *emailcerts*
121 - *orgdomaincerts*
122 - *orgemailcerts*
123
124 **X.509 Signing Request Payload:**
125
126 - PEM encoded PKCS#10 / :rfc:`2986` certifcate signing request or SPKAC
127 (Netscape) signed public key and challenge (i.e. generated from a
128 `\<keygen\> HTML form element <keygen>`_)
129 - comma separated list of SubjectAlternative names in a format that is
130 accepted by openssl configuration file directive ``subjectAltName`` (see
131 https://www.openssl.org/docs/man1.0.2/apps/x509v3_config.html#Subject-Alternative-Name)
132 - The requested subject DN in openssl format (parts separated by ``/``)
133
134 .. _keygen: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/keygen
135
136 .. _table-cert-roots:
137
138 .. table:: CA root certificate identifiers
139
140 == =================================================
141 Id CA root
142 == =================================================
143 0 CAcert root (aka CAcert class 1 root)
144 1 CAcert class3
145 2 CAcert class3s
146 x root{}
147 == =================================================
148
149 .. note::
150
151 The CA root identifier is retrieved from the database by
152 :ref:`client.pl <commmodule-client-pl>` the value that is found there is
153 decremented by 1 before it is sent to the server.
154
155 The server in :ref:`server.pl <commmodule-server-pl>` restricts the allowed
156 root id in its ``CheckSystem`` function.
157
158 .. _table-cert-profiles:
159
160 .. table:: Certificate profile ids
161
162 == ======================
163 Id Profile
164 == ======================
165 0 Client (personal)
166 1 Client (Organization)
167 2 Client (Code signing)
168 3 Client (Machine)
169 4 Client (ADS)
170 5 Server (personal)
171 6 Server (Organization)
172 7 Server (Jabber)
173 8 Server (OCSP)
174 9 Server (Timestamp)
175 10 Proxy
176 11 SubCA
177 == ======================
178
179 .. note::
180
181 :ref:`client.pl <commmodule-client-pl>` supports profiles 0, 1, 2, 4,
182 5, 6, 8 and 9 only.
183
184 .. _table-md-ids:
185
186 .. table:: Message digest ids
187
188 == ==========
189 Id Algorithm
190 == ==========
191 1 MD5
192 2 SHA-1
193 3 RIPE-MD160
194 8 SHA-256
195 9 SHA-384
196 10 SHA-512
197 == ==========
198
199 .. _signer-openpgp-request-format:
200
201 Format of OpenPGP key signing request messages
202 ----------------------------------------------
203
204 OpenPGP key signing request messages are sent in
205 :ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
206 OpenPGP key.
207
208 .. table:: OpenPGP key signing request header format
209
210 ==== =============================
211 Byte Value
212 ==== =============================
213 0 Version (``0x01``)
214 1 Action (``0x01``)
215 2 System (``0x02`` for OpenPGP)
216 3 ``0x00``
217 4 ``0x00``
218 5 ``0x02`` [#unused-server]_
219 6-7 366 encoded as ``0x016e``
220 8 ``0x00``
221 ==== =============================
222
223 **OpenPGP Signing Request Payload:**
224
225 - OpenPGP public keyring in binary format (see :rfc:`4880`)
226 - ""
227 - ""
228
229 .. [#unused-server] the field is unused in
230 :ref:`server.pl <commmodule-server-pl>`
231
232 .. _signer-csr-request-format:
233
234 Format of X.509 certificate revocation request messages
235 -------------------------------------------------------
236
237 X.509 certificate revocation request messages are sent in
238 :ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
239 X.509 certificate revocation.
240
241 ==== ===========================
242 Byte Value
243 ==== ===========================
244 0 Version (``0x01``)
245 1 Action (``0x02``)
246 2 System (``0x01`` for X.509)
247 3 Root
248 4 ``0x00``
249 5 ``0x00``
250 6-7 365 encoded as ``0x016d``
251 8 ``0x00``
252 ==== ===========================
253
254 **X.509 Certificate Revocation Request Payload:**
255
256 - PEM encoded certificate data of the certificate to be revoked
257 - ""
258 - hexadecimal encoded SHA-1 hash of the CRL known CRL file of the requested
259 CA Root (header byte 3)
260
261 .. _signer-response-data-format:
262
263 Signer response data format specification
264 =========================================
265
266 Protocol response data is encoded in the following format:
267
268 .. table:: signer response message format:
269
270 ======= =======================================================
271 Byte Data
272 ======= =======================================================
273 0-2 length of header + data in network byte order
274 3-5 length of header network byte order
275 6-9 header data
276 10-12 length of payload data 1 in network byte order
277 13-N payload data 1
278 N+1-N+3 length of payload data 2 network byte order
279 N+4-M payload data 2
280 M+1-M+3 length of payload data 3 network byte order
281 M+4-End payload data 3
282 ======= =======================================================
283
284 General response header format
285 ------------------------------
286
287 Every protocol response header (bytes 6-9 of protocol response message)
288 follows the same 4 byte structure. The content of bytes 3 and 4 are not used
289 yet.
290
291 .. table:: general response header format
292
293 ==== ==================
294 Byte Value
295 ==== ==================
296 0 Version (``0x01``)
297 1 Action
298 2 ``0x00`` unused
299 3 ``0x00`` unused
300 ==== ==================
301
302 .. _signer-nul-response-format:
303
304 Format of NUL Responses
305 -----------------------
306
307 NUL responses are sent in response to
308 :ref:`NUL requests <signer-nul-request-format>`.
309
310 .. table:: NUL response header format
311
312 ==== ==================
313 Byte Value
314 ==== ==================
315 0 Version (``0x01``)
316 1 Action (``0x00``)
317 2 ``0x00`` unused
318 3 ``0x00`` unused
319 ==== ==================
320
321 **NUL Response Payload:**
322
323 - ""
324 - ""
325 - ""
326
327 Format of X.509 certificate response messages
328 ---------------------------------------------
329
330 X.509 certificate response messages are sent in response to
331 :ref:`X.509 certificate signing request messages <signer-x509-request-format>`.
332
333 .. table:: X.509 certificate response header format
334
335 ==== ==================
336 Byte Value
337 ==== ==================
338 0 Version (``0x01``)
339 1 Action (``0x01``)
340 2 ``0x00`` unused
341 3 ``0x00`` unused
342 ==== ==================
343
344 **X.509 certificate response payload:**
345
346 - PEM encoded X.509 certificate
347 - ""
348 - ""
349
350 .. _signer-openpgp-response-format:
351
352 Format of OpenPGP key signature response messages
353 -------------------------------------------------
354
355 OpenPGP key signature response messages are sent in response to
356 :ref:`OpenPGP key signing request messages <signer-openpgp-request-format>`.
357
358 .. table:: OpenPGP key signature response header format
359
360 ==== ==================
361 Byte Value
362 ==== ==================
363 0 Version (``0x01``)
364 1 Action (``0x02``)
365 2 ``0x00`` unused
366 3 ``0x00`` unused
367 ==== ==================
368
369 **OpenPGP key signature response payload:**
370
371 - ASCII armored PGP public key block
372 - ""
373 - ""
374
375 Format of X.509 certificate revocation response messages
376 --------------------------------------------------------
377
378 X.509 certificate revocation response messages are sent in response to
379 :ref:`X.509 certificate revocation request messages
380 <signer-csr-request-format>`.
381
382 .. table:: X.509 certificate revocation response header format
383
384 ==== =====================================
385 Byte Value
386 ==== =====================================
387 0 Version (``0x01``)
388 1 Action (``0x02``) [#overlap-openpgp]_
389 2 ``0x00`` unused
390 3 ``0x00`` unused
391 ==== =====================================
392
393 .. [#overlap-openpgp] this response type uses the same action byte as the
394 :ref:`OpenPGP key signature response message <signer-openpgp-response-format>`
395
396 **X.509 certificate revocation response payload:**
397
398 - CRL diff in :program:`xdelta` format or "" if the original CRL specified
399 by the SHA-1 hash in the third payload field of the request is not
400 available
401 - ""
402 - ""
403
404
405 Protocol messages
406 =================
407
408 .. _signer-message-handshake:
409
410 Handshake
411 ---------
412
413 #. client sends 1 byte ``0x02`` to serial port
414 #. client reads 1 byte from serial port (with a 20 second timeout)
415 #. client checks whether the byte is ``0x10``
416
417 .. seqdiag::
418
419 seqdiag handhake {
420 client -> server [label = "0x02"];
421 client <-- server [label = "0x10"];
422 }
423
424 If anything different is received there was a protocol error and no further
425 messages should be sent over the serial connection.
426
427 .. _signer-message-senddata:
428
429 Send data
430 ---------
431
432 :Preconditions:
433 successful :ref:`Handshake <signer-message-handshake>`,
434 data is encoded according to the :ref:`signer-request-data-format`
435
436 #. client builds byte wise xor of all data bytes into 1 byte $xor
437 #. client sends concatenated $data string + xor-Byte + "rie4Ech7"
438 #. client reads 1 byte (with a 5 second timeout)
439 #. if received byte is ``0x11`` try again
440 #. if received byte is ``0x10`` the message has been sent successfully
441
442 .. seqdiag::
443
444 seqdiag request_with_retry {
445 client -> client [label = "xor $data"];
446 client -> server [label = "$data . $xor . \"rie4Ech7\""];
447 server -> server [label = "detect corruption"];
448 client <-- server [label = "0x11"];
449 client -> server [label = "$data . $xor . \"rie4Ech7\""];
450 client <-- server [label = "0x10"];
451 }
452
453 If anything different is received there was a protocol error and no further
454 messages should be sent over the serial connection.
455
456 Receive data
457 ------------
458
459 :Preconditions:
460 client :ref:`sent data <signer-message-senddata>`
461
462 #. client waits for a response (with a 120 second timeout)
463 #. server builds byte wise xor of all data bytes in 1 byte $xor
464 #. server sends ``0x02`` to start transmission
465 #. client sends ``0x10`` to confirm receipt (server timeout 1 second)
466 #. server sends concatenated $data string + xor-Byte + "rie4Ech7"
467 #. client reads data in 100 byte segments (5 second timeout)
468 #. client sends ``0x11`` in case of corrupted data and retries reading
469 #. client sends ``0x10`` if successful
470 #. server waits for response for 5 seconds
471 #. server sends concatenated $data string + xor-Byte + "rie4Ech7" if client
472 response is ``0x11``
473
474 .. seqdiag::
475
476 seqdiag response_with_retry {
477 client -> server [label = "wait"];
478 server -> server [label = "xor $data"];
479 client <- server [label = "0x02"];
480 client --> server [label = "0x10"];
481 client <- server [label = "$data . $xor . \"rie4Ech7\""];
482 client -> client [label = "detect corruption"];
483 client --> server [label = "0x11"];
484 client <- server [label = "$data . $xor . \"rie4Ech7\""];
485 client --> server [label = "0x10"];
486 }