署名付き URL

署名付き URL は、呼び出し元がアカウントで認証することなく、保護されたリソースへの時間制限付きのリソーススコープアクセスを提供します。このパターンはファイルダウンロード、事前署名付きアップロードスロット、第三者と一時的なアクセスを共有する必要があるあらゆるケースで使用されます。

中核概念

署名付き URL にはアクセスを認可するために必要なすべてが含まれています: リソース ID、有効期限、および URL が信頼されたサーバーによって生成されたことを証明する HMAC 署名。サーバーは検証に自身のシークレットキーだけが必要です — データベース検索は不要です。

トークンフォーマット

base64url({resource_id}|{expires_at}|{hmac-sha256(resource_id|expires_at, secret)})

HMAC は resource_id|expires_at を一緒にカバーします。どちらかの部分を変更すると署名が無効になります。これにより、トークンは正確に 1 つのリソースと 1 つの有効期限ウィンドウに束縛されます。

Signer 実装

php

final readonly class HmacSigner
{
    private const string ALGO = 'sha256';

    public function __construct(
        private string $secret,
    ) {}

    public function sign(int $resourceId, string $expiresAt): string
    {
        $payload = $resourceId . '|' . $expiresAt;
        $mac     = hash_hmac(self::ALGO, $payload, $this->secret);

        return $this->base64UrlEncode($payload . '|' . $mac);
    }

    public function verify(string $token, string $now): ?int
    {
        $decoded = $this->base64UrlDecode($token);
        if ($decoded === null) {
            return null;
        }

        $parts = explode('|', $decoded, 3);
        if (count($parts) !== 3) {
            return null;
        }

        [$resourceId, $expiresAt, $storedMac] = $parts;

        $expectedMac = hash_hmac(self::ALGO, $resourceId . '|' . $expiresAt, $this->secret);

        // hash_equals() は必須 — === を使うとタイミング情報が漏洩する
        if (!hash_equals($expectedMac, $storedMac)) {
            return null;
        }

        if ($expiresAt < $now) {
            return null;
        }

        return (int) $resourceId;
    }
}

hash_equals() は交渉の余地がありません。文字列等価比較は最初の不一致で終了し、HMAC の何文字が一致するかを漏洩します。攻撃者はこれを利用して署名をバイトごとに偽造できます。hash_equals() は常にすべての文字を比較します。

有効期限切れトークンの 410 Gone vs 401 Unauthorized

ユーザーはリンクが期限切れになった（新しいものを要求すべき）のか、リンクが一度も有効でなかったのかを知ることでメリットを得ます。Signer は最初に HMAC を検証し、次に有効期限を確認します。HTTP レスポンスでこれらを区別するには:

php

$resourceId = $this->signer->verify($token, $now);

if ($resourceId === null) {
    // HMAC 検証なしで有効期限を抽出
    $expiresAt = $this->signer->extractExpiresAt($token);
    if ($expiresAt !== null && $expiresAt < $now) {
        return $problems->create($request, 'gone', 'This link has expired.', 410, '');
    }
    return $problems->create($request, 'unauthorized', 'Invalid or expired token.', 401, '');
}

extractExpiresAt() は base64 をデコードして | で分割するだけです — HMAC を検証しません。これは安全です。なぜなら:

有効期限はシークレットではありません（署名付き URL に元々表示されています）。
攻撃者は操作された有効期限で有効なトークンを偽造できません。verify() がそれを拒否します。
410 レスポンスはトークンの偽造に役立つ情報を提供しません。

「HMAC ミスマッチ」と「有効期限切れ」に対して異なるエラーメッセージを公開しないでください — 攻撃者がまず任意の有効期限値に対して有効な署名を構築し、次にそれらを使ってタイミングを調査できるようになります。