Komunikácia

Všetka komunikácia v eOrdering API prebieha štandardným HTTPS pripojením, tj. pripojením zabezpečeným SSL certifikátom. PharmINFO používa výhradne certifikáty od dôveryhodných certifikačných autorít.

Autentifikácia

Autentifikácia voči API je založená na použití páru verejného a privátneho kľúča (access-key a private-key). Klient sa pri volaní API identifikuje verejným kľúčom a požiadavku podpíše privátny kľúčom použitím HMAC hešu.

Každý klient môže mať neobmedzené množstvo párov kľúčov. Každý z párov tak môže použiť v rôznych implementáciách API a v prípade kompromitovania jedného z párov, môže tento bez ovplyvnenia ostatných zakázať.

Viz tiež: HMAC: http://en.wikipedia.org/wiki/Hash-based_message_authentication_code

Podpis požiadavky

Každá požiadavka musí byť podpísaná známym a platným privátnym kľúčom. Podpis je prenášaný v HTTP hlavičke požiadavky. Ak nie je možné použiť HTTP hlavičku "Date" (.NET Framework 3.5 a nižšie), je možné použiť alternatívu "X-Date".

Authorization: verzia-autentifikacie access-key:podpis-hmac
Date: datum-poziadavky

Podpis požiadavky je generovaný zahešovaním textového reťazca použitím HMAC-SHA256 hešu a privátneho kľúča. Vstupný textový reťazec je vyskladaný nasledovne:

access-key\n
method\n
date\n
request-params

Pričom:

access-key je verejným kľúčom
method je použitá HTTP metóda GET, POST, PUT, DELETE
date je dátum odoslania požiadavky vo formáte RFC 1123, pričom hodnota sa môže odchyľovať od času servera o +/- 10 minút
request-params je z URL adresy vyskladaný reťazec zahŕňajúci cestu (bez adresy servera a protokolu) a alfanumericky zoradené parametre

Reťazec sa za použitia UTF-8 znakovej sady prekonvertuje na bajtové pole, to sa následne podpíše a výsledné dáta sa konvertujú na textový reťazec použitím Base64 kódovania.

Aktuálna verzia autentifikačného procesu je EOv1.

Viz tiež: RFC 1123 http://www.ietf.org/rfc/rfc1123.txt

Príklad

Nasledujúci príklad ilustruje autentifikáciu požiadavky pre získanie zoznamu dodávateľov (z adresy https://pharminfo.sk/eo/api.svc/json/suppliers?page=1&pageSize=100)

Verejný kľúč: j2SjQgX883bEn59Kpvds
Privátny kľúč: 5&6XMHG25$2t$^9h&F!7$m8&bDsQ5Q4NC@7#Xw@Nrj3N2N44@q
URI identifikujúca požadovaný prostriedok, v tomto prípade /eo/api.svc/json/suppliers?page=1&pageSize=100 v reálnej prevádzke iná.

Hotový reťazec pripravený na podpis teda môže vyzerať nasledovne

j2SjQgX883bEn59Kpvds\n
GET\n
Tue, 14 Sep 2013 10:02:21 GMT\n
/eo/api.svc/json/suppliers?page=1&pageSize=100

Vytvorenie autorizačného podpisu v C#

public static class Helper {

    /// 
    /// Vytvorenie autorizacneho podpisu pre poziadavku na eOrdering API.
    /// 
    /// Verejny kluc klienta.
    /// Pouzita HTTP metoda (GET, POST, PUT, DELETE).
    /// Datum a cas vytvorenia poziadavky podla RFC-1123.
    /// URI poziadavky.
    /// Privatny kluc klienta.
    /// 
    public static string CreateApiRequestSignature(string accessKey, string httpVerb, string requestDate, string requestUri, string privateKey)
    {
        var uri = new Uri(requestUri);

        // zoradenie parametrov z URI
        var requestParams = uri.AbsolutePath + UriHelper.ReorderQuery(uri.Query);

        // vyskladanie spravy pre zahesovanie
        var msgToHash = string.Format("{0}\n{1}\n{2}\n{3}", accessKey, httpVerb, requestDate, requestParams);

        // hes
        var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(privateKey));
        var hash = hmacsha256.ComputeHash(Encoding.UTF8.GetBytes(msgToHash));

        // vysledny podpis poziadavky
        return Convert.ToBase64String(hash);
    }
}

Výsledná požiadavka potom môže vyzerať nasledovne

GET https://pharminfo.sk/eo/api.svc/json/suppliers?page=1&pageSize=100 HTTP/1.1
Authorization: EOv1 j2SjQgX883bEn59Kpvds:ag1fjzEkeaxaG6q0kuhuHQgJ65OAMEZyU9kGkzex5DQ=
Date: Tue, 14 Sep 2013 10:02:21 GMT

alebo

curl -i -H "Authorization: EOv1 j2SjQgX883bEn59Kpvds:8vaNZ/3XWJ92+CRoDLZO4zO00BPGwvJkv4ktI9km0p8=" -H "Date: Wed, 02 Oct 2013 13:50:44 GMT" https://pharminfo.sk/eo/api.svc/json/suppliers?page=1&pageSize=100

Príklad v PowerShell

Generovanie podpisu v PowerShell

<#

Vytvorene podla https://www.pharminfo.sk/portal/eOrdering/api/security.html

Verejný kľúč: j2SjQgX883bEn59Kpvds
Privátny kľúč: 5&6XMHG25$2t$^9h&F!7$m8&bDsQ5Q4NC@7#Xw@Nrj3N2N44@q

Pri praci s textom je potrebne vsetky konverzie robit z (do) UTF-8!

Tento priklad je pisany v powershell scripte. Powershell znak pre "line feed" (novy riadok) je `n (v dokumentacii je uvedene vseobecne zname \n )

#>

# Ziskanie potrebnych vstupov

Write-Host "Zadaj access-key (verejny kluc):"
$msgAC = Read-Host

Write-Host "Zadaj method (GET, POST, PUT, DELETE):"
$msgM = Read-Host

Write-Host "Zadaj date (UTC vo formate RFC1123):"
$msgD = Read-Host

Write-Host "Zadaj request-params (uz zoradeny):"
$msgRP = Read-Host

# Vytvorenie textoveho retazca na podpisanie (pozor, powershell pouziva `n miesto \n)

$msgToHash = [System.String]::Format("{0}`n{1}`n{2}`n{3}", $msgAC, $msgM, $msgD, $msgRP);
Write-Host "`nPodpisovana sprava:`n----------------------"
Write-Host $msgToHash
Write-Host "----------------------"

# Ziskanie privatneho kluca a jeho konverzia na bytove pole

Write-Host "`nZadaj privatny kluc:"
$key = Read-Host
$keyBytes = [System.Text.Encoding]::UTF8.GetBytes($key)

# Vytvorenie instancie hmacsha256 utility z privatneho kluca

$hmacsha256 = [System.Security.Cryptography.HMACSHA256]::new($keyBytes)

# Vyratanie podpisanej spravy

$sign = [System.Convert]::ToBase64String($hmacsha256.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($msgToHash)))

Write-Host "`nPodpisana sprava:"
Write-Host $sign

# Cely podpis v hlavicke HTTP
$httpAuth = [System.String]::Format("EOv1 {0}:{1}", $msgAC, $sign)

Write-Host "`nHlavicka HTTP Authorization:"
Write-Host $httpAuth

stiahnuť príklad

Na testovanie môžete použiť tieto dáta:

Verejný kľúč:   j2SjQgX883bEn59Kpvds
HTTP metóda:    GET
Dátum:          Thu, 29 Dec 2016 13:50:23 GMT
Url paramtre:   /eo/api.svc/json/suppliers?page=1&pageSize=100

Privátny kľúč:  5&6XMHG25$2t$^9h&F!7$m8&bDsQ5Q4NC@7#Xw@Nrj3N2N44@q

Vo výsledku získate podpis:

v0+o6Pe9dUBHTMSG0C7PnDpBUwhfAOEvzJ3x6iQrZPc=

Stiahnutie zoznamu dodávateľov v PowerShell

<#

Vytvorene podla https://www.pharminfo.sk/portal/eOrdering/api/security.html

Verejný kľúč: j2SjQgX883bEn59Kpvds
Privátny kľúč: 5&6XMHG25$2t$^9h&F!7$m8&bDsQ5Q4NC@7#Xw@Nrj3N2N44@q

Pri praci s textom je potrebne vsetky konverzie robit z (do) UTF-8!

Tento priklad je pisany v powershell scripte. Powershell znak pre "line feed" (novy riadok) je `n (v dokumentacii je uvedene vseobecne zname \n )

#>

# Ziskanie potrebnych vstupov

Write-Host "Zadaj access-key (verejny kluc):"
$msgAC = Read-Host

# metoda je GET
$msgM = "GET"

# UTC cas formatovany podla RFC1123
$msgD = [System.DateTime]::UtcNow.ToString("r")

# poziadavka s zoradenymi parametrami
$msgRP = "/eordering-test-api-1.3/api.svc/json/suppliers?page=1&pageSize=100"

# Vytvorenie textoveho retazca na podpisanie (pozor, powershell pouziva `n miesto \n)

$msgToHash = [System.String]::Format("{0}`n{1}`n{2}`n{3}", $msgAC, $msgM, $msgD, $msgRP);
Write-Host "`nPodpisovana sprava:`n----------------------"
Write-Host $msgToHash
Write-Host "----------------------"

# Ziskanie privatneho kluca a jeho konverzia na bytove pole

Write-Host "`nZadaj privatny kluc:"
$key = Read-Host
$keyBytes = [System.Text.Encoding]::UTF8.GetBytes($key)

# Vytvorenie instancie hmacsha256 utility z privatneho kluca

$hmacsha256 = [System.Security.Cryptography.HMACSHA256]::new($keyBytes)

# Vyratanie podpisanej spravy

$sign = [System.Convert]::ToBase64String($hmacsha256.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($msgToHash)))

Write-Host "`nPodpisana sprava:"
Write-Host $sign

# Cely podpis v hlavicke HTTP
$httpAuth = [System.String]::Format("EOv1 {0}:{1}", $msgAC, $sign)

Write-Host "`nHlavicka HTTP Authorization:"
Write-Host $httpAuth

Invoke-RestMethod -Uri "https://www.pharminfo.sk$msgRP" -Headers @{ Authorization = $httpAuth; Date = $msgD }

stiahnuť príklad