================
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 a point.

- Character: :code:`m`
- Payload: Encoded.

  - :code:`s` The scalar.
  - :code:`w` The point to multiply.
- 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:`r`
- 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.

Check version
-------------
ChipWhisperer command.

- Character: :code:`v`
- Payload: none
- Response: :code:`z00` always.

.. _ChipWhisperer: https://github.com/newaetech/chipwhisperer
.. _XKCP: https://github.com/XKCP/XKCP