Dokument popisuje, aký certifikát je potrebné zabezpečiť, aby QASIDA API
mohla bežať na HTTPS.
QASIDA API beží ako Windows služba s vlastným web serverom (Kestrel) – nie pod IIS.
Nie je preto potrebné vytvárať žiadny IIS binding ani netsh http sslcert väzbu.
Kedy sa certifikát zadáva:
inštalátor nainštaluje API v režime HTTP a certifikát nezadáva.
Prechod na HTTPS – teda pripojenie certifikátu – a ďalšie úpravy nastavení sa vykonávajú po inštalácii prostredníctvom administračného rozhrania k API.
Tento dokument popisuje, aký certifikát si má zákazník zabezpečiť, aby ho v tom kroku bolo možné použiť.
| Možnosť | Kedy použiť |
|---|---|
A – PFX súbor (.pfx / .p12) |
Odporúčané. Certifikát dodaný certifikačnou autoritou ako súbor. |
| B – Windows úložisko certifikátov | Certifikát je už nainštalovaný na serveri (napr. vydaný firemnou CA / AD CS cez autoenrollment). |
Migrácia z IIS: ak na zadanom porte beží QASIDA API pod IIS, inštalátor zistí, aký certifikát je na binding-u nastavený, a zobrazí ho. Certifikát sa nepreberá – po inštalácii ho pripojíte cez administračné rozhranie k API. Podporované sú obe úložiská, ktoré IIS používa: Personal aj Web Hosting.
| Vlastnosť | Požiadavka |
|---|---|
| Typ | TLS/SSL serverový certifikát |
| Enhanced Key Usage (EKU) | Server Authentication – OID 1.3.6.1.5.5.7.3.1 (alebo certifikát bez EKU) |
| Key Usage | Digital Signature + Key Encipherment |
| Privátny kľúč | Musí byť súčasťou certifikátu. Bez privátneho kľúča sa služba nespustí. |
| Typ kľúča | RSA minimálne 2048 bit (odporúčame 3072/4096) alebo ECDSA P-256/P-384 |
| Podpisový algoritmus | SHA-256 alebo silnejší (SHA-1 nie) |
| Platnosť | Certifikát musí byť platný v čase inštalácie; odporúčame platnosť aspoň 1 rok |
| CN / SAN | Musí obsahovať názov, ktorým sa klienti na API pripájajú – viď nižšie |
Inštalátor zapíše adresu API do databázy (nastavenie QASIDA_API_BASE_URL) v tvare:
https://<KRÁTKE_WINDOWS_MENO_SERVERA>:<port>
kde <KRÁTKE_WINDOWS_MENO_SERVERA> je hodnota %COMPUTERNAME% (teda krátke meno servera,
nie FQDN). Klienti QASIDA sa potom pripájajú na túto adresu.
Preto musí SAN certifikátu obsahovať minimálne krátke meno servera. Odporúčame do SAN
zahrnúť všetky varianty:
DNS: SERVER – krátke meno servera (povinné, ak sa nezmení QASIDA_API_BASE_URL)DNS: server.domena.local – FQDN servera (odporúčané)DNS: alias – prípadný DNS alias, ak sa používaIP: 10.x.x.x – IP adresa servera (voliteľné, ak sa klienti pripájajú po IP)Krátke meno servera zistíte na serveri príkazom:
$env:COMPUTERNAME
Pozor pri certifikáte od verejnej CA: verejné certifikačné autority nesmú vydávať
certifikáty na interné názvy (krátke meno servera,.localdomény). V takom prípade sú
dve možnosti:
- použiť certifikát z firemnej/internej CA (AD CS), ktorý interné názvy obsahovať môže, alebo
- použiť verejný certifikát na FQDN a po inštalácii zmeniť nastavenie
QASIDA_API_BASE_URLv databáze nahttps://<FQDN>:<port>.Wildcard certifikát (
*.firma.sk) je použiteľný, ale pokrýva len FQDN v danej doméne –
nepokrýva krátke meno servera.
.pfx alebo .p12.C:\Qasida\Certs\qasida-api.pfx.C:\Qasida\QasidaAPI). Inštalátor tentoappsettings.json).NT SERVICE\AssecoQasidaAPI) musí mať na PFX súbor právo čítania.Pri PFX variante nemusí byť certifikát dôveryhodný na samotnom serveri – služba ho načíta
tak, ako je. Dôveryhodný musí byť na strane klientov, ktorí sa na API pripájajú.
Certifikát je nainštalovaný v úložisku počítača – Local Computer (Počítač) → Personal (Osobné)
(Cert:\LocalMachine\My) alebo Web Hosting (Cert:\LocalMachine\WebHosting, tam ho ukladá IIS).
Nie v úložisku aktuálneho používateľa (CurrentUser) – inštalátor to odmietne.
Certifikát má privátny kľúč uložený ako kľúč počítača (machine key set) v softvérovom
úložisku kľúčov, teda ako súbor v %ProgramData%\Microsoft\Crypto\Keys alebo
...\Crypto\RSA\MachineKeys. Inštalátor tomuto súboru prideľuje práva pre účet služby.
Certifikát je platný a dôveryhodný priamo na serveri:
Toto je striktná požiadavka: služba je nakonfigurovaná tak, že neplatný alebo
nedôveryhodný certifikát z úložiska odmietne načítať a nespustí sa. Self-signed
certifikát je preto v tejto variante použiteľný len vtedy, ak je zároveň vložený do
Trusted Root daného servera.
V danom úložisku smie byť len jeden certifikát s daným Subject/CN.
Ak sú tam dva (napr. starý a obnovený), môže služba načítať iný certifikát, než na ktorý
boli pridelené práva ku kľúču, a TLS spojenie zlyhá. Starý certifikát preto pri obnove
odstráňte.
.cer / .crt).| Situácia | Dôsledok |
|---|---|
Certifikát bez privátneho kľúča (.cer, .crt, .pem bez kľúča) |
Nedá sa použiť, treba PFX alebo import s kľúčom |
| PFX bez hesla | Nedá sa použiť, PFX musí mať neprázdne heslo |
| PFX v inštalačnom adresári API | Pri preinštalácii API sa vymaže, služba sa potom nespustí |
Certifikát v úložisku CurrentUser |
Nedá sa použiť, vyžaduje sa LocalMachine |
| Kľúč v HSM / TPM / na smart karte | Účtu služby sa nedá prideliť prístup ku kľúču |
| Expirovaný certifikát | Klienti odmietnu spojenie; pri variante B sa služba ani nespustí |
| Varianta B a nedôveryhodný / neúplný reťazec na serveri | Služba nenájde certifikát a nespustí sa |
| V SAN chýba názov, ktorým sa klienti pripájajú | Klienti hlásia nezhodu názvu certifikátu |
Dva certifikáty s rovnakým CN v LocalMachine\Personal |
Nestabilné TLS spojenie po inštalácii |
Na prvej obrazovke inštalátora:
Inštalátor certifikát nezadáva – nainštaluje API v režime HTTP. Po inštalácii je API dostupné na
http://<meno_servera>:<port> (štandardne port 8888) a dá sa otestovať na
http://<meno_servera>:<port>/health.
Certifikát sa pripája až potom, cez administračné rozhranie k API. Zákazník teda pred
inštaláciou nemusí mať certifikát pripravený; potrebný je až v momente prechodu na HTTPS.
Požiadavky z kapitol 2 – 5 platia nezmenene aj pre tento krok.
Nezabudnite po prechode na HTTPS upraviť nastavenie
QASIDA_API_BASE_URL(viď kapitola 2.1) – > inštalátor ho zapísal so schémouhttp://, takže klienti by sa naďalej pripájali nešifrovane.
Certifikát od CA nie je na inštaláciu potrebný – tá prebehne v režime HTTP. Ak chcete HTTPS
otestovať ešte pred vydaním ostrého certifikátu, self-signed certifikát si vytvorte na serveri
priamo (spustiť ako administrátor):
New-SelfSignedCertificate -DnsName $env:COMPUTERNAME, "$env:COMPUTERNAME.$env:USERDNSDOMAIN", "localhost" `
-CertStoreLocation Cert:\LocalMachine\My -KeyAlgorithm RSA -KeyLength 2048 `
-KeyUsage DigitalSignature, KeyEncipherment -TextExtension "2.5.29.37={text}1.3.6.1.5.5.7.3.1" `
-NotAfter (Get-Date).AddYears(2)
Aby ho služba z úložiska prijala, doplňte ho aj do Trusted Root daného servera (viď kapitola 4,
bod 3). Toto je vhodné len na testovanie alebo pre uzavreté interné prostredie – takémuto
certifikátu nebude dôverovať žiadny iný počítač, kým ho tam neimportujete manuálne.
Varianta A (PFX):
NT SERVICE\AssecoQasidaAPI má na nový súbor právo čítania –AssecoQasidaAPI.Varianta B (úložisko):
LocalMachine\Personal (resp. do pôvodného úložiska).Toto je možné poslať priamo CA / správcovi internej PKI:
Účel: TLS serverový certifikát pre webovú službu (REST API)
Subject (CN): server.domena.sk (FQDN servera)
Subject Alternative Names:
DNS: server.domena.sk (FQDN)
DNS: SERVER (krátke meno servera)
IP: 10.0.0.10 (voliteľné)
Enhanced Key Usage: Server Authentication (1.3.6.1.5.5.7.3.1)
Key Usage: Digital Signature, Key Encipherment
Kľúč: RSA 2048 bit (alebo viac)
Hash: SHA-256
Požadovaná forma dodania:
PKCS#12 súbor (.pfx) obsahujúci privátny kľúč a celý reťazec CA,
chránený neprázdnym heslom (heslo dodať samostatným kanálom)
Krátke meno servera, ktoré musí byť v SAN:
$env:COMPUTERNAME
Kontrola obsahu PFX súboru (vypíše certifikát aj to, či obsahuje privátny kľúč):
$pwd = Read-Host "Heslo k PFX" -AsSecureString
$data = Get-PfxData -FilePath 'C:\Qasida\Certs\qasida-api.pfx' -Password $pwd
$data.EndEntityCertificates | Format-List Subject, NotAfter, HasPrivateKey, Thumbprint
$data.OtherCertificates | Select-Object Subject # reťazec CA v PFX
Výpis SAN z certifikátu v PFX:
$data.EndEntityCertificates[0].Extensions |
Where-Object { $_.Oid.FriendlyName -like '*Alternative Name*' } |
ForEach-Object { $_.Format($true) }
Kontrola certifikátu v úložisku počítača (varianta B):
Get-ChildItem Cert:\LocalMachine\My |
Format-List Subject, NotAfter, HasPrivateKey, Thumbprint
Overenie, že certifikát z úložiska je platný a dôveryhodný pre TLS server
(musí vrátiť True, inak sa služba nespustí):
Test-Certificate -Cert Cert:\LocalMachine\My\<THUMBPRINT> -Policy SSL
Vytvorenie PFX, ak CA dodala certifikát a kľúč v PEM formáte (OpenSSL):
openssl pkcs12 -export -out qasida-api.pfx -inkey privkey.pem -in cert.pem -certfile chain.pem