OpenSSL API：主要な構造体と落とし穴

EVP（Envelope）APIは、暗号処理のためのOpenSSLの高レベルインターフェースであり、アプリケーションコードで使用すべき正しいAPIです。アルゴリズム固有の詳細を一貫したインターフェースの背後に抽象化し、エンジンやプロバイダーによるハードウェアアクセラレーションを自動的にサポートし、パディングやモードの詳細を正しく処理します。OpenSSLの低レベルなアルゴリズム固有APIは最新バージョンでは非推奨であり、使用すべきではありません。

OpenSSLでの対称暗号化には、EVP_CIPHER_CTXコンテキストオブジェクトを使用します。処理の流れは、EVP_CIPHER_CTX_newでコンテキストを割り当て、EVP_EncryptInit_exで暗号と鍵を使って初期化し、EVP_EncryptUpdateを繰り返し呼び出してデータを処理し、EVP_EncryptFinal_exで最後のブロックをフラッシュして残りの出力を取得し、EVP_CIPHER_CTX_freeでメモリを解放するというものです。EncryptFinal_exを省略すると出力が途中で切れるという、よくあるミスにつながります。

メッセージダイジェストの計算には、EVP_MD_CTXを同様に使用します。EVP_MD_CTX_new、アルゴリズム（EVP_sha256()、EVP_sha3_256()など）を指定するEVP_DigestInit_ex、データチャンクを渡すEVP_DigestUpdate、そしてハッシュを取得するEVP_DigestFinal_exを使用します。HMAC操作には、専用のHMAC_CTXまたは新しいEVP_MAC APIを使用します。EVPの抽象化により、関数呼び出しを1か所変更するだけでハッシュアルゴリズムを切り替えられます。

EVP_PKEYはOpenSSLにおける統一された非対称鍵オブジェクトであり、RSA、ECDSA、Ed25519、DHなどのアルゴリズムを単一のインターフェースでサポートします。鍵は、PEM_read_PrivateKeyやPEM_read_PUBKEYを使用してPEMまたはDERファイルから作成するか、EVP_PKEY_keygenで生成します。EVP_PKEY_signとEVP_PKEY_verifyを使うと、鍵の種類にかかわらず同じ関数呼び出しで署名と検証を実行できます。

BIO（Basic I/O）はOpenSSLのI/O抽象化レイヤーであり、BIOオブジェクトのチェーンを通じてTLSで保護されたデータや生データを読み書きできます。BIOチェーンは、BIO_new_connect（TCP接続）にBIO_new_ssl（TLSレイヤー）を連結した構成にできます。SSL BIOに書き込むと、データは自動的に暗号化されて送信され、読み込むと受信データが復号されます。BIOオブジェクトは、ファイル、ソケット、メモリバッファー、フィルター（base64、バッファリング）をサポートします。

OpenSSLのTLS接続では、2つのオブジェクトを使用します。SSL_CTX（コンテキスト）は、証明書、秘密鍵、CAバンドル、プロトコルバージョンの制限、暗号スイートリストといった共有設定を保持します。SSLは、コンテキストから派生する個々の接続を表します。アプリケーションごとに1つのSSL_CTXを作成し、各接続に対してそこからSSLオブジェクトを作成します。SSL_readとSSL_writeは平文を転送し、OpenSSLがTLSのフレーミングと暗号化をすべて内部で処理します。

OpenSSLで最も危険なミスは、戻り値を無視することです。EVP_EncryptFinal_ex、SSL_read、SSL_writeは、エラーを示すために負の値または0を返します。SSL_get_errorを確認せずにSSL_readをループ内で呼び出すと、無限ループが発生したり、エラーを見逃したりする可能性があります。失敗する可能性があるOpenSSLのすべての関数について、戻り値を確認する必要があります。失敗は、ハンドシェイクの失敗や証明書検証エラーなど、セキュリティに関わる状態を示していることがよくあります。

SSL_readとSSL_writeは、SSL_ERROR_WANT_READまたはSSL_ERROR_WANT_WRITEを返すことがあります。これは、I/Oを待機した後に操作を再試行する必要があることを示します。これらは本当のエラーではなく、ノンブロッキングI/Oに関する通知です。SSL_get_errorを呼び出さず、want-read/want-writeに応じて正しく分岐しないコードは、ビジーループを発生させたり、これらの状態を誤ってエラーとして扱ったりします。TLSのI/O操作で負の戻り値を解釈する際は、必ずSSL_get_errorを使用してください。

OpenSSLには、 新しいコードで使用すべきではない非推奨の低レベル関数が多数あります。たとえば、DES_encrypt1の直接呼び出し、EVPレイヤーを介さないSHA1またはMD5ハッシュ関数の直接使用、EVP_PKEY_signの代わりにRSA_private_encryptを使用すること、AES_encrypt（認証なしのAES ECB）などです。これらのAPIはセキュリティチェックを回避したり、非推奨のアルゴリズムを使用したり、単にEVP版より安全性が低かったりします。コンパイラーの警告で、非推奨APIの使用が指摘されることもよくあります。

OpenSSLでは明示的なメモリ管理を行うため、割り当てたすべてのオブジェクトを明示的に解放する必要があります。よくあるメモリリークには、暗号化後にEVP_CIPHER_CTX_freeを呼び出し忘れること、接続を閉じた後にSSL_freeを呼び出さないこと、証明書検証後にX509_freeを呼び出さないことなどがあります。長時間稼働するサーバーでは、こうしたリークによってメモリが徐々に枯渇します。開発中は、valgrindやAddressSanitizerなどのツールを使ってOpenSSLのメモリリークを検出してください。

OpenSSL 3.0では、ハードウェアアクセラレーション用の従来のENGINE APIに代わってプロバイダーモデルが導入されました。プロバイダーは暗号アルゴリズムを実装するロード可能なモジュールです。デフォルトプロバイダー（ソフトウェア）、レガシープロバイダー（古いアルゴリズム）、FIPSプロバイダー（FIPS 140-2検証済み）、HSM向けのサードパーティープロバイダーなどがあります。FIPSプロバイダーを使用すると、アプリケーションコードを変更せずに、利用可能なアルゴリズムをFIPS 140-2で承認されたものに制限して、規格に準拠した運用を実現できます。

OpenSSLのEVP APIが、アルゴリズム固有の低レベルAPIよりも推奨されるのはなぜでしょうか。

OpenSSL APIのまとめ：常にEVP高レベルAPIを使用し、対称暗号操作にはEVP_CIPHER_CTX、ハッシュ化にはEVP_MD_CTX、非対称鍵にはEVP_PKEYを使用します。I/Oの抽象化にはBIOチェーン、TLS接続にはSSL_CTXとSSLを使用し、必ず戻り値を確認してSSL_get_errorを呼び出してください。メモリリークを防ぐために、割り当てたすべてのオブジェクトを解放し、非推奨の低レベル関数は避けます。FIPS準拠やハードウェアアクセラレーションには、OpenSSL 3.0のプロバイダーを使用してください。