diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index b5ac140..630966f 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -32,7 +32,7 @@ jobs: mv site ../_site - name: Copy shared files run: | - for dir in domain nginx apache; do + for dir in domain nginx apache iis; do mkdir -p $dir/_includes cp _includes/head_custom.html $dir/_includes/head_custom.html done @@ -51,6 +51,11 @@ jobs: with: source: ./apache destination: ./_site/apache + - name: Build iis page docs + uses: actions/jekyll-build-pages@v1 + with: + source: ./iis + destination: ./_site/iis - name: Upload artifact uses: actions/upload-pages-artifact@v5 diff --git a/README.md b/README.md index 7ecbf1e..fdcfa66 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ * [Domain Controller Configuration](http://open-eid.github.io/domain) * [Apache2 SSL Configuration](http://open-eid.github.io/apache) * [Nginx SSL Configuration](http://open-eid.github.io/nginx) + * [IIS SSL Configuration](http://open-eid.github.io/iis) ## Editing and building "Architecture of ID-software" @@ -64,6 +65,22 @@ pandoc nginx/index.md -L kramdown-toc.lua -o nginx_SSL_EN.pdf pandoc nginx/index.et.md -L kramdown-toc.lua -o nginx_SSL_ET.pdf ``` +## Editing and building "IIS SSL Configuration" + +Uses https://jekyllrb.com and https://just-the-docs.com styles for generating documentation. + +1. Update source files in iis/ + +2. Build PDF document + +```bash +# Export English version +pandoc iis/index.md -L kramdown-toc.lua -o iis_SSL_EN.pdf + +# Export Estonian version +pandoc iis/index.et.md -L kramdown-toc.lua -o iis_SSL_ET.pdf +``` + ## Support Official builds are provided through official distribution point [id.ee](https://www.id.ee/en/article/install-id-software/). If you want support, you need to be using official builds. Contact our support via www.id.ee for assistance. diff --git a/iis/_config.yml b/iis/_config.yml new file mode 100644 index 0000000..d1a1dcc --- /dev/null +++ b/iis/_config.yml @@ -0,0 +1,7 @@ +remote_theme: just-the-docs/just-the-docs +title: Estonian eID IIS Configuration +description: Technical documentation for configuring IIS to support Estonian Digital ID-card for authentication. +google_analytics: +layout: minimal +nav_enabled: false +baseurl: "/iis" diff --git a/iis/img/image1.png b/iis/img/image1.png new file mode 100644 index 0000000..f456858 Binary files /dev/null and b/iis/img/image1.png differ diff --git a/iis/img/image10.png b/iis/img/image10.png new file mode 100644 index 0000000..b49c7e3 Binary files /dev/null and b/iis/img/image10.png differ diff --git a/iis/img/image11.png b/iis/img/image11.png new file mode 100644 index 0000000..b331287 Binary files /dev/null and b/iis/img/image11.png differ diff --git a/iis/img/image12.png b/iis/img/image12.png new file mode 100644 index 0000000..1c4eec8 Binary files /dev/null and b/iis/img/image12.png differ diff --git a/iis/img/image13.png b/iis/img/image13.png new file mode 100644 index 0000000..5039787 Binary files /dev/null and b/iis/img/image13.png differ diff --git a/iis/img/image14.png b/iis/img/image14.png new file mode 100644 index 0000000..d2e5f1b Binary files /dev/null and b/iis/img/image14.png differ diff --git a/iis/img/image15.png b/iis/img/image15.png new file mode 100644 index 0000000..39a0a96 Binary files /dev/null and b/iis/img/image15.png differ diff --git a/iis/img/image16.png b/iis/img/image16.png new file mode 100644 index 0000000..d1fdf66 Binary files /dev/null and b/iis/img/image16.png differ diff --git a/iis/img/image17.png b/iis/img/image17.png new file mode 100644 index 0000000..e100a13 Binary files /dev/null and b/iis/img/image17.png differ diff --git a/iis/img/image18.png b/iis/img/image18.png new file mode 100644 index 0000000..0455c31 Binary files /dev/null and b/iis/img/image18.png differ diff --git a/iis/img/image19.png b/iis/img/image19.png new file mode 100644 index 0000000..5a20dde Binary files /dev/null and b/iis/img/image19.png differ diff --git a/iis/img/image2.png b/iis/img/image2.png new file mode 100644 index 0000000..bf50515 Binary files /dev/null and b/iis/img/image2.png differ diff --git a/iis/img/image20.png b/iis/img/image20.png new file mode 100644 index 0000000..e2b45bd Binary files /dev/null and b/iis/img/image20.png differ diff --git a/iis/img/image21.png b/iis/img/image21.png new file mode 100644 index 0000000..86d8b28 Binary files /dev/null and b/iis/img/image21.png differ diff --git a/iis/img/image22.png b/iis/img/image22.png new file mode 100644 index 0000000..74def95 Binary files /dev/null and b/iis/img/image22.png differ diff --git a/iis/img/image23.png b/iis/img/image23.png new file mode 100644 index 0000000..3045b5b Binary files /dev/null and b/iis/img/image23.png differ diff --git a/iis/img/image24.png b/iis/img/image24.png new file mode 100644 index 0000000..70204e6 Binary files /dev/null and b/iis/img/image24.png differ diff --git a/iis/img/image25.png b/iis/img/image25.png new file mode 100644 index 0000000..a570bc2 Binary files /dev/null and b/iis/img/image25.png differ diff --git a/iis/img/image26.png b/iis/img/image26.png new file mode 100644 index 0000000..3c28643 Binary files /dev/null and b/iis/img/image26.png differ diff --git a/iis/img/image27.png b/iis/img/image27.png new file mode 100644 index 0000000..eadc1de Binary files /dev/null and b/iis/img/image27.png differ diff --git a/iis/img/image28.png b/iis/img/image28.png new file mode 100644 index 0000000..1ea22c1 Binary files /dev/null and b/iis/img/image28.png differ diff --git a/iis/img/image29.png b/iis/img/image29.png new file mode 100644 index 0000000..d3812b3 Binary files /dev/null and b/iis/img/image29.png differ diff --git a/iis/img/image3.png b/iis/img/image3.png new file mode 100644 index 0000000..2f6665f Binary files /dev/null and b/iis/img/image3.png differ diff --git a/iis/img/image30.png b/iis/img/image30.png new file mode 100644 index 0000000..82b5bdf Binary files /dev/null and b/iis/img/image30.png differ diff --git a/iis/img/image31.png b/iis/img/image31.png new file mode 100644 index 0000000..030a2aa Binary files /dev/null and b/iis/img/image31.png differ diff --git a/iis/img/image32.png b/iis/img/image32.png new file mode 100644 index 0000000..d428290 Binary files /dev/null and b/iis/img/image32.png differ diff --git a/iis/img/image33.png b/iis/img/image33.png new file mode 100644 index 0000000..6eb8838 Binary files /dev/null and b/iis/img/image33.png differ diff --git a/iis/img/image34.png b/iis/img/image34.png new file mode 100644 index 0000000..edaf61d Binary files /dev/null and b/iis/img/image34.png differ diff --git a/iis/img/image4.png b/iis/img/image4.png new file mode 100644 index 0000000..84269b0 Binary files /dev/null and b/iis/img/image4.png differ diff --git a/iis/img/image5.png b/iis/img/image5.png new file mode 100644 index 0000000..454502e Binary files /dev/null and b/iis/img/image5.png differ diff --git a/iis/img/image6.png b/iis/img/image6.png new file mode 100644 index 0000000..49c4a23 Binary files /dev/null and b/iis/img/image6.png differ diff --git a/iis/img/image7.png b/iis/img/image7.png new file mode 100644 index 0000000..6cfda4d Binary files /dev/null and b/iis/img/image7.png differ diff --git a/iis/img/image8.png b/iis/img/image8.png new file mode 100644 index 0000000..85dd079 Binary files /dev/null and b/iis/img/image8.png differ diff --git a/iis/img/image9.png b/iis/img/image9.png new file mode 100644 index 0000000..4b4638e Binary files /dev/null and b/iis/img/image9.png differ diff --git a/iis/index.et.md b/iis/index.et.md new file mode 100644 index 0000000..b497e9a --- /dev/null +++ b/iis/index.et.md @@ -0,0 +1,351 @@ +# IIS veebiserverile ID-kaardi toe seadistamine + +**[In English](index.md)** + +**Versioon:** 26.04/1 + +**Väljaandja:** [RIA](https://www.ria.ee/) + +**Versiooni info** + +| Kuupäev | Versioon | Muutused/märkused +|:-----------|:--------:|:----------------------------------------------------------- +| 21.01.2019 | 19.01/1 | Avalik versioon, baseerub `18.12` tarkvaral. +| 12.02.2019 | 19.02/1 | Lisatud OCSP konfiguratsioonivõimalused. — Muutja: Urmas Vanem +| 01.10.2019 | 19.10/1 | Lisatud info Windows serveri (IIS) paranduste staatuse ja tulevase kättesaadavuse osas versioonide lõikes. Vt. sissejuhatuse viimane lõik. — Muutja: Urmas Vanem +| 18.10.2019 | 19.10/2 | Kirjeldatud Windows Server 2016 uuendus `KB4516061`, mis lahendab Chrome-IIS probleemi. — Muutja: Urmas Vanem +| 08.11.2019 | 19.11/1 | Kirjeldatud Windows Server 2019 uuendus `KB4520062`, mis lahendab Chrome-IIS probleemi. — Muutja: Urmas Vanem +| 14.11.2019 | 19.11/2 | Kirjeldatud Windows Server 1903 (SAC) uuendus `KB4524570`, mis lahendab Chrome-IIS probleemi. — Muutja: Urmas Vanem +| 12.12.2019 | 19.12/1 | Lisatud soovitused IIS'i turvamiseks. — Muutja: Urmas Vanem +| 14.12.2020 | 20.12/1 | Lisatud turvasätted ebasoovitavate CA-de ligipääsu piiramiseks. — Muutja: Urmas Vanem +| 17.12.2020 | 20.12/2 | Lisatud mõned turvasoovitused peatükki „Ebavajalike CA-de juurdepääsu piiramine". — Muutja: Urmas Vanem +| 03.03.2021 | 21.03/1 | Eemaldatud aegunud IIS ja Google Chrome autentimise probleem ning täpsustatud infot. — Muutja: Kristjan Vaikla +| 30.04.2021 | 21.04/1 | Eemaldatud aegunud `ESTEID-SK 2011` sertifikaatide tugi. — Muutja: Urmas Vanem +| 14.12.2021 | 21.12/1 | Muudetud Windows platvorm versioonile Server 2022. Lisatud kolmandalt osapoolelt ECDSA algoritmil põhineva sertifikaadi päringu protseduur. Täiendatud on TLS ja Cipher soovitusi. — Muutja: Urmas Vanem +| 18.01.2022 | 22.01/1 | Lisatud Windows Server 2022 ja `TLS 1.3` protokolliga seotud informatsioon, k.a. in-handshake autentimismeetodi konfigureerimise protseduur sertifikaadiga autentimise lubamiseks `TLS 1.3` protokolliga. — Muutja: Urmas Vanem +| 18.12.2023 | 23.12/1 | Eemaldatud `ESTEID-SK 2015` ahel. — Muutja: Urmas Vanem +| 31.10.2025 | 25.10/1 | Lisatud Zetes ahelad. — Muutja: Raul Kaidro +| 22.04.2026 | 26.04/1 | Konverteeritud Markdown formaati. — Muutja: Raul Metsma + +Juhend, kuidas autentida kasutajat IIS veebiserveril Eesti eID kaartidega. + +--- + +- TOC +{:toc} + +## Sissejuhatus + +Käesolevas juhendis kirjeldame IIS veebiserveri konfiguratsiooni kahepoolse SSL-i kasutamiseks, kus kliendi poolseks sertifikaadiks on Eesti eID kaardile (ID-kaart, elamisloakaart, digi-ID ja e-residendi digi-ID) väljastatud sertifikaat. + +Juhendi loomisel on kasutatud Windows Server 2022 ja Windows 10 operatsioonisüsteeme. Näidisjuhendis on toetatud [SK ID Solutions](https://www.skidsolutions.eu/resources/certificates/) `EE-GovCA2018` ja [Zetes](https://repository.eidpki.ee/) `EEGovCA2025` ahelast pärinevad sertifikaadid. Tagamaks sertifikaatide äratundmist on kohustuslikuks komponendiks kliendi poolel ka ID-tarkvara[^1]. Näidisjuhendi serveri sertifikaat on väljastatud OctoX testkeskkonnast. + +IIS kasutamisel on võimalik rakendada erinevaid autentimismeetodeid. Käesolev dokument vaatleb sertifikaadi nõude kehtestamist IIS anonüümse autentimise jaoks – st. peale sertifikaadi kehtivuse kontrolli lubatakse kasutaja eelnevalt määratud kasutaja (IUSR) õigustes veebisaidile ligi. + +Hetkel on testid edukalt läbi viidud järgmiste brauseritega (viimased versioonid): + +1. Microsoft Edge +2. Mozilla Firefox +3. Google Chrome + +## Ühepoolse SSL/TLS-i konfigureerimine + +### Windows serveri sertifikaadi konfiguratsioon + +Pakkumaks turvalist veebiteenust peab IIS serverile olema määratud TLS sertifikaat - meie näites on kasutusel OctoX testkeskkonnast väljastatud sertifikaat. Samuti peavad nii kliendid kui ka veebiserver ise usaldama nimetatud sertifikaati. + +Domeeni keskkonnas ja domeeni (*enterprise*) CA olemasolul on tõenäoliselt kõige mõistlikum küsida ka serveri sertifikaat domeeni CA-lt. Ent juhul, kui meid ei rahulda domeeni taseme turvalisus ja võimalused või kui vajame sertifikaati, mis on laiemalt usaldatud, tuleb luua privaatvõti ning sertifikaadi päring ja lasta viimase alusel luua sertifikaat mõnel üldtuntud CA-l. + +#### Serveri sertifikaadi hankimine + +Kuna IIS halduskonsoolilt loodav sertifikaadi päring on üsna piiratud võimalustega, kasutame serveri sertifikaadi loomiseks hoopis sertifikaatide halduskonsooli. Käivitame IIS serveril `mmc.exe` ja lisame sinna lokaalse arvuti sertifikaadid. Loome kohandatud päringu: + +![Alustame kohandatud päringu loomisega](./img/image1.png) + +Klikime kolm korda *Next* ja valime *Details, Properties.* Avaneb sertifikaadi päringu omaduste aken: + +![Sertifikaadi päringu omaduste aken](./img/image2.png) + +Järgnevalt saame määrata päringufailile täpsed omadused, milliseid tahame hiljem oma veebiserveri sertifikaadi juures näha. + +Juhul, kui meil on tarvis sarnaseid päringufaile tihedamini luua, soovitame tegevuse automatiseerimiseks tutvuda `PowerShell` võimalustega. + +##### Sakk General + +Siin määrame soovi korral sertifikaadi hüüdnime ja põgusa kirjelduse. Need väljad ei ole sertifikaadi sisulised osad ja omavad tähendust selgituse, hilisema lihtsama arusaama mõttes. + +![Sertifikaadi üldinfo](./img/image3.png) + +##### Sakk Subject + +Aknas *Subject* kirjeldame subjekti nagu ikka. Kui soovime kasutada erinevaid SAN DNS nimesid või kasutame *common name* puhul midagi muud kui FQDN, siis tuleb üks või mitu DNS aliast siin ka kirjeldada. + +![Subjekti näidiskonfiguratsioon](./img/image4.png) + +##### Sakk Extensions + +Aknas *Extensions* määrame järgmised omadused: + +1. Key Usage: + 1. Digital signature; + 2. Key encipherment. +2. Extended Key Usage: + 1. Server Authentication. + +![Laienduste määramine](./img/image5.png) + +##### Sakk Private Key + +Siit aknast valime CSP ehk sertifikaadi võtmete algoritmi. Näidis-konfiguratsioonis kasutame algoritmi `ECDSA_P256`, seega valime loendist `ECDSA_P256` ja eemaldame nimekirja alguses oleva RSA. + +![CSP valimine](./img/image6.png) + +Klikime *OK* ja *Next*, määrame kausta ning nime ja salvestame sertifikaadi päringu `Base64` formaadis. + +Võime värskelt loodud sertifikaadi päringufaili omadused kontrollida üle käsuga `certutil -dump PÄRINGUFAILI_NIMI`. + +![Päringufaili sisu](./img/image7.png) + +Veendume, et ka DNS alternatiivsed nimed on päringufailis olemas: + +![DNS aliased päringufailis](./img/image8.png) + +Nüüd edastame sertifikaadi päringufaili mõnele CA serverile ja palume selle alusel endale sertifikaadi genereerida. Tulemus on järgmine: + +![IIS serveri sertifikaat](./img/image9.png) + +#### Sertifikaadi installeerimine + +IIS server peab usaldama sertifikaati `OctoX Demo CA 21.11`, mis on serveri sertifikaadi väljastajaks. Selleks peame kontrollima selle sertifikaadi olemasolu *usaldusväärsete juursertifikaatide*[^2] konteineris. Kui väljastaja CA sertifikaat sealt puudub, tuleb see lisada![^3] + +![IIS server usaldab temale sertifikaadi väljastanud CA-d.](./img/image10.png) + +IIS serveri sertifikaat ise tuleb paigaldada IIS serveril lokaalse arvuti personaalsesse konteinerisse: + +![Avades sertifikaadi näeme, et IIS serveril on ka selle privaatvõti kasutada!](./img/image11.png) + +### Ühepoolse SSL-konfiguratsiooni loomine + +Ühepoolse SSL-i kehtestamiseks peab veebisaidil olema kirjeldatud SSL port (vaikimisi 443) ja see peab olema seotud soovitava sertifikaadiga. Koheselt keelame ka vanade SSL/TLS protokollide (vanemad kui 1.2) kasutamise! + +![Veebisaidil on lubatud 443 port ja kasutatavaks sertifikaadiks on iis2111.kaheksa.xi, vanad TLS protokollid tuleb keelata!](./img/image12.png) + +Peale määrangute kinnitamist ühepoolne SSL töötab! + +![Ühepoolne SSL töötab TLS 1.3 protokolliga, veebilehitsejaks on Firefox!](./img/image13.png) + +Ühepoolse SSL-i demonstreerimiseks kasutatud Firefox veebilehitseja näitab lisainfo akendes meile veel ka järgmist: + +1. Kasutusel on meie värskelt installeeritud sertifikaat `2111.kaheksa.xi`; +2. Kasutusel on TLS 1.3 protokoll. + +#### HTTP ligipääsu piiramine + +HTTP ligipääsu keelamiseks eemaldame pordi 80 seotud protokollide loendist ja keelame tulemüürist ka vastava ligipääsu. Alternatiivina võime suunata HTTP liikluse automaatselt HTTPS saidile vältimaks probleemi, kus kasutajad kirjutavad ise brauserisse saidi aadressi ent ei taipa sinna ette HTTPS:// määrangut panna. + +## Kahepoolse SSL-i, sertifikaadiga autentimise nõudmine + +### Eelhäälestus + +> **Märkus:** IIS 10/Schannel, mis töötab Windows Server 2022 platvormil, kasutab sertifikaadiga autentimiseks protokolli `TLS 1.3` abil vaikimisi post-handshake autentimismeetodit (kehtib alates 2022. aastast, aktuaalne ka 2026. aastal). Kuna aga enimlevinud brauserid seda ei toeta[^4], siis see lahendus paraku praktikas ei tööta! Juhul, kui `TLS 1.3` on sisse lülitatud, ei saada server kliendile vaikimisi konfiguratsioonis sertifikaadi päringut ja katkestab ühenduse! Sertifikaadiga autentimise tööle saamiseks tuleb keelata `TLS 1.3` kasutamine. Alternatiivina saame sisse lülitada in-handshake autentimismeetodi, vt. peatükk „[In-handshake autentimismeetodi lubamine](#in-handshake-autentimismeetodi-lubamine)". + +> **Märkus:** Windows Server 2025 platvormil on see probleem lahendatud — IIS lisab HTTPS-seose seadistustesse „Negotiate Client Certificate" märkeruudu, mis võimaldab in-handshake autentimist otse liidesest ilma allpool kirjeldatud `netsh` käsuta. + +`TLS 1.3` protokolli versiooni saame välja lülitada IIS HTTPS seose lehelt, märkides linnukese lahtrisse `Disable TLS 1.3 over TCP`: + +![Sertifikaadiga autentimise lubamiseks peame paraku TLS 1.3 protokolli keelama](./img/image14.png) + +### Eesti eID sertifikaatide häälestus IIS serveril + +Kahepoolse SSL-i lubamiseks tuleb IIS serveri poolt nõuda sertifikaadiga autentimist. Vaikimisi lubab server enda poole pöördumisel kasutada kõiki sertifikaate, mis on tema poolt usaldatud ja millel on EKU-s kirjeldatud `client authentication` laiend. Korrektseks toimimiseks peab server suutma luua kogu sertifikaadiahela alates kasutajasertifikaadist kuni juursertifikaadini – see tähendab, et lisaks juurtaseme sertifikaatide olemasolule IIS serveris on vajalik ka kesktaseme (*intermediate*) sertifikaatide olemasolu. + +Meie konfiguratsiooni puhul tuleb IIS serveris sertifikaadid publitseerida järgmiselt: + +1. Usaldusväärsete juursertifikaatide konteinerisse: + 1. `EE-GovCA2018` () + 2. `EEGovCA2025` () +2. Kesktaseme sertifikaatide konteinerisse[^5]: + 1. `ESTEID2018` () + 2. `ESTEID2025` () + +Veebisaidi SSL omaduste alt tuleb nõuda SSL protokolli ja kliendi sertifikaatide kasutamist: + +![SSL ja sertifikaadi nõue](./img/image15.png) + +Loodud konfiguratsioon lubab veebisaidile ligipääsu 443 pordi kaudu, kasutajalt nõutakse sertifikaati. Pöördudes veebisaidi poole lubatakse valida soovitav serveri poolt aktsepteeritud sertifikaat: + +![Sertifikaadi küsimine veebisaidile pöördudes Firefox brauseris](./img/image16.png) + +Peale PIN-i sisestamist kontrollitakse sertifikaadi kehtivust veebiserveri poolt ja kui kõik on korras, lastakse kasutaja veebisaidile ligi. + +![Autentimine õnnestus kasutades protokolli TLS 1.2](./img/image17.png) + +Alternatiivina võib IIS-i poolse sertifikaadinõude (`Require`) asemel kasutada ka lihtsat sertifikaadi aktsepteerimist (`Accept`) IIS serveri poolt – see võimaldab lisaks sertifikaadile saada serverile ligi ka kasutajanime ja parooliga või üldse autentimata. + +### In-handshake autentimismeetodi lubamine + +Kui soovime siiski kasutada `TLS 1.3` protokolli ja kasutada sertifikaadiga autentimist, saame lubada in-handshake autentimismeetodi. Selle meetodi puhul küsib server kliendilt *Server Hello* saatmisel koheselt ka sertifikaati. + +In-handshake autentimismeetodi lubamiseks tuleb teha järgmist: + +1. Dokumenteerida olemasoleva sertifikaadi määrangud käsuga `netsh http show sslcert`. Oluline on üles märkida `Certificate Hash` ja `Application ID`: + + ![Vaikimisi on määrang "negotiate client certificate" keelatud](./img/image18.png) + +2. Eemaldame sertifikaadi seotuse 443 pordiga käsuga `netsh http del sslcert 0.0.0.0:443`: + + ![Sertifikaadi eemaldamine 443 pordi küljest.](./img/image19.png) + +3. Ja lisame selle uuesti lubades ühtlasi ka in-handshake autentimismeetodi käsuga `netsh http add sslcert ipport=0.0.0.0:443 certhash=312bbb70898b5ae10753998c67bceeeb97d49f79 appid={4dc3e181-e14b-4a21-b022-59fc669b0914} certstorename=MY clientcertnegotiation=Enable`: + + ![Clientcertnegotiation lubamine](./img/image20.png) + +Vaadates uuesti sertifikaadi infot näeme, et `Negotiate Client Certificate` on nüüd lubatud: + +![In-handshake autentimismeetod on nüüd sees](./img/image21.png) + +> **Märkus:** Kuna *session renegotiation* on `TLS 1.3` puhul keelatud, siis selle meetodi puhul tuleb arvestada asjaoluga, et autentimine peab toimuma „esimesel lehel". Kui oleme juba kliendi sertifikaadiga autentimata ühepoolse SSL ühenduse loonud ja samal lehel soovime kliendi sertifikaadiga autentides mõnele kaitstud ressursile ligi pääseda, siis me ebaõnnestume, kuna `TLS 1.3` ei toeta sellist lähenemist. Vajadusel tuleb see „maandumise" probleem ühel või teisel viisil lahendada. + +### Autentimine + +Meie näites on lubatud ainult anonüümne autentimine: + +![Anonüümne autentimine, kasutaja saab saidile ligi kasutaja IUSR õigustes](./img/image22.png) + +## Võimalikud lisakonfiguratsioonid + +Selle dokumendi eesmärgiks ei ole anda täpseid juhiseid optimaalseks veebisaitide konfigureerimiseks ega turvamiseks. Pigem tahame tutvustada konfiguratsiooni kahepoolse SSL-i kasutamiseks Eesti eID kaartidega. Siiski toome järgnevalt välja punktid, mida peame oluliseks mainida. + +### Kasutajapoolsete sertifikaatide filtreerimine + +Vaikimisi pakutakse kasutajapoolse kahepoolse SSL sessiooni alustamisel IIS puhul kliendile välja kõik sertifikaadid, millistel on EKU omaduste all kirjas kliendi autentimine (ja loomulikult peab olema ka sertifikaadi privaatvõti). IIS-i poolt on aga kliendile võimalik ette anda loend autentimiskeskustest millised on lubatud ja seeläbi kuvatakse edaspidi klientidele vaid toetatud ahelate sertifikaadid. + +Seame eesmärgiks kuvada kasutaja pool vaid sertifikaadid, mis pärinevad kindla juurserveri `EE-GovCA2018` ja `EEGovCA2025` ahelast. + +1. Kuvame aktiivse IIS sertifikaadi info käsuga `netsh http show sslcert 0.0.0.0:443`: + + ![Vaikimisi seotud sertifikaadi omadused](./img/image23.png) + +2. Eemaldame selle sertifikaadi seose käsuga `netsh http del sslcert 0.0.0.0:443`: + + ![Sertifikaadi eemaldamine](./img/image19.png) + +3. Lisame sertifikaadi uuesti ja ütleme, et sertifikaatide filtreerimiseks kasutame arvuti sertifikaatide kausta `Client Authentication Issuers`. Käsuks on `netsh http add sslcert ipport=0.0.0.0:443 certhash=1e75c77c696aa4d49686bb1ef73ac3b07fdff38a appid={4dc3e181-e14b-4a21-b022-59fc669b0914} sslctlstorename=ClientAuthIssuer`: + + ![Lisame sertifikaadi uute omadustega](./img/image24.png) + + `Certhash` ja `appid` väärtused saame 1. sammu väljundist ülal. + +4. Kontrollime, et `CTL Store Name` on uuel sertifikaadi väljavõttel `ClientAuthIssuer`: + + ![Uuesti seotud sertifikaadi omadused](./img/image25.png) + + Näeme soovi korral ka IIS-i konfiguratsioonist, et SSL sertifikaat on uuesti korrektselt seotud 443 pordiga. + +5. Lubame IIS serveri registrist sertifikaatide filtreerimise lisades määrangu `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\SendTrustedIssuerList=1`: + + ![Sertifikaatide filtreerimise lubamine registris](./img/image26.png) + +6. Lisame SK kesktaseme sertifikaadi IIS serveri sertifikaatide konteinerisse `Client Authentication Issuers`: + + ![Kliendi jaoks lubatud sertifikaatide lisamine õigesse konteinerisse](./img/image27.png) + +7. Vajadusel taaskäivitame IIS teenuse või serveri ja kontrollime soovitud lahenduse toimimist! + +### Kliendisertifikaatide kehtivuse kontroll OCSP teenuse vastu + +OCSP teenuse abil saame kasutaja sertifikaadi kehtivust kontrollida praktiliselt reaalajas. Iga kasutaja autentimisel saadab veebiserver päringu OCSP teenusele, mis tagastab sertifikaadi kehtivuse info. + +`ESTEID2018` ja `ESTEID2025` CA alt väljastatud sertifikaatide puhul on AIA OCSP aadress juba sertifikaadis kirjas ( ja ), nii et siin me tegelikult midagi eraldi konfigureerima ei pea. Küll aga saame soovi korral kehtestada ka keskelt AIA OCSP kontrolli: + +![AIA OCSP tee konfigureerimine](./img/image28.png) + +> **Märkus:** Kordan siin selguse mõttes, et `ESTEID2018` / `ESTEID2025` CA alt väljastatud sertifikaatidel on kehtivuskontrollina kasutusel AIA OCSP teenus aadressiga . CRL teed neis kirjeldatud ei ole. + +> **Märkus:** Windows serveri puhul pöördutakse vaikimisi OCSP põhiselt sertifikaatide kehtivuse kontrollilt tagasi CRL põhisele kontrollile, kui vahemälus olevate OCSP päringute hulk ületab 50-ne piiri. Meie konfiguratsiooni puhul ei ole see tegelikult oluline, kuna CRL-i me üldse ei kasuta. Muude konfiguratsioonide puhuks mainin, et seda numbrit on võimalik muuta luues registri väärtuse `HKEY_LOCAL_MACHINE/Software/Policies/Microsoft/SystemCertificates/ChainEngine/Config/CryptnetCachedOcspSwitchToCrlCount` ja määrates sinna uue väärtuse. Vt. ka OCSP [*magic count*](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/ee619754(v=ws.10)#determining-preference-between-ocsp-and-crls) või *magic number*. Ehk aga lihtsamgi tee selle omaduse muutmiseks on *windows policy*: + +![Maagilise OCSP numbri muutmine](./img/image29.png) + +### Soovituslikud IIS'i sätted + +#### SSL/TLS + +IIS'i versioon 10 serveril 2022 kasutab vaikimisi kõiki TLS protokollide versioone, 1.0–1.3[^6]. Vanemad SSL protokollid ei ole vaikimisi kasutusel. + +Tänapäeval ei tohiks kindlasti enam kasutada `TLS 1.0` ja `TLS 1.1`. Kahepoolse autentimise toimimiseks peab olema lubatud `TLS 1.2` ja loodetavasti ajutiselt keelatud `TLS 1.3` (loe täpsemalt peatükist „Kahepoolse SSL-i, sertifikaadiga autentimise nõudmine – Eelhäälestus"). Kui sertifikaadiga autentimine ei ole oluline, võib hea mõte olla lubada vaid `TLS 1.3`. + +Rohkem infot TLS protokolli kasutamise soovituste kohta leiab RIA tellitud krüptograafiliste algoritmide elutsükli uuringust aadressil . + +Lisaks IIS konfiguratsiooni juures vanade TLS protokollide keelamisele saame seda teha ka otse registris. Kui me soovime keelata `TLS 1.0` ja `TLS 1.1`, tuleb meil lisada registrisse järgmine konfiguratsioon[^7]: + +- `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\`[^8]: + - `TLS 1.0\Server` + - `Enabled DWORD:0` + - `DisabledByDefault = DWORD:1` + - `TLS 1.1\Server` + - `Enabled DWORD:0` + - `DisabledByDefault = DWORD:1` + +![TLS versioonide 1.0 ja 1.1 keelamine registris](./img/image30.png) + +Ja muidugi on võimalik ülaltoodud registri konfiguratsiooni levitada ka kesksete poliitikate abil. + +#### Šifrikomplektid (Cipher suites) + +Windows serveriga tuleb vaikimisi kaasa mitmeid šifrikomplekte. Kõiki neid saame vaadata näiteks `PowerShell` käsuga `Get-TLSCipherSuite`[^9]. + +Kindlat soovitust erinevate šifrikomplektide kasutamiseks ei ole veebisaidile esitatavaid tingimusi teadmata võimalik anda. Küll aga tundub mõistlik eemaldada loendist ebaturvalised šifrikomplektid (juhul, kui neid seal on). Enne konfiguratsiooniga jätkamist soovitame kindlasti tutvuda RIA tellitud krüptograafiliste algoritmide elutsükli uuringu soovitustega aadressil . Mõistlik võib olla konkreetsete šifrikomplektide lubamine. + +Seega, kui soovime ise täpsemalt määrata kasutatavaid šifrikomplekte, on ilmselt parim selleks kasutada kohalikke või keskseid poliitikaid. Kasutamaks ainult šifrikomplekte `ECDHE-ECDSA-AES256-GCM-SHA384` ja `ECDHE-RSA-AES256-GCM-SHA384`, tuleb meil modifitseerida määrangut `Computer Configuration/Administrative Templates/Network/SSL Configuration Settings: SSL Cipher Suite Order`. Šifrikomplektid tuleb eraldada komaga.[^10] + +![Kindlate šifrikomplektide määramine keskse poliitikaga](./img/image31.png) + +Eelmises punktis määratud konfiguratsioon kirjutatakse registrisse: + +![Poliitikaga määratud konfiguratsioon](./img/image32.png) + +Vaikimisi on šifrikomplektid kirjeldatud järgmisel pildil kirjeldatud asukohas: + +![Vaikimisi šifrikomplektide konfiguratsioon](./img/image33.png) + +##### Muud konfigureeritavad Schannel omadused + +Vaikimisi asukoht Schanneli konfigureeritavatele omadustele on registris: `HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL`. Siin on võimalik erinevaid komponente lubada või keelata, kirjutada vajadusel üle vaikimisi konfiguratsiooni määranguid. + +![Schannel konfigureeritavad omadused](./img/image34.png) + +#### Muud võimalused + +Lisaks TLS-i ja šifrikomplektide konfigureerimisele, saame palju muudki ära teha oma IIS-i serveri turvamiseks: + +- Hoiame operatsioonisüsteemi ajakohasena. +- Keelame serveri info presenteerimise. +- Keelame HTTP päringud. +- Keelame failide lappamise võimaluse (*directory listing*). +- Kasutame mitte-süsteemseid ja mitte-administraator kontosid. +- Lubame HSTS'i. +- … + +Palume suhtuda ülaltoodusse kui näidisloendisse demonstreerimaks, mida veel saab IIS'i turvalisemaks muutmise jaoks ära teha. Põhjalikemaid soovitusi on võimalik leida paljudelt internetilehtedelt: + + + +[^1]: + +[^2]: Trusted root certification authorities + +[^3]: Juhul, kui sertifikaadi on väljastanud mõni kesktaseme CA, siis tuleb see puudumisel lisada *kesktaseme sertimiskeskuste* konteinerisse. Ja kesktaseme CA sertifikaadi väljastanud juur-CA sertifikaat tuleb puudumisel lisada *usaldusväärsete juursertifikaatide* konteinerisse. + +[^4]: Firefox teadaolevalt toetab, ent ka sellel brauseril ei ole see vaikimisi lubatud. + +[^5]: SK poolt väljastatud organisatsioonide kaartide kasutuse puhul peavad kesktaseme sertifikaatide hulka olema häälestatud ka `EID-SK 2016` () sertifikaadid! + +[^6]: + +[^7]: Vaikimisi neid väärtuseid ei eksisteeri. + +[^8]: Võimalik on konfigureerida eraldi ka kliendi osa SSL/TLS protokollide vaates. Hetkel aga räägime ainult serveri poole häälestusest. See ei tähenda, et kliendi osa konfigureerimine ei ole soovitatav, see sõltub alati konkreetsest situatsioonist. + +[^9]: + +[^10]: Märgime siinkohal, et nende konkreetsete määrangutega `TLS 1.3` ei toimi! Pigem võib nende määrangute kasutamine olla mõttekas juhul, kui me ei soovi `TLS 1.3`-e kasutada, kasvõi näiteks sertifikaadiga autentimise lubamise puhul. diff --git a/iis/index.md b/iis/index.md new file mode 100644 index 0000000..e9170b5 --- /dev/null +++ b/iis/index.md @@ -0,0 +1,347 @@ +# Configuring IIS to support Estonian Digital ID-card for authentication + +**[Eesti keeles (In Estonian)](index.et.md)** + +**Version:** 26.04/1 + +**Published by:** [RIA](https://www.ria.ee/) + +**Version information** + +| Date | Version | Changes/Notes +|:-----------|:--------:|:----------------------------------------------------------- +| 21.01.2019 | 19.01/1 | Public version, based on `18.12` software. +| 12.02.2019 | 19.02/1 | Added OCSP options. — Changed by: Urmas Vanem +| 01.10.2019 | 19.10/1 | Added information about Windows server (IIS) patches statuses and future availability by versions. — Changed by: Urmas Vanem +| 18.10.2019 | 19.10/2 | Added information about Windows Server 2016 update `KB4516061`, which solves Chrome-IIS problem. — Changed by: Urmas Vanem +| 08.11.2019 | 19.11/1 | Added information about Windows Server 2019 update `KB4520062`, which solves Chrome-IIS problem. — Changed by: Urmas Vanem +| 14.11.2019 | 19.11/2 | Added information about Windows Server 1903 (SAC) update `KB4524570`, which solves Chrome-IIS problem. — Changed by: Urmas Vanem +| 12.12.2019 | 19.12/1 | Added recommendations for securing IIS. — Changed by: Urmas Vanem +| 14.12.2020 | 20.12/1 | Added security recommendations to block access for certificates issued by third sub-CA's. — Changed by: Urmas Vanem +| 17.12.2020 | 20.12/2 | Added some security recommendations to chapter "Denying access for unnecessary CA-s". — Changed by: Urmas Vanem +| 03.03.2021 | 21.03/1 | Removed deprecated info of IIS and Chrome combination and updated to the latest. — Changed by: Kristjan Vaikla +| 30.04.2021 | 21.04/1 | Support for aged `ESTEID-SK 2011` certificates removed. — Changed by: Urmas Vanem +| 14.12.2021 | 21.12/1 | Server platform upgraded to version 2022. Added ECDSA certificate request procedure. TLS and cipher recommendations are updated. — Changed by: Urmas Vanem +| 18.01.2022 | 22.01/1 | Added Windows Server 2022 and `TLS 1.3` protocol related information, including procedure for enabling in-handshake authentication method to allow certificate-based authentication with `TLS 1.3` protocol. — Changed by: Urmas Vanem +| 18.12.2023 | 23.12/1 | Removed `ESTEID-SK 2015` chain. — Changed by: Urmas Vanem +| 31.10.2025 | 25.10/1 | Added Zetes certificates. — Changed by: Raul Kaidro +| 22.04.2026 | 26.04/1 | Converted to Markdown format. — Changed by: Raul Metsma + +Instructions on how to configure IIS to support Estonian eID cards for authentication. + +--- + +- TOC +{:toc} + +## Introduction + +In this guide we describe how to configure Microsoft IIS web services to require two-way SSL. On the server side we can use any certificate with `server authentication` EKU, trusted by clients. On client side we use any of Estonian eID card (ID-card, residence card, digital ID or e-Resident's digital ID). + +Windows Server 2022 and Windows 10 operating systems have been used to create this guide. On client side we support certificates issued from the [SK ID Solutions](https://www.skidsolutions.eu/resources/certificates/) `EE-GovCA2018` and [Zetes](https://repository.eidpki.ee/) `EEGovCA2025` chain. To recognize user smart card certificate, we also need ID-software on the client side[^1]. Server certificate in this demo-guidance is issued from OctoX test CA. + +We can use different authentication methods in IIS. In this guide we configure IIS in simplest possible way and use only anonymous authentication after authentication users can access website as dedicated (IUSR) user. + +Currently we tested the configuration with the following browsers (latest versions): + +1. Microsoft Edge +2. Mozilla Firefox +3. Google Chrome + +## Configuration for one-way SSL/TLS + +### Configuring Windows Server certificate + +IIS server needs a TLS certificate to offer web services securely. In our example we use certificate issued from OctoX test environment. Both clients and web server itself must trust the certificate. + +In domain environment it can make sense to use internal CA as web server certificate issuer. But if the security level is not good enough or we want to offer IIS services widely (for public services for example), it can be a good idea to get a certificate from any commonly trusted CA. + +#### Requesting server certificate + +Because using IIS management console for querying TLS certificate is quite limited, we use certificates management console for that. Let's start `mmc.exe` on IIS server and add `Local Computer/Certificates` snap-in into it. Now we have to create `custom query`: + +![Start with custom request](./img/image1.png) + +Let's click three times *Next* and then select *Details, Properties*. Certificate query custom request properties window appears: + +![Certificate query properties window](./img/image2.png) + +In the certificate query properties window we can set the exact properties we want to see in our new certificate. + +If we need to do similar queries more often, then we recommend to use `PowerShell` for automation. + +##### Tab General + +Here we can set certificate friendly name and description. These fields are actually not inner parts of certificate but can be useful for later certificate selection and understanding what is what. + +![Certificate general information](./img/image3.png) + +##### Tab Subject + +Here we describe certificate subject as usual. If we want to use different DNS aliases or common name for any reason is not FQDN, then it is necessary to describe SAN DNS names in this tab too! + +![Subject example configuration](./img/image4.png) + +##### Tab Extensions + +In extensions tab we set following options: + +1. Key Usage: + 1. Digital signature; + 2. Key encipherment. +2. Extended Key Usage: + 1. Server Authentication. + +![Describing extensions](./img/image5.png) + +##### Tab Private Key + +Here we select CSP (cryptographic service provider). In our example we want to use `ECDSA_P256`, so we unselect RSA and select `ECDSA_P256`. + +![Selecting CSP](./img/image6.png) + +Let's click *OK* and *Next* to save the request file with any name you like in `Base64` format. + +We can check the contents of request file with command `certutil -dump REQUEST_FILE_NAME`. + +![Request file contents](./img/image7.png) + +We can also see DNS aliases we defined in this query: + +![DNS aliases in query file](./img/image8.png) + +Now we must send the query file to any CA for certificate generation. If everything goes fine, we'll get the certificate back. + +![Certificate for IIS server](./img/image9.png) + +#### Installing certificate + +Issuing CA certificate `OctoX Demo CA 21.11` must be trusted by our IIS server. It means it must be in IIS server `Trusted Root Certification Authorities` container.[^2] + +![Issuing root CA certificate in correct container](./img/image10.png) + +Certificate for IIS server must belong to `Local Computer/Personal` certificates container on IIS server. + +![IIS certificate in correct container, certificate have private key](./img/image11.png) + +### Configuring IIS for one-way SSL + +To configure one-way SSL on IIS server we must add new HTTP(S) binding (usually port 443) and apply certificate to it. And it is definitely a good idea to disable legacy TLS protocols! + +![Defining HTTPS binding with certificate iis2111.kaheksa.xi and disabling legacy TLS protocols](./img/image12.png) + +After applying settings one-way SSL works and we can access website over HTTPS protocol. + +![One-way SSL works with TLS 1.3 protocol, browser is Firefox](./img/image13.png) + +In information window of Firefox, we can see that: + +1. Our web server certificate `iis2111.kaheksa.xi` is in use; +2. TLS protocol version 1.3 is in use. + +#### Disabling HTTP access + +To disable access to website over unsecure HTTP (usually port 80) we can remove the binding from configuration and disable firewall access to port 80. As an alternative we can create automatic redirection rule from port 80 to port 443. It can be useful for cases when users do not type https:// prefix to server address and cannot reach to website. + +## Requiring two-way SSL, certificate authentication + +### Preset + +> **Note:** As of 2022 and still applicable in 2026, IIS 10/Schannel running on Windows Server 2022 uses post-handshake authentication method with `TLS 1.3` by default. But because common browsers do not support this method, this configuration in practice is faulty. The problem with `TLS 1.3` is that the server will not send certificate request query to the client in default configuration and because of missing client certificate server resets connection. To re-enable certificate-based authentication we must turn `TLS 1.3` off. Alternative way is to enable in-handshake authentication method, we discuss it later in chapter "[Enabling in-handshake authentication method](#enabling-in-handshake-authentication-method)". + +> **Note:** On Windows Server 2025 this has been resolved natively — IIS adds a "Negotiate Client Certificate" checkbox directly in the HTTPS binding UI, enabling in-handshake authentication without the `netsh` workaround described below. + +Until the problem exists with Windows Server 2022, we must turn `TLS 1.3` over TCP off. We can do it by selecting `Disable TLS 1.3 over TCP` in IIS bindings window: + +![Turn TLS 1.3 off to enable certificate based authentication](./img/image14.png) + +### Configuring IIS server to support Estonian eID cards + +To enable two-way SSL certificate authentication must be turned on. By default, all trusted certificates with `client authentication` extension in EKU can be used. Client certificate chain must be known by server, intermediate certificates must belong to intermediate certificates container and root certificates must belong to `Trusted Root Certification Authorities` container. + +In our case we need to add following certificates into IIS server certificate store: + +1. Trusted Root Certification Authorities: + 1. `EE-GovCA2018` () + 2. `EEGovCA2025` () +2. Intermediate Certification Authorities[^3]: + 1. `ESTEID2018` () + 2. `ESTEID2025` () + +After defining certificate chains, we can enable certificate requirement in website SSL settings: + +![Requiring client certificate](./img/image15.png) + +Described configuration allows access to website over port 443, client certificate is required. While connecting to server over https certificate request appears: + +![Certificate requires pin in Firefox browser](./img/image16.png) + +After entering PIN, certificate revocation status will be checked by IIS server and if it is good, user can access website. + +![Authentication succeeded over TLS 1.2 protocol](./img/image17.png) + +As an alternative we can use certificate acceptance instead of requiring it. In this case we can access websites also with username or password or without authentication at all. + +### Enabling in-handshake authentication method + +If we want to use `TLS 1.3` protocol with Windows Server 2022 IIS 10, we must enable the in-handshake authentication method. With this method certificate request query is sent to client with *Server Hello*. + +Please follow next steps to enable in-handshake authentication method: + +1. Document `Certificate Hash` and `Application ID` values with command `netsh http show sslcert`: + + !["negotiate client certificate" is disabled by default](./img/image18.png) + +2. Remove certificate binding from port 443 with command `netsh http del sslcert 0.0.0.0:443`: + + ![Remove certificate from port 443](./img/image19.png) + +3. Bind certificate to port 443 again and also enable in-handshake authentication with command `netsh http add sslcert ipport=0.0.0.0:443 certhash=312bbb70898b5ae10753998c67bceeeb97d49f79 appid={4dc3e181-e14b-4a21-b022-59fc669b0914} certstorename=MY clientcertnegotiation=Enable`: + + ![Enabling clientcertnegotiation](./img/image20.png) + +If we check certificate binding information again, we can see that `Negotiate Client Certificate` is now enabled: + +![In-handshake authentication method is now enabled](./img/image21.png) + +> **Note:** Because session renegotiation is disabled with `TLS 1.3`, we must understand that authentication must happen on first page. If we already have one-way SSL connection with any website, renegotiation will fail if some parts of this site/page require it. So, if necessary, we must somehow solve this "landing" problem. + +### Authentication + +In our configuration we use only anonymous authentication: + +![Anonymous authentication, user can access website as user IUSR](./img/image22.png) + +## Possible additional configurations + +The purpose of this document is not to give exact guidance how to configure or secure web sites. But we want to introduce useful configurations for using two-way SSL with Estonian eID cards. In the following chapters, we point out possibilities we think are important. + +### Filtering certificate list on client side + +By default, all personal certificates with private key and `user authentication` EKU on client side are accepted by IIS. But it is possible to teach IIS to share list of acceptable certificate authorities with clients – in this case browser shows only certificates from supported chains to user. + +Our goal is to support only certificates issued from chains under root CA `EE-GovCA2018` and `EEGovCA2025`. + +1. Get IIS certificate information with command `netsh http show sslcert 0.0.0.0:443`: + + ![Default https certificate options](./img/image23.png) + +2. Remove certificate binding with command `netsh http del sslcert 0.0.0.0:443`: + + ![Unbind certificate](./img/image19.png) + +3. Add certificate again and point it to user store `Client Authentication Issuers` as list for acceptable certification authorities for clients. Command is `netsh http add sslcert ipport=0.0.0.0:443 certhash=1e75c77c696aa4d49686bb1ef73ac3b07fdff38a appid={4dc3e181-e14b-4a21-b022-59fc669b0914} sslctlstorename=ClientAuthIssuer`: + + ![Binding certificate with new option](./img/image24.png) + + `Certhash` and `appid` values can be taken from the output in step 1 above. + +4. Check that `ClientAuthIssuer` value exists after `CTL Store Name`: + + ![Updated output](./img/image25.png) + + We can also check IIS configuration to be sure SSL certificate is correctly bound to port 443. + +5. Enable certificate filtering option in IIS server registry by adding value `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\SendTrustedIssuerList=1`: + + ![Enabling certificate client side filtering in IIS server registry](./img/image26.png) + +6. Add our intermediate CA to certificates container `Client Authentication Issuers` in IIS server to support only specific CA: + + ![We trust only 2 intermediate CA's](./img/image27.png) + +7. If necessary, restart the IIS service or server and check if everything works as expected. + +### Checking revocation status of client certificates against OCSP service + +Using OCSP service we can check revocation status of client certificates practically in real time. In every client authentication attempt web server sends query to OCSP service, which responds with client certificate revocation status. + +Certificates issued by `ESTEID2018` and `ESTEID2025` CA have AIA OCSP service location included in end user certificate ( and ), so we do not need to make any change here. But we still can configure our server to check revocation status of certificates using AIA OCSP service: + +![Configuring AIA OCSP path on IIS server](./img/image28.png) + +> **Note:** I repeat here for clarity: certificates issued by `ESTEID2018` / `ESTEID2025` CA have AIA OCSP path described in certificate. CRL is not described for those certificates. + +> **Note:** Windows server by default changes from OCSP based revocation check to CRL based revocation checking after 50 OCSP queries. In our configuration, this doesn't really matter since we don't use CRL at all. For other configurations I mention here that we can change this behavior by changing registry value of registry key `HKEY_LOCAL_MACHINE/Software/Policies/Microsoft/SystemCertificates/ChainEngine/Config/CryptnetCachedOcspSwitchToCrlCount`. For more information take a look at [OCSP magic count](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/ee619754(v=ws.10)#determining-preference-between-ocsp-and-crls) or *magic number*. We can also change the behavior with windows policy: + +![Changing OCSP magic count](./img/image29.png) + +### Recommended security settings for IIS + +#### SSL/TLS + +IIS version 10 is using TLS protocol versions from 1.0 to 1.3 by default[^4]. Older SSL versions are disabled by default. + +Old unsecure SSL/TLS protocols with version number lower than `TLS 1.2` should definitely no longer be used. `TLS 1.2` should be the lowest version to use! From Windows Server version 2022 `TLS 1.3` is also available. If you need one-way SSL, it can be a good idea to enable only `TLS 1.3`! + +More information about the recommendations for the use of the TLS protocol can be found in the cryptographic algorithms life cycle reports ordered by RIA at . + +In addition to disabling older TLS versions in IIS management console, we can disable `TLS 1.0` and `TLS 1.1` in registry keys by defining following values[^5]: + +- `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\`[^6]: + - `TLS 1.0\Server` + - `Enabled DWORD:0` + - `DisabledByDefault = DWORD:1` + - `TLS 1.1\Server` + - `Enabled DWORD:0` + - `DisabledByDefault = DWORD:1` + +![Disabling TLS 1.0 and 1.1 for server part in registry](./img/image30.png) + +Of course, it is also possible to deploy TLS/SSL versions settings through group policy by deploying registry settings. + +#### Cipher suites + +There are many different cipher suites available with Windows Server. We can list available cipher suites with `PowerShell` command `Get-TLSCipherSuite`[^7]. + +It is impossible to give an exact recommendation for configuring cipher suites because different environments have different requirements. And requirements and possibilities are changing in time. The only recommendation we can give here is to remove non-secure cipher suites from the list if any exist. Before going on with configuring cipher suites, we recommend getting acquainted with RIA's recommendations for the use of the cipher suites in the cryptographic algorithms life cycle report at . It can make sense to enable only specific cipher combinations. + +So, if we want to configure specific cipher suites, the best way to do it is probably using local or group policy. To configure cipher suites `ECDHE-ECDSA-AES256-GCM-SHA384` and `ECDHE-RSA-AES256-GCM-SHA384` as only ones in our configuration, we must modify policy setting `Computer Configuration/Administrative Templates/Network/SSL Configuration Settings: SSL Cipher Suite Order`. Cipher suites must be separated with comma.[^8] + +![Modifying cipher suites with group policy](./img/image31.png) + +Assigned configuration can be found from registry location presented on the following picture: + +![Applied policy settings](./img/image32.png) + +Default configuration settings can be found from registry location presented on the following picture: + +![Cipher suites default configuration](./img/image33.png) + +##### Other configurable Schannel settings + +Default location for all Schannel settings is `HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL`. It is possible to enable or disable different Schannel components here, overwrite default configuration. + +![Schannel configurable options](./img/image34.png) + +#### Additional possibilities + +In addition to TLS and cipher suite configuration there are many other things we can do to secure our server: + +- Keep operating system up to date. +- Disable presenting server information. +- Disable HTTP requests. +- Disable directory listing. +- Run under separate non-system and non-administrator accounts. +- Enable HSTS. +- … + +Please take the list above as a short demo recommendations list. Of course, it makes sense to follow the recommendations, but there can be much more you can do to secure your server: + + + +[^1]: + +[^2]: If certificate is issued by intermediate CA, it must be in `Intermediate Certification Authorities` container. In this case root CA certificate for intermediate CA must be in `Trusted Root Certification Authorities` container. + +[^3]: To support EID cards issued for organizations by SK ID Solutions, we must add to the list also `EID-SK 2016` () certificates! + +[^4]: + +[^5]: These entries do not exist in the registry by default. + +[^6]: It is also possible to configure client part for SSL/TLS versions, but currently we are talking about server configuration. It does not mean that configuring client part is not recommended, it just depends. + +[^7]: + +[^8]: With cipher settings described here `TLS 1.3` will not work. So, those settings can be useful if we don't want to use `TLS 1.3` for any reason, for enabling certificate authentication for example. diff --git a/iis/media/image1.png b/iis/media/image1.png new file mode 100644 index 0000000..f456858 Binary files /dev/null and b/iis/media/image1.png differ diff --git a/iis/media/image10.png b/iis/media/image10.png new file mode 100644 index 0000000..b49c7e3 Binary files /dev/null and b/iis/media/image10.png differ diff --git a/iis/media/image11.png b/iis/media/image11.png new file mode 100644 index 0000000..b331287 Binary files /dev/null and b/iis/media/image11.png differ diff --git a/iis/media/image12.png b/iis/media/image12.png new file mode 100644 index 0000000..1c4eec8 Binary files /dev/null and b/iis/media/image12.png differ diff --git a/iis/media/image13.png b/iis/media/image13.png new file mode 100644 index 0000000..5039787 Binary files /dev/null and b/iis/media/image13.png differ diff --git a/iis/media/image14.png b/iis/media/image14.png new file mode 100644 index 0000000..d2e5f1b Binary files /dev/null and b/iis/media/image14.png differ diff --git a/iis/media/image15.png b/iis/media/image15.png new file mode 100644 index 0000000..39a0a96 Binary files /dev/null and b/iis/media/image15.png differ diff --git a/iis/media/image16.png b/iis/media/image16.png new file mode 100644 index 0000000..d1fdf66 Binary files /dev/null and b/iis/media/image16.png differ diff --git a/iis/media/image17.png b/iis/media/image17.png new file mode 100644 index 0000000..e100a13 Binary files /dev/null and b/iis/media/image17.png differ diff --git a/iis/media/image18.png b/iis/media/image18.png new file mode 100644 index 0000000..0455c31 Binary files /dev/null and b/iis/media/image18.png differ diff --git a/iis/media/image19.png b/iis/media/image19.png new file mode 100644 index 0000000..5a20dde Binary files /dev/null and b/iis/media/image19.png differ diff --git a/iis/media/image2.png b/iis/media/image2.png new file mode 100644 index 0000000..bf50515 Binary files /dev/null and b/iis/media/image2.png differ diff --git a/iis/media/image20.png b/iis/media/image20.png new file mode 100644 index 0000000..e2b45bd Binary files /dev/null and b/iis/media/image20.png differ diff --git a/iis/media/image21.png b/iis/media/image21.png new file mode 100644 index 0000000..86d8b28 Binary files /dev/null and b/iis/media/image21.png differ diff --git a/iis/media/image22.png b/iis/media/image22.png new file mode 100644 index 0000000..74def95 Binary files /dev/null and b/iis/media/image22.png differ diff --git a/iis/media/image23.png b/iis/media/image23.png new file mode 100644 index 0000000..3045b5b Binary files /dev/null and b/iis/media/image23.png differ diff --git a/iis/media/image24.png b/iis/media/image24.png new file mode 100644 index 0000000..70204e6 Binary files /dev/null and b/iis/media/image24.png differ diff --git a/iis/media/image25.png b/iis/media/image25.png new file mode 100644 index 0000000..a570bc2 Binary files /dev/null and b/iis/media/image25.png differ diff --git a/iis/media/image26.png b/iis/media/image26.png new file mode 100644 index 0000000..3c28643 Binary files /dev/null and b/iis/media/image26.png differ diff --git a/iis/media/image27.png b/iis/media/image27.png new file mode 100644 index 0000000..eadc1de Binary files /dev/null and b/iis/media/image27.png differ diff --git a/iis/media/image28.png b/iis/media/image28.png new file mode 100644 index 0000000..1ea22c1 Binary files /dev/null and b/iis/media/image28.png differ diff --git a/iis/media/image29.png b/iis/media/image29.png new file mode 100644 index 0000000..d3812b3 Binary files /dev/null and b/iis/media/image29.png differ diff --git a/iis/media/image3.png b/iis/media/image3.png new file mode 100644 index 0000000..2f6665f Binary files /dev/null and b/iis/media/image3.png differ diff --git a/iis/media/image30.png b/iis/media/image30.png new file mode 100644 index 0000000..82b5bdf Binary files /dev/null and b/iis/media/image30.png differ diff --git a/iis/media/image31.png b/iis/media/image31.png new file mode 100644 index 0000000..030a2aa Binary files /dev/null and b/iis/media/image31.png differ diff --git a/iis/media/image32.png b/iis/media/image32.png new file mode 100644 index 0000000..d428290 Binary files /dev/null and b/iis/media/image32.png differ diff --git a/iis/media/image33.png b/iis/media/image33.png new file mode 100644 index 0000000..6eb8838 Binary files /dev/null and b/iis/media/image33.png differ diff --git a/iis/media/image34.png b/iis/media/image34.png new file mode 100644 index 0000000..edaf61d Binary files /dev/null and b/iis/media/image34.png differ diff --git a/iis/media/image4.png b/iis/media/image4.png new file mode 100644 index 0000000..84269b0 Binary files /dev/null and b/iis/media/image4.png differ diff --git a/iis/media/image5.png b/iis/media/image5.png new file mode 100644 index 0000000..454502e Binary files /dev/null and b/iis/media/image5.png differ diff --git a/iis/media/image6.png b/iis/media/image6.png new file mode 100644 index 0000000..49c4a23 Binary files /dev/null and b/iis/media/image6.png differ diff --git a/iis/media/image7.png b/iis/media/image7.png new file mode 100644 index 0000000..6cfda4d Binary files /dev/null and b/iis/media/image7.png differ diff --git a/iis/media/image8.png b/iis/media/image8.png new file mode 100644 index 0000000..85dd079 Binary files /dev/null and b/iis/media/image8.png differ diff --git a/iis/media/image9.png b/iis/media/image9.png new file mode 100644 index 0000000..4b4638e Binary files /dev/null and b/iis/media/image9.png differ