Rework client.

1 files changed, 178 insertions, 0 deletions

diff --git a/docs/commands.rst b/docs/commands.rst
new file mode 100644
index 0000000..9954832
--- /dev/null
+++ b/docs/commands.rst
@@ -0,0 +1,178 @@
+================
+Target interface
+================
+
+The implementations generated by **pyecsca** provide a serial
+interface somewhat adhering to the ChipWhisperer_ SimpleSerial interface.
+
+They provide 10 commands (some may be disabled). The commands
+all start with a single ASCII lowercase character and then a HEX
+payload, like::
+
+    i1234deadbeef
+
+Responses from the implementation are formatted in the same way, with
+the exception of the :code:`z` response, which is inherent to the SimpleSerial
+protocol and is send after every command finishes processing.
+
+Encoding
+========
+
+Payloads
+--------
+
+Command payloads are either raw, in which case the payload is an unformatted byte string, or they are encoded.
+
+Encoded payloads consist of a tree Name-Length-Value structure.
+
+**Name**: Single lowercase ASCII character, if it has the MSB set, it is a node in
+the tree which has children.
+
+**Length**: Single unsigned byte.
+
+**Value**: Either a byte string, if the node is a leaf, or a byte string which
+is an encoding of one or several Name-Length-Value structures.
+
+Points
+------
+
+Affine points are a structure of two coordinates, :code:`x` and :code:`y`.
+
+Points in implementation defined coordinate systems have different coordinate names.
+
+Integers
+--------
+
+Big-endian.
+
+Commands
+========
+
+Init PRNG
+---------
+
+Seeds the PRNG, which is a KeccakWidth200-SpongePRG, see Keccak XKCP_.
+
+- Character: :code:`i`
+- Payload: Raw. Any byte string.
+- Response: none
+
+Set curve
+---------
+
+Sets the curve.
+
+- Character: :code:`c`
+- Payload: Encoded.
+
+  - :code:`p` The prime.
+  - :code:`n` The order of the generator.
+  - :code:`h` The cofactor.
+  - :code:`g` The generator, in affine coordinates.
+  - :code:`i` The neutral point, in the implementation coordinates.
+  - The curve parameters (e.g. :code:`a`, :code:`b` for Short Weierstrass curves).
+- Response: none
+
+Generate keypair
+----------------
+
+Generates a keypair, requires a curve setup.
+
+- Character: :code:`g`
+- Payload: none
+- Response: Two responses.
+
+  - :code:`s` The generated private key.
+  - :code:`w` The generated public key, in affine coordinates.
+- Available if the :code:`keygen` option was enabled in the configuration.
+
+Set private key
+---------------
+
+Set the private key.
+
+- Character: :code:`s`
+- Payload: Encoded.
+
+  - :code:`s` The private key.
+- Response: none
+
+Set public key
+--------------
+
+Set the public key.
+
+- Character: :code:`w`
+- Payload: Encoded.
+
+  - :code:`w` The public key, in affine coordinates.
+- Response: none
+
+Perform scalar multiplication
+-----------------------------
+
+Perform scalar multiplication of the curve generator.
+
+- Character: :code:`m`
+- Payload: Encoded.
+
+  - :code:`s` The scalar.
+- Response:
+  - :code:`w` The resulting point, in the implementation coordinates.
+
+Perform ECDH
+------------
+
+Perform ECDH key agreement.
+
+- Character: :code:`e`
+- Payload: Encoded.
+
+  - :code:`w` The other public key.
+- Response:
+
+  - :code:`r` The (hashed) shared secret.
+- Available if the :code:`ecdh` option was enabled in the configuration.
+
+Sign with ECDSA
+---------------
+
+Sign a message with ECDSA.
+
+- Character: :code:`a`
+- Payload: Encoded.
+
+  - :code:`d` The message to sign.
+- Response:
+
+  - :code:`s` The signature, ASN.1 DER encoded SEQUENCE of two integers.
+- Available if the :code:`ecdsa` option was enabled in the configuration.
+
+Verify with ECDSA
+-----------------
+
+Verify a message signature with ECDSA.
+
+- Character: :code:`v`
+- Payload: Encoded.
+
+  - :code:`d` The message to verify.
+  - :code:`s` The signature, ASN.1 DER encoded SEQUENCE of two integers.
+- Response:
+
+  - :code:`r` The verification result, a single byte, :code:`1` on success, :code:`0` on failure.
+- Available if the :code:`ecdsa` option was enabled in the configuration.
+
+Debug
+-----
+
+Send back the implementation configuration (model and coordinate system).
+
+- Character: :code:`d`
+- Payload: none
+- Response:
+
+  - :code:`d` The model shortname and coordinate system name, ASCII, comma-separated.
+
+.. _ChipWhisperer: https://github.com/newaetech/chipwhisperer
+.. _XKCP: https://github.com/XKCP/XKCP
\ No newline at end of file