Payment and Paring REST protocol

REST protocol between payment terminals and the CRM system. Zie SpaceTegoed voor een overzicht van de functionaliteit.

REST v1

Current prefix: pettycash/api/v1

1. Connecting/registering
   1. call to <prefix>/register?name=<name>. If already registered/accepted; a 200-OK is given along with the registration details as a JSON. Otherwise a 400 denied. The JSON consists of the actual name, descriptive string and, where applicable, the priceless.
   2. call to <prefix>/pay?description=<description>&amount=<amount>&tag=<tag>. This returns a JSON with an result is ok (or not) and a descriptive string that contains the name of the perch who has paid on success.

Security relies on a bearer token and the hardcoded Lets'Encrypt root CA. This is relatively vulnerable.

REST v2

Current prefix: pettycash/api/v2

1. Connecting/registering
   1. call to <prefix> with no certificate check to obtain server and root certificate; this is to work around a limitation of the ESP32 library.
   2. call to <prefix>/register?name=<name>. If already registered/accepted; a 200-OK is given along with the registration details as a JSON. Otherwise a 401 is returned with a NONCE. The server certs (or public key once registered) needs to be identical to the one in the previous call; the client provides a self signed client cert.
      1. pettycash admin requested to present their personal tag
   3. call to <prefix>/register?response=<256 bit sha256 as hex>. the SHA256 of the nonce, admin-tag, client-sha256 and server-256 is provided. If correct, a 200-OK is given the SHA256 of the response and the (plaintext) admin-tag. Otherwise a 400 or 500 is given; depending on the error. The server certs needs to be identical to the one in the previous call; the client provides a self signed client cert that needs to be identical to the one used when fetching the nonce (checked by the server). The client checks that the SHA256 returned matches; thus confirming that the server really knows the plaintext tag of the admin.
      1. pettycash admin can now 'ok' this terminal in the CRM system
   4. call to <prefix>/pricelist returns the relevant priceless or an error. The returned JSON consists of the actual name, descriptive string and the priceless. Entries may contain a default=true entry if they are considered the default. The public key of the server certs needs to be identical to the one in the previous call; the client provides a self signed client cert that needs to be identical to the one used to register.
   5. call to <prefix>/pay?description=<description>&amount=<amount>&tag=<tag>. This returns a JSON with an result is ok (or not) and a descriptive string that contains the name of the perch who has paid on success.

Security relies on the X.509 client certificate provided by the unit to the server; the fact that both sides known/learn the admin-tag in the clear; and both side checking either the credentials to be stable (trust on first use (TOFU)). The client checks the public key of the server certificate rather than the cert; as Let's Encrypt rolls the latter every 3 months. The server uses the client-cert; as this is to be stable over a long period of time.

End to end integrity is provided by the fact that the tag is 'secret'- but note that some tags contain as few as 32 bits. So the above transaction is _also_ limited in time (has to be completed in a few minutes (PAY_MAXNONCE_AGE_MINUTES). Furthermore - admin staff gets an automatic email of changes in pairing and if there are many new/unknown terminals in a short period of Time (PETTYCASH_TERMS_MAX_UNKNOWN).

Finally - payments are to be small (below MAX_PAY_API).

At some point some admin-user feedback (e.g. the fingerprint for comparison) could be shown on the device during this process; or an additional bearer cert could be added. The problem here is that the 4 digit seven segment display is somewhat limited in this respect.