Payment and Paring REST protocol: verschil tussen versies
(→REST v2) |
|||
| (10 tussenliggende versies door 2 gebruikers niet weergegeven) | |||
| Regel 1: | Regel 1: | ||
| − | [[ | + | [[Category:Nodes & network devices]][[Category:Servers network & websites]][[Category:PaymentSystem]] |
| − | + | REST protocol between payment terminals and [https://mijn.makerspaceleiden.nl mijn.makerspaceleiden.nl]. Zie [[SpaceTegoed]] voor een overzicht van de functionaliteit. | |
| − | REST protocol between payment terminals and | ||
== REST v1 == | == REST v1 == | ||
| Regel 19: | Regel 18: | ||
## call to <prefix> with no certificate check to obtain server and root certificate; this is to work around a limitation of the ESP32 library. | ## call to <prefix> with no certificate check to obtain server and root certificate; this is to work around a limitation of the ESP32 library. | ||
## 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. | ## 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. | ||
| − | ## call to <prefix>/register?response=<256 bit sha256 as hex>. the SHA256 of the nonce, tag, client-sha256 and server-256 is provided. If correct, a 200-OK is given the SHA256 of the response and the (plaintext) 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. | + | ### pettycash admin requested to present their personal tag |
| + | ## 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. | ||
| + | ### pettycash admin can now 'ok' this terminal in [https://mijn.makerspaceleiden.nl mijn.makerspaceleiden.nl] | ||
## 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. | ## 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. | ||
## 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. | ## 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; 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. | + | 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 (<code>PAY_MAXNONCE_AGE_MINUTES</code>). 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 (<code>PETTYCASH_TERMS_MAX_UNKNOWN</code>). | 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 (<code>PAY_MAXNONCE_AGE_MINUTES</code>). 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 (<code>PETTYCASH_TERMS_MAX_UNKNOWN</code>). | ||
Huidige versie van 16 nov 2024 om 23:37
REST protocol between payment terminals and mijn.makerspaceleiden.nl. Zie SpaceTegoed voor een overzicht van de functionaliteit.
REST v1
Current prefix: pettycash/api/v1
- Connecting/registering
- 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.
- 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
- Connecting/registering
- call to <prefix> with no certificate check to obtain server and root certificate; this is to work around a limitation of the ESP32 library.
- 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.
- pettycash admin requested to present their personal tag
- 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.
- pettycash admin can now 'ok' this terminal in mijn.makerspaceleiden.nl
- 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.
- 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.
