POST upload
Způsoby nahrání uživatelského programu do SDS přes web-POST
V současné době je implementace poskytnuta pouzde do SDS-BIG-512 a SDS-STSW-512. V budoucnu bude stejný protokol povolen i v dalších SDS (64,128 a řada ST).
Výchozí způsob nahrávání uživatelských řidících programů (SDSC, FULLC) a dalších prvků (UserWEB project) do SDS, je prováděn přes proprietární UDP protokol, skrze výrobcem dodávanou aplikaci (SDSC.exe, FULLC.exe, SDSLOAD.exe).
Toto řešení ale nelze vždy všude využít - čast v prostředí kde je přísný firewall co zahazuje UDP komunikaci, nebo při konfiguraci SDS které jsou za neprostupným NATem. Důvodů může být mnoho.
Jako vhodnou a bezpečnou alternativu nabízí SDS možnost nahrání své konfigurace a řídících programů (a UserWeb projektu) prostřednictvím autorizovaného HTTP POST.
Pozn. Speciální firmware pro BIG-512 bude poskytovat HTTPS POST - nicméně protokol API atd. uvnitř komunikace s webovém serverem v SDS bude stále zcela stejné..
Co se dá přes autorizovaný POST nahrát
1. [/changeip] změna konfigurace (IP atd.) 2. [/sv] FULL-C zápis do SharedVars - pouze SDS Druhé Produktové Řady ! 3. [/newsdsc] zápis nového SDSC programu - soubor .SCB - pouze SDS První Produktové Řady ! 4. [/newfullc] zápis nového FULLC programu - soubor .FCB - pouze SDS Druhé Produktové Řady ! 5. [/newuserweb] zápis nového UserWEB projektu - soubor .UWB 6. [/firmware] nahrání nového firmware pro SDS do paměti (a následná instalace)
Tyto prvky jsou vybrány tak, aby bylo také možné plně skriptovat "nahrávání" SDS, bez nutnosti uživatele použít GUI a ručně klikat atd.
Text v hranatých závorkách je příkaz, ten se musí zapsat za POST - tedy např. "POST /newfullc HTTP/1.1<cr><nl>" (první celý řádek hlavičky)
Pozn. Soubory .FCB a .UWB vygenerujete pomocí aplikaci FULLC.exe. Soubor .SCB pomocí aplikace SDSC.exe.
Zabezpečení
Dle průmyslového standardu, je vždy potřeba se, jako klient, vhodným způsobem autorizovat vůči serveru. Metoda také musí odpovídat průmyslovému standardu a být plně auditovatelná uživatelem (proto je i zde popsána). K dispozici jsou i vzorové příklady (např. aplikace se zdrojovým kódem).
SDS tedy vždy, pro každé jednotlivé spojení, vyžaduje novou unikátní autorizaci klienta.
Pro každé spojení SDS vygeneruje unikátní 256bit SALT, který není nikdy opakován (využívá se HW-RNG v SDS), a tento SALT je platný jen po dobu tohoto jednoho spojení (pro jeden příkaz).
Klient daný SALT přijme, provede s ním kryptografické operace (průmyslový standard saltování hesla: dvojitá SHA-256 operace).
Stejné operace provede i server u sebe, a jakmile klient pošle serveru svůj výsledek, server provede ověření (porovnání svého a zaslaného výsledku).
Pouze pokud klient zašle správný výsledek, znamená to, že klient zná identické heslo, jaké je nastaveno v SDS - a tedy může se pokračovat. Jinak je spojení ukončeno. Všechny pokusy jsou logovány.
Přenos na úrovni komunikace s webovým serverem není šifrován. Pokud je potřeba úplné šifrování, je využit TLS (nižší OSI7 vrstva) - pouze speciální firmware pro BIG-512.
Soubory .FCB (.SCB) a .UWB jsou zabezpečeny už při jejich vytvoření, takže jsou chráněny nejen při přenosu tímto protokolem, ale i v klidu např. na disku (zabezpečení je šifrováním a kontrolním podpisem detekujícím jakoukoliv změnu). Proto není potřeba je dodatečně při přenosu šifrovat (mimo eventuální TLS což ale genericky šifruje celý HTTP provoz, nicméně klient vždy odesílá soubory 1:1 tak jak je čte z disku - o tento detail mi teď šlo).
Detaily
Probíhat může vždy jen jedno spojení. Je to logické, pokud se nahrává program, nelze v prostředku nahrávání začít posílat jiný (musí se počkat až se původní činnost dokončí).
V takovém případě server informuje klienty v nových spojení že je BUSY a spojení uzavře. Je na klientovi počkat a zkusit znovu (za vhodný čas).
Protokol
Jedná se o standardní komunikaci s webovým serverem, kde je implementován specifický příkazový ping-pong. Na straně klienta ji lze realizovat libovolným způsobem, buď nějakou vaší knihovnou, nebo klidně prostřednictvím vlastního lowlevel kódu nad TCP socketem... důležité je dodržet dále popsanou specifikaci komunikace.
Klient otevře spojení, pošle HTTP hlavičku s POST (a příkazem), a pak provede autorizaci, a (pokud je autorizován) tak provede kroky k nahrání programu či aktualizaci konfigurace.
HTTP POST
client <-> server
-----------------------------------------------------------------------------------------------------------------------------------
[1] open TCP connection to HTTP server | <accept>
|
-+-
[2] send POST header + command name in URI |
|
POST /command HTTP/1.1<cr><nl> |
Host: 192.168.4.250<cr><nl> |
Content-Length: 12<cr><nl> |
<cr><nl> |
NoncePlease<cr><nl> |
|
-+-
| [3] response from server
|
| Nonce:HEXSTRING(32B)<cr><nl>
|
| or
|
| Busy:CLOSING<cr><nl>
| -> and closes the connection
|
-+-
[4] compute SHA-256 HASHes for SALTED-PWD | compute SHA-256 HASHes for SALTED-PWD
|
-+-
[5] send hash result to server |
|
Auth:SHA-256:HEXSTRING(32B)<cr><nl> |
|
-+-
| [6] response from server
|
| Auth:REJECTED<cr><nl>
| -> and closes the connection
|
| or
|
| Auth:CONTINUE<cr><nl>
|
-+-
[7] if Auth:CONTINUE, |
then |
client sends: |
START:START<cr><nl> |
|
-+-
| [8] server starts its internal process,
|
| *(a) for "newsdsc", "newfullc", "newuserweb", "firmware" commands,
| memory erase (this takes up to 45 seconds !) and client has to wait;
| once done, server sends:
|
| Erased:ReadyToWrite<cr><nl>
|
| or (for any error during the memory erase, or in presented data so far)
|
| Deny:UnableToEraseOrWrongContentLen<cr><nl>
| -> and closes the connection
|
| *(b) for the "changeip" and "sv" commands,
| server sends this:
|
| Status:ReadyToWrite<cr><nl>
|
| or (for any error in presented data so far)
|
| Deny:UnableToEraseOrWrongContentLen<cr><nl>
| -> and closes the connection
|
-+-
[9] only if the client gets the |
"Erased:ReadyToWrite" response |
(where required), |
or the "Status:ReadyToWrite" response; |
the client shall then send all |
the binary data |
|
client sends: raw binary data, do not encode | ... server receives all the data, and writes it to memory as it comes
| (server accepts binary data of size that equals to the Content-Length value)
note. Content-Length -> |
exact size of 'raw binary data' |
(do not include length of any data |
of the protocol itself) |
|
-+-
| [10] once all data are received (or during the transfer on any error), server sends:
|
| Done:result<cr><nl> -> and close connection
|
| or - (only specifically) for any mismatching data
| (again, this could happen any time during the trasnfer):
|
| Error:Rejected
|
|
----------
notes.
HEXSTRING(32B) = 64 characters, HEX16 encoded (each byte = 2 chars), fmt: 32 x "%02X" , no spaces , always uppercase
Done:result -> 'result' is textual printout of a uint32_t number
0 = OK
1..n = ERROR
Vzorový záchyt
Pro tento příklad, Heslo je nastaveno na tyto čtyři písmena:
test
Příkaz je:
/newfullc
Záchyt příkladu komunikace (wiresharkem): [C] = data od klienta, [S] = data ze serveru
[C] POST /newfullc HTTP/1.1 [C] Host: 192.168.4.250 [C] Content-Type: application/octet-stream [C] Content-Length: 2048 [C] [C] NoncePlease [S] Nonce:C5B2D98081FE6499E5AACDE7585BF6F545E1362BBD1B4A5E49346078667D898C [C] Auth:SHA-256:94419346948EC5D826E7D2AE0CF4F12CFE84EE29A37CBC48A68D3301EAD5865C [S] Auth:CONTINUE [C] START:START [S] Erased:ReadyToWrite [C] *******FCB-file-contents-1:1-sent-here---example-size:2048B******* [S] Done:0
Respektive jako hexdump z wiresharku (pro přehlednost jen do momentu kdy se začne odesílat .FCB z klienta na server):
00000000 50 4f 53 54 20 2f 6e 65 77 66 75 6c 6c 63 20 48 POST /ne wfullc H 00000010 54 54 50 2f 31 2e 31 0d 0a 48 6f 73 74 3a 20 31 TTP/1.1. .Host: 1 00000020 39 32 2e 31 36 38 2e 34 2e 32 35 30 0d 0a 43 6f 92.168.4 .250..Co 00000030 6e 6e 65 63 74 69 6f 6e 3a 20 6b 65 65 70 2d 61 nnection : keep-a 00000040 6c 69 76 65 0d 0a 43 6f 6e 74 65 6e 74 2d 54 79 live..Co ntent-Ty 00000050 70 65 3a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2f pe: appl ication/ 00000060 6f 63 74 65 74 2d 73 74 72 65 61 6d 0d 0a 43 6f octet-st ream..Co 00000070 6e 74 65 6e 74 2d 4c 65 6e 67 74 68 3a 20 32 30 ntent-Le ngth: 20 00000080 34 38 0d 0a 0d 0a 4e 6f 6e 63 65 50 6c 65 61 73 48....No ncePleas 00000090 65 0d 0a e.. 00000000 4e 6f 6e 63 65 3a 43 35 42 32 44 39 38 30 38 31 Nonce:C5 B2D98081 00000010 46 45 36 34 39 39 45 35 41 41 43 44 45 37 35 38 FE6499E5 AACDE758 00000020 35 42 46 36 46 35 34 35 45 31 33 36 32 42 42 44 5BF6F545 E1362BBD 00000030 31 42 34 41 35 45 34 39 33 34 36 30 37 38 36 36 1B4A5E49 34607866 00000040 37 44 38 39 38 43 0d 0a 7D898C.. 00000093 41 75 74 68 3a 53 48 41 2d 32 35 36 3a 39 34 34 Auth:SHA -256:944 000000A3 31 39 33 34 36 39 34 38 45 43 35 44 38 32 36 45 19346948 EC5D826E 000000B3 37 44 32 41 45 30 43 46 34 46 31 32 43 46 45 38 7D2AE0CF 4F12CFE8 000000C3 34 45 45 32 39 41 33 37 43 42 43 34 38 41 36 38 4EE29A37 CBC48A68 000000D3 44 33 33 30 31 45 41 44 35 38 36 35 43 0d 0a D3301EAD 5865C.. 00000048 41 75 74 68 3a 43 4f 4e 54 49 4e 55 45 0d 0a Auth:CON TINUE.. 000000E2 53 54 41 52 54 3a 53 54 41 52 54 0d 0a START:ST ART.. 00000057 45 72 61 73 65 64 3a 52 65 61 64 79 54 6f 57 72 Erased:R eadyToWr 00000067 69 74 65 0d 0a ite.. ... klient teď odesílá obsah .FCB, o velikosti 2048B viz Content-Length... 0000006C 44 6f 6e 65 3a 30 0d 0a Done:0..
Autorizační mechanismus
Základní popis:
HASH FUNCTION:
Nonce -> unqiue 32 bytes (represented as 64char hexstring) originated on server
(an always-random number, tied to each single TCP connection only - once closed, Nonce is invalid)
(new nonce is generated for every each new connection)
SHA-256 HASH result -> process:
1. Calculate SHA-256 hash of 'password' -> resultA[32]
2. Convert resultA[32] to a 64 character string -> textHashP[64]
3. Take 'salt' as 64 character string (exactly as it come) -> textSalt[64]
4. Concatenate textHashP with textSalt -> forHash[128]
5. Calculate SHA-256 hash of string forHash[64] -> resultH[32]
6. Convert resultH[32] to 64 character string -> transmitH[64]
7. Send transmitH[64] to server
Server and client does the same exact process, and if transmitH[64] is equal on both sides, server allows the client to continue
Doporučuji podívat se na zdrojové kódy příkladů, uvidíte sami jak jednoduchá a přímočará je implementace.
Proč se používá dvojitý hash ? Protože vám to umožní neukládat surové heslo ve vašem skriptu/programu, ale jen jeho hash. Tím se zabrání prozrazení čistého hesla při eventuálním úniku skriptu či programu. Ale tato realizace je už na vás.
Ukázky autorizace
Pro tento příklad, Heslo je nastaveno na tyto čtyři písmena:
test
Server poslal tento SALT (tedy obsah textSalt[64])
C5B2D98081FE6499E5AACDE7585BF6F545E1362BBD1B4A5E49346078667D898C
textHashP[64]
9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08
textSalt[64]
C5B2D98081FE6499E5AACDE7585BF6F545E1362BBD1B4A5E49346078667D898C
forHash[128]
9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08C5B2D98081FE6499E5AACDE7585BF6F545E1362BBD1B4A5E49346078667D898C
transmitH[64]
94419346948EC5D826E7D2AE0CF4F12CFE84EE29A37CBC48A68D3301EAD5865C
Tento příklad můžete použít jako referenci při odlaďování vaší implementace.
COMMAND: /changeip
Určeno k provedení změny konfigurace IP adres a dalších prvků, vše v jednom kroku.
TODO text
COMMAND: /sv
Určeno k zápisu do sdílených proměnných programu FULL-C.
TODO text
COMMAND: /newsdsc
Využito pro nahrání nového SDSC programu.
TODO text
COMMAND: /newfullc
Využito pro nahrání nového FULLC programu - ten je k dispozici formou obsahu .FCB souboru (tento soubor si vytvoříte ve FULLC.exe z vašeho zdrojového FULLC programu).
Hodnoty Done:X --------------- 0 = vše OK, nový program je v paměti SDS a je ihned spuštěn 1 = chyba při nahrávání (ukládání) do paměti - SDS je bez programu, žádný program není spuštěn (nahrejte nový správně)
TODO text
COMMAND: /newuserweb
Využito pro nahrání nového UserWeb projektu.
TODO text
COMMAND: /firmware
Využito pro nahrání nového firmware pro SDS.
Nahrát lze pouze odpovídající BIN soubor, vydaný výrobcem SDS.
Vzor očekávané komunikace (když je vše v pořádku):
[C] POST /firmware HTTP/1.1
[C] Host: 192.168.4.250
[C] Content-Type: application/octet-stream
[C] Content-Length: 424548
[C]
[C] NoncePlease
[S] Nonce:...text...
[C] Auth:SHA-256:...text...
[S] Auth:CONTINUE
[C] START:START
... SDS now erases the NVM memory block, this takes up to 45 seconds ...
[S] Erased:ReadyToWrite
[C] *******BIN-file-contents-1:1-sent-here---example-size:424548 bytes*******
[S] Done:0
Pokud nahrání proběhne jak má (včetně ihned následujícího ověření, uvnitŘ SDS, že nahraná data jsou platným firmware pro dané SDS), dojde k resetu zařízení SDS a instalaci tohoto nového firmware. Instalace se spustí okamžite po dokončení nahrávání (po odeslání "Done:0") - toto je potřeba vědět (např. pokud v SDS běží váš FULLC program, tak budu po dobu instalace vypnut, stejně tak jako např. všechny výstupy !!!).
Hodnoty Done:X --------------- 0 = vše OK, firmware nahrán do NVM a bude z ní obratem ihned instalován do SDS 1 = chyba při nahrávání (ukládání) do NVM - instalace nebude provedena 2 = jiná chyba - instalace nebude provedena
Zde je vzor komunikace - když je zasílaný soubor s firmware odmítnut (např. pošlete firmware který do daného typu SDS nepatří, tzn. firmware pro jiný typ SDS):
... (all same as previous example) [S] Erased:ReadyToWrite [C] *******BIN-file-contents-1:1-sent-here---example-size:424548 bytes******* [S] Error:Rejected
Všimněte si že místo "Done:X" je posláno "Error:Rejected" (a server ukončí spojení), a to obvykle hned po zaslání cca prvních dat z (nevhodného) bin souboru.