cURL とクライアント証明書による安全なファイルアップロード
クライアント証明書を要求する HTTPS エンドポイントにファイルをアップロードするには、同じ cURL コマンドで --upload-file、--cert、--key を組み合わせます。この手順では、ローカルの相互 TLS(mTLS)サーバーと一時的な証明書を用意し、アップロードしたファイルをバイト単位で照合します。
サーバーの信頼性確認とクライアント認証の違い
HTTPS は接続を暗号化し、cURL がサーバーの身元を検証できるようにします。mTLS では、クライアントが信頼された証明書の秘密鍵を保持している証明もサーバーが要求します。これらの検証は、互いに逆の方向で行われます。
| cURL オプション | この例での用途 |
|---|---|
--cacert ca.crt | サーバー証明書を発行した CA を信頼します。URL のホスト名も引き続き検証します。 |
--cert client.crt | クライアントの公開証明書をサーバーに提示します。 |
--key client.key | 対応する秘密鍵を保持していることを証明します。 |
クライアント証明書があっても、信頼できないサーバーが信頼できるようにはなりません。cURL のサーバー検証は有効にしておいてください。--insecure を指定すると、この検証を回避してしまいます。以下の一時的な CA は、システムの信頼ストアを変更せず、これらのコマンドと受信サーバーだけで信頼します。
ローカルツールの準備
前提条件
Bash、OpenSSL を使用してビルドした cURL、OpenSSL 3、Python 3、cmp がある Linux シェルを使用します。Python パッケージは不要です。インストール済みのツールを確認します。
curl --version
openssl version
python3 --version
この cURL コマンドでは、cURL 7.76.0 以降で利用できる
--fail-with-body を使用します。後述のテスト済みの組み合わせを参照してください。この手順では、Windows の証明書ストアや他の TLS バックエンドでの動作は確認していません。
一時的な証明書の作成
mtls-demo を作成できるディレクトリから実行してください。サブシェルはエラー時に停止し、既存のディレクトリの再利用を拒否します。実行後も、ターミナルの作業ディレクトリは親ディレクトリのままです。すべての鍵と証明書は mtls-demo 内に保存され、証明書は二日後に有効期限が切れます。
(
set -eu
umask 077
mkdir mtls-demo
cd mtls-demo
openssl req -x509 -newkey rsa:2048 -noenc -sha256 -days 2 \
-keyout ca.key -out ca.crt -subj '/CN=Local upload demo CA' \
-addext 'basicConstraints=critical,CA:TRUE' \
-addext 'keyUsage=critical,keyCertSign,cRLSign'
openssl req -new -newkey rsa:2048 -noenc \
-keyout server.key -out server.csr -subj '/CN=localhost'
printf '%s\n' 'basicConstraints=critical,CA:FALSE' \
'keyUsage=critical,digitalSignature,keyEncipherment' \
'extendedKeyUsage=serverAuth' 'subjectAltName=DNS:localhost' > server.ext
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
-set_serial 1 -days 2 -sha256 -extfile server.ext -out server.crt
openssl req -new -newkey rsa:2048 -noenc \
-keyout client.key -out client.csr -subj '/CN=Local upload client'
printf '%s\n' 'basicConstraints=critical,CA:FALSE' \
'keyUsage=critical,digitalSignature' 'extendedKeyUsage=clientAuth' > client.ext
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
-set_serial 2 -days 2 -sha256 -extfile client.ext -out client.crt
)
証明書拡張により、サーバーとクライアントに別々の役割を割り当てます。サーバーのサブジェクト代替名は localhost で、アップロード URL のホスト名と一致する必要があります。OpenSSL のドキュメントでは、これらの証明書拡張と、使い捨ての鍵を暗号化せずに保存する
-noenc オプションを説明しています。umask 077 は、新しいディレクトリとファイルへのアクセスを実行アカウントだけに制限します。
クライアント証明書を要求する受信サーバーの起動
以下を mtls-demo/receiver.py として保存します。このサーバーは、Content-Length が既知の生の
PUT /upload を、空の本文も含めて最大 1 MiB まで受け付けます。アップロードが完了するたびに received.bin を置き換えます。リクエストを拒否した場合、以前のファイルはそのまま残ります。
import argparse
import ssl
from http.server import BaseHTTPRequestHandler, HTTPServer
from pathlib import Path
class UploadHandler(BaseHTTPRequestHandler):
def do_PUT(self):
if self.path != "/upload":
self.send_error(404, "Use /upload")
return
length = self.headers.get("Content-Length", "")
if self.headers.get("Transfer-Encoding") or not length.isascii() or not length.isdecimal():
self.send_error(411, "A Content-Length is required")
return
size = int(length)
if size > 1024 * 1024:
self.send_error(413, "Limit is 1 MiB")
return
self.connection.settimeout(10)
data = self.rfile.read(size)
if len(data) != size:
self.send_error(400, "Incomplete upload")
return
Path("received.bin").write_bytes(data)
reply = f"Stored {len(data)} bytes\n".encode()
self.send_response(201)
self.send_header("Content-Type", "text/plain; charset=utf-8")
self.send_header("Content-Length", str(len(reply)))
self.end_headers()
self.wfile.write(reply)
parser = argparse.ArgumentParser()
parser.add_argument("--port", type=int, default=0)
args = parser.parse_args()
context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.minimum_version = ssl.TLSVersion.TLSv1_2
context.load_cert_chain("server.crt", "server.key")
context.load_verify_locations("ca.crt")
context.verify_mode = ssl.CERT_REQUIRED
with HTTPServer(("127.0.0.1", args.port), UploadHandler) as server:
server.socket = context.wrap_socket(server.socket, server_side=True)
print(f"https://localhost:{server.server_port}/upload", flush=True)
server.serve_forever()
Python の CERT_REQUIRED は、信頼された CA が発行した有効な証明書を持たないクライアントを拒否します。このデモでは、用意した CA の有効なクライアント証明書があれば、どれでもアップロードできます。実際のサービスには、独自の認可ポリシーも必要です。
親ディレクトリから受信サーバーを起動し、そのまま実行しておきます。
(cd mtls-demo && python3 receiver.py)
IPv4 ループバックだけにバインドし、利用可能なポートを含むアップロード URL を出力します。次の手順に備えて、その URL をコピーしてください。証明書がない場合やバインドエラーが発生した場合は、URL を出力する前に起動を停止します。これはローカルで学習するためのサーバーです。Python の
http.server は本番環境向けではありません。
ファイルのアップロードと照合
別のターミナルで同じ親ディレクトリを開き、小さなファイルを作成します。このコマンドは、デモ用ディレクトリに既存の payload.txt があれば置き換えます。
(cd mtls-demo && printf 'mTLS upload\n' > payload.txt)
以下のブロックの PORT を、受信サーバーが出力したポートに置き換えます。親ディレクトリから実行してください。
(
set -eu
cd mtls-demo
upload_url='https://localhost:PORT/upload'
status=$(curl --disable --silent --show-error --fail-with-body \
--noproxy '*' --connect-timeout 5 --max-time 20 \
--cacert ca.crt --cert client.crt --key client.key \
--upload-file payload.txt --output response.txt --write-out '%{http_code}' \
"$upload_url")
cat response.txt
printf 'HTTP %s\n' "$status"
test "$status" = 201
cmp payload.txt received.bin
)
想定される出力:
Stored 12 bytes
HTTP 201
cmp は、送信元と受信したバイト列が一致すると何も出力しません。このエンドポイントでは、HTTP 201 は受信サーバーがファイルを書き込んだことを意味します。セキュリティスキャン、バックアップ、永続的な保存は保証しません。受信サーバーを停止しても、ファイルはディスク上に残ります。
--upload-file は、ファイルをリクエスト本文とする
HTTP PUT を選択します。マルチパート POST を想定する API には別のリクエスト形式が必要です。このコマンドを応用する前に、エンドポイントのメソッドと本文の仕様を確認してください。
--fail-with-body を指定すると、HTTP エラー時に
cURL が終了コード 22 を返し、レスポンス本文を
response.txt に保存します。サブシェルはこの失敗で停止します。明示的な 201 のチェックでも、想定外の成功やリダイレクトのステータスを拒否します。レスポンスを受信すると response.txt を上書きしますが、初期段階の TLS の失敗では、古いレスポンスファイルが残ることがあります。そのファイルだけを成功の証拠にしないでください。--disable はデフォルトの cURL 設定を読み込まず、--noproxy '*' は、このループバックリクエストが環境設定のプロキシを経由しないようにします。
よくある問題のトラブルシューティング
保存されたレスポンスを調べる前に、cURL のエラーを読んでください。サブシェルの終了ステータスを確認するには、アップロード用ブロックの直後に
echo "$?" を実行します。以下は一つずつ試し、試行の間には成功したコマンドの状態に戻してください。
証明書の検証失敗
URL のホスト名を localhost から 127.0.0.1 に変更すると、cURL エラー 60 が発生するはずです。証明書に指定されているのは localhost であり、IP アドレスではないためです。--cacert に無関係な CA を指定した場合も検証に失敗します。サーバー運用者の信頼できる CA と、証明書の対象となるホスト名を使用してください。どちらの失敗も、検証を無効にして解決しないでください。
クライアント証明書のエラー
--cert client.crt --key client.key を削除すると、アップロードハンドラーが実行される前に
TLS ハンドシェイクが失敗するはずです。信頼されていないクライアント証明書も失敗します。ハンドシェイクが拒否されたときの cURL の正確なコードは、TLS のバージョンやバックエンドによって異なる場合があります。これは HTTP による拒否とは異なります。ビルドによっては、証明書固有のメッセージではなく、送信エラーや受信エラーを報告します。
一方、エラー 58 は、ローカルのクライアント認証情報の読み込みや使用に問題があることを示します。証明書が PEM 形式であること、秘密鍵が証明書と一致すること、実行アカウントで両方のファイルを読み取れることを確認してください。TLS バックエンドに適した証明書オプションを使用します。cURL 8.22.0 では、鍵ファイルがない場合、より早い段階でコード
43 とファイル読み込みの診断メッセージを返して拒否します。
HTTP による拒否
有効な証明書を維持したまま、/upload を
/missing に変更します。TLS は成功しますが、サーバーは HTTP 404 を返し、cURL は 22 で終了します。1 MiB を超えるファイルは HTTP 413 で拒否されます。どちらの場合も received.bin は置き換えられません。これらの HTTP エラーでは、mtls-demo/response.txt の現在のレスポンス本文を確認してください。証明書を変更しても、間違ったパスやサイズ超過のファイルは修正できません。
セキュリティのベストプラクティス
ca.key、server.key、client.key は、鍵を含む結合 PEM ファイルも含め、非公開にしてください。コミットしたり、デモ用ディレクトリをアップロードしたりしないでください。完了したら Ctrl+C で受信サーバーを停止し、残したいものがないことを確認してから、使い捨てのディレクトリを削除します。
証明書のパスフレーズの扱い
このデモの鍵は、ローカルの演習を入力プロンプトなしで実行できるよう、暗号化していません。暗号化した PEM 鍵と OpenSSL バックエンドを使う場合、cURL はパスフレーズの入力を求められます。パスフレーズを --cert に追加したり、コマンドライン引数として渡したりしないでください。シェルの履歴やプロセスの引数から漏れるおそれがあります。無人実行のジョブには、シークレットマネージャーやアクセスを制限した認証情報ファイルなど、サービスアカウントだけがアクセスできる、別のシークレット受け渡しの仕組みが必要です。
バージョンの互換性
このローカル手順全体を、Linux 上で以下の組み合わせを使用して実行しました。
| 環境 | cURL と TLS バックエンド | OpenSSL CLI | Python |
|---|---|---|---|
| Ubuntu 24.04 コンテナ | cURL 8.5.0, OpenSSL 3.0.13 | 3.0.13 | 3.12.3 |
| Arch ベースのホスト | cURL 8.22.0, OpenSSL 3.6.4 | 3.6.4 | 3.14.7 |
これらの確認は、ローカルの受信サーバーでのファイルのバイト列と失敗時の動作を対象としています。Windows、macOS、他の TLS バックエンド、本番環境のアップロードサービスは、それぞれ検証が必要です。
