diff options
Diffstat (limited to 'source/signer.rst')
| -rw-r--r-- | source/signer.rst | 222 |
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. + |