=================== The Signer Protocol =================== Communication with the signer is performed via a serial connection. That connection 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 (used crypto system) 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 `'s main loop. .. table:: NUL request header format ==== ================== Byte Value ==== ================== 0 Version (``0x01``) 1 Action (``0x00``) 2 System (``0x00``) 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 `'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 X.509) 3 Root (see table :ref:`table-cert-roots`) 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 [#unused-server]_ ==== =================================================================== The key type is stored in the column *keytype* of the certificate request table which is one of - *domaincerts* - *emailcerts* - *orgdomaincerts* - *orgemailcerts* **X.509 Signing Request Payload:** - PEM encoded PKCS#10 / :rfc:`2986` certifcate signing request or SPKAC (Netscape) signed public key and challenge (i.e. generated from a `\ HTML form element `_) - comma separated list of SubjectAlternative names in a format that is accepted by openssl configuration file directive ``subjectAltName`` (see https://www.openssl.org/docs/man1.0.2/apps/x509v3_config.html#Subject-Alternative-Name) - The requested subject DN in openssl format (parts separated by ``/``) .. _keygen: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/keygen .. _table-cert-roots: .. table:: CA root certificate identifiers == ================================================= Id CA root == ================================================= 0 CAcert root (aka CAcert class 1 root) 1 CAcert class3 2 CAcert class3s x root{} == ================================================= .. note:: The CA root identifier is retrieved from the database by :ref:`client.pl ` the value that is found there is decremented by 1 before it is sent to the server. The server in :ref:`server.pl ` restricts the allowed root id in its ``CheckSystem`` function. .. _table-cert-profiles: .. table:: Certificate profile ids == ====================== Id Profile == ====================== 0 Client (personal) 1 Client (Organization) 2 Client (Code signing) 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 ` 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 == ========== Format of OpenPGP key signing requests -------------------------------------- OpenPGP key signing requests are sent in :ref:`client.pl `'s main loop for each requested OpenPGP key. .. table:: OpenPGP key signing request header format ==== ============================= Byte Value ==== ============================= 0 Version (``0x01``) 1 Action (``0x01``) 2 System (``0x02`` for OpenPGP) 3 ``0x00`` 4 ``0x00`` 5 ``0x02`` [#unused-server]_ 6-7 366 encoded as ``0x016e`` 8 ``0x00`` ==== ============================= **OpenPGP Signing Request Payload:** - OpenPGP public keyring in binary format (see :rfc:`4880`) - "" - "" .. [#unused-server] the field is unused in :ref:`server.pl ` Format of X.509 certificate revocation requests ----------------------------------------------- .. Request($ver, 2, 1, $row{'rootcert'} - 1, 0, 0, 365, 0, $content, "", $revokehash); ==== =========================== Byte Value ==== =========================== 0 Version (``0x01``) 1 Action (``0x02``) 2 System (``0x01`` for X.509) 3 Root 4 ``0x00`` 5 ``0x00`` 6-7 365 encoded as ``0x016d`` 8 ``0x00`` ==== =========================== **X.509 Certificate Revocation Request Payload:** - PEM encoded certificate data of the certificate to be revoked - "" - hexadecimal encoded SHA-1 hash of the CRL known CRL file of the requested CA Root (header byte 3) .. _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 `, 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.