TBC.OpenBanking.Jws

JSON ვებხელმოწერა ღია ბანკინგის გარემოში

საქართველოში განხორციელებულია საქართველოს კანონმდებლობასთან თავსებადი ღია ბანკინგის დანერგვა NextGenPSD2 XS2A ჩარჩოს საფუძველზე. ტექნიკური თვალსაზრისით ღია ბანკინგი წარმოადგენს RESTful API-ს, რომელსაც აქვეყნებს ანგარიშის მომსახურე საგადახდო მომსახურების პროვაიდერი (ამსმპ), ინგლისურად Account Servicing Payment Service Provider (ASPSP) და რომლის გამოყენებაც შეუძლია მესამე მხარის პროვაიდერს (მმპ), ინგლისურად Third Party Provider (TPP).

API-ს უსაფრთხოების მიზნით, სხვა საშუალებებთან ერთად, გამოყენებულია ციფრული ხელმოწერა. ღია ბანკინგის ფარგლებში ინფორმაციის გაცვლისას ნებისმიერი HTTP მოთხოვნა (Request) და პასუხი (Response) ციფრულად ხელმოწერილია შესაბამისი მომთხოვნის და მოპასუხეს მიერ. ხელმოწერა ხორციელდება "JSON ვებხელმოწერის (JWS) განხორციელების სახელმძღვანელო ღია ფინანსების სისტემაში" სახელმძღვანელოს მიხედვით, რომელიც თავის მხრივ ძირითადში ეფუძნება "Open Banking Europe. JSON Web Signature Profile for Open Banking" და "RFC 7515 - JSON Web Signature (JWS)"-ს.

რეპოზიტორი შეიცავს ორ ძირითად პროექტს და რამდენიმე მაგალითს

პროექტი TBC.OpenBanking.Jws

ეს არის ბიბლიოთეკა, რომლის დახმარებით ზემოხსენებული სტანდარტით შესაძლებელია HTTP მოთხოვნის და HTTP პასუხის მონაცემებზე ხელმოწერის შექმნა და არსებული ხელმოწერის შემოწმება.

ბიბლიოთეკა დაწერილია C#-ის პროგრამირების ენაზე და თავსებადია .NET Standard 2.0-თან. დამოკიდებულია მხოლოდ კომპანია Microsoft-ის წარმოებულ კომპონენტებზე.

ბიბლიოთეკის გამოყენების მაგალითი განთავსებულია აქ SampleConsole

პროექტი TBC.OpenBanking.Jws.Http

ეს არის ბიბლიოთეკა, რომელიც მნიშვნელოვნად ამარტივებს TBC.OpenBanking.Jws ბიბლიოთეკის გამოყენებას.

ბიბლიოთეკა დაწერილია C#-ის პროგრამირების ენაზე და თავსებადია .NET Standard 2.0-თან. დამოკიდებულია მხოლოდ კომპანია Microsoft-ის წარმოებულ კომპონენტებზე.

ბიბლიოთეკა შეიცავს ორ ძირითად კლასს

• class TBC.OpenBanking.Jws.Http.JwsMessageHandler DelegatingHandler-ის შვილობილი კლასი, რომელშიც განხორციელებულია TBC.OpenBanking.Jws-ის დახმარებით ღია ბანკინგის მოთხოვნების შესაბამისად HTTP მოთხოვნის ხელმოწერა და HTTP პასუხის ხელმოწერის შემოწმება
• class TBC.OpenBanking.Jws.Http.JwsClientOptions IOptions ინტერფეისის (Microsoft.Extensions.Options) იმპლემენტაციას, რომელიც გაძლევთ საშუალებას ხელმოწერის შექმნისათვის და შემოწმებისათვის საჭირო პარამეტრები მართოთ კონფიგურაციიდან

JwsMessageHandler-ის კლასი იძლევა საშუალებას ჩაჯდეთ Request-ის და Response-ის ჯაჭვში და შესაბამისად Request-ს დაადოთ ხელმოწერა, ხოლო Response-ს მოყოლილი ხელმოწერა შეამოწმოთ.

ბიბლიოთეკის გამოყენების მაგალითი განთავსებულია აქ WebApiHttpClientExample

მაგალითების პროექტები

რეპოზიტორიში მოცემულია სამი მაგალითი

SampleConsole

ეს არის TBC.OpenBanking.Jws ბიბლიოთეკის გამოყენების მაგალითი.

დამატებითი ფაილები:

• "HttpRequest-001.txt" – ტექსტური ფაილი, რომელიც შეიცავს სამაგალითო HTTP მოთხოვნას
• "HttpResponse-001.txt" – ტექსტური ფაილი რომელიც შეიცავს სამაგალითო HTTP პასუხს
• keyandcert.pfx – პირადი გასაღების და სერტიფიკატის შემცველი ფაილი. ეს გასაღები და სერტიფიკატი გამოიყენება ხელმოწერის შექმნისათვის და შემოწმებისათვის
• rootCACert.crt – ძირი სერტიფიკატი.

ყურადღება! იმისათვის, რომ პროგრამა უშეცდომოდ იმუშაოს, "rootCACert.crt" ფაილში განთავსებული სერტიფიკატი უნდა განვათავსოთ Windows-ის "Trusted Root Certificate Authorities"-ს სათავსში. საქმე იმაშია, რომ ხელმოწერის შემოწმებაში ასევე შედის იმ სერტიფიკატის შემოწმება, რომლის მეწყვილე პირადი გასაღებით შეიქმნა ხელმოწერა. სერტიფიკატის შემოწმებისას ასევე მოწმდება სანდოა თუ არა ამ სერტიფიკატის "მშობელი". თუ სერტიფიკატი არ არის სანდო, ხდება ხელმოწერის შემოწმების შეცდომა.

პროგრამის მუშაობის მიმდევრობა ასეთია:

1. პროგრამა კითხულობს პირად გასაღებს და სერტიფიკატს "keyandcert.pfx" ფაილიდან
2. HTTP მოთხოვნის ხელმოწერა
   1. პროგრამა კითხულობს და პარსავს "HttpRequest-001.txt" ფაილს. იღებს მოთხოვნის თავსართების (headers) და ტანის (body) შიგთავს
   2. მიღებული მონაცემებით და TBC.OpenBanking.Jws დახმარებით ქმნის მოთხოვნის ციფრულ ხელმოწერას
   3. ქმნის ხელმოწერილ მოთხოვნას – არსებულ მოთხოვნას ემატება ორი თავსართი: "digest", სადაც განთავსებულია ტანის ჰეში და "x-jws-signature", სადაც განთავსებულია ციფრული ხელმოწერა
   4. ხელმოწერილი მოთხოვნა ინახავს ფაილში "SignedRequest.txt"
3. ხელმოწერილი HTTP მოთხოვნის ხელმოწერის შემოწმება
   1. პროგრამა კითხულობს და პარსავს "SignedRequest.txt" ფაილს. იღებს მოთხოვნის თავსართების (headers) და ტანის (body) შიგთავს
   2. მიღებული მონაცემებით და TBC.OpenBanking.Jws დახმარებით ამოწმებს მოთხოვნის ციფრულ ხელმოწერას
4. HTTP პასუხის ხელმოწერა
   1. პროგრამა კითხულობს და პარსავს "HttpResponse-001.txt" ფაილს. იღებს მოთხოვნის თავსართების (headers) და ტანის (body) შიგთავს
   2. მიღებული მონაცემებით და TBC.OpenBanking.Jws დახმარებით ქმნის მოთხოვნის ციფრულ ხელმოწერას
   3. ქმნის ხელმოწერილ მოთხოვნას – არსებულ მოთხოვნას ემატება ორი თავსართი: "digest", სადაც განთავსებულია ტანის ჰეში და "x-jws-signature", სადაც განთავსებულია ციფრული ხელმოწერა
   4. ხელმოწერილი მოთხოვნა ინახავს ფაილში "SignedResponse.txt"
5. ხელმოწერილი HTTP პასუხის ხელმოწერის შემოწმება
   1. პროგრამა კითხულობს და პარსავს "SignedResponse.txt" ფაილს. იღებს მოთხოვნის თავსართების (headers) და ტანის (body) შიგთავს
   2. მიღებული მონაცემებით და TBC.OpenBanking.Jws დახმარებით ამოწმებს მოთხოვნის ციფრულ ხელმოწერას

როგორც ხედავთ, პროგრამაში გატარებულია ყველა ის ქმედება რაც შეიძლება დაგჭირდეთ TBC.OpenBanking.Jws გამოყენებისას

TBC.OpenBanking.Jws კლასების გამოყენება მაგალითის მიხედვით

HTTP მოთხოვნის ხელმოწერა

JWS სტანდარტით HTTP მოთხოვნის ხელმოსაწერად გვჭირდება რამდენიმე ნაბიჯი

1. მონაცემების შეგროვება, რომელსაც ხელი უნდა მოვაწეროთ(ამოკრეფილი HTTP მოთხოვნიდან) გამოიყენება კლასი TBC.OpenBanking.Jws.HttpRequestData
2. ხელმომწერი პირადი გასაღების შესაბამისი სერტიფიკატის და მისი მშობელი სერტიფიკატების, გარდა ძირი (root) სერტიფიკატისა, ჯაჭვის მიღება
3. ალგორითმის და პირადი გასაღების განსაზღვრა, რომლითაც ეწერება ხელი მონაცემებს გამოიყენება კლასი TBC.OpenBanking.Jws.SupportedAlgorithms
4. ზედა ბიჯების შედეგების გამოყენებით ხელმოწერის შექმნა და შედეგის HTTP მოთხოვნაში განთავსება გამოიყენება კლასი TBC.OpenBanking.Jws.HttpSigner

განხილვისთვის გამოვიყენოთ ამონარიდი მაგალითიდან.

private static void SignHttpRequestSample(
    string algorithmName,
    string inFileName,
    string outFileName,
    X509Certificate2 publicKeyCert,
    X509Certificate2 privateKeyCert,
    ILoggerFactory loggerFactory)
{
    try
    {
        // Get HttpRequestData from HTTP Request
        var httpData = ReadHttpRequestDataFromString(File.ReadAllText(inFileName));

        // Get certificate chain
        // If it is possible, better to cache chain, because chain creation is slow
        X509Certificate2Collection chainCertificates = GetCertificateChain(publicKeyCert);

        // Get ISigner
        var signer = SupportedAlgorithms.CreateSigner(privateKeyCert, algorithmName);

        // Create HttpSigner.
        // Need ISigner, certificate with signer's public key and
        // certificate chain in X509Certificate2Collection
        var reqSign = new HttpSigner<HttpRequestData>(loggerFactory.CreateLogger<HttpSigner<HttpRequestData>>())
        {
            Signer = signer,
            SignerCertificate = publicKeyCert,
            SignerCertificateChain = chainCertificates
        };

        // Create signature
        reqSign.CreateSignature(httpData);

        if (reqSign.IsSignatureCreated)
        {
            httpData.Headers.Add(HttpMessageData.DigestHeadertName, reqSign.DigestHeaderValue);
            httpData.Headers.Add(HttpMessageData.SignatureHeaderName, reqSign.SignatureHeaderValue);

            WriteHttpRequestDataToFile(httpData, outFileName);
        }
    }
    catch (Exception x)
    {
        Console.Error.WriteLine(x.ToString());
    }
}

<ins>პირველი ნაბიჯი</ins>: HttpRequestData კლასის ობიექტის შექმნა და შევსება. ხელმოწერისათვის საჭიროა HTTP მოთხოვნიდან HttpRequestData კლასის ობიექტში გადმოვიტანოთ ყველა თავსართი (header-ი), HTTP გამოძახების მეთოდი (post, get და ა.შ.) და HTTP გამოძახების შიგთავსი (body).

    // Get HttpRequestData from HTTP Request
    var httpData = ReadHttpRequestDataFromString(File.ReadAllText(inFileName));

<ins>მეორე ნაბიჯი</ins>: ვიღებთ ხელმომწერი პირადი გასაღების სერტიფიკატის მშობლებს (ძირი (root) სერტიფიკატის გარდა) და ვქმნით სერტიფიკატების ჯაჭვს. სერტიფიკატების ჯაჭვის შექმნის კოდი შეგიძლიათ ნახოთ GetCertificateChain ფუნქციაში.

    // Get certificate chain
    // If it is possible, better to cache chain, because chain creation is slow
    X509Certificate2Collection chainCertificates = GetCertificateCha