事象

PythonがリンクするOpenSSLのバージョンによっては、ノードが正常に稼働しているにもかかわらず health コマンドが失敗する。

今回確認した環境では、Ubuntu 24標準のPythonはOpenSSL 3.0系とリンクしていた。
一方、uvで作成した仮想環境ではOpenSSL 3.5系とリンクしたPythonが入り、この事象が発生した。

PythonがリンクするOpenSSLのバージョンを調べるコマンドは以下。

python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"

再現

Python + OpenSSL3.0系

Ubuntu標準のPythonで仮想環境を作成

mkdir shoestring-openssl30
cd shoestring-openssl30
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install symbol-shoestring

バージョンの確認

$ python3 --version
Python 3.12.3

$ python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
OpenSSL 3.0.13 30 Jan 2024

shoestringのウィザードを使用して、Symbol Dualノードの環境を作成。

LC_MESSAGES=ja python3 -m shoestring.wizard

ノードを起動後、health コマンドを実行する。

docker compose up -d
LC_MESSAGES=ja python3 -m shoestring health --config shoestring/shoestring.ini --directory .

問題なくhealthコマンドが動作する。

$ LC_MESSAGES=ja python3 -m shoestring health --config shoestring/shoestring.ini --directory .
     ...    | モジュール peer certificate のヘルスエージェントを実行
      i     | ca 証明書の有効期限にはまだ余裕があります (7299 日間)
      i     | node 証明書の有効期限にはまだ余裕があります (374 日間)
keys/cert/ca.crt.pem: OK
keys/cert/node.crt.pem: OK
     ...    | モジュール peer API のヘルスエージェントを実行
      i     | ピアAPIにアクセス可能、ブロック高 = 1801
     ...    | モジュール REST API のヘルスエージェントを実行
      i     | REST APIにアクセス可能、ブロック高 = 1801
     ...    | モジュール REST websockets のヘルスエージェントを実行
      i     | エンドポイント ws://r.nemnesia.com:3000/ws にWebSocket接続中、ブロックを待機して購読中
      i     | WebSocketがブロックを受信しました。ブロック高 1802

Python + OpenSSL3.5系

uvでPython仮想環境を作成

mkdir shoestring-openssl35
cd shoestring-openssl35
uv venv --python 3.12
source .venv/bin/activate
uv pip install pip
pip install symbol-shoestring

バージョンの確認

$ python3 --version
Python 3.12.12

$ python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
OpenSSL 3.5.5 27 Jan 2026

shoestringのウィザードを使用して、Symbol Dualノードの環境を作成。

LC_MESSAGES=ja python3 -m shoestring.wizard

ノードを起動後、health コマンドを実行する。

docker compose up -d
LC_MESSAGES=ja python3 -m shoestring health --config shoestring/shoestring.ini --directory .

healthコマンドが失敗する。

$ LC_MESSAGES=ja python3 -m shoestring health --config shoestring/shoestring.ini --directory .
     ...    | モジュール peer certificate のヘルスエージェントを実行
      i     | ca 証明書の有効期限にはまだ余裕があります (7299 日間)
      i     | node 証明書の有効期限にはまだ余裕があります (374 日間)
keys/cert/ca.crt.pem: OK
keys/cert/node.crt.pem: OK
     ...    | モジュール peer API のヘルスエージェントを実行
    [!!!]   | ポート 7900 の localhost でピアAPIにアクセスできません
     ...    | モジュール REST API のヘルスエージェントを実行
      i     | REST APIにアクセス可能、ブロック高 = 181
     ...    | モジュール REST websockets のヘルスエージェントを実行
      i     | エンドポイント ws://r.nemnesia.com:3000/ws にWebSocket接続中、ブロックを待機して購読中
      i     | WebSocketがブロックを受信しました。ブロック高 200

原因

今回の不具合は、shoestring本体というより、内部で使用しているlightapiのSSL/TLSハンドシェイク処理にあると考えられる。

lightapiでは、ssl.SSLContext の内部表現から SSL_CTX * を固定オフセットで取り出し、SSL_CTX_set_verify を呼び出している。つまり、Pythonオブジェクトのメモリ配置に依存したABI前提の実装になっている。

lightapi/python/symbollightapi/connector/SymbolPeerConnector.py

  # get python wrapper object address (SSL_CTX* is offset 16 bytes)
  ssl_context_object_address = id(self.ssl_context)
  ssl_context_raw_address = ctypes.cast(ssl_context_object_address, ctypes.POINTER(ctypes.c_uint64))[2]
  ssl_context_pointer = ffi.cast('SSL_CTX *', ssl_context_raw_address)

  self._verify_callback_wrapper = ffi.callback('int (*)(int, X509_STORE_CTX *)', self._verify_callback)
  lib.SSL_CTX_set_verify(
   ssl_context_pointer,
   lib.SSL_VERIFY_PEER | lib.SSL_VERIFY_FAIL_IF_NO_PEER_CERT,
   self._verify_callback_wrapper)

この方法は、Python側の内部表現やリンク先のOpenSSLが変わると崩れる可能性がある。実際に今回の再現では、OpenSSL 3.0系とリンクしたPythonでは正常に動作し、OpenSSL 3.5系とリンクしたPythonではpeer APIの接続だけが失敗した。

そのため、原因は「OpenSSL 3.5そのものが悪い」というより、lightapiが前提にしているABIと、OpenSSL 3.5系をリンクしたPython実行環境のABIが一致せず、SSL_CTX_set_verify 周辺でハンドシェイクに失敗したことにある可能性が高い。

対応案

暫定対応（運用回避）

OpenSSL 3.0系とリンクしたPythonを使用する。

今回の再現環境では、Ubuntu 24標準Python（OpenSSL 3.0系）では health が成功したため、修正が入るまでの回避策としては有効。

ただし、この方法は実行環境をOpenSSL 3.0系に寄せる前提が必要であり、OpenSSL 3.5系を含む環境を同時に安定運用する解決にはならない。

恒久対応（推奨）

根本対応としては、lightapiのABI依存実装をやめる方向が望ましい。

具体的には次の2案がある。

OpenSSL 3.5向けにABIを作り直す
そもそもABIを使用しない

暫定対応では吸収しきれないため、実質的には恒久対応が必要になる。

保守性と再発防止の観点では、2の「ABIを使用しない」方針を推奨する。