Asynchronní dešifrování souborů

Krok č. 1) Přihlášení

Pro přístup k API je nutné nejprve získat přístupový token pomocí koncového bodu pro přihlášení externího informačního systému pod identitou konkrétního uživatele.

Koncový bod: /api/sofa/v1/auth/extis/login-impersonate

Metoda: POST

Hlavičky:

  • Accept: application/json

  • Content-Type: application/json

Parametry:

  • login … uživatelské jméno externího informačního systému.

  • password … heslo externího informačního systému.

  • impersonateUserId … LDAP identifikátor uživatele, jehož identitou má externí informační systém vystupovat (návod na zjištění tohoto identifikátoru je uveden v kapitole Postupy).

Příklad:

POST /api/sofa/v1/auth/extis/login-impersonate HTTP/1.1
Host: sofaws.602.cz
Accept: application/json
Content-Length: …
Content-Type: application/json

{
  "login": "48a0ecdd540849f0af416307406467f0",
  "password": "wau3S99vx2d_NW2P",
  "impersonateUserId": "9e5f2f76-fff5-44c3-b943-06a95fdc08e2"
}

Výsledek:

{
  "token": "eyJhbGciOiJBMjU2…"
}

Krok č. 2) Nahrání souborů

V dalším kroku je nutné nahrát dokumenty jeden po druhém do výchozího úložiště (default) pomocí koncového bodu File API. Výsledkem bude seznam identifikátorů souborů použitý v dalším kroku.

Koncový bod: /api/sofa/v2/file?storeId=default

Metoda: POST

Hlavičky:

  • Accept: application/json

  • Authorization: Bearer <token>

  • Content-Type: multipart/form-data

Parametry:

  • file … soubor dokumentu

    Ve verzi 2.0 se již nepoužívá hlavička FileId s parametry kódovanými ve formátu JSON, ale přenáší se standardní cestou pro upload souborů podle RFC 2854, tzn. že se název souboru uvádí v hlavičce Content-Disposition, velikost souboru v hlavičce Content-Length a typ souboru v hlavičce Content-Type.

Příklad:

POST /api/sofa/v2/file?storeId=default HTTP/1.1
Host: sofaws.602.cz
Accept: application/json
Authorization: Bearer eyJhbGciOiJBMjU2…
Content-Length: …
Content-Type: multipart/form-data; boundary="-----086735ab-f408-405e-9628-4eb525d56d71"

-------086735ab-f408-405e-9628-4eb525d56d71
Content-Disposition: form-data; name="file"; filename="Document.pdf"
Content-Length: …
Content-Type: application/pdf

…binary file content…
-------086735ab-f408-405e-9628-4eb525d56d71--

Výsledek:

{
  "fileId": "eyJhbGciOiJIUzI1…"
}

Krok č. 3) Spuštění GraphQL mutace

Pro dešifrování dokumentů je nutné zavolat koncový bod GraphQL API s mutací pro dešifrování souborů, které předáme seznam identifikátorů dokumentů a parametry dešifrování. Výsledkem bude URL, pomocí které lze čekat na dokončení operace, viz následující krok.

Parametry dešifrování lze specifikovat globálně pro všechny dokumenty nebo samostatně pro každý dokument, případně lze kombinovat globální parametry s parametry jednotlivých dokumentů, přičemž parametry uvedené u jednotlivých dokumentů mají přednost před globálními parametry. Aktuálně jsou podporované následující parametry:

  • fileId … identifikátor souboru.

  • algorithmId … identifikátor algoritmu, např. SHA-256 nebo SHA-512 (výchozí hodnota: SHA-256).

  • certificateId … identifikátor certifikátu (HSM ID).

  • certificatePIN … PIN certifikátu.

Koncový bod: /api/sofa/v1/graphql

Metoda: POST

Hlavičky:

  • Accept: application/json

  • Authorization: Bearer <token>

  • Content-Type: application/json

GraphQL operace:

mutation decryptFiles(
  $files: [Signing_DecryptOperationParameters!]!
  $parameters: Signing_DecryptBatchParameters = null
) {
  signing {
    decryptFiles(files: $files, parameters: $parameters) {
      jobOperationUrl
      jobOperationIdent
    }
  }
}

Příklad:

POST /api/sofa/v1/graphql HTTP/1.1
Host: sofaws.602.cz
Accept: application/json
Authorization: Bearer eyJhbGciOiJBMjU2…
Content-Length: …
Content-Type: application/json

{
  "operationName": "decryptFiles",
  "query": "mutation decryptFiles(\n  $files: …",
  "variables": {
    "files": [
      {
        "fileId": "eyJhbGciOiJIUzI1…"
      }
    ],
    "parameters": {
      "algorithmId": null,
      "certificateId": "3fbc87f3-f5fb-4211-934a-881b76ca52b6-x3x",
      "certificatePIN": "12345"
    }
  }
}

Výsledek:

{
  "data": {
    "signing": {
      "decryptFiles": {
        "jobOperationUrl": "https:// sofa.602.cz/api/sofa/v1/operations/job?wait=true&operationToken=eyJhbGciOiJBMjU2…",
        "jobOperationIdent": "4118d157-9489-4b87-a5ab-a57711c4ce53"
      }
    }
  }
}

Krok č. 4) Čekání na dokončení operace

Před stažením dešifrovaných dokumentů je potřeba nejprve počkat na dokončení zpracování. K tomu slouží URL z výsledku GraphQL mutace z předchozího kroku, která vede na koncový bod Job Operations API, které slouží pro získání stavu probíhajících dlouhotrvajících operací. V případě zmíněné URL se pro zjednodušení jedná o synchronní volání, tzn. že koncový bod nevrací výsledek ihned, ale snaží se počkat co nejdéle na dokončení probíhající operace. V případě chyby, dokončení operace nebo vypršení časového limitu se vrátí výsledek, který obsahuje stavovou informaci (state), která může nabývat jednu z následujících hodnot:

  • done – operace byla úspěšně dokončena.

  • canceled – operace byla zrušena.

  • error – došlo k chybě.

  • pending – operace stále probíhá.

  • deleted - vypršela platnost operace (doba platnosti: 4 hodiny).

JSONPath pro získání stavu operace/podepisování:

$.state

JSONPath pro získání seznamu souborů (platné pouze pro stav done):

$.data.files

Kromě stavu pending jsou všechny ostatní stavy konečné, tzn. že nemá smysl koncový bod volat znovu. V případě úspěšného dokončení operace (done) se navíc vrací strukturovaná data ve formátu JSON, která obsahují výsledek operace obsahující identifikátory dešifrovaných dokumentů doplněné o identifikátory původních dokumentů kvůli spárování.

Koncový bod: /api/sofa/v1/operations/job

Metoda: GET

Hlavičky:

  • Authorization: Bearer <token>

Příklad:

GET /api/sofa/v1/operations/job?wait=true&operationToken=eyJhbGciOiJBMjU2…
Host: sofaws.602.cz
Authorization: Bearer eyJhbGciOiJBMjU2…

Výsledek v případě úspěšného dokončení operace:

{
  "id": "8e9f882e-6f2a-4ce7-ba50-a7e208729b43",
  "type": "signpoint-sdk",
  "state": "done",
  "data": {
    "files": [
      {
        "state": "done",
        "fileId": "eyJhbGciOiJIUzI1…",
        "resultFileId": "eyJhbGciOiJIUzI1…"
      }
    ]
}

Výsledek v případě stále probíhající operace:

{
  "id": "8e9f882e-6f2a-4ce7-ba50-a7e208729b43",
  "type": "signpoint-sdk",
  "state": "pending",
  "data": null
}

Výsledek v případě chyby:

{
  "id": "8e9f882e-6f2a-4ce7-ba50-a7e208729b43",
  "type": "signpoint-sdk",
  "state": "error",
  "data": null
}

Krok č. 5) Stažení souborů

Posledním krokem je stažení dešifrovaných souborů jeden po druhém pomocí koncového bodu File API:

Koncový bod: /api/sofa/v2/file

Metoda: GET

Hlavičky:

  • Authorization: Bearer <token>

Parametry:

  • fileId … identifikátor stahovaného dokumentu.

Příklad:

GET /api/sofa/v2/file?fileId=eyJhbGciOiJIUzI1…
Host: sofaws.602.cz
Authorization: Bearer eyJhbGciOiJBMjU2…

Výsledek:

Výsledkem je stahovaný dokument.

Název souboru lze získat buď standardně z hlavičky Content-Disposition, nebo File API v2 nastavuje pro snazší zpracování hlavičku X-Sofa-FileName.