🔐

Node.jsの--openssl-legacy-providerの役割とNode.jsとOpenSSLの関係について

2025/01/29に公開

背景

Node.jsの使用時に “Error: error:0308010C:digital envelope routines::unsupported” というエラーを引き起こした際、--openssl-legacy-provider オプションを渡して実行すると解決したケースがこれまでに何度かありました。

どんなものかもよく分からず使用していたので、調べたことを共有します。

--openssl-legacy-providerオプションとは

--openssl-legacy-provider は、Node.jsのOpenSSLに関連するオプションで、特にOpenSSL 3.0以降の変更に対応するために導入されました。

--openssl-legacy-provider の役割

OpenSSLの「レガシープロバイダ(legacy provider)」を有効にし、OpenSSL1.x系と互換性のある暗号アルゴリズムやAPIを使用できるようになります。

Node.jsでは17以降でOpenSSL3.0が導入され、いくつかの非推奨の暗号アルゴリズムがデフォルトで無効になりました。

これにより、古いライブラリやフレームワーク(特にWebpackなどのバンドラ)が “Error: error:0308010C:digital envelope routines::unsupported” というエラーを引き起こすことがありました。

使用時の注意点

  • --openssl-legacy-provider は 古い暗号アルゴリズムを許可する ため、セキュリティ的にリスクがある場合があります。
  • 根本的な解決策としては、依存ライブラリを最新のものに更新 し、OpenSSL 3.0 に対応したコードに移行するのが推奨されます。
  • Node.js18 以降では、Webpack 5.x などのモダンなツールチェーンが OpenSSL 3.0 に対応しているため、基本的には不要になるはずです。

そもそもOpenSSLとは

OpenSSL(オープンエスエスエル)は、インターネット上で安全な通信を実現するための 暗号ライブラリ です。TLS(Transport Layer Securityやその旧バージョンのSSL(Secure Sockets Layer)を実装しており、データの暗号化・復号、証明書の管理などを行うことができます。

OpenSSLの主な役割

  1. 通信の暗号化
    HTTPS、SSH、VPN などで使われ、データを暗号化して安全な通信を提供。
  2. データの暗号化・復号
    AES、RSA、ECDSA などの暗号アルゴリズムを使用して、データを暗号化・復号。
  3. デジタル証明書の管理
    サーバー証明書(SSL/TLS証明書)の作成、署名、検証などを行う。
  4. ハッシュ計算
    SHA-256、MD5 などのハッシュ関数を使用してデータの整合性を確認。

OpenSSLの利用例

  • Webサーバー(Apache, Nginx)
    HTTPS 通信を実現するために OpenSSL を利用。
  • プログラミング言語(Node.js, Python, PHP など)
    HTTPS リクエストや暗号化機能を実装するために内部で OpenSSL を使用。
  • VPN(OpenVPN など)
    VPN 通信の暗号化に利用。
  • SSL証明書の管理
    独自のSSL証明書を作成・管理するために利用(例:openssl req -new -x509)。

Node.jsとOpenSSLの関係

Node.jsは内部でOpenSSLを使用しており、HTTPS サーバーの実装やcryptoモジュールを通じた暗号化処理に利用されています。

参考元

Node.js 公式ドキュメント - OpenSSL サポート

https://nodejs.org/api/crypto.html
Node.jsにおけるOpenSSLの利用方法が書かれています。

Node.js v17の変更点(OpenSSL 3.0対応)

https://nodejs.org/en/blog/release/v17.0.0
Node.js17以降でOpenSSL3.0が導入されたことや影響について説明されています。

--openssl-legacy-providerオプションの説明

https://github.com/nodejs/node/issues/42351
Node.js 17 で --openssl-legacy-provider オプションが必要になった理由についての議論。

Discussion