Describe the missing parts of the signer protocol
authorJan Dittberner <jandd@cacert.org>
Sun, 28 Oct 2018 22:38:37 +0000 (23:38 +0100)
committerJan Dittberner <jandd@cacert.org>
Sun, 28 Oct 2018 22:38:37 +0000 (23:38 +0100)
source/signer.rst

index 1fb2b7e..1f8d969 100644 (file)
@@ -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"];
+   }