ObjectDeliverer データ形式と運用

このページでは、送受信データの形式、TLS/mTLSの設定、プラットフォームごとの注意点、トラブル発生時の確認項目を説明します。

データ形式とシリアライズ

StartでDeliveryBoxを指定しない場合、送受信はバイト配列（TArray<uint8>）で行われます。DeliveryBoxを指定すると、送受信のたびに次の形式へ自動変換されます。

DeliveryBox送受信するデータBlueprintでの扱い
なし（既定）バイト配列SendのData Buffer、ReceiveDataのBuffer
Utf8StringDeliveryBoxUTF-8文字列Sendに FString を渡し、Receivedで FString を受け取る
ObjectDeliveryBoxUsingJsonJSON文字列Sendに UObject を渡し、Receivedで UObject を受け取る

ObjectDeliveryBoxUsingJsonの2つの形式

JSONへのシリアライズ形式はEODJsonSerializeTypeで切り替えます。

NoWriteType（既定のCreate Object Delivery Box Using Json） — クラス名を含まない形式です。

{
  "Prop": 1
}

WriteType（Create Dynamic Object Delivery Box Using Json） — クラス名を含む形式です。

{
  "Type": "SampleClassName",
  "Body": {
    "Prop": 1
  }
}

NoWriteTypeは1つのDeliveryBoxで扱えるクラスが1種類になります。WriteTypeはJSONにクラス名が保存されるため、1つのDeliveryBoxで複数のクラスを送受信でき、基底クラスのプロパティとして保持したオブジェクトでも情報が失われません。その代わり、クラス名の分だけデータサイズが増えます。

クラスごとに形式を混在させるCreate Custom Object Delivery Box Using Jsonも用意されています。詳細はFAQ: ObjectDeliveryBoxUsingJsonの利用方法を参照してください。

TLSとmTLS

TCP/IP TLS（v1.9.0以降）を使用すると、通信内容の暗号化と証明書ベースの認証が行えます。プラグインにはTLS処理に必要なライブラリが含まれており、追加のセットアップは不要です。

最小バージョンの指定

Minimum ProtocolはTLSの最小バージョンを指定します（TLS 1.2を指定すると1.2以上を許可）。TLS 1.1とTLS 1.0は非推奨の値です。通常は既定値のTLS 1.2を使用してください。

クライアント側の証明書検証

Create Protocol Tcp Ip Client Tlsの戻り値に対して、With系ノードで検証方法を指定します。代表例は次のとおりです。

構成使用するノード
標準の検証（公開CAの証明書）With Certificate Verification
プライベートCA・自己署名のルートを使うWith Trusted Ca Certificate（＋必要に応じてWith Allow Self Signed Certificates）
公開鍵ピンニングWith Pinned Public KeyまたはWith Pinned Public Key From File
mTLS（クライアント認証）With Client Certificate

構成ごとの選び方はFAQ: ユースケース別TLSオプション構成にまとめています。

mTLS（相互認証）

サーバー側でWith Client Auth ModeをRequiredにすると、クライアント証明書の提示を必須にできます（Optionalは提示があれば検証、Noneは要求しない）。検証にはWith Client Ca Bundleで指定したCAバンドルが使用されます。クライアント側はWith Client Certificateで証明書と秘密鍵を指定します。

mTLSとTLSの違いについてはFAQ: TLSとmTLSの違いも参照してください。

接続失敗の理由を確認する

TLS接続が失敗したときは、クライアントのGet Last Tls Errorで理由を文字列で取得できます。ハンドシェイク失敗（信頼できないCAが署名した証明書チェーンなど）、証明書やCAの設定不備、ハンドシェイク直後の切断が対象です。接続が確立した時点でクリアされます。

Peer Verification Disabledを指定するとサーバー証明書の検証自体が行われなくなります。通信の暗号化はされますが、なりすましを検出できなくなるため、通常は使用しないでください（FAQ: 検証無効化の安全性）。

ホスト名・IPアドレスと証明書の不一致で失敗するケースはFAQ: TLSが失敗する理由を参照してください。

証明書の作成

OpenSSLコマンドで証明書を手動作成する手順はFAQ: OpenSSLで証明書を作成するに、自己署名証明書の設定はFAQ: 自己署名証明書のTLS構成にまとめています。

C++では、開発・テスト用に自己署名証明書やCA証明書を生成するUObjectDelivererCertificateGeneratorも利用できます（Blueprint非公開）。

ObjectDelivererのTLSクライアントと通信できるTLSサーバーのサンプルは、GitHubのAyumaxSoft/TLSServerSampleで公開しています。

証明書の信頼ポリシー（v1.9.1以降）

v1.9.1から、TLS接続時の証明書検証に、プラグイン組み込みの「信頼できないCAリスト」が常に適用されます。

  • 2026年10月に秘密鍵が漏洩したeMudhraの中間CA 8件と、その署名元ルート3件が発行した証明書チェーンを拒否します。OSやエンジンの信頼ストアがそれらを信頼している状態でも拒否します。
  • クライアント側のサーバー証明書検証と、サーバー側のクライアント証明書検証（mTLS）の両方に適用されます。
  • 証明書チェーンを検査できない場合は接続を拒否します（fail-closed）。
  • 接続失敗の理由はクライアントのGet Last Tls Error（Blueprintから利用可能）で確認できます。
  • 独自に信頼できないCAを追加したい場合（インシデント対応など）は、C++ API（FObjectDelivererTlsTrustPolicy）で登録できます。追加の登録はプロセス内でのみ有効です。
  • Peer Verification Disabledを指定した場合、証明書検証自体が行われないため、このリストも適用されません（非推奨設定）。

バッファサイズ

Protocolごとに受信・送信バッファサイズをWith Receive Buffer Size・With Send Buffer Sizeで指定できます。既定値は1MBです。大量データを一度に送受信する場合に調整してください。

プラットフォームの注意点

項目内容
共有メモリWindowsでのみ使用できます。ほかのプラットフォームでは使用できません
TLSの暗号化Windows、Mac、Linux、iOS、Androidで使用できます。必要なライブラリはプラグインに含まれています
iOSでのwss接続iOSではエンジンがiOSのシステム証明書ストアを読み込まないため、プロジェクト側にCAバンドル（Content/Certificates/cacert.pem）を配置し、パッケージ設定のDirectoriesToAlwaysStageAsUFSでCertificatesをステージングする必要があります
Androidの証明書Androidではエンジンがシステムの証明書ストアを追加で読み込むため、一般的な公開CAの証明書はそのまま検証できます

iOSのwssにおけるCAバンドル配置の経緯と詳細な手順は、プラグインの検証記録（Docs/iOS_WebSocket_wss_CA_Bundle_Notes.md、ObjectDelivererV2リポジトリ）に基づいています。

トラブルシューティング

症状確認する項目関連情報
通信がまったく成立しない両者のプロトコル種別・アドレス・ポートが一致しているか。ファイアウォールの設定クイックスタートのエラー時の確認
受信データが欠ける・壊れるパケット分割ルールが両者で一致しているか（SizeBodyならSize LengthとEndianも）。TCP/IPでNodivisionを使っていないかパケット分割ルールを切り替える
UDPで届かないことがあるUDPの仕様上、パケットロスが起き得ます。再送が必要ならTCP/IPを使用してくださいFAQ: パケットが届かない場合
共有メモリ・ファイルで値がスキップされる受信側がポーリング方式のため、上書きが速いと間引きが起きます。書き込み間隔を確認してくださいFAQ: 共有メモリ通信が動かない場合
TLS接続が失敗するGet Last Tls Errorの内容。証明書のパス・期限・ホスト名一致・検証オプションの組み合わせFAQ: TLSオプション構成
iOSのwssで接続エラーになるプロジェクトにCAバンドルが配置・ステージングされているかこのページの「iOSでのwss接続」
送信したのにRecipientが受け取らないDeliveryBox使用時はSendはDeliveryBox経由。ObjectDelivererManager.Sendを使っていないかDeliveryBoxを切り替える

原因を切り分けるには、Blueprint APIのロギングでプラグイン内部のログを取得する方法もあります。

セキュリティチェックリスト

公開環境・製品環境で通信を使用する前に、次を確認してください。

  • 通信経路に暗号化が必要な場合、TLS（またはwss）を使用している
  • Peer Verification Disabledを指定していない
  • TLSの最小バージョンとしてTLS 1.2以上を指定している
  • 本番のサーバー証明書として、開発・テスト用の自己署名証明書を使い残していない
  • 証明書や秘密鍵のファイルをスクリーンショット・ログ・リポジトリに含めていない
  • ポート番号・共有メモリ名などが、意図しない他プロセスと衝突していない