summaryrefslogtreecommitdiff
path: root/source/signer.rst
diff options
context:
space:
mode:
authorJan Dittberner <jandd@cacert.org>2018-10-28 19:22:32 +0100
committerJan Dittberner <jandd@cacert.org>2018-10-28 19:25:06 +0100
commitcff7cc67797d3b2a7ab03c6bf2b726d5725f26cd (patch)
treef51f20447c655dbd05873bcc27ae2443825e7496 /source/signer.rst
parente2045ba3c673588d80923e734d311e2a1b5b424a (diff)
downloadcacert-codedocs-cff7cc67797d3b2a7ab03c6bf2b726d5725f26cd.tar.gz
cacert-codedocs-cff7cc67797d3b2a7ab03c6bf2b726d5725f26cd.tar.xz
cacert-codedocs-cff7cc67797d3b2a7ab03c6bf2b726d5725f26cd.zip
Start documenting CommModule
- add a file meant to collect general observations - add a file meant to collect information related to the database schema - add a glossary file - add documentation for the CommModule files in source/directories.rst - start signer protocol specification in source/signer.rst - add support for block and sequence diagrams via sphinxcontrib-blockdiag and sphinxcontrib-seqdiag
Diffstat (limited to 'source/signer.rst')
-rw-r--r--source/signer.rst222
1 files changed, 222 insertions, 0 deletions
diff --git a/source/signer.rst b/source/signer.rst
new file mode 100644
index 0000000..299562a
--- /dev/null
+++ b/source/signer.rst
@@ -0,0 +1,222 @@
+===================
+The Signer Protocol
+===================
+
+Communication with the signer is performed via a serial connection. That has
+to be established by the client before speaking the protocol defined here.
+
+.. _signer-request-data-format:
+
+Signer request data format specification
+========================================
+
+Protocol data is encoded with the following format:
+
+.. table:: signer request message format
+
+ ======= ==============================================================
+ Byte Data
+ ======= ==============================================================
+ 0-2 length of header + data in network byte order
+ 3-12 action specific header
+ 13-15 length of first action specific content in network byte order
+ 15-N fist action specific content string
+ N+1-N+3 length of second action specific content in network byte order
+ N+4-M second action specific content string
+ M+1-M+3 lenght of third action specific content in network byte order
+ M+4-End third action specific content string
+ ======= ==============================================================
+
+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
+---------------------
+
+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.
+
+.. table:: general request header format
+
+ ==== =============================================================
+ Byte Value
+ ==== =============================================================
+ 0 Version (``0x01``)
+ 1 Action
+ 2 System (``0x01`` for :ref:`client.pl <commmodule-client-pl>`)
+ 3 8 bits root
+ 4 8 bits configuration
+ 5 8 bits parameter
+ 6-7 16 bits parameter
+ 8 8 bits parameter
+ ==== =============================================================
+
+.. _signer-nul-request-format:
+
+Format of NUL Requests
+----------------------
+
+NUL requests are sent at the end of each iteration in
+:ref:`client.pl <commmodule-client-pl>`'s main loop.
+
+.. table:: NUL request header format
+
+ ==== =========================================================
+ Byte Value
+ ==== =========================================================
+ 0 Version (``0x01``)
+ 1 Action ``0x00``
+ 2 System (``0x01`` for :ref:`client.pl <commmodule-client-pl>`)
+ 3 ``0x00``
+ 4 ``0x00``
+ 5 ``0x00``
+ 6-7 ``0x0000``
+ 8 ``0x00``
+ ==== =========================================================
+
+**NUL Request Payload:**
+
+- GMT timestamp in %m%d%H%M%Y.%S format
+- ""
+- ""
+
+Format of X.509 signing request messages
+----------------------------------------
+
+X.509 signing request messages are sent in
+:ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
+certificate.
+
+.. table:: X.509 certificate signing request header format
+
+ ==== =========================================================
+ Byte Value
+ ==== =========================================================
+ 0 Version (0x01)
+ 1 Action 0x01
+ 2 System (0x01 for :ref:`client.pl <commmodule-client-pl>`)
+ 3 Root
+ 4 Profile (see table :ref:`table-cert-profiles`)
+ 5 Message Digest Id (see table :ref:`table-md-ids`)
+ 6-7 Days in big-endian format
+ 8 Key type (``0x01`` for 'NS', ``0x00`` for others)
+ ==== =========================================================
+
+.. todo:: describe which root is identified by which root id
+
+The key type is stored in the column *keytype* of the certificate request
+table which is one of
+
+- *domaincerts*
+- *emailcerts*
+- *orgdomaincerts*
+- *orgemailcerts*
+
+.. todo:: describe what 'NS' means for key type
+
+
+**X.509 Signing Request Payload:**
+
+- "$content"
+- "$SAN"
+- "$subject"
+
+.. _table-cert-profiles:
+
+.. table:: Certificate profile ids
+
+ == ======================
+ Id Profile
+ == ======================
+ 0 Client (personal)
+ 1 Client (Organization)
+ 2 Client (Codesigning)
+ 3 Client (Machine)
+ 4 Client (ADS)
+ 5 Server (personal)
+ 6 Server (Organization)
+ 7 Server (Jabber)
+ 8 Server (OCSP)
+ 9 Server (Timestamp)
+ 10 Proxy
+ 11 SubCA
+ == ======================
+
+.. note::
+
+ :ref:`client.pl <commmodule-client-pl>` supports profiles 0, 1, 2, 4,
+ 5, 6, 8 and 9 only.
+
+.. _table-md-ids:
+
+.. table:: Message digest ids
+
+ == ==========
+ Id Algorithm
+ == ==========
+ 1 MD5
+ 2 SHA-1
+ 3 RIPE-MD160
+ 8 SHA-256
+ 9 SHA-384
+ 10 SHA-512
+ == ==========
+
+
+.. todo:: describe other request types
+
+.. _signer-response-data-format:
+
+Signer response data format specification
+=========================================
+
+.. todo:: describe signer response
+
+Protocol messages
+=================
+
+.. _signer-message-handshake:
+
+Handshake
+---------
+
+#. client sends 1 byte ``0x02`` to serial port
+#. client reads 1 byte from serial port (with a 20 second timeout)
+#. client checks whether the byte is ``0x10``
+
+.. seqdiag::
+
+ seqdiag handhake {
+ client -> server [label = "0x02"];
+ client <-- server [label = "0x10"];
+ }
+
+If anything different is received there was a protocol error and no further
+messages should be sent over the serial connection.
+
+Send data
+---------
+
+:Preconditions:
+ successful :ref:`Handshake <signer-message-handshake>`,
+ data is encoded according to the :ref:`signer-request-data-format`
+
+#. client builds byte wise xor of all data bytes into 1 byte $xor
+#. client sends concatenated $data string + xor-Byte + "rie4Ech7"
+#. client reads 1 byte (with a 5 second timeout)
+#. if received byte is ``0x11`` try again
+#. if received byte is ``0x10`` the message has been sent successfully
+
+.. seqdiag::
+
+ seqdiag with_retry {
+ client -> client [label = "xor $data"];
+ client -> server [label = "$data . $xor . \"rie4Ech7\""];
+ client <-- server [label = "0x11"];
+ client -> server [label = "$data . $xor . \"rie4Ech7\""];
+ client <-- server [label = "0x10"];
+ }
+
+If anything different is received there was a protocol error and no further
+messages should be sent over the serial connection.
+