diff --git a/apache/index.et.md b/apache/index.et.md index f97428f..9e4d9f2 100644 --- a/apache/index.et.md +++ b/apache/index.et.md @@ -2,7 +2,7 @@ **[In English](index.md)** -**Versioon:** 26.04/1 +**Versioon:** 26.08/1 **Väljaandja:** [RIA](https://www.ria.ee/) @@ -27,6 +27,7 @@ | 22.08.2024 | 24.08/1 | Ubuntu uuendatud versioonile Ubuntu Server 24.04 ja Apache versioonile 2.4.62. — 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 +| 21.08.2026 | 26.08/1 | Uuendatud sertifikaadivõtme, TLS-protokollide, šifrikomplektide, sertifikaadipoliitikate ja OCSP juhiseid 2026. aasta krüptograafiliste algoritmide elutsükli aruande põhjal. --- @@ -145,6 +146,17 @@ $ openssl req -new -key Apache2404.key -out Apache2404.csr -subj /C=EE/O=OctoX/C veebilehe tegelikule aadressile[^3]. Need nimed peavad ka nimeserveris lahenema. +Genereeri igale sõltumatule TLS-serverile eraldi privaatvõti. Ära kopeeri +sama võtit mitmesse serverisse üksnes seetõttu, et metamärgiga või mitme SAN +nimega sertifikaat kataks kõik serverinimed. Eraldi võtmed piiravad serveri +või võtme kompromiteerumise mõju. + +Tootmislahenduses kasuta võimaluse korral füüsilist turvamoodulit (HSM) või +samaväärset mitteeksporditava võtmega riistvaralist võtmehoidlat. Genereeri +võti seadmes ja hoia see mitteeksporditavana. Enne kasutuselevõttu veendu, et +HSM, OpenSSL-i integratsioon ja sertifikaadi väljastaja toetavad valitud ECDSA +P-384 võtit. Näite failipõhine võti ei ole HSM-i seadistus. + Loodud sertifikaadi päringufaili sisu on võimalik vaadata käsuga ```bash @@ -174,68 +186,6 @@ Certificate Request: Signature Value: ``` -###### RSA - -*See jaotis on säilitatud neile, kes eelistavad RSA-põhiseid sertifikaate. Ülejäänud dokument kasutab ECC-d.* - -Loo sertifikaadi päring ja privaatvõti käsuga - -```bash -$ openssl req -newkey rsa:2048 -keyout Apache2021.key -sha256 -subj "/CN=Apache5.kaheksa.xi" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf "[SAN]\nsubjectAltName=DNS:Apache2021.kaheksa.xi,DNS:Apache5.kaheksa.xi")) -out Apache2021.csr -nodes -Generating a RSA private key -........+++++ -.++++ -writing new private key to 'Apache2021.key' ------ -``` - -1. `Apache2021.key` on sertifikaadi privaatvõti; -2. `Apache2021.csr` on sertifikaadi päringufail, mis edastatakse - sertifitseerimiskeskusele; - -3. `Apache5.kaheksa.xi` on väljastatava sertifikaadi subjekt; -4. `Apache2021.kaheksa.xi` ja `Apache5.kaheksa.xi` on sertifikaadil olevad - SAN DNS nimed, mis peavad kindlasti vastama veebilehe tegelikule - aadressile[^4]. Need nimed peavad ka nimeserveris lahenema. - -Loodud sertifikaadi päringufaili sisu on võimalik vaadata käsuga - -```bash -$ openssl req -in Apache2021.csr -noout -text -Certificate Request: - Data: - Version: 1 (0x0) - Subject: CN = Apache5.kaheksa.xi - Subject Public Key Info: - Public Key Algorithm: rsaEncryption - RSA Public-Key: (2048 bit) - Modulus: - 00:c9:4f:a2:54:bd:1a:bb:88:a6:ec:16:c9:3e:28: - ee:f6:09:3d:a3:d7:86:fa:67:a4:e5:73:3b:38:70: - 70:73:b0:01:95:7a:8d:c3:47:46:49:b9:12:52:20: - 08:0c:ed:f5:ec:c5:4e:25:3e:27:9b:98:67:b0:bd: - c2:cd:00:98:54:36:d4:bf:b8:60:d9:aa:26:de:6a: - da:11:23:2e:a9:05:94:ff:e8:bb:d2:5e:c2:68:8d: - 63:97:71:5e:0a:a0:49:fc:27:c7:28:c4:7d:53:12: - 1c:e6:2e:9d:bd:81:5b:ff:6a:e5:cf:b5:1a:1b:a3: - 5a:2e:9b:bd:0c:fe:c8:8f:ed:ff:b6:08:9a:1a:69: - 4f:88:a1:1c:c7:9d:84:53:f0:77:2f:db:ba:2a:9a: - 16:f4:78:02:ca:e2:29:f7:f0:f3:61:df:00:ce:3f: - fa:80:c5:ca:2d:37:a4:2e:a4:8c:be:a2:b3:c9:fd: - 46:4e:20:fb:18:8b:3d:09:6a:be:01:3d:af:29:dd: - e2:b6:63:3c:3e:46:c1:7a:9b:08:83:c9:32:c5:54: - b2:e6:3d:a3:68:b6:8d:53:cb:36:c2:20:7d:77:63: - c7:cf:c9:11:36:b3:47:9b:10:8f:19:66:cb:a4:0f: - 50:f5:35:bf:0d:53:82:cb:ad:3c:1f:5a:1a:2b:70: - a4:8f - Exponent: 65537 (0x10001) - Attributes: - Requested Extensions: - X509v3 Subject Alternative Name: - DNS:Apache2021.kaheksa.xi, DNS:Apache5.kaheksa.xi - Signature Algorithm: sha256WithRSAEncryption -``` - ##### SSL sertifikaadi tellimine ja paigaldamine Järgnevalt tuleb saata sertifikaadi päringufail `Apache2404.csr` @@ -425,16 +375,13 @@ To Action From 443/tcp (v6) ALLOW Anywhere (v6) ``` -### Kasutaja sertifikaadi staatuse kontroll OCSP teenuse vastu[^5] +### Kliendisertifikaadi tühistusoleku kontroll OCSP abil[^4] -OCSP (*Online Certificate Status Protocol*) teenuse abil saab kasutaja -sertifikaadi staatust kontrollida reaalajas. Iga kasutaja autentimisel -saadab veebiserver päringu OCSP teenusele, mis tagastab sertifikaadi -staatuse info. +OCSP (*Online Certificate Status Protocol*) võimaldab Apache'il kontrollida +kliendisertifikaadi tühistusolekut autentimise ajal. -SK ja Zetes pakuvad vaba ligipääsuga (tasuta) AIA OCSP teenust. -`ESTEID2018` ja `ESTEID2025` CA alt väljastatud sertifikaatide puhul on AIA -OCSP aadress juba sertifikaadis kirjas (, +CA-de `ESTEID2018` ja `ESTEID2025` väljastatud sertifikaatides on AIA OCSP +teenuse aadress ( ja ). ![ESTEID2018 AIA OCSP aadress sertifikaadis](./img/image8.png) @@ -448,9 +395,50 @@ SSLOCSPEnable leaf SSLOCSPUseRequestNonce off ``` -Taaskäivita Apache2 veebiteenus käsuga `systemctl reload apache2`. -Ülaltoodud konfiguratsiooni puhul võetakse OCSP teenuse aadress kasutaja -sertifikaadist. +Väärtus `leaf` kontrollib lõppkasutaja sertifikaati. OCSP teenuse aadress +võetakse sellest sertifikaadist. See range konfiguratsioon ei kasuta valikut +`no_ocsp_for_cert_ok`: puuduva OCSP aadressi või ebaõnnestunud kontrolli korral +kliendisertifikaadiga autentimine ei õnnestu. Luba serverist väljuv +HTTP-liiklus mõlemasse OCSP teenusesse ja monitoori Apache tõrkeid. Pärast +muudatuse rakendamist laadi Apache uuesti käsuga `systemctl reload apache2`. + +### Serverisertifikaadi OCSP vastuse stapling + +Eespool kirjeldatud kliendisertifikaadi kontroll ja serverisertifikaadi OCSP +stapling on eri funktsioonid. Stapling võimaldab Apache'il hankida oma +serverisertifikaadi kohta allkirjastatud olekuvastuse ja saata selle TLS +kätluse ajal. Nii ei pea iga veebilehitseja väljastanud CA-le eraldi päringut +tegema ja kliendi privaatsus paraneb.[^5] + +Esmalt kontrolli, kas serverisertifikaat sisaldab OCSP teenuse URI-d: + +```bash +$ openssl x509 -in /etc/ssl/certs/Apache2404.pem -noout -ocsp_uri +``` + +Kui käsk tagastab toetatud URI, luba jagatud mälu vahemälu ja tootmiskeskkonna +tõrkekäitlus failis `/etc/apache2/mods-available/ssl.conf`: + +```apache +SSLStaplingCache "shmcb:${APACHE_RUN_DIR}/ssl_stapling(32768)" +SSLStaplingReturnResponderErrors off +SSLStaplingResponderTimeout 4 +SSLStaplingErrorCacheTimeout 60 +``` + +Kontrolli, et `socache_shmcb` on lubatud, ning lisa HTTPS-virtuaalhosti +`SSLUseStapling On`. Ära luba stapling'ut, kui sertifikaadi väljastaja OCSP +teenust ei paku. + +```bash +$ a2enmod socache_shmcb +$ systemctl restart apache2 +$ openssl s_client -connect Apache2404.octox.demo:443 \ + -servername Apache2404.octox.demo -status Require expr ( - (%{SSL_CLIENT_I_DN_CN} == "ESTEID2018" || %{SSL_CLIENT_I_DN_CN} == "ESTEID2025") - and "TLS Web Client Authentication, E-mail Protection" in PeerExtList('extendedKeyUsage') + ( + %{SSL_CLIENT_I_DN_CN} == "ESTEID2018" + || %{SSL_CLIENT_I_DN_CN} == "ESTEID2025" + ) + and ( + "TLS Web Client Authentication, E-mail Protection" + in PeerExtList('extendedKeyUsage') + ) ) ``` -Selle konfiguratsiooni võib lisada kas virtuaalse hosti või Apache -serveri üld-konfiguratsiooni juurde. Pärast ülaltoodud tingimuste -lisamist on teenuse poole lubatud pöörduda vaid sertifikaatidega millel -on korrektne `extendedKeyUsage` väli ning mis on väljastatud serveri -poolt lubatud ahelast. +Konfiguratsiooni võib lisada virtuaalhosti või Apache üldkonfiguratsiooni. +Rakendus või autentimislüüs peab seejärel parsima valideeritud +lõppsertifikaati ja autentimise tagasi lükkama, kui selles ei ole nii NCP+ +OID-d kui ka väljastajale vastavat dokumendipoliitika OID-d. +Sertifikaaditoodet ei tohi tuletada ainult subjekti, väljastaja või EKU järgi +ning `anyPolicy` OID-d (`2.5.29.32.0`) ei tohi käsitleda ID-kaardi poliitika +tõendina. + +Kui rakendus on liidestatud CGI või mõne muu Apache keskkonnamuutujaid +kasutava liidese kaudu, teeb `SSLOptions +ExportCertData` PEM-kodeeritud +lõppsertifikaadi kättesaadavaks muutujas `SSL_CLIENT_CERT`. Muude liideste +puhul tuleb kasutada rakendusplatvormi TLS kliendisertifikaadi API-t. +Sertifikaadi andmeid tohib usaldada ainult kaitstud Apache ja rakenduse +vahelisest ühendusest; kliendi saadetud sertifikaadipäist ei tohi usaldada. + +Eksporditud sertifikaadi laienduse kontrollimiseks testi: + +```bash +$ openssl x509 -in client.pem -noout -text +``` + +Võrdle jaotist `X509v3 Certificate Policies` eespool viidatud kehtivate +poliitika- ja sertifikaadiprofiilide allikatega. Testi vähemalt üht +lubatud ID-kaardi sertifikaati ja seotud hierarhiates väljastatud muude +toodete sertifikaate, sealhulgas vajaduse korral Mobiil-ID-d. > **Märkus:** Kui on kasutusel mõni muu liikluse filtreerimise vahend/võimalus, siis > on soovitav turvaline konfiguratsioon juurutada ka seal. SK on F5 @@ -601,16 +665,6 @@ poolt lubatud ahelast. > peatükist „Defence: implement ID-card authentication securely": > -> **Märkus:** Soovituslik meetod ebakorrektsete sertifikaatide vältimiseks on -> kasutada sertifikaatides olevaid OIDe. Paraku ei ole hetkeseisuga -> teada meetodit, kuidas seda serveri tasemel teha. Võimalusel tuleks -> võtta autentimise sertifikaat veebirakenduse tasemel lahti ja -> kontrollida, kas see sisaldab mõnda korrektset OIDi ning kui ei -> sisalda, siis mitte autentida. Hetkeseisuga teadaolevad OIDid on SK -> publitseerinud peatükis „Only accept certificates with trusted -> issuance policy": -> - #### Kasutajale kuvatavate sertifikaatide filtreerimine Vaikimisi konfiguratsioonis ei piirata kasutajale kuvatavate @@ -868,20 +922,33 @@ Täielik näidiskonfiguratsiooni fail on saadaval aadressil Require expr ( - (%{SSL_CLIENT_I_DN_CN} == "ESTEID2018" || %{SSL_CLIENT_I_DN_CN} == "ESTEID2025") - and "TLS Web Client Authentication, E-mail Protection" in PeerExtList('extendedKeyUsage') + ( + %{SSL_CLIENT_I_DN_CN} == "ESTEID2018" + || %{SSL_CLIENT_I_DN_CN} == "ESTEID2025" + ) + and ( + "TLS Web Client Authentication, E-mail Protection" + in PeerExtList('extendedKeyUsage') + ) ) @@ -901,16 +968,19 @@ Täielik näidiskonfiguratsiooni fail on saadaval aadressil + +[^6]: Lubatud loend põhineb + [ESTEID2018 sertifitseerimispoliitikal v4.0](https://www.id.ee/wp-content/uploads/2025/10/cp_esteid_v4.0-08.10.2025.pdf), + [ESTEID2025 sertifitseerimispoliitikal v2.0](https://repository.eidpki.ee/static/documents/eid-cp-v-2.0_04.06.2026_allkirjastatud.pdf) + ja [Zetesi sertifikaadiprofiilidel](https://repository.eidpki.ee/static/documents/CertificateProfiles-20260520.pdf). + Enne tootmise lubatud loendi muutmist kontrolli + [Zetesi repositooriumi](https://repository.eidpki.ee/repository/) ning + teenuseosutajate kehtivaid poliitikaid ja profiile. diff --git a/apache/index.md b/apache/index.md index 37fe95b..0401c78 100644 --- a/apache/index.md +++ b/apache/index.md @@ -2,7 +2,7 @@ **[Eesti keeles (In Estonian)](index.et.md)** -**Version:** 26.04/1 +**Version:** 26.08/1 **Published by:** [RIA](https://www.ria.ee/) @@ -27,6 +27,7 @@ | 22/08/2024 | 24.08/1 | Ubuntu version updated to Ubuntu Server 24.04. Apache version updated to 2.4.62. Updates in the virtual host configuration. — 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 +| 21/08/2026 | 26.08/1 | Updated certificate-key, TLS protocol, cipher-suite, certificate-policy, and OCSP guidance based on the 2026 cryptographic algorithms life-cycle report. --- @@ -143,6 +144,17 @@ $ openssl req -new -key Apache2404.key -out Apache2404.csr -subj /C=EE/O=OctoX/C the actual address of the website[^3]. The names must also be resolvable in name services. +Generate a separate private key for every independent TLS server. Do not copy +one key between servers merely because a wildcard or multi-SAN certificate +could cover all their names. Keeping keys separate limits the impact of a +server or key compromise. + +For production deployments, use a hardware security module (HSM) or an +equivalent non-exportable hardware-backed key store where supported. Generate +the key inside the device and keep it non-exportable. Confirm that the HSM, +OpenSSL integration, and certificate issuer support the selected ECDSA P-384 +key before deployment. The file-based key in this example is not an HSM setup. + The contents of the CSR can be viewed by running ```bash @@ -172,67 +184,6 @@ Certificate Request: Signature Value: ``` -###### RSA - -*This section is retained for those who prefer RSA-based certificates. The rest of the document uses ECC.* - -Create a CSR and a private key with the command - -```bash -$ openssl req -newkey rsa:2048 -keyout Apache2021.key -sha256 -subj "/CN=Apache5.kaheksa.xi" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf "[SAN]\nsubjectAltName=DNS:Apache2021.kaheksa.xi,DNS:Apache5.kaheksa.xi")) -out Apache2021.csr -nodes -Generating a RSA private key -........+++++ -.++++ -writing new private key to 'Apache2021.key' ------ -``` - -1. `Apache2021.key` is the private key of the certificate; -2. `Apache2021.csr` is the CSR for the CA; -3. `Apache5.kaheksa.xi` is the subject name for the certificate; -4. `Apache2021.kaheksa.xi` and `Apache5.kaheksa.xi` are the SAN DNS names - for the certificate. These names must correspond to the actual - address of the website[^4]. The names must also be resolvable in - name services. - -The contents of the CSR can be viewed with the command - -```bash -$ openssl req -in Apache2021.csr -noout -text -Certificate Request: - Data: - Version: 1 (0x0) - Subject: CN = Apache5.kaheksa.xi - Subject Public Key Info: - Public Key Algorithm: rsaEncryption - RSA Public-Key: (2048 bit) - Modulus: - 00:c9:4f:a2:54:bd:1a:bb:88:a6:ec:16:c9:3e:28: - ee:f6:09:3d:a3:d7:86:fa:67:a4:e5:73:3b:38:70: - 70:73:b0:01:95:7a:8d:c3:47:46:49:b9:12:52:20: - 08:0c:ed:f5:ec:c5:4e:25:3e:27:9b:98:67:b0:bd: - c2:cd:00:98:54:36:d4:bf:b8:60:d9:aa:26:de:6a: - da:11:23:2e:a9:05:94:ff:e8:bb:d2:5e:c2:68:8d: - 63:97:71:5e:0a:a0:49:fc:27:c7:28:c4:7d:53:12: - 1c:e6:2e:9d:bd:81:5b:ff:6a:e5:cf:b5:1a:1b:a3: - 5a:2e:9b:bd:0c:fe:c8:8f:ed:ff:b6:08:9a:1a:69: - 4f:88:a1:1c:c7:9d:84:53:f0:77:2f:db:ba:2a:9a: - 16:f4:78:02:ca:e2:29:f7:f0:f3:61:df:00:ce:3f: - fa:80:c5:ca:2d:37:a4:2e:a4:8c:be:a2:b3:c9:fd: - 46:4e:20:fb:18:8b:3d:09:6a:be:01:3d:af:29:dd: - e2:b6:63:3c:3e:46:c1:7a:9b:08:83:c9:32:c5:54: - b2:e6:3d:a3:68:b6:8d:53:cb:36:c2:20:7d:77:63: - c7:cf:c9:11:36:b3:47:9b:10:8f:19:66:cb:a4:0f: - 50:f5:35:bf:0d:53:82:cb:ad:3c:1f:5a:1a:2b:70: - a4:8f - Exponent: 65537 (0x10001) - Attributes: - Requested Extensions: - X509v3 Subject Alternative Name: - DNS:Apache2021.kaheksa.xi, DNS:Apache5.kaheksa.xi - Signature Algorithm: sha256WithRSAEncryption -``` - ##### Ordering and installing an SSL certificate The CSR `Apache2404.csr` should be sent to trustworthy CA. In the demo @@ -420,17 +371,14 @@ To Action From 443/tcp (v6) ALLOW Anywhere (v6) ``` -### Checking the status of the user's certificate against the OCSP service[^5] +### Checking client-certificate revocation with OCSP[^4] -Using the OCSP (Online Certificate Status Protocol) service, you can -check the revocation status of client certificates practically in real -time. With every client authentication attempt, the web server sends a -query to the OCSP service, which responds with the certificate status. +OCSP (Online Certificate Status Protocol) lets Apache check the revocation +status of a client certificate during authentication. -SK and Zetes offer a free-access (free-of-charge) AIA OCSP service. For -certificates issued under the `ESTEID2018` and `ESTEID2025` CA, AIA OCSP -service location is already included in the certificate -(, ). +Certificates issued under the `ESTEID2018` and `ESTEID2025` CAs contain +their AIA OCSP service address ( and +). ![ESTEID2018 AIA OCSP address in the certificate](./img/image8.png) @@ -443,8 +391,49 @@ SSLOCSPEnable leaf SSLOCSPUseRequestNonce off ``` -Reload the Apache2 web service with `systemctl reload apache2`. With this configuration, the OCSP service address is taken -from the user certificate. +The `leaf` value checks the end-user certificate. The responder address is +taken from that certificate. This strict configuration does not use +`no_ocsp_for_cert_ok`: a missing responder URL or an unsuccessful OCSP check +prevents client-certificate authentication. Allow outbound HTTP access to +both responders and monitor Apache errors. Reload Apache with +`systemctl reload apache2` after applying the change. + +### Stapling the server-certificate OCSP response + +Client-certificate validation above and server-certificate OCSP stapling are +separate functions. Stapling lets Apache obtain a signed status response for +its own server certificate and send it during the TLS handshake. This avoids +each browser querying the issuing CA and improves client privacy.[^5] + +First check whether the server certificate contains an OCSP responder URI: + +```bash +$ openssl x509 -in /etc/ssl/certs/Apache2404.pem -noout -ocsp_uri +``` + +If the command returns a supported URI, enable the shared-memory cache and +production error handling in `/etc/apache2/mods-available/ssl.conf`: + +```apache +SSLStaplingCache "shmcb:${APACHE_RUN_DIR}/ssl_stapling(32768)" +SSLStaplingReturnResponderErrors off +SSLStaplingResponderTimeout 4 +SSLStaplingErrorCacheTimeout 60 +``` + +Ensure `socache_shmcb` is enabled, then add `SSLUseStapling On` to the HTTPS +virtual host. Do not enable stapling when the issuing CA does not provide an +OCSP service. + +```bash +$ a2enmod socache_shmcb +$ systemctl restart apache2 +$ openssl s_client -connect Apache2404.octox.demo:443 \ + -servername Apache2404.octox.demo -status Require expr ( - (%{SSL_CLIENT_I_DN_CN} == "ESTEID2018" || %{SSL_CLIENT_I_DN_CN} == "ESTEID2025") - and "TLS Web Client Authentication, E-mail Protection" in PeerExtList('extendedKeyUsage') + ( + %{SSL_CLIENT_I_DN_CN} == "ESTEID2018" + || %{SSL_CLIENT_I_DN_CN} == "ESTEID2025" + ) + and ( + "TLS Web Client Authentication, E-mail Protection" + in PeerExtList('extendedKeyUsage') + ) ) ``` -The configuration above can be added to the virtual host or to the -Apache main configuration. After adding these requirements, only -certificates with the correct `extendedKeyUsage` field issued from the -enabled chain can access the services. +The configuration can be added to the virtual host or Apache's main +configuration. The application or an authentication gateway must then parse +the verified leaf certificate and reject authentication unless both the NCP+ +OID and a matching document-policy OID are present. Do not infer the +certificate product from its subject, issuer, or EKU alone, and do not treat +the `anyPolicy` OID (`2.5.29.32.0`) as proof of an ID-card policy. + +When the application is integrated through CGI or another interface that +uses Apache environment variables, `SSLOptions +ExportCertData` makes the +PEM-encoded leaf certificate available as `SSL_CLIENT_CERT`. Other +application interfaces should use their native TLS client-certificate API. +Only accept certificate data supplied through the trusted Apache-to- +application connection; never trust a client-provided certificate header. + +To inspect the extension while testing an exported certificate: + +```bash +$ openssl x509 -in client.pem -noout -text +``` + +Check the `X509v3 Certificate Policies` section against the current policy +and certificate-profile sources cited above. Test at least one +accepted ID-card certificate and certificates for other products issued in +related hierarchies, including Mobile-ID where applicable. > **Note:** If you are using another feature to filter network traffic, the secure > configuration should be implemented there, too. SK has published @@ -593,16 +660,6 @@ enabled chain can access the services. > securely': > -> **Note:** The recommended method for avoiding incorrect certificates is using -> OIDs in the certificates. Unfortunately, there is currently no method -> for doing this at the server level. If possible, open the certificate -> at the web application level, check for a correct OID in the -> certificate, and if there is none, reject the authentication request. -> All currently known OIDs are listed in the chapter 'Only accept -> certificates with trusted issuance policy' in the following article -> published by SK: -> - #### Filtering certificates displayed to the user By default, the selection of certificates displayed to the user is not @@ -861,20 +918,33 @@ The full demonstrative configuration file is available at Require expr ( - (%{SSL_CLIENT_I_DN_CN} == "ESTEID2018" || %{SSL_CLIENT_I_DN_CN} == "ESTEID2025") - and "TLS Web Client Authentication, E-mail Protection" in PeerExtList('extendedKeyUsage') + ( + %{SSL_CLIENT_I_DN_CN} == "ESTEID2018" + || %{SSL_CLIENT_I_DN_CN} == "ESTEID2025" + ) + and ( + "TLS Web Client Authentication, E-mail Protection" + in PeerExtList('extendedKeyUsage') + ) ) @@ -894,16 +964,19 @@ The full demonstrative configuration file is available at + +[^6]: The allowlist is based on the + [ESTEID2018 certificate policy v4.0](https://www.id.ee/wp-content/uploads/2025/10/cp_esteid_v4.0-08.10.2025.pdf) + and the [ESTEID2025 certificate policy v2.0](https://repository.eidpki.ee/static/documents/eid-cp-v-2.0_04.06.2026_allkirjastatud.pdf), + supplemented by the [Zetes certificate profiles](https://repository.eidpki.ee/static/documents/CertificateProfiles-20260520.pdf). + Check the [Zetes repository](https://repository.eidpki.ee/repository/) + and the service providers' current policies and profiles before changing + the production allowlist. diff --git a/iis/_config.yml b/iis/_config.yml index d1a1dcc..8036be6 100644 --- a/iis/_config.yml +++ b/iis/_config.yml @@ -4,4 +4,5 @@ description: Technical documentation for configuring IIS to support Estonian Dig google_analytics: layout: minimal nav_enabled: false +enable_copy_code_button: true baseurl: "/iis" diff --git a/iis/img/image12.png b/iis/img/image12.png index 1c4eec8..59f802e 100644 Binary files a/iis/img/image12.png and b/iis/img/image12.png differ diff --git a/iis/img/image14.png b/iis/img/image14.png index d2e5f1b..357aeb5 100644 Binary files a/iis/img/image14.png and b/iis/img/image14.png differ diff --git a/iis/img/image18.png b/iis/img/image18.png deleted file mode 100644 index 0455c31..0000000 Binary files a/iis/img/image18.png and /dev/null differ diff --git a/iis/img/image19.png b/iis/img/image19.png deleted file mode 100644 index 5a20dde..0000000 Binary files a/iis/img/image19.png and /dev/null differ diff --git a/iis/img/image20.png b/iis/img/image20.png deleted file mode 100644 index e2b45bd..0000000 Binary files a/iis/img/image20.png and /dev/null differ diff --git a/iis/img/image21.png b/iis/img/image21.png deleted file mode 100644 index 86d8b28..0000000 Binary files a/iis/img/image21.png and /dev/null differ diff --git a/iis/img/image23.png b/iis/img/image23.png deleted file mode 100644 index 3045b5b..0000000 Binary files a/iis/img/image23.png and /dev/null differ diff --git a/iis/img/image24.png b/iis/img/image24.png deleted file mode 100644 index 70204e6..0000000 Binary files a/iis/img/image24.png and /dev/null differ diff --git a/iis/img/image25.png b/iis/img/image25.png deleted file mode 100644 index a570bc2..0000000 Binary files a/iis/img/image25.png and /dev/null differ diff --git a/iis/img/image28.png b/iis/img/image28.png deleted file mode 100644 index 1ea22c1..0000000 Binary files a/iis/img/image28.png and /dev/null differ diff --git a/iis/img/image29.png b/iis/img/image29.png deleted file mode 100644 index d3812b3..0000000 Binary files a/iis/img/image29.png and /dev/null differ diff --git a/iis/img/image31.png b/iis/img/image31.png deleted file mode 100644 index 030a2aa..0000000 Binary files a/iis/img/image31.png and /dev/null differ diff --git a/iis/img/image32.png b/iis/img/image32.png deleted file mode 100644 index d428290..0000000 Binary files a/iis/img/image32.png and /dev/null differ diff --git a/iis/img/image33.png b/iis/img/image33.png deleted file mode 100644 index 6eb8838..0000000 Binary files a/iis/img/image33.png and /dev/null differ diff --git a/iis/img/image34.png b/iis/img/image34.png deleted file mode 100644 index edaf61d..0000000 Binary files a/iis/img/image34.png and /dev/null differ diff --git a/iis/img/image6.png b/iis/img/image6.png index 49c4a23..53e9988 100644 Binary files a/iis/img/image6.png and b/iis/img/image6.png differ diff --git a/iis/img/image7.png b/iis/img/image7.png deleted file mode 100644 index 6cfda4d..0000000 Binary files a/iis/img/image7.png and /dev/null differ diff --git a/iis/img/image8.png b/iis/img/image8.png deleted file mode 100644 index 85dd079..0000000 Binary files a/iis/img/image8.png and /dev/null differ diff --git a/iis/index.et.md b/iis/index.et.md index cfaa83a..48fe66f 100644 --- a/iis/index.et.md +++ b/iis/index.et.md @@ -2,7 +2,7 @@ **[In English](index.md)** -**Versioon:** 26.04/1 +**Versioon:** 26.08/1 **Väljaandja:** [RIA](https://www.ria.ee/) @@ -26,6 +26,7 @@ | 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 +| 21.08.2026 | 26.08/1 | Uuendatud platvorm Windows Server 2025 versioonile ning sertifikaadivõtme, TLS-i, šifrikomplektide, sertifikaadipoliitikate ja OCSP juhiseid 2026. aasta krüptograafiliste algoritmide elutsükli aruande põhjal. Juhend, kuidas autentida kasutajat IIS veebiserveril Eesti eID kaartidega. @@ -38,7 +39,13 @@ Juhend, kuidas autentida kasutajat IIS veebiserveril Eesti eID kaartidega. Käesolev juhend kirjeldab 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. +Juhendi serveriplatvorm on Windows Server 2025; kliendi poolel kasutatakse +Windows 10 operatsioonisüsteemi. Näidisjuhendis toetatakse +[SK ID Solutions](https://www.skidsolutions.eu/resources/certificates/) +`EE-GovCA2018` ja [Zetes](https://repository.eidpki.ee/) `EEGovCA2025` +ahelast pärinevaid sertifikaate. Kliendi poolel on kiipkaardi sertifikaadi +äratundmiseks vajalik 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. @@ -96,19 +103,57 @@ Aknas *Extensions* tuleb määrata järgmised omadused: ##### Sakk Private Key -Siit aknast valitakse CSP ehk sertifikaadi võtmete algoritm. Näidis-konfiguratsioonis kasutatakse algoritmi `ECDSA_P256`, seega valitakse loendist `ECDSA_P256` ja eemaldatakse nimekirja alguses olev RSA. +Siit aknast valitakse CSP ehk sertifikaadi võtmete algoritm. +Näidiskonfiguratsioonis eemaldatakse RSA valik ja valitakse `ECDSA_P384`. -![CSP valimine](./img/image6.png) +![ECDSA P-384 CSP valimine](./img/image6.png) + +Genereeri igale sõltumatule TLS-serverile eraldi privaatvõti. Ära kopeeri +sama võtit mitmesse serverisse üksnes seetõttu, et metamärgiga või mitme SAN +nimega sertifikaat kataks kõik serverinimed. Eraldi võtmed piiravad serveri +või võtme kompromiteerumise mõju. + +Tootmislahenduses kasuta võimaluse korral füüsilist turvamoodulit (HSM) või +samaväärset mitteeksporditava võtmega riistvaralist võtmepakkujat. Genereeri +võti seadmes ja hoia see mitteeksporditavana. Enne kasutuselevõttu veendu, et +HSM-i võtmepakkuja, IIS ja sertifikaadi väljastaja toetavad valitud ECDSA +P-384 võtit. Siin näidatud tarkvaralise võtmepakkuja töövoog ei ole HSM-i +seadistus. Klikkige *OK* ja *Next*, määrake kaust ning nimi ja salvestage sertifikaadi päring `Base64` formaadis. -Värskelt loodud sertifikaadi päringufaili omadused on võimalik kontrollida käsuga `certutil -dump PÄRINGUFAILI_NIMI`. +Kontrolli värskelt loodud sertifikaadi päringufaili `certutil` abil: + +```bat +certutil -dump iis2112.req +``` + +Oluline väljund peaks sarnanema järgmisega; päringuspetsiifilised räsid ja +avaliku võtme toorbaidid on välja jäetud: -![Päringufaili sisu](./img/image7.png) +```text +PKCS10 Certificate Request: +Version: 1 +Subject: + CN=iis2111.kaheksa.xi + C=EE + O=OctoX + OU=DEV -Tuleb veenduda, et ka DNS alternatiivsed nimed on päringufailis olemas: +Public Key Algorithm: + Algorithm ObjectId: 1.2.840.10045.2.1 ECC + Algorithm Parameters: + 1.3.132.0.34 ECDH_P384 +Public Key Length: 384 bits -![DNS aliased päringufailis](./img/image8.png) +Subject Alternative Name + DNS Name=iis2112.kaheksa.xi + DNS Name=iis2111.kaheksa.xi + DNS Name=MyWebServer.kaheksa.xi +``` + +Kontrolli, et avalik võti on 384-bitine ja kõik vajalikud DNS-nimed on +jaotises `Subject Alternative Name` olemas. Sertifikaadi päringufail edastatakse mõnele CA serverile, paludes selle alusel sertifikaat genereerida. Tulemus on järgmine: @@ -116,7 +161,11 @@ Sertifikaadi päringufail edastatakse mõnele CA serverile, paludes selle alusel #### Sertifikaadi installeerimine -IIS server peab usaldama sertifikaati `OctoX Demo CA 21.11`, mis on serveri sertifikaadi väljastajaks. Selleks tuleb kontrollida selle sertifikaadi olemasolu *usaldusväärsete juursertifikaatide*[^2] konteineris. Kui väljastaja CA sertifikaat sealt puudub, tuleb see lisada![^3] +IIS server peab usaldama sertifikaati `OctoX Demo CA 21.11`, mis on serveri +sertifikaadi väljastajaks. Selleks tuleb kontrollida selle sertifikaadi +olemasolu *usaldusväärsete juursertifikaatide* (*Trusted Root Certification +Authorities*) konteineris. Kui väljastaja CA sertifikaat sealt puudub, tuleb +see lisada![^2] ![IIS server usaldab temale sertifikaadi väljastanud CA-d.](./img/image10.png) @@ -126,9 +175,14 @@ IIS serveri sertifikaat ise tuleb paigaldada IIS serveril lokaalse arvuti person ### Ühepoolse SSL-konfiguratsiooni loomine -Ühepoolse SSL-i kehtestamiseks peab veebisaidil olema kirjeldatud SSL port (vaikimisi 443) ja see peab olema seotud soovitava sertifikaadiga. Koheselt tuleb keelata ka vanade SSL/TLS protokollide (vanemad kui 1.2) kasutamine! +Ühepoolse TLS-i konfigureerimiseks lisa HTTPS-seos (tavaliselt port 443), +vali serveri sertifikaat ja keela pärand-TLS-protokollid. + +Järgmisel ekraanipildil on Windows Server 2025 seose olulised seadistused. +Vali serveri sertifikaat, hoia *Disable Legacy TLS* märgituna ja jäta +*Disable TLS 1.3 over TCP* märkimata. -![Veebisaidil on lubatud 443 port ja kasutatavaks sertifikaadiks on iis2111.kaheksa.xi, vanad TLS protokollid tuleb keelata!](./img/image12.png) +![Windows Server 2025 HTTPS-seose seadistused](./img/image12.png) Peale määrangute kinnitamist ühepoolne SSL töötab! @@ -139,6 +193,37 @@ Peale määrangute kinnitamist ühepoolne SSL töötab! 1. Kasutusel on värskelt installeeritud sertifikaat `2111.kaheksa.xi`; 2. Kasutusel on TLS 1.3 protokoll. +#### Serverisertifikaadi OCSP vastuse stapling + +Kui serverisertifikaat sisaldab OCSP teenuse URI-d ja sertifikaadi väljastanud +CA toetab OCSP-d, jäta HTTPS-seose valik *Disable OCSP Stapling* märkimata. +HTTP.sys saab siis hankida serverisertifikaadi kohta allkirjastatud +olekuvastuse ja saata selle TLS kätluse ajal. Nii ei pea iga veebilehitseja +väljastanud CA-le eraldi päringut tegema ja kliendi privaatsus paraneb.[^8] + +Kuva seos ja kontrolli, et OCSP stapling ei ole keelatud: + +```bat +netsh http show sslcert 0.0.0.0:443 +``` + +Vajadusel luba stapling olemasoleval seosel: + +```bat +netsh http update sslcert ipport=0.0.0.0:443 disableocspstapling=disable +``` + +Ära luba stapling'ut, kui sertifikaadi väljastaja OCSP teenust ei paku. +Kontrolli tulemust OpenSSL-iga kliendist: + +```bash +$ openssl s_client -connect iis2111.kaheksa.xi:443 \ + -servername iis2111.kaheksa.xi -status **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 saab 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 saab 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) +> **Märkus:** TLS 1.3 koos *in-handshake* kliendisertifikaadi autentimisega +> on Windows Server 2025 soovituslik konfiguratsioon. HTTPS-seose +> seadistustes tuleb märkida *Negotiate Client Certificate*, et HTTP.sys +> küsiks kliendisertifikaati esialgse TLS kätluse ajal. Valikut +> *Disable TLS 1.3 over TCP* ei märgita. Microsoft kirjeldab Server 2025 +> lahendust IIS Support Blogis[^3]. + +> **Ühilduvus:** Windows Server 2022 ei kuva IIS Manageris valikut +> *Negotiate Client Certificate*. Kui Server 2022 kasutamine peab jätkuma, +> tuleb kasutada allpool kirjeldatud +> [`netsh` protseduuri](#windows-server-2022-uhilduvus). Levinud +> veebilehitsejad ei toeta selle platvormi vaikimisi kasutatavat TLS 1.3 +> *post-handshake* autentimist. TLS 1.3 võib keelata ja TLS 1.2 kasutada +> ainult dokumenteeritud erandina, kui rakendus peab küsima +> kliendisertifikaati pärast esialgse TLS ühenduse loomist ja rakenduse +> voogu ei ole võimalik muuta. + +Järgmine Windows Server 2025 ekraanipilt näitab TLS 1.2 ühilduvuserandit. +Enne seose salvestamist vali serveri sertifikaat. See ei ole Windows Server +2025 soovituslik konfiguratsioon: + +![TLS 1.2 ühilduvuserand: TLS 1.3 keelamine HTTPS-seose seadistustes](./img/image14.png) ### Eesti eID sertifikaatide häälestus IIS serveril @@ -164,7 +264,7 @@ IIS serveris tuleb sertifikaadid publitseerida järgmiselt: 1. Usaldusväärsete juursertifikaatide konteinerisse: 1. `EE-GovCA2018` () 2. `EEGovCA2025` () -2. Kesktaseme sertifikaatide konteinerisse[^5]: +2. Kesktaseme sertifikaatide konteinerisse[^4]: 1. `ESTEID2018` () 2. `ESTEID2025` () @@ -178,31 +278,75 @@ Loodud konfiguratsioon lubab veebisaidile ligipääsu 443 pordi kaudu, kasutajal 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) +![TLS 1.2 ühilduvuserandi näide: autentimine õnnestus](./img/image17.png) + +Enne soovitusliku TLS 1.3 konfiguratsiooni testimist tuleb lubada allpool +kirjeldatud *in-handshake* autentimine. 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 soovitakse siiski kasutada `TLS 1.3` protokolli ja sertifikaadiga autentimist, saab lubada in-handshake autentimismeetodi. Selle meetodi puhul küsib server kliendilt *Server Hello* saatmisel koheselt ka sertifikaati. +*In-handshake* autentimise korral küsib server kliendisertifikaati esialgse +TLS kätluse ajal. See on vajalik, sest TLS 1.3 ei toeta korduskätlust. + +#### Windows Server 2025 + +1. Vali IIS Manageris veebisait ja ava *Bindings*. +2. Vali HTTPS-seos ja vajuta *Edit*. +3. Märgi *Negotiate Client Certificate*. +4. Jäta *Disable TLS 1.3 over TCP* märkimata ja salvesta seos. +5. Vajadusel kontrolli käsuga `netsh http show sslcert`, et seose väärtus + `Negotiate Client Certificate` on lubatud. + +#### Windows Server 2022 ühilduvus {#windows-server-2022-uhilduvus} + +Windows Server 2022 ei paku seose juures vastavat märkeruutu. Ainult sellel +vanemal platvormil tuleb kliendisertifikaadi läbirääkimine lubada käsuga +`netsh`: + +1. Kuva seose konfiguratsioon: + + ```bat + netsh http show sslcert 0.0.0.0:443 + ``` -In-handshake autentimismeetodi lubamiseks tuleb teha järgmist: + Salvesta räsi ja rakenduse ID. Enne muudatust sarnaneb oluline väljund + järgmisega: -1. Dokumenteerida olemasoleva sertifikaadi määrangud käsuga `netsh http show sslcert`. Oluline on üles märkida `Certificate Hash` ja `Application ID`: + ```text + Certificate Hash : + Application ID : {} + Negotiate Client Certificate : Disabled + ``` - ![Vaikimisi on määrang "negotiate client certificate" keelatud](./img/image18.png) +2. Eemalda sertifikaadi seotus 443 pordiga: -2. Eemaldatakse sertifikaadi seotus 443 pordiga käsuga `netsh http del sslcert 0.0.0.0:443`: + ```bat + netsh http del sslcert 0.0.0.0:443 + ``` - ![Sertifikaadi eemaldamine 443 pordi küljest.](./img/image19.png) + Käsu edukas väljund on `SSL Certificate successfully deleted`. -3. Sertifikaat lisatakse 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`: +3. Seo sertifikaat uuesti pordiga 443 ja luba *in-handshake* + kliendisertifikaadiga autentimine: - ![Clientcertnegotiation lubamine](./img/image20.png) + ```bat + netsh http add sslcert ipport=0.0.0.0:443 ^ + certhash= ^ + appid={} ^ + certstorename=MY ^ + clientcertnegotiation=Enable + ``` -Vaadates uuesti sertifikaadi infot, on näha, et `Negotiate Client Certificate` on nüüd lubatud: + Asenda `CERTIFICATE_HASH` ja `APPLICATION_ID` 1. sammus saadud + väärtustega. Käsu edukas väljund on `SSL Certificate successfully added`. -![In-handshake autentimismeetod on nüüd sees](./img/image21.png) +Käivita uuesti 1. sammu käsk `show sslcert`. Oluline väljund peab nüüd olema: + +```text +Negotiate Client Certificate : Enabled +``` > **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 ühepoolne SSL ühendus on juba kliendi sertifikaadiga autentimata loodud ja samal lehel soovitakse kliendi sertifikaadiga autentides mõnele kaitstud ressursile ligi pääseda, siis see ebaõnnestub, kuna `TLS 1.3` ei toeta sellist lähenemist. Vajadusel tuleb see „maandumise" probleem ühel või teisel viisil lahendada. @@ -216,29 +360,61 @@ Käesolevas näites on lubatud ainult anonüümne autentimine: Selle dokumendi eesmärgiks ei ole anda täpseid juhiseid optimaalseks veebisaitide konfigureerimiseks ega turvamiseks. Pigem tutvustatakse siin konfiguratsiooni kahepoolse SSL-i kasutamiseks Eesti eID kaartidega. Siiski tuuakse järgnevalt välja punktid, mida on oluline mainida. -### Kasutajapoolsete sertifikaatide filtreerimine +### Kasutajale kuvatavate sertifikaatide filtreerimine + +Vaikimisi võib klient kuvada kõiki isiklikke sertifikaate, millel on privaatvõti +ja kliendi autentimise EKU. IIS saab saata lubatud sertimiskeskuste loendi, et +klient kuvaks toetatud ahelate sertifikaate. -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. +Väljastajate loend parandab sertifikaadi valimist, kuid ei tõesta, et valitud +lõppsertifikaat on ID-kaardi autentimissertifikaat. Erinevad +sertifikaaditooted võivad kasutada sama juur- või kesktaseme CA-d. Enne +autenditud identiteedi aktsepteerimist tuleb rakendada järgmises jaotises +kirjeldatud sertifikaadipoliitika kontroll. Seame eesmärgiks kuvada kasutaja pool vaid sertifikaadid, mis pärinevad kindla juurserveri `EE-GovCA2018` ja `EEGovCA2025` ahelast. -1. Kuvatakse aktiivse IIS sertifikaadi info käsuga `netsh http show sslcert 0.0.0.0:443`: +1. Kuva aktiivse seose konfiguratsioon: + + ```bat + netsh http show sslcert 0.0.0.0:443 + ``` - ![Vaikimisi seotud sertifikaadi omadused](./img/image23.png) + Salvesta räsi ja rakenduse ID. Enne muudatust sarnaneb oluline väljund + järgmisega: -2. Eemaldatakse sertifikaadi seos käsuga `netsh http del sslcert 0.0.0.0:443`: + ```text + Certificate Hash : + Application ID : {} + Ctl Store Name : (null) + ``` - ![Sertifikaadi eemaldamine](./img/image19.png) +2. Eemalda sertifikaadi seos: -3. Sertifikaat lisatakse uuesti, määrates sertifikaatide filtreerimiseks arvuti sertifikaatide kaust `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`: + ```bat + netsh http del sslcert 0.0.0.0:443 + ``` - ![Lisame sertifikaadi uute omadustega](./img/image24.png) + Käsu edukas väljund on `SSL Certificate successfully deleted`. - `Certhash` ja `appid` väärtused saab võtta 1. sammu väljundist ülal. +3. Lisa sertifikaat uuesti ja kasuta lubatud sertimiskeskuste loendina + sertifikaadihoidlat `Client Authentication Issuers`: -4. Tuleb kontrollida, et `CTL Store Name` on uuel sertifikaadi väljavõttel `ClientAuthIssuer`: + ```bat + netsh http add sslcert ipport=0.0.0.0:443 ^ + certhash= ^ + appid={} ^ + sslctlstorename=ClientAuthIssuer + ``` - ![Uuesti seotud sertifikaadi omadused](./img/image25.png) + Asenda `CERTIFICATE_HASH` ja `APPLICATION_ID` 1. sammus saadud + väärtustega. Käsu edukas väljund on `SSL Certificate successfully added`. + +4. Käivita uuesti 1. sammu käsk `show sslcert` ja kontrolli olulist väljundit: + + ```text + Ctl Store Name : ClientAuthIssuer + ``` Soovi korral on võimalik vaadata ka IIS-i konfiguratsioonist, et SSL sertifikaat on uuesti korrektselt seotud 443 pordiga. @@ -252,33 +428,148 @@ Seame eesmärgiks kuvada kasutaja pool vaid sertifikaadid, mis pärinevad kindla 7. Vajadusel taaskäivitatakse IIS teenus või server ja kontrollitakse soovitud lahenduse toimimist! -### Kliendisertifikaatide kehtivuse kontroll OCSP teenuse vastu - -OCSP teenuse abil on võimalik 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 tegelikult midagi eraldi konfigureerima ei ole vaja. Küll aga on soovi korral võimalik kehtestada ka keskelt AIA OCSP kontroll: - -![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. Käesoleva konfiguratsiooni puhul ei ole see tegelikult oluline, kuna CRL-i üldse ei kasutata. 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) +### ID-kaardi sertifikaadipoliitika valideerimine + +Enne autenditud identiteedi aktsepteerimist tuleb nõuda, et: + +1. HTTP.sys valideerib edukalt kogu sertifikaadiahela; +2. väljastaja on selgesõnaliselt lubatud kesktaseme CA; +3. `extendedKeyUsage` lubab TLS veebikliendi autentimist; +4. lõppsertifikaadi laiendus `X509v3 CertificatePolicies` (`2.5.29.32`) + sisaldab nii NCP+ autentimispoliitika OID-d kui ka sertifikaadi CA + põlvkonnale vastavat lubatud dokumendipoliitika OID-d.[^9] + +Käesolevas juhendis käsitletud tootmissertifikaatide lubatud loend on: + +```text +# Nõutav igas aktsepteeritavas autentimissertifikaadis +0.4.0.2042.1.2 + +# ESTEID2018 - nõua üht neist dokumendipoliitika OID-dest +1.3.6.1.4.1.51361.1.1.1 +1.3.6.1.4.1.51361.1.1.2 +1.3.6.1.4.1.51361.1.1.3 +1.3.6.1.4.1.51361.1.1.4 +1.3.6.1.4.1.51361.1.1.5 +1.3.6.1.4.1.51361.1.1.6 +1.3.6.1.4.1.51361.1.1.7 +1.3.6.1.4.1.51455.1.1.1 + +# ESTEID2025 - nõua üht neist dokumendipoliitika OID-dest +1.3.6.1.4.1.51361.2.1.1 +1.3.6.1.4.1.51361.2.1.2 +1.3.6.1.4.1.51361.2.1.3 +1.3.6.1.4.1.51361.2.1.4 +1.3.6.1.4.1.51361.2.1.5 +1.3.6.1.4.1.51361.2.1.6 +1.3.6.1.4.1.51455.2.1.1 +``` + +Seosta dokumendipoliitika OID valideeritud väljastajaga: `ESTEID2018` +sertifikaati ei tohi aktsepteerida `ESTEID2025` poliitika OID alusel ega +vastupidi. Ühine NCP+ OID ei ole tootepõhine ja sellest üksi ei piisa. +Tootmise lubatud loendisse ei tohi lisada test-OID-sid, näiteks Zetesi OID-sid +prefiksiga `2.999`. + +Sertifikaadihoidla `Client Authentication Issuers` ja EKU kontroll on +kasulikud lisakaitsed, kuid need ei tuvasta sertifikaaditoodet. IIS-i rakendus +või autentimislüüs peab valideeritud kliendisertifikaati kontrollima ja +autentimise tagasi lükkama, kui selles ei ole nii NCP+ OID-d kui ka +väljastajale vastavat dokumendipoliitika OID-d. Sertifikaaditoodet ei tohi +tuletada ainult subjekti, väljastaja või EKU järgi ning `anyPolicy` OID-d +(`2.5.29.32.0`) ei tohi käsitleda ID-kaardi poliitika tõendina. + +Kasuta rakendusplatvormi kliendisertifikaadi API-t. .NET-i rakenduses valideeri +sertifikaat `X509ChainPolicy.CertificatePolicy` abil.[^10] Kontrolli iga +lubatud, väljastajaga seotud kombinatsiooni eraldi: nõua samas ahela +valideerimises NCP+ OID-d ja üht vastava CA põlvkonna lubatud +dokumendipoliitika OID-d. Dokumendipoliitika OID-d on alternatiivid; ära lisa +kõiki lubatud dokumendipoliitika OID-sid ühte valideerimisse samaaegselt +nõutavate poliitikatena. + +HTTP päringu päises edastatud sertifikaati ei tohi usaldada, välja arvatud +juhul, kui usaldatud pöördproksi kirjutab päise üle ja rakendus on ligipääsetav +üksnes selle proksi kaudu. + +Eksporditud sertifikaadi kontrollimiseks testi: + +```bat +certutil -dump client.cer +``` + +Võrdle laiendust `Certificate Policies` eespool viidatud kehtivate poliitika- +ja sertifikaadiprofiilide allikatega. Testi vähemalt üht lubatud ID-kaardi +sertifikaati ja seotud hierarhiates väljastatud muude toodete sertifikaate, +sealhulgas vajaduse korral Mobiil-ID-d. + +### Kliendisertifikaadi tühistusoleku kontroll OCSP abil + +CA-de `ESTEID2018` ja `ESTEID2025` väljastatud sertifikaatides on AIA OCSP +teenuse aadress ( ja +). HTTP.sys kasutab sertifikaadis avaldatud +tühistusinfo hankimiseks Windowsi sertifikaadiahela mootorit. + +Kuva HTTPS-seos: + +```bat +netsh http show sslcert 0.0.0.0:443 +``` + +Kontrolli, et kliendisertifikaadi tühistusoleku ja kasutusotstarbe kontroll on +lubatud ning tühistusoleku kontroll ei piirdu ainult vahemällu salvestatud +andmetega. Vajadusel uuenda neid poliitikaid:[^8] + +```bat +netsh http update sslcert ipport=0.0.0.0:443 ^ + verifyclientcertrevocation=enable ^ + verifyrevocationwithcachedclientcertonly=disable ^ + usagecheck=enable +``` + +Luba serverist väljuv liiklus tühistusinfo teenustesse, monitoori Windowsi +CAPI2 ja HTTP Service'i tõrkeid ning testi kehtiva ja tühistatud +sertifikaadiga. Määra ja testi rakenduse käitumine tühistusinfo ajutise +kättesaamatuse korral. Ära kasuta aegunud OCSP päringute arvu registripoliitikat +OCSP eelistamiseks CRL-ile; lase praegusel sertifikaadiahela mootoril kasutada +igas sertifikaadis avaldatud tühistusinfot. ### 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 saab seda teha ka otse registris. `TLS 1.0` ja `TLS 1.1` keelamiseks tuleb registrisse lisada järgmine konfiguratsioon[^7]: - -- `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\`[^8]: +TLS protokollide valikul ei tohi tugineda IIS-i või Schanneli +vaikesätetele. TLS 1.0 ja TLS 1.1 tuleb keelata. Uutes ja ajakohastatud +lahendustes tuleb vaikimisi lubada ainult TLS 1.3. + +TLS 1.2 võib lisada üksnes dokumenteeritud erandina, kui teenust peavad +kasutama 2020. aasta või vanemad kliendid või kui kliendisertifikaati +peab küsima pärast esialgse TLS ühenduse loomist. Sertifikaadiga +autentimine iseenesest ei ole põhjus TLS 1.2 lubamiseks. Windows Server +2025 puhul tuleb kasutada eespool kirjeldatud seose valikut +*Negotiate Client Certificate*. + +Aruanne soovitab TLS 1.2 lubamisel korduskätluse keelata. Pärandlahendus, mis +küsib kliendisertifikaati alles pärast esialgset kätlust, ei saa samaaegselt +seda voogu säilitada ja soovitust järgida. Eelista eraldi seosel või +serverinimel kätluse ajal autentimist ning dokumenteeri allesjääv TLS 1.2 +korduskätluse sõltuvus erandina. + +Kui Schannel ja kasutatavad kliendid pakuvad tootmiskõlblikku tuge, eelista +hübriidrühma `X25519MLKEM768`. Juhend ei määra selle jaoks registri- ega +rühmapoliitika väärtust, sest tugi ja standarditud identifikaator sõltuvad +platvormist. Enne sellele tuginemist kontrolli läbiräägitud rühma ajakohase +TLS-skanneriga. + +Rohkem infot TLS protokolli kasutamise soovituste kohta leiab RIA +tellitud krüptograafiliste algoritmide elutsükli uuringust aadressil +. + +TLS protokollid tuleks hallata keskse poliitika või muu Windowsi +haldusvahendiga. Järgmisi registriväärtusi võib kasutada rakendatud +seadistuse kontrollimiseks või juhul, kui keskne haldusvahend ei ole +kasutatav. `TLS 1.0` ja `TLS 1.1` keelamiseks tuleb määrata[^5]: + +- `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\`[^6]: - `TLS 1.0\Server` - `Enabled DWORD:0` - `DisabledByDefault = DWORD:1` @@ -288,31 +579,96 @@ Lisaks IIS konfiguratsiooni juures vanade TLS protokollide keelamisele saab seda ![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. +Ainult TLS 1.3 kasutava serveri jaoks võib samas asukohas keelata ka +`TLS 1.2\Server`, määrates `Enabled DWORD:0` ja +`DisabledByDefault DWORD:1`. See on kogu süsteemi Schanneli +serverirakendusi mõjutav muudatus, mistõttu tuleb enne rakendamist +kontrollida teisi teenuseid ja pärast muudatust need taaskäivitada. +Dokumenteeritud TLS 1.2 ühilduvuserandi korral TLS 1.2 ei keelata. + +##### Pakkimine + +Hoia TLS-i pakkimine keelatuna. HTTP pakkimine on IIS-is eraldiseisev +funktsioon: keela dünaamilise sisu pakkimine rakendustes, mille vastused +sisaldavad koos ründaja juhitavat sisendit ja saladusi. Kui HTTP vastuste +pakkimine peab jääma lubatuks, peab rakendus takistama saitidevahelist +päringuvõltsimist ning leevendama vastuse pikkuse leket. Kontrolli TLS-i +tulemust ajakohase skanneriga, sest IIS ei paku TLS-i pakkimiseks tavapärast +saiditaseme seadistust. #### Šifrikomplektid (Cipher suites) -Windows serveriga tuleb vaikimisi kaasa mitmeid šifrikomplekte. Kõiki neid saab vaadata näiteks `PowerShell` käsuga `Get-TLSCipherSuite`[^9]. +Konfigureeri selge lubatud loend keskse poliitika või Windowsi TLS +PowerShelli käskude abil. Esmalt kontrolli paigaldatud operatsioonisüsteemi +toetatud komplekte käsuga `Get-TlsCipherSuite`[^7]. + +Windows Server 2025 soovitusliku, ainult TLS 1.3 kasutava profiili jaoks +luba järgmised komplektid toodud järjekorras. Schannel toetab kõiki kolme; +ChaCha20-Poly1305 on toetatud, kuid ei ole vaikimisi lubatud: -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. +```text +TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256 +``` -Seega, täpsema kontrolli soovimiseks kasutatavate šifrikomplektide üle, on ilmselt parim kasutada kohalikke või keskseid poliitikaid. Kasutamaks ainult šifrikomplekte `ECDHE-ECDSA-AES256-GCM-SHA384` ja `ECDHE-RSA-AES256-GCM-SHA384`, tuleb modifitseerida määrangut `Computer Configuration/Administrative Templates/Network/SSL Configuration Settings: SSL Cipher Suite Order`. Šifrikomplektid tuleb eraldada komaga.[^10] +Dokumenteeritud TLS 1.2 ühilduvuserandi korral lisa Windows Server 2025 +toetatud kaks ECDSA TLS 1.2 komplekti. See vastab juhendis kasutatavale ainult +ECDSA sertifikaadi profiilile: -![Kindlate šifrikomplektide määramine keskse poliitikaga](./img/image31.png) +```text +TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 +``` -Eelmises punktis määratud konfiguratsioon kirjutatakse registrisse: +Aruanne lubab TLS 1.2 puhul ka ECDHE-ECDSA komplekti šifriga +ChaCha20-Poly1305, kuid Windows Server 2025 Schannel seda ei paku. Aruanne +lubab ka RSA-ga autenditud komplekte, kuid see ainult ECDSA profiil jätab need +välja. `TLS_AES_128_CCM_SHA256` on ainult varuvariant juhuks, kui AES-GCM ja +ChaCha20-Poly1305 ei ole saadaval, ning ei kuulu sellesse Windows Serveri +profiili. RSA autentimist ega võtmevahetust, DHE varuvarianti, CBC-d, CCM_8-t +ega muid mitte-AEAD komplekte ei tohi lubada. -![Poliitikaga määratud konfiguratsioon](./img/image32.png) +Sisesta sobiv komadega eraldatud lubatud loend määrangusse *SSL Cipher Suite +Order*. Poliitika asub: -Vaikimisi on šifrikomplektid kirjeldatud järgmisel pildil kirjeldatud asukohas: +- kohalikus rühmapoliitika redaktoris: *Computer Configuration* → + *Administrative Templates* → *Network* → *SSL Configuration Settings* → + *SSL Cipher Suite Order*; +- domeeni rühmapoliitika halduses: *Computer Configuration* → *Policies* → + *Administrative Templates* → *Network* → *SSL Configuration Settings* → + *SSL Cipher Suite Order*. -![Vaikimisi šifrikomplektide konfiguratsioon](./img/image33.png) +Poliitika väärtus `Functions` talletatakse registris: + +```text +HKLM\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002 +``` + +Pärast poliitika rakendamist kuva tegelikud šifrikomplektid tähtsuse +järjekorras: + +```powershell +Get-TlsCipherSuite +``` + +Käsk kuvab iga komplekti eraldi kirjena; komplekti nimi on väljal `Name`. +Poliitikaga määratud toorväärtuse kontrollimiseks käivita: + +```powershell +Get-ItemPropertyValue ` + -Path 'HKLM:\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002' ` + -Name Functions +``` ##### 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. +Muud Schanneli seadistused asuvad registris: + +```text +HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL +``` -![Schannel konfigureeritavad omadused](./img/image34.png) +Loo ainult paigaldatud Windows Serveri versiooni jaoks dokumenteeritud +väärtusi. Algoritmi nime olemasolu registris ei näita iseenesest, kas +algoritm on lubatud või kasutusel. #### Muud võimalused @@ -332,20 +688,34 @@ Palume suhtuda ülaltoodusse kui näidisloendisse demonstreerimaks, mida veel sa [^1]: -[^2]: Trusted root certification authorities +[^2]: 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. -[^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. +[^3]: -[^4]: Firefox teadaolevalt toetab, ent ka sellel brauseril ei ole see vaikimisi lubatud. +[^4]: SK poolt väljastatud organisatsioonide kaartide kasutuse puhul peavad + kesktaseme sertifikaatide hulka olema häälestatud ka `EID-SK 2016` + () sertifikaadid! -[^5]: SK poolt väljastatud organisatsioonide kaartide kasutuse puhul peavad kesktaseme sertifikaatide hulka olema häälestatud ka `EID-SK 2016` () sertifikaadid! +[^5]: Vaikimisi neid väärtuseid ei eksisteeri. -[^6]: +[^6]: Võimalik on konfigureerida eraldi ka kliendi osa SSL/TLS protokollide + vaates. Käesolev juhend käsitleb ainult serveri poole häälestust. See ei + tähenda, et kliendi osa konfigureerimine ei ole soovitatav, see sõltub + alati konkreetsest situatsioonist. -[^7]: Vaikimisi neid väärtuseid ei eksisteeri. +[^7]: -[^8]: Võimalik on konfigureerida eraldi ka kliendi osa SSL/TLS protokollide vaates. Käesolev juhend käsitleb ainult serveri poole häälestust. See ei tähenda, et kliendi osa konfigureerimine ei ole soovitatav, see sõltub alati konkreetsest situatsioonist. +[^8]: -[^9]: +[^9]: Lubatud loend põhineb + [ESTEID2018 sertifitseerimispoliitikal v4.0](https://www.id.ee/wp-content/uploads/2025/10/cp_esteid_v4.0-08.10.2025.pdf), + [ESTEID2025 sertifitseerimispoliitikal v2.0](https://repository.eidpki.ee/static/documents/eid-cp-v-2.0_04.06.2026_allkirjastatud.pdf) + ja [Zetesi sertifikaadiprofiilidel](https://repository.eidpki.ee/static/documents/CertificateProfiles-20260520.pdf). + Enne tootmise lubatud loendi muutmist kontrolli + [Zetesi repositooriumi](https://repository.eidpki.ee/repository/) ning + teenuseosutajate kehtivaid poliitikaid ja profiile. -[^10]: Märgitagu siinkohal, et nende konkreetsete määrangutega `TLS 1.3` ei toimi! Pigem võib nende määrangute kasutamine olla mõttekas juhul, kui `TLS 1.3`-e ei soovita kasutada, kasvõi näiteks sertifikaadiga autentimise lubamise puhul. +[^10]: diff --git a/iis/index.md b/iis/index.md index fad3efe..bb9da48 100644 --- a/iis/index.md +++ b/iis/index.md @@ -2,7 +2,7 @@ **[Eesti keeles (In Estonian)](index.et.md)** -**Version:** 26.04/1 +**Version:** 26.08/1 **Published by:** [RIA](https://www.ria.ee/) @@ -26,6 +26,7 @@ | 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 +| 21.08.2026 | 26.08/1 | Updated the platform to Windows Server 2025 and revised certificate-key, TLS, cipher-suite, certificate-policy, and OCSP guidance based on the 2026 cryptographic algorithms life-cycle report. Instructions on how to configure IIS to support Estonian eID cards for authentication. @@ -38,7 +39,13 @@ Instructions on how to configure IIS to support Estonian eID cards for authentic This guide describes how to configure Microsoft IIS web services to require two-way SSL. On the server side, any certificate with `server authentication` EKU trusted by clients can be used. On the client side, any Estonian eID card (ID-card, residence card, digital ID or e-Resident's digital ID) can be used. -Windows Server 2022 and Windows 10 operating systems have been used to create this guide. On the client side, certificates issued from the [SK ID Solutions](https://www.skidsolutions.eu/resources/certificates/) `EE-GovCA2018` and [Zetes](https://repository.eidpki.ee/) `EEGovCA2025` chain are supported. To recognize user smart card certificate, ID-software is also needed on the client side[^1]. The server certificate in this demo-guidance is issued from OctoX test CA. +This guide targets Windows Server 2025; Windows 10 is used on the client +side. Client certificates issued from the +[SK ID Solutions](https://www.skidsolutions.eu/resources/certificates/) +`EE-GovCA2018` and [Zetes](https://repository.eidpki.ee/) `EEGovCA2025` +chains are supported. ID-software is also required on the client to recognize +the smart-card certificate[^1]. The server certificate in this example is +issued by the OctoX test CA. Different authentication methods are available in IIS. In this guide, IIS is configured in the simplest possible way and only anonymous authentication is used — after authentication, users can access the website as the dedicated (IUSR) user. @@ -96,19 +103,57 @@ In the extensions tab, set the following options: ##### Tab Private Key -Here, select the CSP (cryptographic service provider). In this example, to use `ECDSA_P256`, unselect RSA and select `ECDSA_P256`. +Here, select the CSP (cryptographic service provider). In this example, +unselect RSA and select `ECDSA_P384`. -![Selecting CSP](./img/image6.png) +![Selecting the ECDSA P-384 CSP](./img/image6.png) + +Generate a separate private key for every independent TLS server. Do not copy +one key between servers merely because a wildcard or multi-SAN certificate +could cover all their names. Keeping keys separate limits the impact of a +server or key compromise. + +For production deployments, use a hardware security module (HSM) or an +equivalent non-exportable hardware-backed key provider where supported. +Generate the key inside the device and keep it non-exportable. Confirm that +the HSM provider, IIS, and certificate issuer support the selected ECDSA P-384 +key before deployment. The software-provider workflow shown here is not an +HSM setup. Click *OK* and *Next* to save the request file with any name you like in `Base64` format. -The contents of the request file can be checked with the command `certutil -dump REQUEST_FILE_NAME`. +Inspect the request file with `certutil`: + +```bat +certutil -dump iis2112.req +``` -![Request file contents](./img/image7.png) +The relevant output should resemble the following; request-specific hashes +and raw public-key bytes are omitted: -The DNS aliases defined in this query are also visible: +```text +PKCS10 Certificate Request: +Version: 1 +Subject: + CN=iis2111.kaheksa.xi + C=EE + O=OctoX + OU=DEV -![DNS aliases in query file](./img/image8.png) +Public Key Algorithm: + Algorithm ObjectId: 1.2.840.10045.2.1 ECC + Algorithm Parameters: + 1.3.132.0.34 ECDH_P384 +Public Key Length: 384 bits + +Subject Alternative Name + DNS Name=iis2112.kaheksa.xi + DNS Name=iis2111.kaheksa.xi + DNS Name=MyWebServer.kaheksa.xi +``` + +Verify that the public key is 384 bits and that every required DNS name is +present under `Subject Alternative Name`. The query file must now be sent to any CA for certificate generation. If everything goes fine, the certificate will be returned. @@ -126,9 +171,14 @@ Certificate for IIS server must belong to `Local Computer/Personal` certificates ### Configuring IIS for one-way SSL -To configure one-way SSL on IIS server, a new HTTP(S) binding (usually port 443) must be added and a certificate applied to it. And it is definitely a good idea to disable legacy TLS protocols! +To configure one-way TLS on IIS, add an HTTPS binding (usually port 443), +select the server certificate, and disable legacy TLS protocols. + +The Windows Server 2025 binding dialog below shows the relevant controls. +Select the server certificate, keep *Disable Legacy TLS* selected, and leave +*Disable TLS 1.3 over TCP* unselected. -![Defining HTTPS binding with certificate iis2111.kaheksa.xi and disabling legacy TLS protocols](./img/image12.png) +![Windows Server 2025 HTTPS binding controls](./img/image12.png) After applying settings, one-way SSL works and the website is accessible over HTTPS protocol. @@ -139,6 +189,37 @@ The Firefox information window shows that: 1. Web server certificate `iis2111.kaheksa.xi` is in use; 2. TLS protocol version 1.3 is in use. +#### Stapling the server-certificate OCSP response + +If the server certificate contains an OCSP responder URI and its issuing CA +supports OCSP, keep *Disable OCSP Stapling* unselected in the HTTPS binding. +HTTP.sys can then obtain a signed status response for the server certificate +and send it during the TLS handshake. This avoids each browser querying the +issuing CA and improves client privacy.[^8] + +Display the binding and confirm that OCSP stapling is not disabled: + +```bat +netsh http show sslcert 0.0.0.0:443 +``` + +If required, enable stapling for the existing binding: + +```bat +netsh http update sslcert ipport=0.0.0.0:443 disableocspstapling=disable +``` + +Do not enable stapling when the issuing CA does not provide an OCSP service. +From a client with OpenSSL, verify the result with: + +```bash +$ openssl s_client -connect iis2111.kaheksa.xi:443 \ + -servername iis2111.kaheksa.xi -status **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, `TLS 1.3` must be turned off. An alternative is to enable the in-handshake authentication method, discussed later in chapter "[Enabling in-handshake authentication method](#enabling-in-handshake-authentication-method)". +> **Note:** TLS 1.3 with in-handshake client-certificate authentication +> is the recommended Windows Server 2025 configuration. In the HTTPS site +> binding, select *Negotiate Client Certificate* so that HTTP.sys requests +> the certificate during the initial TLS handshake. Leave +> *Disable TLS 1.3 over TCP* unselected. Microsoft describes this Server 2025 +> behavior in the IIS Support Blog[^3]. -> **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. +> **Compatibility:** Windows Server 2022 does not expose the +> *Negotiate Client Certificate* option in IIS Manager. Use the legacy +> [`netsh` procedure](#windows-server-2022-compatibility) below when Server +> 2022 must be retained. Common browsers do not support the TLS 1.3 +> post-handshake client authentication used by default on this platform. +> Disable TLS 1.3 and use TLS 1.2 only as a documented exception when the +> application must request a client certificate after the initial TLS +> connection and its flow cannot be changed. -On Windows Server 2022, while this problem exists, `TLS 1.3` over TCP must be turned off. This can be done by selecting `Disable TLS 1.3 over TCP` in the IIS bindings window: +The following Windows Server 2025 screenshot shows the TLS 1.2 compatibility +exception. Select the server certificate before saving the binding. This is +not the recommended Windows Server 2025 configuration: -![Turn TLS 1.3 off to enable certificate based authentication](./img/image14.png) +![TLS 1.2 compatibility exception: disabling TLS 1.3 in the HTTPS binding](./img/image14.png) ### Configuring IIS server to support Estonian eID cards @@ -164,7 +259,7 @@ The following certificates must be added to the IIS server certificate store: 1. Trusted Root Certification Authorities: 1. `EE-GovCA2018` () 2. `EEGovCA2025` () -2. Intermediate Certification Authorities[^3]: +2. Intermediate Certification Authorities[^4]: 1. `ESTEID2018` () 2. `ESTEID2025` () @@ -178,31 +273,76 @@ Described configuration allows access to website over port 443, client certifica 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) +![TLS 1.2 compatibility example: authentication succeeded](./img/image17.png) + +Before testing the recommended TLS 1.3 configuration, enable in-handshake +authentication as described below. As an alternative, certificate acceptance can be used instead of requiring it. In this case, websites can be accessed also with username or password or without authentication at all. ### Enabling in-handshake authentication method -To use `TLS 1.3` protocol with Windows Server 2022 IIS 10, the in-handshake authentication method must be enabled. With this method, the certificate request query is sent to the client with *Server Hello*. +With in-handshake authentication, the server requests the client certificate +during the initial TLS handshake. This is required because TLS 1.3 does not +support renegotiation. + +#### Windows Server 2025 + +1. In IIS Manager, select the website and open *Bindings*. +2. Select the HTTPS binding and choose *Edit*. +3. Select *Negotiate Client Certificate*. +4. Leave *Disable TLS 1.3 over TCP* unselected and save the binding. +5. If verification is needed, run `netsh http show sslcert` and confirm that + `Negotiate Client Certificate` is enabled for the binding. -Please follow next steps to enable in-handshake authentication method: +#### Windows Server 2022 compatibility {#windows-server-2022-compatibility} -1. Document `Certificate Hash` and `Application ID` values with command `netsh http show sslcert`: +Windows Server 2022 does not provide the binding checkbox. For this legacy +platform only, enable client-certificate negotiation with `netsh`: - !["negotiate client certificate" is disabled by default](./img/image18.png) +1. Display the binding configuration: -2. Remove certificate binding from port 443 with command `netsh http del sslcert 0.0.0.0:443`: + ```bat + netsh http show sslcert 0.0.0.0:443 + ``` - ![Remove certificate from port 443](./img/image19.png) + Record the hash and application ID. Before the change, the relevant + output resembles: -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`: + ```text + Certificate Hash : + Application ID : {} + Negotiate Client Certificate : Disabled + ``` - ![Enabling clientcertnegotiation](./img/image20.png) +2. Remove the certificate binding from port 443: -Checking certificate binding information again, `Negotiate Client Certificate` is now enabled: + ```bat + netsh http del sslcert 0.0.0.0:443 + ``` -![In-handshake authentication method is now enabled](./img/image21.png) + The command should report `SSL Certificate successfully deleted`. + +3. Bind the certificate to port 443 again and enable in-handshake + client-certificate authentication: + + ```bat + netsh http add sslcert ipport=0.0.0.0:443 ^ + certhash= ^ + appid={} ^ + certstorename=MY ^ + clientcertnegotiation=Enable + ``` + + Replace `CERTIFICATE_HASH` and `APPLICATION_ID` with the values from + step 1. The command should report `SSL Certificate successfully added`. + +Run the `show sslcert` command from step 1 again. The relevant output should +now be: + +```text +Negotiate Client Certificate : Enabled +``` > **Note:** Because session renegotiation is disabled with `TLS 1.3`, it must be understood that authentication must happen on the first page. If a one-way SSL connection already exists with any website, renegotiation will fail if some parts of this site/page require it. So, if necessary, this *landing* problem must be solved. @@ -216,29 +356,63 @@ In this configuration, only anonymous authentication is used: The purpose of this document is not to give exact guidance on how to configure or secure websites. This section introduces useful configurations for using two-way SSL with Estonian eID cards. The following sections cover options worth considering. -### Filtering certificate list on client side +### Filtering certificates displayed to the client + +By default, the client can display every personal certificate that has a +private key and a client-authentication EKU. IIS can send a list of acceptable +certificate authorities so that the client displays certificates from the +supported chains. -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. +This issuer list improves certificate selection but does not prove that the +selected leaf certificate is an ID-card authentication certificate. Different +certificate products can share a root or intermediate CA. Enforce the +certificate-policy check described in the next section before accepting the +authenticated identity. The 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`: +1. Display the current binding configuration: - ![Default https certificate options](./img/image23.png) + ```bat + netsh http show sslcert 0.0.0.0:443 + ``` -2. Remove certificate binding with command `netsh http del sslcert 0.0.0.0:443`: + Record the hash and application ID. Before the change, the relevant + output resembles: - ![Unbind certificate](./img/image19.png) + ```text + Certificate Hash : + Application ID : {} + Ctl Store Name : (null) + ``` -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`: +2. Remove the certificate binding: - ![Binding certificate with new option](./img/image24.png) + ```bat + netsh http del sslcert 0.0.0.0:443 + ``` - `Certhash` and `appid` values can be taken from the output in step 1 above. + The command should report `SSL Certificate successfully deleted`. -4. Check that `ClientAuthIssuer` value exists after `CTL Store Name`: +3. Add the certificate again and use the `Client Authentication Issuers` + store as the list of acceptable certification authorities: - ![Updated output](./img/image25.png) + ```bat + netsh http add sslcert ipport=0.0.0.0:443 ^ + certhash= ^ + appid={} ^ + sslctlstorename=ClientAuthIssuer + ``` + + Replace `CERTIFICATE_HASH` and `APPLICATION_ID` with the values from + step 1. The command should report `SSL Certificate successfully added`. + +4. Run the `show sslcert` command from step 1 again and confirm the relevant + output: + + ```text + Ctl Store Name : ClientAuthIssuer + ``` The IIS configuration can also be checked to confirm the SSL certificate is correctly bound to port 443. @@ -252,31 +426,148 @@ The goal is to support only certificates issued from chains under root CA `EE-Go 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 the OCSP service, the revocation status of client certificates can be checked practically in real time. In every client authentication attempt, the web server sends a query to the OCSP service, which responds with the client certificate revocation status. - -Certificates issued by `ESTEID2018` and `ESTEID2025` CA have AIA OCSP service location included in the end user certificate ( and ), so no changes are needed here. The server can still be configured to check revocation status of certificates using the 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 this configuration, this doesn't really matter since CRL is not used at all. For other configurations, note that this behavior can be changed by changing the 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*. This behavior can also be changed with windows policy: - -![Changing OCSP magic count](./img/image29.png) +### Validating the ID-card certificate policy + +Before accepting an authenticated identity, require all of the following: + +1. HTTP.sys successfully validates the complete certificate chain; +2. the issuer is an explicitly allowed intermediate CA; +3. `extendedKeyUsage` permits TLS web-client authentication; +4. the leaf certificate's `X509v3 CertificatePolicies` extension + (`2.5.29.32`) contains both the NCP+ authentication-policy OID and an + allowed document-policy OID for the certificate's CA generation.[^9] + +For production certificates covered by this guide, use this allowlist: + +```text +# Required in every accepted authentication certificate +0.4.0.2042.1.2 + +# ESTEID2018 - require one of these document-policy OIDs +1.3.6.1.4.1.51361.1.1.1 +1.3.6.1.4.1.51361.1.1.2 +1.3.6.1.4.1.51361.1.1.3 +1.3.6.1.4.1.51361.1.1.4 +1.3.6.1.4.1.51361.1.1.5 +1.3.6.1.4.1.51361.1.1.6 +1.3.6.1.4.1.51361.1.1.7 +1.3.6.1.4.1.51455.1.1.1 + +# ESTEID2025 - require one of these document-policy OIDs +1.3.6.1.4.1.51361.2.1.1 +1.3.6.1.4.1.51361.2.1.2 +1.3.6.1.4.1.51361.2.1.3 +1.3.6.1.4.1.51361.2.1.4 +1.3.6.1.4.1.51361.2.1.5 +1.3.6.1.4.1.51361.2.1.6 +1.3.6.1.4.1.51455.2.1.1 +``` + +Correlate the document-policy OID with the validated issuer: an `ESTEID2018` +certificate must not be accepted using an `ESTEID2025` policy OID, or vice +versa. The common NCP+ OID is not product-specific and is insufficient on its +own. Do not add test OIDs, such as Zetes OIDs prefixed with `2.999`, to a +production allowlist. + +The `Client Authentication Issuers` store and the EKU check are useful +defence in depth, but they do not identify the certificate product. The IIS +application or an authentication gateway must inspect the verified client +certificate and reject authentication unless both the NCP+ OID and a +document-policy OID matching the issuer are present. Do not infer the +certificate product from its subject, issuer, or EKU alone, and do not treat +the `anyPolicy` OID (`2.5.29.32.0`) as proof of an ID-card policy. + +Use the application platform's native client-certificate API. In a .NET +application, validate the certificate with +`X509ChainPolicy.CertificatePolicy`.[^10] Evaluate each permitted, +issuer-matched combination separately: require the NCP+ OID and one allowed +document-policy OID from the corresponding CA generation in the same chain +validation. The document-policy OIDs are alternatives; do not add every +allowed document-policy OID to one validation as simultaneously required +policies. + +Do not accept a certificate supplied in an HTTP request header unless a +trusted reverse proxy overwrites that header and the application is reachable +exclusively through that proxy. + +To inspect an exported certificate during testing, use: + +```bat +certutil -dump client.cer +``` + +Check the `Certificate Policies` extension against the current policy and +certificate-profile sources cited above. Test at least one accepted +ID-card certificate and certificates for other products issued in related +hierarchies, including Mobile-ID where applicable. + +### Checking client-certificate revocation with OCSP + +Certificates issued under the `ESTEID2018` and `ESTEID2025` CAs contain +their AIA OCSP service address ( and +). HTTP.sys uses the Windows certificate-chain engine +to retrieve revocation information from the locations in the certificate. + +Display the HTTPS binding: + +```bat +netsh http show sslcert 0.0.0.0:443 +``` + +Confirm that client-certificate revocation checking and certificate usage +checking are enabled, and that revocation checking is not restricted to +cached data. If necessary, update those policies:[^8] + +```bat +netsh http update sslcert ipport=0.0.0.0:443 ^ + verifyclientcertrevocation=enable ^ + verifyrevocationwithcachedclientcertonly=disable ^ + usagecheck=enable +``` + +Allow outbound access to the revocation endpoints, monitor Windows CAPI2 and +HTTP Service errors, and test both valid and revoked certificates. Define and +test the application's behaviour when revocation information is temporarily +unavailable. Do not use the obsolete OCSP query-count registry policy to +force OCSP over CRL; let the current chain engine use the revocation data +published in each certificate. ### 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 the IIS management console, `TLS 1.0` and `TLS 1.1` can be disabled in registry keys by defining the following values[^5]: +Do not rely on the IIS or Schannel defaults to select TLS protocol +versions. Disable TLS 1.0 and TLS 1.1. New and updated deployments +should enable only TLS 1.3 by default. + +Add TLS 1.2 only as a documented exception when the service must support +clients from 2020 or earlier, or when a client certificate must be +requested after the initial TLS connection has been established. +Certificate authentication alone is not a reason to enable TLS 1.2. On +Windows Server 2025, use the *Negotiate Client Certificate* binding option +described above. + +The report recommends disabling renegotiation when TLS 1.2 is enabled. A +legacy design that requests a client certificate only after the initial +handshake cannot both retain that flow and follow this recommendation. Prefer +in-handshake authentication on a dedicated binding or hostname, and document +any remaining TLS 1.2 renegotiation dependency as an exception. + +When Schannel and deployed clients provide production support, prioritize the +hybrid `X25519MLKEM768` group. This guide does not prescribe a registry or +Group Policy value for it because support and the standardized identifier are +platform-dependent. Confirm the negotiated group with a current TLS scanner +before relying on it. + +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 +. + +Manage TLS protocols through Group Policy or another Windows management +tool. The following registry values can be used to verify the applied +configuration or when central management is unavailable. To disable +`TLS 1.0` and `TLS 1.1`, set[^5]: - `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\`[^6]: - `TLS 1.0\Server` @@ -288,31 +579,94 @@ In addition to disabling older TLS versions in the IIS management console, `TLS ![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. +For a TLS 1.3-only server, TLS 1.2 can also be disabled under +`TLS 1.2\Server` by setting `Enabled DWORD:0` and +`DisabledByDefault DWORD:1`. This system-wide change affects all +Schannel server applications, so check other services before applying it +and restart them afterwards. Do not disable TLS 1.2 when a documented +compatibility exception applies. + +##### Compression + +Keep TLS compression disabled. HTTP compression in IIS is a separate feature: +disable dynamic-content compression for applications whose responses combine +attacker-controlled input with secrets. If HTTP response compression must +remain enabled, the application must prevent cross-site request forgery and +mitigate response-length leakage. Verify the TLS result with a current scanner +because IIS does not expose TLS compression as a normal site-level setting. #### Cipher suites -There are many different cipher suites available with Windows Server. Available cipher suites can be listed with the `PowerShell` command `Get-TLSCipherSuite`[^7]. +Configure an explicit allowlist through Group Policy or the Windows TLS +PowerShell cmdlets. First check the suites supported by the installed +operating-system version with `Get-TlsCipherSuite`[^7]. + +For the recommended TLS 1.3-only profile on Windows Server 2025, enable +these suites in order. Schannel supports all three; ChaCha20-Poly1305 is +supported but is not enabled by default: + +```text +TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256 +``` + +For a documented TLS 1.2 compatibility exception, append the two ECDSA TLS 1.2 +suites supported by Windows Server 2025. This matches the ECDSA-only +certificate profile used in this guide: + +```text +TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 +``` -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 is to remove non-secure cipher suites from the list if any exist. Before going on with configuring cipher suites, it is recommended to get 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. +The report also permits ECDHE-ECDSA with ChaCha20-Poly1305 for TLS 1.2, +but Windows Server 2025 Schannel does not provide that suite. It also permits +RSA-authenticated suites, but this ECDSA-only profile omits them. +`TLS_AES_128_CCM_SHA256` is only a fallback when AES-GCM and +ChaCha20-Poly1305 are unavailable and is not part of this Windows Server +profile. Do not enable RSA authentication or key exchange, DHE fallback, CBC, +CCM_8, or other non-AEAD suites. -So, to configure specific cipher suites, the best way is probably using local or group policy. To configure cipher suites `ECDHE-ECDSA-AES256-GCM-SHA384` and `ECDHE-RSA-AES256-GCM-SHA384` as the only ones in this configuration, the policy setting `Computer Configuration/Administrative Templates/Network/SSL Configuration Settings: SSL Cipher Suite Order` must be modified. Cipher suites must be separated with comma.[^8] +Enter the appropriate comma-separated allowlist under *SSL Cipher Suite +Order*. The policy is located at: -![Modifying cipher suites with group policy](./img/image31.png) +- Local Group Policy Editor: *Computer Configuration* → *Administrative + Templates* → *Network* → *SSL Configuration Settings* → *SSL Cipher Suite + Order*. +- Domain Group Policy Management: *Computer Configuration* → *Policies* → + *Administrative Templates* → *Network* → *SSL Configuration Settings* → + *SSL Cipher Suite Order*. -Assigned configuration can be found from registry location presented on the following picture: +The policy stores its `Functions` value at: -![Applied policy settings](./img/image32.png) +```text +HKLM\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002 +``` -Default configuration settings can be found from registry location presented on the following picture: +After applying the policy, list the effective cipher suites in priority order: -![Cipher suites default configuration](./img/image33.png) +```powershell +Get-TlsCipherSuite +``` + +The command displays one record per suite; check its `Name` field. To verify +the raw value delivered by policy, run: + +```powershell +Get-ItemPropertyValue ` + -Path 'HKLM:\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002' ` + -Name Functions +``` ##### 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. +Other Schannel settings are located under: + +```text +HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL +``` -![Schannel configurable options](./img/image34.png) +Only create values documented for the installed Windows Server version. +The presence of an algorithm name in the registry does not by itself show +whether that algorithm is enabled or used. #### Additional possibilities @@ -334,14 +688,28 @@ Please take the list above as a short demo recommendations list. Of course, it m [^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, `EID-SK 2016` () certificates must also be added to the list! +[^3]: -[^4]: +[^4]: To support EID cards issued for organizations by SK ID Solutions, + `EID-SK 2016` () + certificates must also be added to the list! [^5]: These entries do not exist in the registry by default. -[^6]: It is also possible to configure the client part for SSL/TLS versions, but this guide covers server configuration. It does not mean that configuring the client part is not recommended, it just depends. +[^6]: It is also possible to configure the client part for SSL/TLS versions, + but this guide covers server configuration. It does not mean that + configuring the client part is not recommended, it just depends. + +[^7]: + +[^8]: -[^7]: +[^9]: The allowlist is based on the + [ESTEID2018 certificate policy v4.0](https://www.id.ee/wp-content/uploads/2025/10/cp_esteid_v4.0-08.10.2025.pdf) + and the [ESTEID2025 certificate policy v2.0](https://repository.eidpki.ee/static/documents/eid-cp-v-2.0_04.06.2026_allkirjastatud.pdf), + supplemented by the [Zetes certificate profiles](https://repository.eidpki.ee/static/documents/CertificateProfiles-20260520.pdf). + Check the [Zetes repository](https://repository.eidpki.ee/repository/) + and the service providers' current policies and profiles before changing + the production allowlist. -[^8]: With the cipher settings described here, `TLS 1.3` will not work. So, those settings can be useful if `TLS 1.3` is not to be used for any reason, for enabling certificate authentication for example. +[^10]: diff --git a/iis/media/image1.png b/iis/media/image1.png deleted file mode 100644 index f456858..0000000 Binary files a/iis/media/image1.png and /dev/null differ diff --git a/iis/media/image10.png b/iis/media/image10.png deleted file mode 100644 index b49c7e3..0000000 Binary files a/iis/media/image10.png and /dev/null differ diff --git a/iis/media/image11.png b/iis/media/image11.png deleted file mode 100644 index b331287..0000000 Binary files a/iis/media/image11.png and /dev/null differ diff --git a/iis/media/image12.png b/iis/media/image12.png deleted file mode 100644 index 1c4eec8..0000000 Binary files a/iis/media/image12.png and /dev/null differ diff --git a/iis/media/image13.png b/iis/media/image13.png deleted file mode 100644 index 5039787..0000000 Binary files a/iis/media/image13.png and /dev/null differ diff --git a/iis/media/image14.png b/iis/media/image14.png deleted file mode 100644 index d2e5f1b..0000000 Binary files a/iis/media/image14.png and /dev/null differ diff --git a/iis/media/image15.png b/iis/media/image15.png deleted file mode 100644 index 39a0a96..0000000 Binary files a/iis/media/image15.png and /dev/null differ diff --git a/iis/media/image16.png b/iis/media/image16.png deleted file mode 100644 index d1fdf66..0000000 Binary files a/iis/media/image16.png and /dev/null differ diff --git a/iis/media/image17.png b/iis/media/image17.png deleted file mode 100644 index e100a13..0000000 Binary files a/iis/media/image17.png and /dev/null differ diff --git a/iis/media/image18.png b/iis/media/image18.png deleted file mode 100644 index 0455c31..0000000 Binary files a/iis/media/image18.png and /dev/null differ diff --git a/iis/media/image19.png b/iis/media/image19.png deleted file mode 100644 index 5a20dde..0000000 Binary files a/iis/media/image19.png and /dev/null differ diff --git a/iis/media/image2.png b/iis/media/image2.png deleted file mode 100644 index bf50515..0000000 Binary files a/iis/media/image2.png and /dev/null differ diff --git a/iis/media/image20.png b/iis/media/image20.png deleted file mode 100644 index e2b45bd..0000000 Binary files a/iis/media/image20.png and /dev/null differ diff --git a/iis/media/image21.png b/iis/media/image21.png deleted file mode 100644 index 86d8b28..0000000 Binary files a/iis/media/image21.png and /dev/null differ diff --git a/iis/media/image22.png b/iis/media/image22.png deleted file mode 100644 index 74def95..0000000 Binary files a/iis/media/image22.png and /dev/null differ diff --git a/iis/media/image23.png b/iis/media/image23.png deleted file mode 100644 index 3045b5b..0000000 Binary files a/iis/media/image23.png and /dev/null differ diff --git a/iis/media/image24.png b/iis/media/image24.png deleted file mode 100644 index 70204e6..0000000 Binary files a/iis/media/image24.png and /dev/null differ diff --git a/iis/media/image25.png b/iis/media/image25.png deleted file mode 100644 index a570bc2..0000000 Binary files a/iis/media/image25.png and /dev/null differ diff --git a/iis/media/image26.png b/iis/media/image26.png deleted file mode 100644 index 3c28643..0000000 Binary files a/iis/media/image26.png and /dev/null differ diff --git a/iis/media/image27.png b/iis/media/image27.png deleted file mode 100644 index eadc1de..0000000 Binary files a/iis/media/image27.png and /dev/null differ diff --git a/iis/media/image28.png b/iis/media/image28.png deleted file mode 100644 index 1ea22c1..0000000 Binary files a/iis/media/image28.png and /dev/null differ diff --git a/iis/media/image29.png b/iis/media/image29.png deleted file mode 100644 index d3812b3..0000000 Binary files a/iis/media/image29.png and /dev/null differ diff --git a/iis/media/image3.png b/iis/media/image3.png deleted file mode 100644 index 2f6665f..0000000 Binary files a/iis/media/image3.png and /dev/null differ diff --git a/iis/media/image30.png b/iis/media/image30.png deleted file mode 100644 index 82b5bdf..0000000 Binary files a/iis/media/image30.png and /dev/null differ diff --git a/iis/media/image31.png b/iis/media/image31.png deleted file mode 100644 index 030a2aa..0000000 Binary files a/iis/media/image31.png and /dev/null differ diff --git a/iis/media/image32.png b/iis/media/image32.png deleted file mode 100644 index d428290..0000000 Binary files a/iis/media/image32.png and /dev/null differ diff --git a/iis/media/image33.png b/iis/media/image33.png deleted file mode 100644 index 6eb8838..0000000 Binary files a/iis/media/image33.png and /dev/null differ diff --git a/iis/media/image34.png b/iis/media/image34.png deleted file mode 100644 index edaf61d..0000000 Binary files a/iis/media/image34.png and /dev/null differ diff --git a/iis/media/image4.png b/iis/media/image4.png deleted file mode 100644 index 84269b0..0000000 Binary files a/iis/media/image4.png and /dev/null differ diff --git a/iis/media/image5.png b/iis/media/image5.png deleted file mode 100644 index 454502e..0000000 Binary files a/iis/media/image5.png and /dev/null differ diff --git a/iis/media/image6.png b/iis/media/image6.png deleted file mode 100644 index 49c4a23..0000000 Binary files a/iis/media/image6.png and /dev/null differ diff --git a/iis/media/image7.png b/iis/media/image7.png deleted file mode 100644 index 6cfda4d..0000000 Binary files a/iis/media/image7.png and /dev/null differ diff --git a/iis/media/image8.png b/iis/media/image8.png deleted file mode 100644 index 85dd079..0000000 Binary files a/iis/media/image8.png and /dev/null differ diff --git a/iis/media/image9.png b/iis/media/image9.png deleted file mode 100644 index 4b4638e..0000000 Binary files a/iis/media/image9.png and /dev/null differ diff --git a/nginx/index.et.md b/nginx/index.et.md index 38ebf3e..8a6ee27 100644 --- a/nginx/index.et.md +++ b/nginx/index.et.md @@ -2,7 +2,7 @@ **[In English](index.md)** -**Versioon:** 26.04/1 +**Versioon:** 26.08/1 **Väljaandja:** [RIA](https://www.ria.ee/) @@ -23,6 +23,7 @@ | 22.08.2024 | 24.08/1 | Ubuntu uuendatud versioonile Ubuntu Server 24.04 ja Nginx versioonile 1.27.1. — Muutja: Urmas Vanem | 31.10.2025 | 25.10/1 | Lisatud Zetes ahelad, eemaldatud SK OCSP lõik. — Muutja: Lauris Kaplinski | 22.04.2026 | 26.04/1 | Konverteeritud Markdown formaati. — Muutja: Raul Metsma +| 21.08.2026 | 26.08/1 | Uuendatud sertifikaadivõtme, TLS-protokollide, šifrikomplektide, sertifikaadipoliitikate ja OCSP juhiseid 2026. aasta krüptograafiliste algoritmide elutsükli aruande põhjal. --- @@ -36,7 +37,8 @@ Käesolevas juhendis kirjeldatakse: - Kuidas paigaldada ja häälestada Nginx 1.28.1 veebiserver Ubuntu 24.04 serveril. - Kuidas häälestada HTTPS (ühepoolne SSL) veebiserveril. - Kuidas häälestada [SK ID Solutions](https://www.skidsolutions.eu/resources/certificates/) (`EE-GovCA2018`) ja [Zetes](https://repository.eidpki.ee/) (`EEGovCA2025`) ID-kaartidega autentimine (kahepoolne SSL) veebiserveril. -- Kuidas häälestada OCSP kontroll nii vastu garanteeritud kui AIA OCSP teenust. +- Kuidas kontrollida kliendisertifikaadi tühistusolekut ja häälestada + serverisertifikaadi OCSP stapling. - Kuidas turvata veebiserverit. Lisaks on käsitletud muid konfiguratsioonivõimalusi, nt kuidas HTTP liiklus suunata HTTPS kanalisse jpm. @@ -119,6 +121,17 @@ $ openssl req -new -key Nginx2404.key -out Nginx2404.csr -subj /C=EE/O=OctoX/CN= 3. `CN=Nginx2404.octox.demo` on väljastatava sertifikaadi *common name;* 4. `DNS:Nginx2404.octox.demo` ja `DNS:MYWEBSERVER.octox.demo` on sertifikaadil olevad SAN DNS nimed, mis peavad kindlasti vastama veebilehe tegelikule aadressile[^2]. Need nimed peavad ka nimeserveris lahenema. +Genereeri igale sõltumatule TLS-serverile eraldi privaatvõti. Ära kopeeri +sama võtit mitmesse serverisse üksnes seetõttu, et metamärgiga või mitme SAN +nimega sertifikaat kataks kõik serverinimed. Eraldi võtmed piiravad serveri +või võtme kompromiteerumise mõju. + +Tootmislahenduses kasuta võimaluse korral füüsilist turvamoodulit (HSM) või +samaväärset mitteeksporditava võtmega riistvaralist võtmehoidlat. Genereeri +võti seadmes ja hoia see mitteeksporditavana. Enne kasutuselevõttu veendu, et +HSM, OpenSSL-i integratsioon ja sertifikaadi väljastaja toetavad valitud ECDSA +P-384 võtit. Näite failipõhine võti ei ole HSM-i seadistus. + Loodud sertifikaadi päringufaili sisu on võimalik vaadata käsuga ```bash @@ -148,64 +161,6 @@ Certificate Request: Signature Value: ``` -###### RSA - -*See lõik on säilitatud neile, kes eelistavad RSA-põhiseid sertifikaate. Ülejäänud juhend kasutab ECC-d.* - -Loo sertifikaadi päring ja privaatvõti käsuga - -```bash -$ openssl req -newkey rsa:2048 -keyout NGINX20PRIV.key -sha256 -subj "/CN=Nginx20.kaheksa.xi" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf "[SAN]\nsubjectAltName=DNS: Nginx20.kaheksa.xi,DNS: Nginx22.kaheksa.xi ")) -out NGINX20.csr -nodes -Generating a RSA private key -........................................................................+++++ -.....................................+++++ -writing new private key to 'NGINX20PRIV.key' ------ -``` - -1. `NGINX20PRIV.key` on sertifikaadi privaatvõti; -2. `NGINX20.csr` on sertifikaadi päringufail, mis edastatakse sertifitseerimiskeskusele; -3. `Nginx20.kaheksa.xi` on väljastatava sertifikaadi subjekt; -4. `Nginx20.kaheksa.xi` ja `Nginx22.kaheksa.xi` on sertifikaadil olevad SAN DNS nimed, mis peavad kindlasti vastama veebilehe tegelikule aadressile[^3]. Need nimed peavad ka nimeserveris lahenema (piisab ka ühest nimest). - -Loodud sertifikaadi päringufaili sisu on võimalik vaadata käsuga - -```bash -$ openssl req -in NGINX20.csr -noout -text -Certificate Request: - Data: - Version: 1 (0x0) - Subject: CN = Nginx20.kaheksa.xi - Subject Public Key Info: - Public Key Algorithm: rsaEncryption - RSA Public-Key: (2048 bit) - Modulus: - 00:f1:62:c3:ed:1d:0b:ea:cb:7c:22:17:41:1e:e3: - c1:02:a6:7b:f3:72:13:ae:8d:72:72:6f:09:77:d6: - 51:84:4b:2a:f6:7b:65:9d:9f:f3:2a:0c:16:e5:26: - 47:70:aa:3e:c8:4c:50:62:5b:6c:2a:49:ea:51:01: - 60:5c:94:2c:d6:1d:78:70:eb:41:88:6c:09:c8:2f: - e4:d5:bb:2f:fb:ec:2f:9d:0c:42:66:b5:de:91:e3: - 60:62:ff:94:11:21:aa:de:bb:52:bd:20:a6:ff:b4: - c3:92:0a:5b:b5:fc:2f:88:bc:44:3e:b4:5b:a4:ec: - de:49:16:b6:c0:13:ed:d0:e2:ee:d0:58:bc:cb:36: - 32:c9:1b:6d:8f:79:db:83:22:fd:fe:a7:9a:b2:cd: - 26:b1:d7:52:c4:0c:40:6d:0e:49:b5:18:07:c2:3c: - c0:c9:70:5d:06:da:0a:e6:01:1a:a4:78:19:aa:a7: - 38:1c:9d:36:07:4d:db:d2:b5:7b:50:f1:4b:d0:c7: - 5d:90:86:92:2d:a6:ea:d7:d2:09:8f:51:e8:b6:52: - 07:b1:1e:5e:ca:65:f3:d4:69:52:f1:d9:47:02:24: - 98:42:70:83:bc:49:13:c1:92:51:f7:ca:b2:fa:f6: - a7:08:13:c1:74:23:d6:58:ab:27:d5:e5:02:20:3f: - 11:3b - Exponent: 65537 (0x10001) - Attributes: - Requested Extensions: - X509v3 Subject Alternative Name: - DNS:Nginx20.kaheksa.xi, DNS: Nginx22.kaheksa.xi - Signature Algorithm: sha256WithRSAEncryption -``` - ##### SSL sertifikaadi tellimine ja paigaldamine Järgnevalt tuleb saata sertifikaadi päringufail `Nginx2404.csr` mõnele usaldusväärsele sertifitseerimiskeskusele allkirjastamiseks. Näidiskonfiguratsiooni tingimustes on sertifikaadi väljastajaks testkeskkonna sertifitseerimiskeskus. Allkirjastatud sertifikaat väljastatakse PEM formaadis: @@ -260,7 +215,7 @@ Paigalda loodud kausta mõni lihtne ja äratuntav veebileht nimega `index.html`. Järgmiseks tee valmis virtuaalse veebilehe konfiguratsioonifail. Tee uus fail nimega `/etc/nginx/conf.d/Nginx2404.conf` (näiteks käsuga `nano /etc/nginx/conf.d/Nginx2404.conf`). -Nüüd muuda uut konfiguratsioonifaili vastavalt oma soovidele. Lisa sinna järgmine sisu[^4]: +Nüüd muuda uut konfiguratsioonifaili vastavalt oma soovidele. Lisa sinna järgmine sisu[^3]: ```nginx server { @@ -373,11 +328,14 @@ To Action From 443/tcp (v6) ALLOW Anywhere (v6) ``` -### Kasutaja sertifikaadi staatuse kontroll OCSP teenuse vastu[^5] +### Kliendisertifikaadi tühistusoleku kontroll OCSP abil[^4] -OCSP (*Online Certificate Status Protocol*) teenuse abil saab kasutaja sertifikaadi staatust kontrollida reaalajas. Iga kasutaja autentimisel saadab veebiserver päringu OCSP teenusele, mis tagastab sertifikaadi staatuse info. +OCSP (*Online Certificate Status Protocol*) võimaldab Nginxil kontrollida +kliendisertifikaadi tühistusolekut autentimise ajal. -SK ja Zetes pakuvad vaba ligipääsuga (tasuta) AIA OCSP teenust. `ESTEID2018` ja `ESTEID2025` CA alt väljastatud sertifikaatide puhul on AIA OCSP aadress juba sertifikaadis kirjas (, ). +CA-de `ESTEID2018` ja `ESTEID2025` väljastatud sertifikaatides on AIA OCSP +teenuse aadress ( ja +). ![ESTEID2018 AIA OCSP aadress sertifikaadis](./img/image7.png) @@ -391,96 +349,256 @@ ssl_client_certificate /etc/ssl/certs/EID_Bundle.pem; ssl_verify_client on; ssl_verify_depth 2; ssl_ocsp leaf; -ssl_ocsp_cache off; +ssl_ocsp_cache shared:OCSP:10m; +resolver 194.126.115.18; +``` + +Väärtus `leaf` kontrollib lõppkasutaja sertifikaati ja jagatud vahemälu +vähendab korduvaid päringuid. OCSP teenuse aadress võetakse +kliendisertifikaadist. Asenda `resolver` IP-aadress avalikke aadresse lahendava +DNS-serveri IP-aadressiga[^5]. Luba serverist väljuv DNS- ja HTTP-liiklus OCSP +teenustesse ning monitoori Nginxi tõrkeid: OCSP kontrolli ebaõnnestumisel +kliendisertifikaadiga autentimine ei õnnestu. + +### Serverisertifikaadi OCSP vastuse stapling + +Eespool kirjeldatud kliendisertifikaadi kontroll ja serverisertifikaadi OCSP +stapling on eri funktsioonid. Stapling võimaldab Nginxil hankida oma +serverisertifikaadi kohta allkirjastatud olekuvastuse ja saata selle TLS +kätluse ajal. Nii ei pea iga veebilehitseja väljastanud CA-le eraldi päringut +tegema ja kliendi privaatsus paraneb.[^6] + +Esmalt kontrolli, kas serverisertifikaat sisaldab OCSP teenuse URI-d: + +```bash +$ openssl x509 -in /etc/ssl/certs/Nginx2404_Bundle.pem -noout -ocsp_uri +``` + +Kui käsk tagastab toetatud URI, loo PEM-vormingus fail +`/etc/ssl/certs/Nginx2404_CA.pem`, mis sisaldab väljastaja, kesktaseme ja +juur-CA sertifikaate. Seejärel luba stapling ja vastuse kontroll: + +```nginx +ssl_stapling on; +ssl_stapling_verify on; +ssl_trusted_certificate /etc/ssl/certs/Nginx2404_CA.pem; resolver 194.126.115.18; ``` -Ülaltoodud konfiguratsiooni puhul võetakse OCSP teenuse aadress kasutaja sertifikaadist. Asendage `resolver` IP-aadress avaliku DNS-serveri IP-aadressiga[^6]. +Ära luba stapling'ut, kui sertifikaadi väljastaja OCSP teenust ei paku. Pärast +Nginxi konfiguratsiooni taaslaadimist kontrolli kaasatud OCSP vastust: + +```bash +$ openssl s_client -connect Nginx2404.octox.demo:443 \ + -servername Nginx2404.octox.demo -status . +Sama muudatuse serveri tasemel kehtestamiseks muuda `ssl_protocols` +direktiivi failis `/etc/nginx/nginx.conf`. + +Rohkem infot TLS protokolli kasutamise soovituste kohta leiab RIA +tellitud krüptograafiliste algoritmide elutsükli uuringust aadressil +. #### Šifrikomplektid (*Cipher suites*) -TLS 1.3 versiooni kõiki šifreid peetakse hetkeseisuga turvaliseks, seega turvakaalutlustel selle protokolli jaoks lisakonfiguratsiooni looma ei pea. +OpenSSL-i aliastele, näiteks `HIGH`, tuginemise asemel tuleb konfigureerida +selge lubatud loend. TLS 1.3 jaoks luba järgmised šifrikomplektid toodud +järjekorras: + +```nginx +ssl_conf_command Ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256; +``` -TLS 1.2 puhul see päris nii ei ole. Nginx 1.23.3 versiooniga on vaikimisi kasutusel suur hulk erinevaid TLS šifreid[^7], mida näeb käsuga +`TLS_AES_128_CCM_SHA256` võib kasutada ainult varuvariandina, kui AES-GCM +ja ChaCha20-Poly1305 ei ole saadaval. CCM_8 komplekte ei tohi lubada. -```bash -$ openssl ciphers -v +Dokumenteeritud TLS 1.2 ühilduvuserandi korral luba ainult järgmised kolm +ECDHE-ECDSA ja AEAD šifrikomplekti. See vastab juhendis kasutatavale +ainult ECDSA sertifikaadi profiilile: + +```nginx +ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305'; ``` -Kui on soov määrata täpsemalt TLS 1.2 protokolliga kasutatavaid šifrikomplekte, saab Nginx kaustapõhises konfiguratsioonifailis kasutada direktiivi `ssl_ciphers`. Siin omakorda saab kasutada kas eeldefineeritud *alias*i või täpseid šifrikomplektide kirjeldusi. +Direktiiv `ssl_ciphers` juhib TLS 1.2 ja vanemaid versioone; +`ssl_conf_command Ciphersuites` juhib OpenSSL-i kaudu TLS 1.3 komplekte. +TLS 1.2 loend välistab RSA autentimise ja võtmevahetuse, staatilise DH/ECDH, +CBC, CCM_8 ja muud mitte-AEAD komplektid. + +Neid direktiive saab konfigureerida ka serveripõhiselt failis +`/etc/nginx/nginx.conf`. Kontrolli kehtivat loendit käsuga +`openssl ciphers -v` ning testi pärast iga muudatust ajakohase TLS +skanneriga läbiräägitud protokolli ja šifrikomplekti. -Kindlat soovitust erinevate šifrikomplektide kasutamiseks ei ole võimalik anda ilma veebilehele esitatavaid tingimusi teadmata. Küll aga tuleb kindlasti eemaldada loendist ebaturvalised šifrikomplektid. Mõistlik on kirjeldada konkreetsed lubatud šifrikomplektid TLS 1.2 kasutamiseks. +##### Pakkimine ja korduskätlus -Näide — järgnev rida konfiguratsioonifailis lubab vaid loetletud šifrikomplektide kasutamist: +Hoia TLS-i pakkimine ja TLS 1.2 korduskätlus selgesõnaliselt keelatuna: ```nginx -ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384; +ssl_conf_command Options -Compression,NoRenegotiation; ``` -Alternatiivina saab kasutatavaid šifreid konfigureerida serveripõhiselt failis `/etc/nginx/nginx.conf` muutes selles parameetrit `ssl_ciphers`. +HTTP vastuste pakkimine on TLS-i pakkimisest eraldiseisev ja võib saladusi +lekitada, kui vastus sisaldab nii ründaja juhitavat sisendit kui ka tundlikke +andmeid. Määra tundlikes dünaamilistes asukohtades `gzip off;` ja keela seal +ka seadistatud Brotli moodul. Kui vastuste pakkimine peab jääma lubatuks, +peab rakendus takistama saitidevahelist päringuvõltsimist ning leevendama +vastuse pikkuse leket. -Rohkem infot šifrikomplektide soovituste kohta leiab RIA tellitud krüptograafiliste algoritmide elutsükli uuringust aadressil . +Rohkem infot šifrikomplektide soovituste kohta leiab RIA tellitud +krüptograafiliste algoritmide elutsükli uuringust aadressil +. ##### ssl_prefer_server_ciphers -Eelistamaks serveri šifrikomplektide valikut kasutaja omale, tuleb Nginx konfiguratsioonifailis defineerida määrang `ssl_prefer_server_ciphers` ja panna selle väärtuseks `on`. +Eelistamaks serveri šifrikomplektide valikut kasutaja omale, tuleb Nginx +konfiguratsioonifailis defineerida määrang `ssl_prefer_server_ciphers` +ja panna selle väärtuseks `on`. #### Kasutajasertifikaatide lisafiltreerimine -Oluline! Veebiteenusele juurdepääsu piiramiseks vaid õigete sertifikaatidega kasutajatele tuleb serveri konfiguratsioonis kehtestada järgmised nõuded: +CA ahela usaldamine ei tõesta, et lõppsertifikaat on ID-kaardi +autentimissertifikaat. Erinevad sertifikaaditooted võivad kasutada sama juur- +või kesktaseme CA-d. Enne autenditud identiteedi aktsepteerimist tuleb nõuda, +et: + +1. Nginx valideerib edukalt kogu sertifikaadiahela; +2. väljastaja on selgesõnaliselt lubatud kesktaseme CA; +3. `extendedKeyUsage` lubab TLS veebikliendi autentimist; +4. lõppsertifikaadi laiendus `X509v3 CertificatePolicies` (`2.5.29.32`) + sisaldab nii NCP+ autentimispoliitika OID-d kui ka sertifikaadi CA + põlvkonnale vastavat lubatud dokumendipoliitika OID-d.[^7] + +Käesolevas juhendis käsitletud tootmissertifikaatide lubatud loend on: + +```text +# Nõutav igas aktsepteeritavas autentimissertifikaadis +0.4.0.2042.1.2 + +# ESTEID2018 - nõua üht neist dokumendipoliitika OID-dest +1.3.6.1.4.1.51361.1.1.1 +1.3.6.1.4.1.51361.1.1.2 +1.3.6.1.4.1.51361.1.1.3 +1.3.6.1.4.1.51361.1.1.4 +1.3.6.1.4.1.51361.1.1.5 +1.3.6.1.4.1.51361.1.1.6 +1.3.6.1.4.1.51361.1.1.7 +1.3.6.1.4.1.51455.1.1.1 + +# ESTEID2025 - nõua üht neist dokumendipoliitika OID-dest +1.3.6.1.4.1.51361.2.1.1 +1.3.6.1.4.1.51361.2.1.2 +1.3.6.1.4.1.51361.2.1.3 +1.3.6.1.4.1.51361.2.1.4 +1.3.6.1.4.1.51361.2.1.5 +1.3.6.1.4.1.51361.2.1.6 +1.3.6.1.4.1.51455.2.1.1 +``` -1. sertifikaadis peab olema korrektne OID väärtus; -2. sertifikaadi väljastaja peab olema `ESTEID2018` või `ESTEID2025`. +Seosta dokumendipoliitika OID valideeritud väljastajaga: `ESTEID2018` +sertifikaati ei tohi aktsepteerida `ESTEID2025` poliitika OID alusel ega +vastupidi. Ühine NCP+ OID ei ole tootepõhine ja sellest üksi ei piisa. +Tootmise lubatud loendisse ei tohi lisada test-OID-sid, näiteks Zetesi OID-sid +prefiksiga `2.999`. -Hetkeseisuga ei ole teada ühtki meetodit õige OID kontrollimiseks Nginx serveri tasemel. Seetõttu on soovitatav see kontroll teha veebirakenduse tasemel. +Nginxil ei ole direktiivi, mis suudaks `CertificatePolicies` laienduse +poliitika OID-de lubatud loendit usaldusväärselt rakendada. Kontroll tuleb +teha rakenduses või autentimislüüsis. Sertifikaaditoodet ei tohi tuletada +ainult subjekti, väljastaja või EKU järgi ning `anyPolicy` OID-d +(`2.5.29.32.0`) ei tohi käsitleda ID-kaardi poliitika tõendina. -Teise nõude täitmiseks saab luua konfiguratsiooni, kus ühendus katkestatakse, kui sertifikaat ei ole väljastatud serveris lubatud CAde poolt. Selleks tuleb lisada konfiguratsioonifaili (serveri sektsiooni, näiteks SSL kirjeldusele järgnevalt) järgmised tingimused: +Esialgse lisakaitsena lükka tagasi sertifikaadid, mille väljastaja CA nimi ei +ole `ESTEID2018` ega `ESTEID2025`. Lisa järgmised tingimused pärast TLS-i +konfiguratsiooni `server`-sektsiooni: ```nginx -#Determine IMCA and cancel, if not trusted -set $ocspr ""; +# Esialgne filter kesktaseme CA nime järgi +set $trusted_client_issuer 0; -if ($ssl_client_i_dn = "CN=ESTEID2018,organizationIdentifier=NTREE-10747013,O=SK ID Solutions AS,C=EE") { - set $ocspr "http://aia.sk.ee/esteid2018"; +if ($ssl_client_i_dn ~ "^CN=ESTEID2018,") { + set $trusted_client_issuer 1; } -if ($ssl_client_i_dn = "CN=ESTEID2025, organizationIdentifier=NTREE-17066049, O=Zetes Estonia OÜ, C=EE") { - set $ocspr "http://ocsp.eidpki.ee"; +if ($ssl_client_i_dn ~ "^CN=ESTEID2025,") { + set $trusted_client_issuer 1; } -if ($ocspr = "") { +if ($trusted_client_issuer = 0) { return 403; } ``` -Nende tingimuste lisamisel lükatakse ühendus tagasi, kui kasutaja sertifikaati ei ole väljastanud usaldusväärne CA — `ESTEID2018` või `ESTEID2025`. +Nende tingimustega lükkab Nginx sertifikaadi tagasi, kui selle väljastaja ei +ole `ESTEID2018` ega `ESTEID2025`. Väljastaja kontroll ei asenda +sertifikaadipoliitika kontrolli. + +HTTP upstream'i puhul kirjuta valideeritud lõppsertifikaat selleks ettenähtud +päisesse: + +```nginx +proxy_set_header X-Client-Certificate $ssl_client_escaped_cert; +``` + +Rakendus peab sertifikaadi URL-dekodeerima ja parsima ning autentimise tagasi +lükkama, kui selles ei ole nii NCP+ OID-d kui ka väljastajale vastavat +dokumendipoliitika OID-d. Päist tohib usaldada ainult siis, kui rakendus on +ligipääsetav üksnes usaldatud Nginxi proksi kaudu. Muude liideste puhul tuleb +kasutada rakendusplatvormi TLS kliendisertifikaadi integratsiooni. + +Eksporditud sertifikaadi laienduse kontrollimiseks testi: + +```bash +$ openssl x509 -in client.pem -noout -text +``` + +Võrdle jaotist `X509v3 Certificate Policies` eespool viidatud kehtivate +poliitika- ja sertifikaadiprofiilide allikatega. Testi vähemalt üht +lubatud ID-kaardi sertifikaati ja seotud hierarhiates väljastatud muude +toodete sertifikaate, sealhulgas vajaduse korral Mobiil-ID-d. > **Märkus:** Kui on kasutusel mõni muu liikluse filtreerimise vahend/võimalus, siis on soovitav turvaline konfiguratsioon juurutada ka seal. SK on F5 konfiguratsiooni osas publitseerinud järgmise informatsiooni (vt. peakükki „Only accept certificates with trusted key usage"): > **Märkus:** SK soovitused turvaliseks autentimiseks ID-kaardiga on leitavad peatükist „Defence: implement ID-card authentication securely": -> **Märkus:** Soovituslik meetod ebakorrektsete sertifikaatide vältimiseks on kasutada sertifikaatides olevaid OIDe. Paraku ei ole hetkeseisuga teada meetodit, kuidas seda serveri tasemel teha. Võimalusel tuleks võtta autentimise sertifikaat veebirakenduse tasemel lahti ja kontrollida, kas see sisaldab mõnda korrektset OIDi ning kui ei sisalda, siis mitte autentida. Hetkeseisuga teadaolevad OIDid on SK publitseerinud peatükis „Only accept certificates with trusted issuance policy": - #### *HTTP Strict Transport Security* (HSTS) lubamine HSTS teenuse Nginx veebilehele konfigureerimiseks lisa konfiguratsioonifaili rida `add_header Strict-Transport-Security`: @@ -643,14 +761,23 @@ server { ssl_verify_client on; ssl_verify_depth 2; - # OCSP — uncomment to enable AIA OCSP checking - # ssl_ocsp leaf; - # ssl_ocsp_cache off; - # resolver 194.126.115.18; + # Kliendisertifikaadi tühistusoleku kontroll + ssl_ocsp leaf; + ssl_ocsp_cache shared:OCSP:10m; + resolver 194.126.115.18; + + # Serverisertifikaadi OCSP stapling - luba ainult CA OCSP toe korral + # ssl_stapling on; + # ssl_stapling_verify on; + # ssl_trusted_certificate /etc/ssl/certs/Nginx2404_CA.pem; # TLS ssl_protocols TLSv1.3; - # ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384; + ssl_conf_command Ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256; + # Dokumenteeritud ühilduvuserand TLS 1.2 jaoks: + # ssl_protocols TLSv1.2 TLSv1.3; + # ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305'; + ssl_conf_command Options -Compression,NoRenegotiation; ssl_prefer_server_ciphers on; # HSTS and session settings @@ -659,18 +786,19 @@ server { ssl_session_timeout 1h; ssl_session_tickets on; - # Filter by certificate issuer — reject if not a trusted CA - set $ocspr ""; + # Osaline filtreerimine väljastaja CA nime järgi; rakendus peab lisaks + # lubama ainult ID-kaardi CertificatePolicies OID-d + set $trusted_client_issuer 0; - if ($ssl_client_i_dn = "CN=ESTEID2018,organizationIdentifier=NTREE-10747013,O=SK ID Solutions AS,C=EE") { - set $ocspr "http://aia.sk.ee/esteid2018"; + if ($ssl_client_i_dn ~ "^CN=ESTEID2018,") { + set $trusted_client_issuer 1; } - if ($ssl_client_i_dn = "CN=ESTEID2025, organizationIdentifier=NTREE-17066049, O=Zetes Estonia OÜ, C=EE") { - set $ocspr "http://ocsp.eidpki.ee"; + if ($ssl_client_i_dn ~ "^CN=ESTEID2025,") { + set $trusted_client_issuer 1; } - if ($ocspr = "") { + if ($trusted_client_issuer = 0) { return 403; } @@ -682,14 +810,20 @@ server { [^1]: Lisaks käsureal kirjeldatud sertifikaadi atribuutidele C, O ja CN on võimalik soovi korral lisaks kirjeldada atribuudid L, OU ja S. Võib kasutada ka ainult CNi. -[^2]: Kaasaegsed veebilehitsejad ei pea veebilehte usaldusväärseks, kui vähemalt üks SAN DNS ei vasta veebilehe tegelikule aadressile. +[^2]: Kaasaegsed veebilehitsejad usaldavad sertifikaati ainult siis, kui veebilehe aadress vastab vähemalt ühele sertifikaadi SAN DNS nimele. -[^3]: Veebilehitsejad ei pea veebilehte usaldusväärseks, kui vähemalt üks SAN DNS ei vasta veebilehe tegelikule aadressile. +[^3]: HTTP osa siin konfiguratsioonifailis ei ole tegelikult vajalik ja on toodud lihtsalt HTTP -\>HTTPS ümbersuunamise näitena. -[^4]: HTTP osa siin konfiguratsioonifailis ei ole tegelikult vajalik ja on toodud lihtsalt HTTP -\>HTTPS ümbersuunamise näitena. +[^4]: Sertifikaatide kehtivust on võimalik kontrollida ka sertifikaatide tühistusnimekirjade (CRL) abil, ent sellel käesolevas dokumendis ei peatuta, kuna OCSP-põhine lahendus on eelistatum. -[^5]: Sertifikaatide kehtivust on võimalik kontrollida ka sertifikaatide tühistusnimekirjade (CRL) abil, ent sellel käesolevas dokumendis ei peatuta, kuna OCSP-põhine lahendus on eelistatum. +[^5]: *Resolver* -- asendage see soovi korral mõne DNS serveriga, mis on võimeline avalikke DNS aadresse lahendama. Selliseks serveriks võib olla ka teie enda sisevõrgu DNS server. -[^6]: *Resolver* -- asendage see soovi korral mõne DNS serveriga, mis on võimeline avalikke DNS aadresse lahendama. Selliseks serveriks võib olla ka teie enda sisevõrgu DNS server. +[^6]: -[^7]: Siin ei käsitleta teiste TLS protokollide šifreid, kuna versioonist 1.2 vanemad protokollid on eelduslikult keelatud ja 1.3 versioon on hetkel eelistatuim. +[^7]: Lubatud loend põhineb + [ESTEID2018 sertifitseerimispoliitikal v4.0](https://www.id.ee/wp-content/uploads/2025/10/cp_esteid_v4.0-08.10.2025.pdf), + [ESTEID2025 sertifitseerimispoliitikal v2.0](https://repository.eidpki.ee/static/documents/eid-cp-v-2.0_04.06.2026_allkirjastatud.pdf) + ja [Zetesi sertifikaadiprofiilidel](https://repository.eidpki.ee/static/documents/CertificateProfiles-20260520.pdf). + Enne tootmise lubatud loendi muutmist kontrolli + [Zetesi repositooriumi](https://repository.eidpki.ee/repository/) ning + teenuseosutajate kehtivaid poliitikaid ja profiile. diff --git a/nginx/index.md b/nginx/index.md index f8a65c1..3354164 100644 --- a/nginx/index.md +++ b/nginx/index.md @@ -2,7 +2,7 @@ **[Eesti keeles (In Estonian)](index.et.md)** -**Version:** 26.04/1 +**Version:** 26.08/1 **Published by:** [RIA](https://www.ria.ee/) @@ -23,6 +23,7 @@ | 22/08/2024 | 24.08/1 | Ubuntu updated to Server 24.04 and Nginx to 1.27.1. — Changed by: Urmas Vanem | 31/10/2025 | 25.10/1 | Added Zetes chain, removed SK OCSP section. — Changed by: Lauris Kaplinski | 22/04/2026 | 26.04/1 | Converted to Markdown format. — Changed by: Raul Metsma +| 21/08/2026 | 26.08/1 | Updated certificate-key, TLS protocol, cipher-suite, certificate-policy, and OCSP guidance based on the 2026 cryptographic algorithms life-cycle report. --- @@ -36,7 +37,8 @@ This guide describes: - How to install and configure the Nginx 1.28.1 web server on Ubuntu Server 24.04. - How to configure HTTPS (one-way SSL) in the web server. - How to configure ID-card authentication (two-way SSL) using [SK ID Solutions](https://www.skidsolutions.eu/resources/certificates/) (`EE-GovCA2018`) and [Zetes](https://repository.eidpki.ee/) (`EEGovCA2025`) ID-cards. -- How to configure OCSP checks against the guaranteed OCSP as well as the AIA OCSP service. +- How to check client-certificate revocation and configure server-certificate + OCSP stapling. - How to protect the web server. This guide also covers other configuration options such as how to configure HTTP -\> HTTPS redirection, etc. @@ -119,6 +121,17 @@ $ openssl req -new -key Nginx2404.key -out Nginx2404.csr -subj /C=EE/O=OctoX/CN= 3. `CN=Nginx2404.octox.demo` is the common name for the certificate; 4. `DNS:Nginx2404.octox.demo` and `DNS:MYWEBSERVER.octox.demo` are SAN DNS names for the certificate. These names must correspond to the actual address of the website[^2]. The names must also be resolvable in name services. +Generate a separate private key for every independent TLS server. Do not copy +one key between servers merely because a wildcard or multi-SAN certificate +could cover all their names. Keeping keys separate limits the impact of a +server or key compromise. + +For production deployments, use a hardware security module (HSM) or an +equivalent non-exportable hardware-backed key store where supported. Generate +the key inside the device and keep it non-exportable. Confirm that the HSM, +OpenSSL integration, and certificate issuer support the selected ECDSA P-384 +key before deployment. The file-based key in this example is not an HSM setup. + The contents of the CSR can be viewed by running ```bash @@ -148,64 +161,6 @@ Certificate Request: Signature Value: ``` -###### RSA - -*This section is retained for those who prefer RSA-based certificates. The rest of the document uses ECC.* - -Create a CSR and a private key with the command - -```bash -$ openssl req -newkey rsa:2048 -keyout NGINX20PRIV.key -sha256 -subj "/CN=Nginx20.kaheksa.xi" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf "[SAN]\nsubjectAltName=DNS: Nginx20.kaheksa.xi,DNS: Nginx22.kaheksa.xi ")) -out NGINX20.csr -nodes -Generating a RSA private key -........................................................................+++++ -.....................................+++++ -writing new private key to 'NGINX20PRIV.key' ------ -``` - -1. `NGINX20PRIV.key` is the private key of the certificate; -2. `NGINX20.csr` is the CSR for the CA; -3. `Nginx20.kaheksa.xi` is the subject name for the certificate; -4. `Nginx20.kaheksa.xi` and `Nginx22.kaheksa.xi` are certificate SAN DNS names. These names must correspond to the actual address of the website[^3]. The names must also be resolvable in name services. - -The contents of the CSR can be viewed with the command - -```bash -$ openssl req -in NGINX20.csr -noout -text -Certificate Request: - Data: - Version: 1 (0x0) - Subject: CN = Nginx20.kaheksa.xi - Subject Public Key Info: - Public Key Algorithm: rsaEncryption - RSA Public-Key: (2048 bit) - Modulus: - 00:f1:62:c3:ed:1d:0b:ea:cb:7c:22:17:41:1e:e3: - c1:02:a6:7b:f3:72:13:ae:8d:72:72:6f:09:77:d6: - 51:84:4b:2a:f6:7b:65:9d:9f:f3:2a:0c:16:e5:26: - 47:70:aa:3e:c8:4c:50:62:5b:6c:2a:49:ea:51:01: - 60:5c:94:2c:d6:1d:78:70:eb:41:88:6c:09:c8:2f: - e4:d5:bb:2f:fb:ec:2f:9d:0c:42:66:b5:de:91:e3: - 60:62:ff:94:11:21:aa:de:bb:52:bd:20:a6:ff:b4: - c3:92:0a:5b:b5:fc:2f:88:bc:44:3e:b4:5b:a4:ec: - de:49:16:b6:c0:13:ed:d0:e2:ee:d0:58:bc:cb:36: - 32:c9:1b:6d:8f:79:db:83:22:fd:fe:a7:9a:b2:cd: - 26:b1:d7:52:c4:0c:40:6d:0e:49:b5:18:07:c2:3c: - c0:c9:70:5d:06:da:0a:e6:01:1a:a4:78:19:aa:a7: - 38:1c:9d:36:07:4d:db:d2:b5:7b:50:f1:4b:d0:c7: - 5d:90:86:92:2d:a6:ea:d7:d2:09:8f:51:e8:b6:52: - 07:b1:1e:5e:ca:65:f3:d4:69:52:f1:d9:47:02:24: - 98:42:70:83:bc:49:13:c1:92:51:f7:ca:b2:fa:f6: - a7:08:13:c1:74:23:d6:58:ab:27:d5:e5:02:20:3f: - 11:3b - Exponent: 65537 (0x10001) - Attributes: - Requested Extensions: - X509v3 Subject Alternative Name: - DNS:Nginx20.kaheksa.xi, DNS: Nginx22.kaheksa.xi - Signature Algorithm: sha256WithRSAEncryption -``` - ##### Ordering and installing an SSL certificate The CSR `Nginx2404.csr` should be sent to trustworthy CA. In the demo environment, the certificate issuer is the test CA. Signed certificate is issued in PEM format. @@ -264,7 +219,7 @@ Then, prepare the configuration file for the new virtual website. Create a new f $ nano /etc/nginx/conf.d/Nginx2404.conf ``` -Now, change the new configuration file as you wish. Paste the following configuration in it[^4]: +Now, change the new configuration file as you wish. Paste the following configuration in it[^3]: ```nginx server { @@ -377,11 +332,14 @@ To Action From 443/tcp (v6) ALLOW Anywhere (v6) ``` -### Checking the status of the user's certificate against the OCSP service[^5] +### Checking client-certificate revocation with OCSP[^4] -Using the OCSP (Online Certificate Status Protocol) service, you can check the revocation status of client certificates practically in real time. With every client authentication attempt, the web server sends a query to the OCSP service, which responds with the certificate status. +OCSP (Online Certificate Status Protocol) lets Nginx check the revocation +status of a client certificate during authentication. -SK and Zetes offer a free-access (free-of-charge) AIA OCSP service. For certificates issued under the `ESTEID2018` and `ESTEID2025` CA, AIA OCSP service location is already included in the certificate (, ). +Certificates issued under the `ESTEID2018` and `ESTEID2025` CAs contain +their AIA OCSP service address ( and +). ![ESTEID2018 AIA OCSP address in the certificate](./img/image7.png) @@ -395,96 +353,257 @@ ssl_client_certificate /etc/ssl/certs/EID_Bundle.pem; ssl_verify_client on; ssl_verify_depth 2; ssl_ocsp leaf; -ssl_ocsp_cache off; +ssl_ocsp_cache shared:OCSP:10m; resolver 194.126.115.18; ``` -With the configuration shown above, the address of the OCSP service is taken from the client certificate. Replace the `resolver` IP with any DNS server capable of resolving public addresses[^6]. +The `leaf` value checks the end-user certificate, and the shared cache +reduces repeated responder queries. The responder address is taken from the +client certificate. Replace the `resolver` IP with a DNS server capable of +resolving public addresses[^5]. Allow outbound DNS and HTTP access to the +responders and monitor Nginx errors: an OCSP validation failure prevents +client-certificate authentication. + +### Stapling the server-certificate OCSP response + +Client-certificate validation above and server-certificate OCSP stapling are +separate functions. Stapling lets Nginx obtain a signed status response for +its own server certificate and send it during the TLS handshake. This avoids +each browser querying the issuing CA and improves client privacy.[^6] + +First check whether the server certificate contains an OCSP responder URI: + +```bash +$ openssl x509 -in /etc/ssl/certs/Nginx2404_Bundle.pem -noout -ocsp_uri +``` + +If the command returns a supported URI, create +`/etc/ssl/certs/Nginx2404_CA.pem` containing the issuing, intermediate, and +root CA certificates in PEM format. Then enable stapling and response +verification: + +```nginx +ssl_stapling on; +ssl_stapling_verify on; +ssl_trusted_certificate /etc/ssl/certs/Nginx2404_CA.pem; +resolver 194.126.115.18; +``` + +Do not enable stapling when the issuing CA does not provide an OCSP service. +After reloading Nginx, verify the stapled response: + +```bash +$ openssl s_client -connect Nginx2404.octox.demo:443 \ + -servername Nginx2404.octox.demo -status . +When the TLS implementation and deployed clients provide production support, +prioritize the hybrid `X25519MLKEM768` group. This guide does not hard-code a +group setting because support and the standardized identifier depend on the +installed OpenSSL version. Confirm the effective group with a current TLS +scanner before relying on it. + +If you want to make the change at the server level, modify the parameter +`ssl_protocols` in the file `/etc/nginx/nginx.conf`. + +More information about the recommendations for the use of the TLS +protocol can be found in the cryptographic algorithms life cycle report +ordered by RIA at +. #### Cipher suites -All TLS 1.3 cipher suites are currently considered safe, no additional configuration is required for security considerations for this protocol. +Configure an explicit allowlist instead of relying on OpenSSL aliases +such as `HIGH`. For TLS 1.3, enable the following suites in this order: -TLS 1.2 is different. There are many different TLS cipher suites available with Nginx version 1.23.3[^7], which can be viewed with the command +```nginx +ssl_conf_command Ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256; +``` -```bash -$ openssl ciphers -v +`TLS_AES_128_CCM_SHA256` may be used only as a fallback when AES-GCM and +ChaCha20-Poly1305 are unavailable. Do not enable CCM_8 suites. + +When the documented TLS 1.2 compatibility exception applies, enable only the +three ECDHE-ECDSA and AEAD suites below. This matches the ECDSA-only +certificate profile used in this guide: + +```nginx +ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305'; ``` -If you wish to configure the available cipher suites used with TLS 1.2 in more detail, you can use the `ssl_ciphers` directive in the Nginx configuration file. Here, you can use predefined aliases or exact cipher suite descriptions. +The `ssl_ciphers` directive controls TLS 1.2 and older versions; +`ssl_conf_command Ciphersuites` controls TLS 1.3 through OpenSSL. The +TLS 1.2 list excludes RSA authentication and key exchange, static DH/ECDH, +CBC, CCM_8, and non-AEAD suites. + +You can also configure these directives at the server level in +`/etc/nginx/nginx.conf`. Check the effective list with +`openssl ciphers -v` and verify the negotiated protocol and suite with a +current TLS scanner after every configuration change. -It is impossible to give an exact recommendation for configuring cipher suites without knowing the requirements applicable to the webpage. However, non-secure cipher suites must be removed from the list. It is reasonable to describe the specific enabled cipher suites for TLS 1.2. +##### Compression and renegotiation -Example — the following line in the configuration file allows only the described cipher suites: +Keep TLS compression and TLS 1.2 renegotiation disabled explicitly: ```nginx -ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384; +ssl_conf_command Options -Compression,NoRenegotiation; ``` -You can also configure cipher suites at the server level by modifying the parameter `ssl_ciphers` in the file `/etc/nginx/nginx.conf`. +HTTP response compression is separate from TLS compression and can disclose +secrets when a response contains both attacker-controlled input and sensitive +data. Set `gzip off;` for sensitive dynamic locations and also disable any +configured Brotli module there. If response compression must remain enabled, +the application must prevent cross-site request forgery and mitigate +response-length leakage. -More information about the recommendations for the use of the cipher suites can be found in the cryptographic algorithms life cycle report ordered by RIA at . +More information about the recommendations for the use of the cipher +suites can be found in the cryptographic algorithms life cycle report +ordered by RIA at +. ##### ssl_prefer_server_ciphers -Preferring server ciphers over user ciphers can be enabled with `ssl_prefer_server_ciphers`. Set its value to 'on' in the configuration file. +Preferring server ciphers over user ciphers can be enabled with +`ssl_prefer_server_ciphers`. Set its value to `on` in the configuration +file. #### Additional filtering of client certificates -Important! To guarantee access to the web service only for users with the right certificates, it is strongly recommended to add the following additional requirements in the server configuration: +Trusting a CA chain does not prove that the leaf certificate is an ID-card +authentication certificate. Different certificate products can share a root +or intermediate CA. Before accepting the authenticated identity, require all +of the following: + +1. Nginx successfully validates the complete certificate chain; +2. the issuer is an explicitly allowed intermediate CA; +3. `extendedKeyUsage` permits TLS web-client authentication; +4. the leaf certificate's `X509v3 CertificatePolicies` extension + (`2.5.29.32`) contains both the NCP+ authentication-policy OID and an + allowed document-policy OID for the certificate's CA generation.[^7] + +For production certificates covered by this guide, use this allowlist: + +```text +# Required in every accepted authentication certificate +0.4.0.2042.1.2 + +# ESTEID2018 - require one of these document-policy OIDs +1.3.6.1.4.1.51361.1.1.1 +1.3.6.1.4.1.51361.1.1.2 +1.3.6.1.4.1.51361.1.1.3 +1.3.6.1.4.1.51361.1.1.4 +1.3.6.1.4.1.51361.1.1.5 +1.3.6.1.4.1.51361.1.1.6 +1.3.6.1.4.1.51361.1.1.7 +1.3.6.1.4.1.51455.1.1.1 + +# ESTEID2025 - require one of these document-policy OIDs +1.3.6.1.4.1.51361.2.1.1 +1.3.6.1.4.1.51361.2.1.2 +1.3.6.1.4.1.51361.2.1.3 +1.3.6.1.4.1.51361.2.1.4 +1.3.6.1.4.1.51361.2.1.5 +1.3.6.1.4.1.51361.2.1.6 +1.3.6.1.4.1.51455.2.1.1 +``` -1. The certificate must include the correct OID value; -2. The certificate issuer must be `ESTEID2018` or `ESTEID2025`. +Correlate the document-policy OID with the validated issuer: an `ESTEID2018` +certificate must not be accepted using an `ESTEID2025` policy OID, or vice +versa. The common NCP+ OID is not product-specific and is insufficient on its +own. Do not add test OIDs, such as Zetes OIDs prefixed with `2.999`, to a +production allowlist. -There is currently no known way to check the correct OID at the Nginx server level. It is recommended to perform this check at the web application level instead. +Nginx does not provide a directive that can reliably apply an allowlist to +the policy OIDs inside `CertificatePolicies`. Perform that check in the +application or an authentication gateway. Do not infer the certificate +product from its subject, issuer, or EKU alone, and do not treat the +`anyPolicy` OID (`2.5.29.32.0`) as proof of an ID-card policy. -To implement the second recommendation above, you can check the end-user certificate issuer and reject the connection if it is not issued by a CA enabled in the server. To implement it, add the following conditions to the configuration file (server section, e.g. after the SSL description): +As a preliminary, defence-in-depth check, reject certificates whose issuer CA +name is not `ESTEID2018` or `ESTEID2025`. Add these conditions to the `server` +section after the TLS configuration: ```nginx -#Determine IMCA and cancel, if not trusted -set $ocspr ""; +# Preliminary filter by intermediate CA name +set $trusted_client_issuer 0; -if ($ssl_client_i_dn = "CN=ESTEID2018,organizationIdentifier=NTREE-10747013,O=SK ID Solutions AS,C=EE") { - set $ocspr "http://aia.sk.ee/esteid2018"; +if ($ssl_client_i_dn ~ "^CN=ESTEID2018,") { + set $trusted_client_issuer 1; } -if ($ssl_client_i_dn = "CN=ESTEID2025, organizationIdentifier=NTREE-17066049, O=Zetes Estonia OÜ, C=EE") { - set $ocspr "http://ocsp.eidpki.ee"; +if ($ssl_client_i_dn ~ "^CN=ESTEID2025,") { + set $trusted_client_issuer 1; } -if ($ocspr = "") { +if ($trusted_client_issuer = 0) { return 403; } ``` -With these conditions in place, any connection will be rejected if the user certificate was not issued by a trusted CA — `ESTEID2018` or `ESTEID2025`. +With these conditions, Nginx rejects a certificate unless its issuer is +`ESTEID2018` or `ESTEID2025`. This issuer check does not replace the +certificate-policy check. + +For an HTTP upstream, overwrite a dedicated request header with the verified +leaf certificate: + +```nginx +proxy_set_header X-Client-Certificate $ssl_client_escaped_cert; +``` + +The application must URL-decode and parse the certificate, then reject +authentication unless both the NCP+ OID and a document-policy OID matching +the issuer are present. Only trust this header when the application is +reachable exclusively through the trusted Nginx proxy. Other application +interfaces should use their native TLS client-certificate integration. + +To inspect the extension while testing an exported certificate: + +```bash +$ openssl x509 -in client.pem -noout -text +``` + +Check the `X509v3 Certificate Policies` section against the current policy +and certificate-profile sources cited above. Test at least one +accepted ID-card certificate and certificates for other products issued in +related hierarchies, including Mobile-ID where applicable. > **Note:** If you are using another feature to filter network traffic, the secure configuration should be implemented there, too. SK has published information about the F5 configuration in the chapter 'Only accept certificates with trusted key usage' in the following article: > **Note:** SK's recommendations for secure ID-card authentication are published here in the chapter 'Defense: implement ID-card authentication securely': -> **Note:** The recommended method for avoiding incorrect certificates is using OIDs in the certificates. Unfortunately, there is currently no method for doing this at the server level. If possible, open the certificate at the web application level, check for a correct OID in the certificate, and if there is none, reject the authentication request. All currently known OIDs are listed in the chapter 'Only accept certificates with trusted issuance policy' in the following article published by SK: - #### Enabling HTTP Strict Transport Security (HSTS) To enable HSTS for the Nginx webpage, add the `add_header Strict-Transport-Security` line to the configuration file. @@ -647,14 +766,23 @@ server { ssl_verify_client on; ssl_verify_depth 2; - # OCSP — uncomment to enable AIA OCSP checking - # ssl_ocsp leaf; - # ssl_ocsp_cache off; - # resolver 194.126.115.18; + # Client-certificate revocation checking + ssl_ocsp leaf; + ssl_ocsp_cache shared:OCSP:10m; + resolver 194.126.115.18; + + # Server-certificate OCSP stapling - enable only if its CA supports OCSP + # ssl_stapling on; + # ssl_stapling_verify on; + # ssl_trusted_certificate /etc/ssl/certs/Nginx2404_CA.pem; # TLS ssl_protocols TLSv1.3; - # ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384; + ssl_conf_command Ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256; + # Documented TLS 1.2 compatibility exception: + # ssl_protocols TLSv1.2 TLSv1.3; + # ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305'; + ssl_conf_command Options -Compression,NoRenegotiation; ssl_prefer_server_ciphers on; # HSTS and session settings @@ -663,18 +791,19 @@ server { ssl_session_timeout 1h; ssl_session_tickets on; - # Filter by certificate issuer — reject if not a trusted CA - set $ocspr ""; + # Partial filtering by issuer CA name; the application must also + # allowlist ID-card CertificatePolicies OIDs + set $trusted_client_issuer 0; - if ($ssl_client_i_dn = "CN=ESTEID2018,organizationIdentifier=NTREE-10747013,O=SK ID Solutions AS,C=EE") { - set $ocspr "http://aia.sk.ee/esteid2018"; + if ($ssl_client_i_dn ~ "^CN=ESTEID2018,") { + set $trusted_client_issuer 1; } - if ($ssl_client_i_dn = "CN=ESTEID2025, organizationIdentifier=NTREE-17066049, O=Zetes Estonia OÜ, C=EE") { - set $ocspr "http://ocsp.eidpki.ee"; + if ($ssl_client_i_dn ~ "^CN=ESTEID2025,") { + set $trusted_client_issuer 1; } - if ($ocspr = "") { + if ($trusted_client_issuer = 0) { return 403; } @@ -686,14 +815,20 @@ server { [^1]: In addition to the certificate attributes C, O, and CN described on the command line, it is also possible to describe the attributes L, OU, and S if desired. However, only CN can also be used. -[^2]: Modern browsers do not trust websites where at least one SAN DNS name is not equal to the actual address of the website. +[^2]: Modern browsers trust the certificate only when the requested hostname matches at least one of its SAN DNS names. -[^3]: Browsers do not trust websites where at least one SAN DNS name is not equal to the actual address of the website. +[^3]: The HTTP sections in the configuration file are not necessary and are shown here as an example of the HTTP -\> HTTPS redirection. -[^4]: The HTTP sections in the configuration file are not necessary and are shown here as an example of the HTTP -\> HTTPS redirection. +[^4]: The certificate check is also doable with certificate revocation lists (CRL), but this is not covered in this document, as the OCSP-based solution is preferred. -[^5]: The certificate check is also doable with certificate revocation lists (CRL), but this is not covered in this document, as the OCSP-based solution is preferred. +[^5]: Resolver -- replace the IP address here with any DNS server that can resolve public DNS addresses. You can also use the DNS server of your intranet for this. -[^6]: Resolver -- replace the IP address here with any DNS server that can resolve public DNS addresses. You can also use the DNS server of your intranet for this. +[^6]: -[^7]: The ciphers of other protocols are not covered in this chapter, because protocols older than version 1.2 should be disabled and version 1.3. is currently preferred. +[^7]: The allowlist is based on the + [ESTEID2018 certificate policy v4.0](https://www.id.ee/wp-content/uploads/2025/10/cp_esteid_v4.0-08.10.2025.pdf) + and the [ESTEID2025 certificate policy v2.0](https://repository.eidpki.ee/static/documents/eid-cp-v-2.0_04.06.2026_allkirjastatud.pdf), + supplemented by the [Zetes certificate profiles](https://repository.eidpki.ee/static/documents/CertificateProfiles-20260520.pdf). + Check the [Zetes repository](https://repository.eidpki.ee/repository/) + and the service providers' current policies and profiles before changing + the production allowlist.