Przejdź do treści
Home » err_ssl_key_usage_incompatible: Kompleksowy przewodnik po błędzie niezgodności użycia klucza SSL

err_ssl_key_usage_incompatible: Kompleksowy przewodnik po błędzie niezgodności użycia klucza SSL

Pre

W świecie certyfikatów SSL i TLS jednym z najczęściej spotykanych problemów, które psują płynne działanie stron internetowych i usług, jest błąd err_ssl_key_usage_incompatible. Ten komunikat błędu odnosi się do niezgodności między uprawnieniami (Key Usage) lub rozszerzeniami EKU (Extended Key Usage) w certyfikacie a wymaganiami serwera lub klienta. W praktyce może on objawiać się jako „połączenie niezaszyfrowane”, „odmowa połączenia” lub „błąd certyfikatu” podczas próby nawiązania TLS. W poniższym artykule wyjaśniamy, czym dokładnie jest err_ssl_key_usage_incompatible, jakie są typowe przyczyny, jak go diagnozować i jak skutecznie naprawiać ten problem krok po kroku.

err_ssl_key_usage_incompatible: co to znaczy i kiedy się pojawia?

err_ssl_key_usage_incompatible to komunikat, który pojawia się wtedy, gdy certyfikat SSL/TLS używany przez serwer (lub klienta) nie zawiera właściwych KeyUsage lub Extended Key Usage dla danej funkcji. Kluczowa idea: certyfikaty SSL nie są tworzone jedynie po to, aby potwierdzić tożsamość serwera. Muszą także deklarować, do czego są uprawnione (np. klucz do podpisywania cyfrowego, do szyfrowania danych, do uwierzytelniania serwera, a czasem do uwierzytelniania klienta). Brak zgodności pomiędzy wymaganiami TLS a faktycznymi uprawnieniami certyfikatu skutkuje błędem err_ssl_key_usage_incompatible.

W praktyce spotkamy takie scenariusze:

  • Certyfikat serwera nie posiada EKU obejmującego uwierzytelnianie serwera (serverAuth), a serwer wymaga takiego EKU.
  • Certyfikat klienta lub podpisywanej strony nie zawiera odpowiedniego KeyUsage dla operacji szyfrowania lub podpisywania, co prowadzi do odrzucenia połączenia.
  • Certyfikat używany w domenie nie został wydany dla danego celu, na przykład certyfikat z EKU tylko do identyfikacji podmiotu (id-pkix ego) – a system wymaga EKU dla TLS.

Najważniejsze pojęcia: KeyUsage i Extended Key Usage

Klucze używane w certyfikatach SSL posiadają dwa podstawowe atrybuty konfiguracyjne:

  • KeyUsage – zbiór podstawowych uprawnień dla klucza (np. digitalSignature, keyEncipherment, dataEncipherment).
  • Extended Key Usage (EKU) – doprecyzowanie zastosowań, takich jak serverAuth (uwierzytelnianie serwera), clientAuth (uwierzytelnianie klienta), codeSigning, emailProtection itp.

Podstawowy problem polega na tym, że jeśli certyfikat ma nieprawidłowy zestaw KeyUsage lub EKU dla danego zastosowania, TLS rzuca err_ssl_key_usage_incompatible i nie dopuszcza do ustanowienia bezpiecznego połączenia. Dlatego tak ważna jest prawidłowa konfiguracja podczas wygaszania lub odnawiania certyfikatów, a także podczas konfiguracji serwera i klienta.

Dlaczego err_ssl_key_usage_incompatible jest częstym błędem?

Najczęściej problemy wynikają z one of four głównych obszarów:

  • Nowy certyfikat bez właściwych EKU dla TLS nie obsługuje scenariusza, w którym serwer oczekuje uwierzytelniania serwera.
  • Certyfikat jest przeznaczony dla innego celu (np. do podpisywania kodu lub szyfrowania danych) niż TLS.
  • Ścieżka zaufania do certyfikatu jest niekompletna lub wystawiono go przez CA, które nie jest zaufane przez klienta lub serwer.
  • Problemy z konfiguracją serwera lub klientów (np. błędna wersja protokołu TLS, niezgodność zestawów cipher, SNI, ALPN) mogą ujawnić err_ssl_key_usage_incompatible w kontekście błędów certyfikatu.

Również środowiska chmurowe i konteneryzacja mogą wpływać na to, które certyfikaty są używane w danym momencie, co potęguje ryzyko napotkania err_ssl_key_usage_incompatible w zastosowaniach produkcyjnych.

Diagnostyka: jak rozpoznać err_ssl_key_usage_incompatible?

Diagnostyka błędu err_ssl_key_usage_incompatible wymaga kilku kroków, które pozwalają zidentyfikować, czy problem leży w certyfikacie, konfiguracji serwera, czy w konfiguracji klienta. Poniżej przedstawiamy praktyczne metody i narzędzia, które pomagają potwierdzić problem oraz wskazać odpowiednie naprawy.

1) Przegląd certyfikatu i jego EKU

Najpierw należy sprawdzić, jakie EKU i KeyUsage zawiera certyfikat. W przypadku certyfikatów serwera TLS najważniejsze są wartości serverAuth/ clientAuth w EKU oraz keyEncipherment lub digitalSignature w KeyUsage. Można to zrobić za pomocą narzędzi takich jak OpenSSL:

openssl x509 -in cert.pem -text -noout | sed -n '/X509v3 extensions:/,/-----END/ p'

W wyniku zobaczymy sekcję X509v3 extensions, w której znajdują się EKU i KeyUsage. Szukaj wpisów takich jak:

  • Extended Key Usage: TLS Web Server Authentication, TLS Web Client Authentication
  • Key Usage: Digital Signature, Key Encipherment

Jeżeli EKU nie zawiera „serverAuth” (dla serwera), lub EKU nie pasuje do zastosowania TLS, to przyczyną err_ssl_key_usage_incompatible może być właśnie brak EKU wymaganych dla TLS.

2) Sprawdzenie łańcucha certyfikatów i zaufania

Zdarza się, że err_ssl_key_usage_incompatible pojawia się razem z lub w wyniku problemów z zaufaniem do certyfikatu. Sprawdź, czy łańcuch certyfikatów jest kompletny i czy wszystkie certyfikaty pośrednie są zaufane na kliencie. Możesz to zweryfikować na przykład tak:

openssl s_client -connect example.com:443 -servername example.com -showcerts

W wynikach zwróć uwagę na:

  • Zweryfikowany łańcuch certyfikatów (certificate chain) – czy klient uznaje go za zaufany?
  • Czy certyfikat serwera ma poprawny klucz i EKU?

3) Analiza błędów TLS na poziomie przeglądarki

W przeglądarkach internetowych błędy TLS, w tym err_ssl_key_usage_incompatible, zwykle wyświetlają szczegółowy komunikat lub kod błędu w narzędziach deweloperskich. Można uruchomić narzędzia deweloperskie (F12), przejść do zakładki Security i przeanalizować certyfikaty, łańcuch zaufania oraz polityki EKU. Informacje te często potwierdzają, że problem wynika z niezgodności EKU lub KeyUsage.

4) Diagnostyka serwera i logów

Przegląd logów serwera TLS oraz konfiguracji TLS (np. Nginx, Apache, IIS, HAProxy) często ujawnia, czy serwer odrzuca połączenia z powodu błędów certyfikatu. Sprawdź sekcje logów związane z TLS i certyfikatami, a także konfiguracje w zakresie wymogów EKU oraz algorytmów kluczy.

Przykładowe scenariusze err_ssl_key_usage_incompatible

Scenariusz A: Certyfikat serwera bez serverAuth

Serwer używa certyfikatu, który ma EKU bez pozycji serverAuth, a użytkownik próbuje nawiązać TLS z wymogiem uwierzytelniania serwera. W wyniku występuje err_ssl_key_usage_incompatible. Rozwiązanie: wygenerować lub uzyskać certyfikat serwera z EKU serverAuth i upewnić się, że KeyUsage obejmuje Digital Signature i/lub Key Encipherment.

Scenariusz B: Certyfikat klienta z EKU niezgodnym z TLS

W aplikacji klient wymaga certyfikatu z EKU clientAuth, ale certyfikat nie zawiera tego EKU. Połączenie kończy się błędem err_ssl_key_usage_incompatible. Rozwiązanie: wystawić certyfikat klienta z odpowiednim EKU i upewnić się, że serwer akceptuje połączenia z takimi klientami.

Scenariusz C: Niekompletny łańcuch certyfikatów

Certyfikat serwera nie ma pełnego łańcucha aż do CA zaufanego przez klienta, co może prowadzić do błędów podobnych do err_ssl_key_usage_incompatible, zwłaszcza w kontekście walidacji certyfikatu. Rozwiązanie: dołączyć pełny łańcuch certyfikatów, zainstalować pośrednie certyfikaty na serwerze.

Scenariusz D: Wygasły certyfikat i odnowiony, bez aktualizacji EKU

Po odnowieniu certyfikatu, EKU lub KeyUsage mogą nie zostać odświeżone w certyfikacie z nową datą ważności, co prowadzi do err_ssl_key_usage_incompatible. Rozwiązanie: wygenerować nowy certyfikat z właściwymi EKU i KeyUsage i zaktualizować konfigurację serwera.

Jak naprawić err_ssl_key_usage_incompatible: praktyczny krok-po-kroku

Poniższy przewodnik krok po kroku pomaga naprawić err_ssl_key_usage_incompatible w typowych środowiskach. Zaczynamy od zidentyfikowania problemu, a następnie przechodzimy do praktycznych działań naprawczych.

Krok 1: Zidentyfikuj źródło błędu

Przeanalizuj, czy problem dotyczy serwera, klienta, czy połączenia między nimi. Sprawdź EKU i KeyUsage certyfikatu serwera oraz certyfikatu klienta. Sprawdź łańcuch certyfikatów. W razie wątpliwości wykonaj podstawową diagnostykę przy użyciu OpenSSL i przeglądarki.

Krok 2: Zweryfikuj EKU i KeyUsage w certyfikacie

Upewnij się, że certyfikat serwera zawiera EKU serverAuth (lub odpowiadający mu zestaw do TLS) oraz odpowiednie KeyUsage (np. Digital Signature, Key Encipherment). W przypadku certyfikatu klienta upewnij się, że EKU zawiera clientAuth.

Krok 3: Zweryfikuj łańcuch certyfikatów i zaufanie

Sprawdź, czy CA jest zaufane przez klienta i czy pośrednie certyfikaty są wystarczająco zgodne z polityką TLS. Użyj polecenia OpenSSL do weryfikacji łańcucha:

openssl verify -CAfile ca_bundle.pem cert.pem

Krok 4: Zaktualizuj certyfikaty i konfiguracje

Jeżeli zidentyfikowano nieprawidłowy EKU lub KeyUsage, wygeneruj nowy certyfikat lub poproś o odnowienie certyfikatu z prawidłowymi EKU i KeyUsage. Następnie zaktualizuj konfigurację serwera (i klienta, jeśli dotyczy).

Krok 5: Zrestartuj usługi i przetestuj połączenie

Po dokonaniu zmian zrestartuj serwery TLS (np. Nginx, Apache, IIS) i ponownie sprawdź połączenie za pomocą przeglądarki lub OpenSSL. Upewnij się, że err_ssl_key_usage_incompatible nie występuje i połączenie jest ustanawiane z bezpiecznym protokołem TLS.

Krok 6: Weryfikacja po naprawie

Weryfikacja nie ogranicza się do jednej metody. Wykorzystaj zarówno narzędzia CLI (OpenSSL), jak i przeglądarkę, aby potwierdzić, że certyfikat ma odpowiedni EKU i KeyUsage, a łańcuch certyfikatów jest kompletny i zaufany. Dodatkowo, warto uruchomić testy integracyjne, które symulują bezpieczne połączenia w środowisku staging.

Najczęstsze błędy i ich naprawa: praktyczne wskazówki

Oto lista typowych błędów i rekomendowanych rozwiązań:

  • Brak serverAuth w EKU – naprawa: wygeneruj certyfikat z EKU zawierającym serverAuth.
  • Brak clientAuth w EKU – naprawa: wygeneruj certyfikat z EKU zawierającym clientAuth i odpowiednie KeyUsage.
  • Niekompletny łańcuch certyfikatów – naprawa: dołącz pośrednie certyfikaty do pliku cert.pem lub skonfiguruj serwer, aby podawał pełny łańcuch.
  • Wygaśnięcie certyfikatu – naprawa: odnowa certyfikatu i upewnienie się, że EKU/KeyUsage są aktualne i zgodne z zastosowaniem TLS.
  • Nieprawidłowe algorytmy lub klucze – naprawa: upewnij się, że używasz odpowiedniego typu klucza (RSA/ECDSA), zgodnego z wymaganiami serwera i przeglądarki.

Najczęstsze środowiska i konkretne rozwiązania

Serwer Nginx

W przypadku Nginx problem z err_ssl_key_usage_incompatible często wynika z nieprawidłowego EKU w certyfikacie serwera. Rozwiązanie:

  • Wygeneruj nowy certyfikat z EKU serverAuth i odpowiednimi KeyUsage.
  • Upewnij się, że plik cert.pem zawiera pełny łańcuch certyfikatów (certificate chain).
  • Restartuj Nginx po wymianie certyfikatu: sudo systemctl restart nginx.

Serwer Apache

W Apache, konfiguracja TLS powinna wskazywać na właściwe pliki certyfikatów i łańcucha. Sprawdź:

  • SSLCertificateFile i SSLCertificateChainFile (lub jednoczesna definicja w nowszych wersjach).
  • Po odnowieniu certyfikatu, upewnij się, że EKU zawiera serverAuth.
  • Po zmianie certyfikatu, zrestartuj serwer: sudo systemctl restart apache2.

Inne środowiska i usługi

W środowiskach kontenerowych, takich jak Kubernetes, lub w systemach CI/CD, warto wprowadzić polityki weryfikacyjne EKU i KeyUsage podczas procesu wystawiania certyfikatów. Automatyzacja generowania certyfikatów z prawidłowymi EKU ogranicza ryzyko wystąpienia err_ssl_key_usage_incompatible w środowiskach produkcyjnych.

Weryfikacja i testowanie po naprawie

Po dokonaniu napraw warto przeprowadzić serię testów, które potwierdzą, że problem nie występuje. Zalecane są następujące działania:

  • Test połączeń TLS z użyciem OpenSSL (s_client) dla konkretnego hosta i portu.
  • Testy przeglądarkowe w trybie incognito, aby wyeliminować problemy z cache, cookies i starą konfiguracją.
  • Testy automatyczne z użyciem narzędzi CI/CD, które weryfikują TLS podczas deployu.

Przykładowe polecenie testowe:

openssl s_client -connect example.com:443 -servername example.com

W wyniku powinniśmy zobaczyć prawidłowy łańcuch certyfikatów, z odpowiednimi EKU i bez błędów w sekcji TLS.

Najlepsze praktyki: prewencja błędów err_ssl_key_usage_incompatible

Aby zminimalizować ryzyko napotkania err_ssl_key_usage_incompatible, warto zastosować następujące praktyki:

  • Podczas generowania certyfikatów zawsze określaj EKU odpowiedni do zastosowania (serverAuth dla certyfikatów serwera, clientAuth dla certyfikatów klienta).
  • Weryfikuj EKU i KeyUsage przed instalacją certyfikatu w środowisku produkcyjnym.
  • Utrzymuj pełny łańcuch certyfikatów w konfiguracjach serwera i klienta.
  • Stosuj automatyczną rotację certyfikatów oraz mechanizmy monitoringu TLS, aby wykryć problemy zanim wpłyną na użytkowników.
  • Testuj połączenia TLS w różnych przeglądarkach i wersjach protokołu TLS, zwłaszcza przy migracjach na nowe wersje TLS (np. TLS 1.3).

Porady dla developerów i administratorów: jak podejść do błędu err_ssl_key_usage_incompatible

W praktyce skuteczna obsługa błędu err_ssl_key_usage_incompatible zaczyna się od dobrego planu certyfikatów i ich EKU. Oto kilka praktycznych wskazówek:

  • Stwórz standardowy proces generowania certyfikatów z wyraźnie zdefiniowanymi EKU i KeyUsage.
  • Wprowadź politykę audytu certyfikatów – kiedy wygasają, jakie EKU zawierają i czy łańcuch certyfikatów jest kompletny.
  • Uwzględnij różnice między środowiskami (dev/stage/prod) i przygotuj odpowiednie certyfikaty do każdego z nich.
  • W razie awarii, przygotuj scenariusze rollbacku i szybkie odtworzenie starego certyfikatu, jeśli nowy certyfikat nie działa.

Podsumowanie: kluczowe wnioski dotyczące err_ssl_key_usage_incompatible

err_ssl_key_usage_incompatible to błąd, który dotyczy niezgodności między EKU i KeyUsage certyfikatu a rzeczywistym zastosowaniem TLS w środowisku serwerowym lub klienta. Najczęściej przyczyną są nieprawidłowe EKU (np. brak serverAuth lub clientAuth), niekompletny łańcuch certyfikatów, lub zastosowanie certyfikatu w niewłaściwym kontekście. Kluczowymi działaniami w naprawie są diagnostyka EKU i KeyUsage, weryfikacja łańcucha certyfikatów, wygenerowanie certyfikatu z właściwymi EKU, zaktualizowanie konfiguracji serwera i przeprowadzenie testów po naprawie. Dzięki temu błędowi towarzyszący negatywny wpływ na dostępność usług TLS może być skutecznie wyeliminowany, a użytkownicy mogą ponownie łączyć się bez ryzyka naruszenia bezpieczeństwa.