summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJan Dittberner <jandd@cacert.org>2018-10-28 23:38:37 +0100
committerJan Dittberner <jandd@cacert.org>2018-10-28 23:38:37 +0100
commit791e877a69a0a77ab38e5e065c6a942604b5fe94 (patch)
treeffcddc9b3296e2ef848aedf31eeb957dc7cdeda6
parenta6dc337f567f3d60e9b30475a1731b2b9a78e35e (diff)
downloadcacert-codedocs-791e877a69a0a77ab38e5e065c6a942604b5fe94.tar.gz
cacert-codedocs-791e877a69a0a77ab38e5e065c6a942604b5fe94.tar.xz
cacert-codedocs-791e877a69a0a77ab38e5e065c6a942604b5fe94.zip
Describe the missing parts of the signer protocol
-rw-r--r--source/signer.rst219
1 files changed, 205 insertions, 14 deletions
diff --git a/source/signer.rst b/source/signer.rst
index 1fb2b7e..1f8d969 100644
--- a/source/signer.rst
+++ b/source/signer.rst
@@ -11,7 +11,7 @@ defined here.
Signer request data format specification
========================================
-Protocol data is encoded with the following format:
+Protocol request data is encoded in the following format:
.. table:: signer request message format
@@ -31,11 +31,12 @@ Protocol data is encoded with the following format:
Due to the length encoding in 3 bytes the messages can have a maximum length
of 8\ :sup:`3` = 2\ :sup:`24` Bytes which is around 16 MiB.
-General header format
----------------------
+General request header format
+-----------------------------
-Every protocol header (bytes 3-12 of protocol message) follows the same 8 byte
-structure. The content of bits 3-8 are protocol action specific.
+Every protocol request header (bytes 3-12 of protocol request message) follows
+the same 9 byte structure. The content of bytes 3-8 are protocol action
+specific.
.. table:: general request header format
@@ -54,7 +55,7 @@ structure. The content of bits 3-8 are protocol action specific.
.. _signer-nul-request-format:
-Format of NUL Requests
+Format of NUL requests
----------------------
NUL requests are sent at the end of each iteration in
@@ -81,6 +82,14 @@ NUL requests are sent at the end of each iteration in
- ""
- ""
+.. note::
+
+ The timestamp sent with the NUL request is used to create a
+ script to synchronize the time on the signer using :program:`date` and
+ :program:`hwclock`.
+
+.. _signer-x509-request-format:
+
Format of X.509 signing request messages
----------------------------------------
@@ -186,10 +195,12 @@ table which is one of
10 SHA-512
== ==========
-Format of OpenPGP key signing requests
---------------------------------------
+.. _signer-openpgp-request-format:
+
+Format of OpenPGP key signing request messages
+----------------------------------------------
-OpenPGP key signing requests are sent in
+OpenPGP key signing request messages are sent in
:ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
OpenPGP key.
@@ -217,10 +228,14 @@ OpenPGP key.
.. [#unused-server] the field is unused in
:ref:`server.pl <commmodule-server-pl>`
-Format of X.509 certificate revocation requests
------------------------------------------------
+.. _signer-csr-request-format:
-.. Request($ver, 2, 1, $row{'rootcert'} - 1, 0, 0, 365, 0, $content, "", $revokehash);
+Format of X.509 certificate revocation request messages
+-------------------------------------------------------
+
+X.509 certificate revocation request messages are sent in
+:ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
+X.509 certificate revocation.
==== ===========================
Byte Value
@@ -247,7 +262,148 @@ Format of X.509 certificate revocation requests
Signer response data format specification
=========================================
-.. todo:: describe signer response
+Protocol response data is encoded in the following format:
+
+.. table:: signer response message format:
+
+ ======= =======================================================
+ Byte Data
+ ======= =======================================================
+ 0-2 length of header + data in network byte order
+ 3-5 length of header network byte order [#diff-to-request]_
+ 6-9 header data
+ 10-12 length of payload data 1 in network byte order
+ 13-N payload data 1
+ N+1-N+3 length of payload data 2 network byte order
+ N+4-M payload data 2
+ M+1-M+3 length of payload data 3 network byte order
+ M+4-End payload data 3
+ ======= =======================================================
+
+.. [#diff-to-request] this is a difference to the
+ :ref:`signer-request-data-format` that does not add the
+ length of the header
+
+General response header format
+------------------------------
+
+Every protocol response header (bytes 6-9 of protocol response message)
+follows the same 4 byte structure. The content of bytes 3 and 4 are not used
+yet.
+
+.. table:: general response header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action
+ 3 ``0x00`` unused
+ 4 ``0x00`` unused
+ ==== ==================
+
+.. _signer-nul-response-format:
+
+Format of NUL Responses
+-----------------------
+
+NUL responses are sent in response to
+:ref:`NUL requests <signer-nul-request-format>`.
+
+.. table:: NUL response header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action (``0x00``)
+ 3 ``0x00`` unused
+ 4 ``0x00`` unused
+ ==== ==================
+
+**NUL Response Payload:**
+
+- ""
+- ""
+- ""
+
+Format of X.509 certificate response messages
+---------------------------------------------
+
+X.509 certificate response messages are sent in response to
+:ref:`X.509 certificate signing request messages <signer-x509-request-format>`.
+
+.. table:: X.509 certificate response header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action (``0x01``)
+ 3 ``0x00`` unused
+ 4 ``0x00`` unused
+ ==== ==================
+
+**X.509 certificate response payload:**
+
+- PEM encoded X.509 certificate
+- ""
+- ""
+
+.. _signer-openpgp-response-format:
+
+Format of OpenPGP key signature response messages
+-------------------------------------------------
+
+OpenPGP key signature response messages are sent in response to
+:ref:`OpenPGP key signing request messages <signer-openpgp-request-format>`.
+
+.. table:: OpenPGP key signature response header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action (``0x02``)
+ 3 ``0x00`` unused
+ 4 ``0x00`` unused
+ ==== ==================
+
+**OpenPGP key signature response payload:**
+
+- ASCII armored PGP public key block
+- ""
+- ""
+
+Format of X.509 certificate revocation response messages
+--------------------------------------------------------
+
+X.509 certificate revocation response messages are sent in response to
+:ref:`X.509 certificate revocation request messages
+<signer-csr-request-format>`.
+
+.. table:: X.509 certificate revocation response header format
+
+ ==== =====================================
+ Byte Value
+ ==== =====================================
+ 0 Version (``0x01``)
+ 1 Action (``0x02``) [#overlap-openpgp]_
+ 3 ``0x00`` unused
+ 4 ``0x00`` unused
+ ==== =====================================
+
+.. [#overlap-openpgp] this response type uses the same action byte as the
+ :ref:`OpenPGP key signature response message <signer-openpgp-response-format>`
+
+**X.509 certificate revocation response payload:**
+
+- CRL diff in :program:`xdelta` format or "" if the original CRL specified
+ by the SHA-1 hash in the third payload field of the request is not
+ available
+- ""
+- ""
+
Protocol messages
=================
@@ -271,6 +427,8 @@ Handshake
If anything different is received there was a protocol error and no further
messages should be sent over the serial connection.
+.. _signer-message-senddata:
+
Send data
---------
@@ -286,9 +444,10 @@ Send data
.. seqdiag::
- seqdiag with_retry {
+ seqdiag request_with_retry {
client -> client [label = "xor $data"];
client -> server [label = "$data . $xor . \"rie4Ech7\""];
+ server -> server [label = "detect corruption"];
client <-- server [label = "0x11"];
client -> server [label = "$data . $xor . \"rie4Ech7\""];
client <-- server [label = "0x10"];
@@ -296,3 +455,35 @@ Send data
If anything different is received there was a protocol error and no further
messages should be sent over the serial connection.
+
+Receive data
+------------
+
+:Preconditions:
+ client :ref:`sent data <signer-message-senddata>`
+
+#. client waits for a response (with a 120 second timeout)
+#. server builds byte wise xor of all data bytes in 1 byte $xor
+#. server sends ``0x02`` to start transmission
+#. client sends ``0x10`` to confirm receipt (server timeout 1 second)
+#. server sends concatenated $data string + xor-Byte + "rie4Ech7"
+#. client reads data in 100 byte segments (5 second timeout)
+#. client sends ``0x11`` in case of corrupted data and retries reading
+#. client sends ``0x10`` if successful
+#. server waits for response for 5 seconds
+#. server sends concatenated $data string + xor-Byte + "rie4Ech7" if client
+ response is ``0x11``
+
+.. seqdiag::
+
+ seqdiag response_with_retry {
+ client -> server [label = "wait"];
+ server -> server [label = "xor $data"];
+ client <- server [label = "0x02"];
+ client --> server [label = "0x10"];
+ client <- server [label = "$data . $xor . \"rie4Ech7\""];
+ client -> client [label = "detect corruption"];
+ client --> server [label = "0x11"];
+ client <- server [label = "$data . $xor . \"rie4Ech7\""];
+ client --> server [label = "0x10"];
+ }