.. _api_security:

===========
Zabezpečení
===========

Funkce REST API vyžadují autentizovaného uživatele.
Na základě autentizace je provedena autorizace k provedení
dané operace.

Systém podporuje dvě metody zabezpečení přístupu a autentizace:

 - :ref:`api_security_portal`
 - :ref:`api_security_apikey`

.. _api_security_portal:

Autentizace na Portálu NA ČR
============================

Systém CAM je jednou ze služeb tvořících Portál NA ČR.
Uživatelé Portálu mají přiřazeny role, které určují
možnost využívat jednotlivé služby. Pokud se uživatel přihlásí 
na Portál a má alespoň jednu roli pro CAM, tak může volat
požadované funkce.

V případě autentizace pomocí Portálu je každý požadavek
směrující na CAM obohacen o JWT token s informacemi o přihlášeném
uživateli.

Specifikace technického řešení zabezpečení Portálu je součástí 
jeho dokumentace, viz 
https://frnk.lightcomp.cz/download/nacr/ndais/doc/bezpecnost/portal_jwt.html.

.. _api_security_apikey:

Autentizace pomocí API Key
==========================

K autentizaci každého požadavku je možné použít API Key. 
Jedná se o dvojici identifikátoru klíče a tajnou hodnotou
klíče. Utajená hodnota slouží pro podepisování požadavků. 
Každý přijatý požadavek s tímto typem autentizace musí 
obsahovat potřebné informace ve svých hlavičkách.

API Key je tvořen dvojicí hodnot:

 - *identifikátor klíče* - UUID identifikující daný klíč
 - *hodnota klíče* - 40 znaků, které tvoří klíč, 
   znaky jsou v rozsahu [0-9][A-Z][a-z]

  Ke každému uživatelskému účtu je možné přiřadit více přístupových api klíčů.

Hlavičky požadavku
------------------

Zaslaný požadavek musí mít povinně uvedeny dvě hlavičky:

 - :token:`Authorization` - hlavička s informacemi o oprávnění
 - :token:`X-NDA-Date` - čas vzniku požadavku


.. _api_security_apikey_header_x_nda_date:

Hlavička X-NDA-Date
^^^^^^^^^^^^^^^^^^^

Hodnota obsahuje čas vzniku požadavku. Uvádí se čas UTC.

Formát: :token:`yyyymmddHHMMSS`

Příklad: *20190915215620*

Hodnota vstupuje do výpočtu hodnoty podpisu 
(viz :ref:`api_security_apikey_alg`) a čas vzniku požadavku
se nesmí příliš odlišovat od přesného času. Maximální 
povolená odchylka je 2 minuty.


Hlavička Authorization
^^^^^^^^^^^^^^^^^^^^^^

Hodnota obsahuje typ autentizace a sadu hodnot.

Příklad: *NDA-HMAC-SHA256 KeyId=29ca33ec-46bc-402d-b3bd-8d00d387842d,Signature=IT+NIJmiqm2QnB3nW3dqOwCip4z6TBYb9/y9SKv0xTc* 

Jako typ autentizace se uvádí: :token:`NDA-HMAC-SHA256`.

Po typu autentizace za mezerou následují čárkou oddělené hodnoty: 
:token:`KeyId=....` a :token:`Signature=...`. :token:`KeyId=....`
je identifikátor daného klíče, tj. jeho UUID. :token:`Signature=...`
je pomocí *base64* zakódovaný podpis požadavku.


.. _api_security_apikey_alg:

Způsob výpočtu podpisu požadavku
--------------------------------

Podpis je vygenerován podepsáním řetězce funkcí HMAC-SHA256 a 
zakódováním podpisu pomocí Base64. 

Do výpočtu podpisu požadavku vstupuje:

 #. hodnota z hlavičky host (cílový server)
 #. typ HTTP požadavku (GET, POST, ...)
 #. relativní část URL požadavku (cesta)
 #. parametry požadavku uváděné v URL
 #. hodnota z hlavičky X-NDA-Date

Části jsou zřetězeny jedna po druhé do řetězce
bez oddělovačů. Tento řetězec vstupuje do podepisovací 
funkce. Pořadí zřetězení je pevně dané.

Jako token:`secret` pro funkci HMAC-SHA256 slouží 
hodnota klíče.

.. _api_security_apikey_alg_ex1:

Příklad
^^^^^^^

API Key:

 - :token:`KeyId=29ca33ec-46bc-402d-b3bd-8d00d387842d`
 - hodnota: :token:`Pr3fxFN4dB5kMtqdRUzj5lHfJS61eATb5wCqUveb`

Dotaz na entitu číslo 100:

 - URL: :token:`https://portalvyvoj.nacr.cz/cam/entities/100`
 - Metoda: :token:`GET`
 - Čas položení dotazu: 2019-09-15 21:56:20

Řětězec pro podepsání:

.. code-block:: none

   HOST                  cesta            X-NDA-Date

   portalvyvoj.nacr.czGET/cam/entities/10020190915215620


Výsledek: :token:`IT+NIJmiqm2QnB3nW3dqOwCip4z6TBYb9/y9SKv0xTc`


.. _api_security_apikey_alg_ex2:

Příklad 2
^^^^^^^^^^^^^

Dotaz obsahující parametry se podepisuje tak, že se tyto
přidávají do podepisovaného řetězce bez oddělovače.

Pro dotaz metodou :token:`GET` na URL:

.. code-block:: none

    https://portalvyvoj.nacr.cz/cam/api/v1/updates?fromTransId=91812cb8-3519-4f78-b0ec-df6e951e2c7c&toTransId=356f9bdc-06a1-49a3-b373-d3ab8d5021d6&page=1&pageSize=10


Je podepisovaný řetězec:

.. code-block:: none

    portalvyvoj.nacr.czGET/cam/api/v1/updatesfromTransId=91812cb8-3519-4f78-b0ec-df6e951e2c7c&toTransId=356f9bdc-06a1-49a3-b373-d3ab8d5021d6&page=1&pageSize=1020190915215620