API OpenSSL: podstawowe struktury i pułapki

API EVP (Envelope) to wysokopoziomowy interfejs OpenSSL do operacji kryptograficznych i właściwe API do użycia w kodzie aplikacji. Ukrywa szczegóły specyficzne dla algorytmów za spójnym interfejsem, automatycznie obsługuje akcelerację sprzętową przez engine i provider oraz poprawnie obsługuje dopełnienie i szczegóły trybów. Niskopoziomowe API OpenSSL specyficzne dla algorytmów jest w nowszych wersjach przestarzałe i należy go unikać.

Szyfrowanie symetryczne w OpenSSL korzysta z obiektu kontekstu EVP_CIPHER_CTX. Sekwencja operacji wygląda następująco: EVP_CIPHER_CTX_new alokuje kontekst, EVP_EncryptInit_ex inicjalizuje go za pomocą szyfru i klucza, EVP_EncryptUpdate wielokrotnie przetwarza dane, EVP_EncryptFinal_ex opróżnia ostatni blok i pobiera pozostałe dane wyjściowe, a EVP_CIPHER_CTX_free zwalnia pamięć. Pominięcie EncryptFinal_ex jest częstym błędem prowadzącym do powstania obciętych danych wyjściowych.

Obliczanie skrótu wiadomości korzysta z EVP_MD_CTX w podobny sposób: EVP_MD_CTX_new, EVP_DigestInit_ex z algorytmem (EVP_sha256(), EVP_sha3_256() itd.), EVP_DigestUpdate z fragmentami danych oraz EVP_DigestFinal_ex do pobrania skrótu. Operacje HMAC korzystają z osobnego HMAC_CTX lub nowszego API EVP_MAC. Abstrakcja EVP umożliwia zmianę algorytmu skrótu za pomocą modyfikacji jednego wywołania funkcji.

EVP_PKEY to ujednolicony obiekt klucza asymetrycznego w OpenSSL, obsługujący RSA, ECDSA, Ed25519, DH i inne algorytmy za pomocą jednego interfejsu. Klucze są tworzone z plików PEM lub DER za pomocą PEM_read_PrivateKey i PEM_read_PUBKEY albo generowane za pomocą EVP_PKEY_keygen. EVP_PKEY_sign i EVP_PKEY_verify wykonują podpisywanie i weryfikację dla dowolnego typu klucza przy użyciu tych samych wywołań funkcji.

BIO (Basic I/O) to warstwa abstrakcji wejścia-wyjścia OpenSSL, która umożliwia odczytywanie i zapisywanie danych chronionych przez TLS lub surowych danych za pośrednictwem łańcucha obiektów BIO. Łańcuch BIO może wyglądać następująco: BIO_new_ssl (warstwa TLS) połączony z BIO_new_connect (połączenie TCP). Zapisywanie do BIO SSL automatycznie szyfruje i wysyła dane, a odczytywanie odszyfrowuje odebrane dane. Obiekty BIO obsługują pliki, gniazda, bufory pamięci i filtry (base64, buforowanie).

Połączenia TLS w OpenSSL korzystają z dwóch obiektów: SSL_CTX (kontekst) przechowuje współdzieloną konfigurację: certyfikat, klucz prywatny, pakiet CA, ograniczenia wersji protokołu i listę szyfrów. SSL reprezentuje pojedyncze połączenie utworzone na podstawie kontekstu. Należy utworzyć jeden SSL_CTX dla aplikacji, a następnie tworzyć na jego podstawie obiekty SSL dla każdego połączenia. SSL_read i SSL_write przesyłają tekst jawny, a OpenSSL wewnętrznie obsługuje całe ramkowanie i szyfrowanie TLS.

Najbardziej niebezpiecznym błędem w OpenSSL jest ignorowanie wartości zwracanych. EVP_EncryptFinal_ex, SSL_read i SSL_write zwracają wartości ujemne lub zero, aby zasygnalizować błędy. Wywoływanie SSL_read w pętli bez sprawdzania SSL_get_error może prowadzić do nieskończonych pętli lub pomijania błędów. Należy sprawdzać wartość zwracaną przez każdą funkcję OpenSSL, która może zakończyć się niepowodzeniem; błędy często wskazują na warunki istotne z punktu widzenia bezpieczeństwa, takie jak nieudane uzgadnianie lub błędy walidacji certyfikatu.

SSL_read i SSL_write mogą zwrócić SSL_ERROR_WANT_READ lub SSL_ERROR_WANT_WRITE, wskazując, że po oczekiwaniu na operację wejścia-wyjścia należy ponowić daną operację. Nie są to rzeczywiste błędy, lecz powiadomienia dotyczące nieblokujących operacji wejścia-wyjścia. Kod, który nie wywołuje SSL_get_error i nie rozgałęzia wykonania poprawnie dla want-read/want-write, będzie albo wykonywał aktywne oczekiwanie w pętli, albo nieprawidłowo traktował te warunki jako błędy. Należy zawsze używać SSL_get_error do interpretowania ujemnych wartości zwracanych przez operacje wejścia-wyjścia TLS.

OpenSSL zawiera wiele przestarzałych funkcji niskopoziomowych, które nie powinny pojawiać się w nowym kodzie: bezpośrednie wywołania DES_encrypt1, bezpośrednie używanie funkcji skrótu SHA1 lub MD5 bez warstwy EVP, RSA_private_encrypt zamiast EVP_PKEY_sign oraz AES_encrypt (AES ECB bez uwierzytelniania). Te API omijają kontrole bezpieczeństwa, korzystają z przestarzałych algorytmów albo są po prostu mniej bezpieczne niż ich odpowiedniki EVP. Ostrzeżenia kompilatora często sygnalizują użycie przestarzałego API.

OpenSSL korzysta z jawnego zarządzania pamięcią — każdy zaalokowany obiekt należy jawnie zwolnić. Typowe wycieki pamięci wynikają z pominięcia EVP_CIPHER_CTX_free po szyfrowaniu, nie wywołania SSL_free po zamknięciu połączenia lub nie wywołania X509_free po weryfikacji certyfikatu. W długo działających serwerach wycieki te powodują stopniowe wyczerpywanie pamięci. Podczas tworzenia oprogramowania należy używać narzędzi takich jak valgrind lub AddressSanitizer do wykrywania wycieków pamięci w OpenSSL.

OpenSSL 3.0 wprowadził model providerów, zastępując starsze API ENGINE do akceleracji sprzętowej. Providery to ładowalne moduły implementujące algorytmy kryptograficzne: provider domyślny (programowy), provider legacy (starsze algorytmy), provider FIPS (zwalidowany zgodnie z FIPS 140-2) oraz providery innych firm do obsługi HSM. Provider FIPS umożliwia działanie zgodne z wymaganiami, ograniczając dostępne algorytmy do tych zatwierdzonych przez FIPS 140-2, bez konieczności zmiany kodu aplikacji.

Dlaczego API EVP OpenSSL jest preferowane zamiast niskopoziomowych API specyficznych dla algorytmów?

Podsumowanie API OpenSSL: zawsze należy używać wysokopoziomowego API EVP, EVP_CIPHER_CTX do operacji symetrycznych, EVP_MD_CTX do haszowania, EVP_PKEY do kluczy asymetrycznych, łańcuchów BIO jako abstrakcji wejścia-wyjścia, SSL_CTX i SSL do połączeń TLS; należy zawsze sprawdzać wartości zwracane i wywoływać SSL_get_error, zwalniać wszystkie zaalokowane obiekty, aby zapobiegać wyciekom, unikać przestarzałych funkcji niskopoziomowych oraz używać providerów OpenSSL 3.0 do zapewnienia zgodności z FIPS lub akceleracji sprzętowej.