Základní informace o connectorech

Každý connector implementuje rozhraní, které specifikuje jednotlivé komunikace s daným systémem. Je možno si pro vlastní potřeby vytvořit vlastní implementaci jednotlivých konektorů. Rozhraní pro konektory jsou specifikovány v namespace RaConnection.Abstraction.

Inicializace

Každá třída connetoru má konstruktor, který v parametrech přebírá položky, které se za života dané instance nemusí měnit.

CaConnector: ICaConnector:

public CaConnector(HttpClient httpClient, ILoggerFactory loggerFactory, string clientName, IGetReqIdCache? getReqIdCache, IGetCertCache? getCertCache, IGetProvCertCache? getProvCertCache)

BicaConnector: IBicaConnector:

public BicaConnector(ILoggerFactory loggerFactory, string clientName, HttpClient httpClient)

StorageConnector: IStorageConnector:

public StorageConnector(ILoggerFactory loggerFactory, string clientName, HttpClient httpClient)

Společné parametry connectorů:

• HttpClient httpClient - jedná se o instanci třídy HttpClient. Instance se používá na odesílání jednotlivých požadavků. Instanci není potřeba nastavovat žádné specifické hlavičky nebo další parametry. Vše si RaConnection nastaví automaticky v rámci tvorby http požadavku, který se v dané metodě posílá.
• string clientName - identifikace klientské aplikace, která daný systém volá. Doporučuje se uvádět název a verzi klientské aplikace. ClientName se odesílá na cílový systém a ten validuje, zda klientská aplikace může daný systém použít. ClientName se na cílovém systému validuje pomocí regulárního výrazu.
• ILoggerFactory loggerFactory - implementace poskytovatelé loggerů pro jednotlivé třídy. V rámci použití MS.Extensions.Logging a MS.Extensions.DependencyInjection v klientské aplikaci lze využít při vytváření IoC kontejneru metody .ConfigureLgging() a některého z existujících log providerů. V případě vlastního řešení je potřeba vytvořit vlastní implementaci rozhraní ILoggerFactory. Lze také do parametru předat hodnotu null (viz kapitola Logování).

CaConnector - specifické parametry:

CaConnector obsahuje ještě další parametry pro inicializaci cachování dotazů a odpovědí pro specifické komunikace. Více informací o možnosti cachování je dostupné v kapitole Metody třídy CaConnector, vždy u popisu metody, která cahchování umožňuje.

Vlastnosti nastavitelné za běhu klientské aplikace

Data předávané v parametrech nejsou dostačující aby bylo možné provádět jednotlivé komunikace. Všechny connectory ještě navíc obsahují vlastnosti, které je potřeba nastavit po získání instance a je možno je v průběhu běhu aplikace měnit. Jedná se o vlastnosti:

public string ServerUrl { get; set; }
public IOperatorSigner OperatorSigner { get; set; }
public int? RaCode { get; set; }
public AnswerFormatLanguages AnswerLanguage { get; set; } = AnswerFormatLanguages.cs;

• ServerUrl - specifikuje URL adresu daného systému (CA - QICA / SICA, BICA nebo STORAGE)
• OperatorSigner - implementace rozhraní IOperatorSigner, která jejímž úkolem je podepsat data předané na vstupu pomocí privátního klíče operátorského certifikátu. Více o podepisování požadavků je rozebráno v průběhu komunikace se systémy
• RaCode - jedinečný identifikátor RA
• AnswerLanguage - specifikace jazyka textových hlášek, které se můžou vyskytovat v odpovědích od systémů (např. informace o chybě).

Vlastnost ServerUrl musí být nastavena vždy. Vlastnosti OperatorSigner a RaCode jsou vyžadovány ve většině případů. Kde jsou tyto vlastnosti požadovány je detailně popsáno v následujících kapitolách.

Způsoby inicializace

Connnectory lze inicializovat klasickým způsobem, ale primárně jsou navrženy pro použití v kombinaci IoC a Dependency Injection od implementace Microsoft.Extensions.DependencyInjection, kdy se nejprve vloží do IoC instance třídy HttpClient a poté jednotlivé connectory.

Ukázka vložení do IoC:

services
    .AddSingleton<HttpClient>()
    .AddSingleton<ICaConnector, CaConnector>((services) =>
    {
        var httpClient = services.GetRequiredService<HttpClient>();
        var loggerFactory = services.GetRequiredService<ILoggerFactory>();
        var getReqIdCache = services.GetRequiredService<IGetReqIdCache>();
        var getCertCache = services.GetRequiredService<IGetCertCache>();
        var getProvCertCache = services.GetRequiredService<IGetProvCertCache>();

        return new CaConnector(httpClient, loggerFactory, _clientName, getReqIdCache, getCertCache, 
            getProvCertCache);
    })
    .AddSingleton<IBicaConnector, BicaConnector>((services) =>
    {
        var httpClient = services.GetRequiredService<HttpClient>();
        var loggerFactory = services.GetRequiredService<ILoggerFactory>();

        return new BicaConnector(loggerFactory, _clientName, httpClient);
    })
    .AddSingleton<IStorageConnector, StorageConnector>((services) =>
    {
        var httpClient = services.GetRequiredService<HttpClient>();
        var loggerFactory = services.GetRequiredService<ILoggerFactory>();

        return new StorageConnector(loggerFactory, _clientName, httpClient);
    });

Průběh komunikace se systémy I.CA

Komunikace mezi RA a CA probíhá pomocí XML. Knihovna RAConnection serializuje data dané komunikace do XML. Ze XML dat je potřeba vytvořit PKCS#7 data, které je poté potřeba podepsat certifikátem operátora.

Pro vytvoření PKCS#7 podepsaných dat obsahuje RAConnection rozhraní IOperatorSigner, které definuje metodu pro vytvoření a podepsání PKCS#7 dat. Instance IOperatorSigner se nachází ve všech třídách connectorů a je potřeba ji před použitím jednotlivých metod inicializovat vlastní implementací rozhraní IOperatorSigner nebo lze využít výchozí implementaci DefaultOperatorSigner.

K podepsaným PKCS#7 datům je poté přidán nepodepsaný atribut CodeRa (identifikační kód RA), následně je hodnota vložena do těla HTTP požadavku a ten je odeslán na cílový systém.

Všechny systémy I.CA vrací odpověď ve formátu XML. Pokud nenastane chyba při komunikaci se systémem a systém je funkční, HTTP odpověď má vždy HTTP status 200 se XML daty, které obsahují buď navrácená data nebo informace o chybě, která nastala při zpracování požadavku. Pokud odpověď obsahuje chybu, načtou se data o chybě, vytvoří se nová instance výjimky CAServerException, která se posléze vyhazuje. Pokud byl požadavek zpracován úspěšně, jsou data deserializovány do návratového objektu a předány jako výstup dané metody.

Logování

Logování je implementováno pomocí Microsoft.Extension.Logging.Abstraction (verze 7.0.1 >=). V případě používání jiného loggeru než od MS je potřeba naimplementovat vlastní implementaci třídy ILoggerFactory.

Pokud není ani jedna z variant možná, lze v konstruktorech connectorů do parametru pro ILoggerFactory předat hodnotu null. V takovém případě se využije implementace NullLoggerFactory a knihovna nebude logovat žádné informace.

Úrovně logování

• Information - obsahuje základní informace o průběhu volané metody, informace o odesílaném HTTP požadavku (URL adresa, HTTP metoda apod.), základní informace o HTTP odpovědi, detailní informace o chybách.
• Debug - obsahuje to samé jako je uvedeno v Information, a navíc také loguje xml a poté pkcs#7 jednotlivých dotazů a xml odpověď přijatou od cílového systému