Wiki

TLS フィンガープリント

サーバーはインストール時に自己署名証明書を生成します。各クライアントは初回接続時にフィンガープリントを確認します。

安全ですか？ はい。すべての接続とすべてのファイル転送は暗号化されています。ネットワーク上の誰も、あなたの端末とサーバーの間を流れる内容を読み取ることはできません。データはあなた自身のインフラ内にとどまります。第三者にホストされることも、uVersion を経由することもありません。アクセスできるのは、それぞれの認証情報を持つあなたのチームのメンバーだけです。そして接続に異常があれば、ソフトウェアがそれを検知して直ちにブロックし、黙って通過させることはありません。

uVersion はデフォルトですべての接続を HTTPS で暗号化します。ドメイン名も購入した証明書も必要ありません。サーバーは初回起動時に証明書を生成し、管理者がそのフィンガープリントをチームに共有し、各端末が一度だけ確認します。これは TOFU モデルです。最初の接触時に信頼するという方式で、SSH が初回にマシンのフィンガープリントを確認させるのとまったく同じです。以降、クライアントは接続のたびにそれを照合し、変わってしまったサーバーとの通信を拒否します。

サーバーのフィンガープリント、それともチェックサム？ どちらも SHA-256 であり、それがみんなを混乱させます。サーバーのフィンガープリントはあなたのサーバーの証明書を識別します。端末が接続する先のマシンを見分けるためのものです。チェックサムはダウンロードしたファイルが壊れていないかを確認します。このページで扱うのは前者だけです。

手順は二段階です。サーバー上でフィンガープリントを一度見つけ、次に各端末でそれを確認する、端末ごとに一度ずつ。このページの残りは参考資料で、何かが変わった日に読むためのものです。

フィンガープリントを確認する

インストールの最後に、管理者パスワードの隣に表示されます。その後は、最も簡単なものから最も手作業なものまで、三つの確認方法があります。

1. ブラウザーから、何もインストールせずに

サーバーは認証なしの情報ページを公開しています。https://サーバー:8443/api/server-info を開いてください。sudo も、SSH アクセスも、uVersion アカウントも不要で、これがもっとも手早い方法です。

ブラウザーはまずセキュリティ警告を表示します。これは正常で想定どおりです。証明書は自己署名であり、公的な認証局はそれを知りません。サイトへ進んでください。

サーバーのアドレスを初めて開いたときのブラウザーのセキュリティ警告。自己署名証明書にもかかわらず続行できるリンクまたはボタンが表示されている。

続いて表示されるページは生のデータの塊です。フィンガープリントは tls_fingerprint フィールドの値で、コロンで区切られた 16 進のバイト列です。この文字列全体を、そのままチームに伝えます。

ブラウザーで開いた /api/server-info ページ。version、build_sha、self_signed に設定された tls_mode、そしてコロンで区切られた 16 進の SHA-256 フィンガープリントを持つ tls_fingerprint の各フィールド。

このページはサーバーが申告した内容を示します あなたが管理者なのですから、チームにフィンガープリントを公開するには最適です。ただしそれ自体は検証にはなりません。接続を傍受する者は自分の値を返すからです。守ってくれるのは、サーバーが実際に提示したフィンガープリントと、あなたが別の経路（社内チャット、口頭、チームの wiki）で伝えた値とを、各端末が照合することです。コマンドラインクライアントは実際その両方を行い、両者が食い違うときに警告します。

2. サーバーのログから

サーバーは起動のたびにフィンガープリントをログに書き出します。この方法は、データディレクトリをどこに置いていても機能します。

# Linux (paquet .deb)
sudo journalctl -u uversion-server | grep "TLS fingerprint" | tail -1

# Docker
docker compose logs server | grep "TLS fingerprint" | tail -1

3. `fingerprint` ファイルの中

このファイルは証明書の隣に書き込まれます。つまり config.toml に記載された [tls] cert_path のディレクトリです。以下のパスは既定値です。データディレクトリを移動している場合は、まず設定の cert_path を確認してください。

# Linux, dossier de donnees par defaut
sudo cat /var/lib/uversion/data/tls/fingerprint

# Windows
Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"

# Docker : chemin fixe par l'entrypoint, sur le volume de donnees
docker compose exec server cat /data/tls/fingerprint

クライアント側で確認する

端末ごとに一度、そして一度きりです。手順はツールによって異なります。

デスクトップクライアント

ログイン画面を通常どおり入力します。このサーバーへの初回接続では、ログインする代わりに Verify server identity というウィンドウが開きます。表示されたフィンガープリントを管理者が共有したものと照合し、一致していれば Trust this server をクリックします。接続はそのまま自動的に再開します。食い違っていれば Cancel を押し、その理由を確認しに行ってください。

CLI `uversion`

uversion trust https://uversion.example.com:8443          # interactif
uversion trust https://uversion.example.com:8443 --yes    # sans question (CI, script)
uversion trusted                                          # liste les serveurs epingles
uversion login <url>                                      # propose l'epinglage si besoin

uversion trust は対話式です。ホスト、サーバーのバージョン、TLS モード、フィンガープリントを表示し、管理者が伝えた内容と照合するよう促し、そのうえで y/N の確認を待ちます。それ以外の応答は、何も固定せずに中止します。--yes オプションはこの質問を省きます。スクリプトや継続的インテグレーション向けで、誰も見ないまま固定するため、自分が管理する信頼できるネットワークに限って使ってください。

uversion login は、サーバーがまだ固定されていないときに同じ確認を自動的に提示します。端末では、通常その前に実行しておくものは何もありません。

Unreal Engine プラグイン

プロジェクトを開く前に、ターミナルで uversion trust <url> を一度実行するか、先にデスクトップクライアントから接続してください。プラグインはその固定（ピン留め）に従います。エディター内のネイティブなダイアログは今後対応予定です。

Rider プラグイン

内部で uversion を使用します。uversion trust <url> を一度実行すれば、Rider は通ります。

フィンガープリントが変わった場合

クライアントは接続を拒否し、それをはっきりと知らせます。反射的に再確認しないでください。まず管理者に、問題となっている接続とは別の経路で確認してください。考えられる説明は三つあります。サーバーの再インストール、意図的な証明書のローテーション、または端末とサーバーの間に割り込んだ何者か。説明が得られたら次のようにします。

デスクトップクライアント：警告ダイアログの Trust new fingerprint ボタン。
CLI：uversion mistrust <url> の後に uversion login <url>。

証明書を再生成する

証明書はデフォルトで 10 年間有効で、更新の予定は必要ありません。ローテーションを強制するには（侵害の疑い、監査要件など）：

# Linux
sudo rm /var/lib/uversion/data/tls/cert.pem /var/lib/uversion/data/tls/key.pem
sudo systemctl restart uversion-server

# Windows
Remove-Item "C:\ProgramData\uVersion\data\tls\cert.pem"
Remove-Item "C:\ProgramData\uVersion\data\tls\key.pem"
Restart-Service uVersionServer

サーバーは起動時に証明書と新しいフィンガープリントを再生成します。チームに知らせて、それを再共有してください。各端末は再確認が必要になります。

独自の証明書を用意する

社内の PKI や公的な認証局が発行した、独自の証明書を配置できます。有効にするオプションはありません。起動時に、サーバーは [tls] cert_path と [tls] key_path のパスに存在するファイルを再利用し、フィンガープリントを再計算します。これはサーバーが DNS 名を持っている場合にのみ有効です。プライベート IP アドレスに対して証明書を発行する認証局はありません。

形式に関する三つの制約。いずれも、すでに誰かの一晩を費やさせたものです。

証明書ファイルには完全なチェーンを、リーフ（末端の証明書）を先頭にして含めます（certbot の fullchain.pem がまさにこの形です）。
秘密鍵は暗号化されていない PEM です。パスフレーズで保護された鍵は復号されません。
再起動する前に両方のファイルを配置してください。片方しか見つからないと、サーバーは状態が不完全だとみなし、残っていた方の上に自己署名のペアを再生成します。

これが端末にもたらす変化：

ブラウザー：証明書が持つ名前でサーバーを開くかぎり、警告は出なくなります。IP アドレスで開くと、警告は残ります。
すでに固定済みの端末：フィンガープリントが変わるため、各端末は上で述べた警告を目にし、再確認が必要になります。入れ替えの前に知らせてください。さもないとチーム全員が同時に傍受のメッセージに遭遇します。
更新：更新のたびにフィンガープリントが変わり、この儀式がやり直しになります。しかも証明書はサーバーの起動時にしか読み直されません。90 日の公的証明書だと、年に六回のチーム全体での再確認になります。このコストが解消されるまでは、長い有効期間を選んでください。