［PHP］hash_hmac_file関数完全ガイド：ファイル認証を効率的に実装する方法

ファイルの整合性と認証性を確保することは、現代のWebアプリケーションにおいて極めて重要です。PHPのhash_hmac_file関数は、大きなファイルでもメモリ効率よくHMAC値を計算できる強力なツールです。今回は、この関数の詳細な使い方から実践的な応用例まで、包括的に解説していきます。

hash_hmac_file関数とは？

hash_hmac_file関数は、指定したファイルの内容に対してHMAC（Hash-based Message Authentication Code）を計算する関数です。hash_hmac関数がメモリ上のデータを対象とするのに対し、この関数はファイルを直接処理するため、大容量ファイルでもメモリ使用量を抑えて効率的に処理できます。

基本構文

phpstring hash_hmac_file(string $algo, string $filename, string $key, bool $binary = false)

パラメータ

• $algo: 使用するハッシュアルゴリズム（sha256, sha512など）
• $filename: HMAC値を計算するファイルのパス
• $key: 秘密鍵（任意の長さの文字列）
• $binary: 結果を16進数文字列で返すか（false）、バイナリ文字列で返すか（true）

戻り値

• 計算されたHMAC値（文字列）
• エラーの場合はFALSE

hash_hmacとの違い

関数対象メモリ使用量適用場面hash_hmacメモリ上のデータデータサイズに比例小さなデータ、動的生成データhash_hmac_fileファイル一定（少量）大きなファイル、既存ファイル

実践的な使用例

例1：基本的な使用法

php// ファイルのHMAC値を計算
$filename = 'important_document.pdf';
$secretKey = 'your-secret-key-2024';

$hmac = hash_hmac_file('sha256', $filename, $secretKey);

if ($hmac !== false) {
    echo "ファイル '{$filename}' のHMAC-SHA256: {$hmac}";
} else {
    echo "エラー: ファイルが見つからないか、読み取りできません";
}

例2：ファイルアップロード時の整合性検証

phpclass FileIntegrityChecker {
    private $secretKey;
    
    public function __construct($secretKey) {
        $this->secretKey = $secretKey;
    }
    
    // アップロードファイルのHMAC生成
    public function generateFileSignature($filePath) {
        if (!file_exists($filePath)) {
            throw new Exception("ファイルが存在しません: {$filePath}");
        }
        
        $hmac = hash_hmac_file('sha256', $filePath, $this->secretKey);
        
        if ($hmac === false) {
            throw new Exception("HMAC計算に失敗しました");
        }
        
        return $hmac;
    }
    
    // ファイルの整合性を検証
    public function verifyFileIntegrity($filePath, $expectedHmac) {
        try {
            $actualHmac = $this->generateFileSignature($filePath);
            return hash_equals($expectedHmac, $actualHmac);
        } catch (Exception $e) {
            error_log("ファイル検証エラー: " . $e->getMessage());
            return false;
        }
    }
    
    // ファイル情報とHMACをJSON形式で保存
    public function createFileManifest($filePath) {
        $fileInfo = [
            'filename' => basename($filePath),
            'size' => filesize($filePath),
            'modified' => filemtime($filePath),
            'hmac' => $this->generateFileSignature($filePath),
            'created_at' => time()
        ];
        
        return json_encode($fileInfo, JSON_PRETTY_PRINT);
    }
}

// 使用例
$checker = new FileIntegrityChecker('my-application-secret-key');

// ファイルアップロード処理
if (isset($_FILES['document'])) {
    $uploadedFile = $_FILES['document']['tmp_name'];
    $targetPath = 'uploads/' . $_FILES['document']['name'];
    
    if (move_uploaded_file($uploadedFile, $targetPath)) {
        // HMACを計算してメタデータとして保存
        $hmac = $checker->generateFileSignature($targetPath);
        
        // データベースまたはファイルにHMACを保存
        file_put_contents($targetPath . '.hmac', $hmac);
        
        echo "ファイルのアップロードと署名が完了しました";
        echo "HMAC: {$hmac}";
    }
}

例3：バックアップファイルの検証システム

phpclass BackupVerificationSystem {
    private $secretKey;
    private $backupDir;
    
    public function __construct($secretKey, $backupDir) {
        $this->secretKey = $secretKey;
        $this->backupDir = rtrim($backupDir, '/');
    }
    
    // バックアップファイルのカタログ作成
    public function createBackupCatalog() {
        $catalog = [];
        $files = glob($this->backupDir . '/*.{sql,tar,gz,zip}', GLOB_BRACE);
        
        foreach ($files as $file) {
            $filename = basename($file);
            $hmac = hash_hmac_file('sha256', $file, $this->secretKey);
            
            $catalog[$filename] = [
                'path' => $file,
                'size' => filesize($file),
                'modified' => date('Y-m-d H:i:s', filemtime($file)),
                'hmac' => $hmac
            ];
        }
        
        // カタログファイルを保存
        $catalogPath = $this->backupDir . '/backup_catalog.json';
        file_put_contents($catalogPath, json_encode($catalog, JSON_PRETTY_PRINT));
        
        return $catalog;
    }
    
    // バックアップファイルの整合性を一括検証
    public function verifyAllBackups() {
        $catalogPath = $this->backupDir . '/backup_catalog.json';
        
        if (!file_exists($catalogPath)) {
            throw new Exception("バックアップカタログが見つかりません");
        }
        
        $catalog = json_decode(file_get_contents($catalogPath), true);
        $results = [];
        
        foreach ($catalog as $filename => $info) {
            $filePath = $info['path'];
            
            if (!file_exists($filePath)) {
                $results[$filename] = ['status' => 'missing', 'message' => 'ファイルが見つかりません'];
                continue;
            }
            
            $currentHmac = hash_hmac_file('sha256', $filePath, $this->secretKey);
            
            if (hash_equals($info['hmac'], $currentHmac)) {
                $results[$filename] = ['status' => 'valid', 'message' => '整合性確認済み'];
            } else {
                $results[$filename] = ['status' => 'corrupted', 'message' => 'ファイルが破損している可能性があります'];
            }
        }
        
        return $results;
    }
    
    // 検証結果をレポート形式で出力
    public function generateVerificationReport() {
        $results = $this->verifyAllBackups();
        $report = "バックアップ検証レポート - " . date('Y-m-d H:i:s') . "\n";
        $report .= str_repeat("=", 50) . "\n\n";
        
        $validCount = 0;
        $corruptedCount = 0;
        $missingCount = 0;
        
        foreach ($results as $filename => $result) {
            $report .= "ファイル: {$filename}\n";
            $report .= "ステータス: {$result['status']}\n";
            $report .= "メッセージ: {$result['message']}\n\n";
            
            switch ($result['status']) {
                case 'valid': $validCount++; break;
                case 'corrupted': $corruptedCount++; break;
                case 'missing': $missingCount++; break;
            }
        }
        
        $report .= "サマリー:\n";
        $report .= "正常: {$validCount} ファイル\n";
        $report .= "破損: {$corruptedCount} ファイル\n";
        $report .= "欠損: {$missingCount} ファイル\n";
        
        return $report;
    }
}

// 使用例
$verifier = new BackupVerificationSystem('backup-verification-key', '/path/to/backups');

// 定期実行用のスクリプト
try {
    echo "バックアップカタログを作成中...\n";
    $catalog = $verifier->createBackupCatalog();
    echo "カタログ作成完了: " . count($catalog) . " ファイル\n\n";
    
    echo "バックアップファイルを検証中...\n";
    $report = $verifier->generateVerificationReport();
    echo $report;
    
    // レポートをファイルに保存
    file_put_contents('/var/log/backup_verification.log', $report);
    
} catch (Exception $e) {
    error_log("バックアップ検証エラー: " . $e->getMessage());
}

セキュリティ上の考慮事項

1. 強力な秘密鍵の使用

phpclass SecureKeyManager {
    // 安全な秘密鍵を生成
    public static function generateSecureKey($length = 64) {
        return bin2hex(random_bytes($length / 2));
    }
    
    // 環境変数から秘密鍵を安全に取得
    public static function getSecretKey($keyName = 'FILE_HMAC_SECRET') {
        $key = $_ENV[$keyName] ?? getenv($keyName);
        
        if (empty($key)) {
            throw new Exception("秘密鍵が設定されていません: {$keyName}");
        }
        
        if (strlen($key) < 32) {
            throw new Exception("秘密鍵が短すぎます（最低32文字必要）");
        }
        
        return $key;
    }
}

2. エラーハンドリングの強化

phpfunction calculateFileHmac($filename, $key, $algorithm = 'sha256') {
    // ファイル存在チェック
    if (!file_exists($filename)) {
        throw new InvalidArgumentException("ファイルが存在しません: {$filename}");
    }
    
    // 読み取り権限チェック
    if (!is_readable($filename)) {
        throw new InvalidArgumentException("ファイルが読み取れません: {$filename}");
    }
    
    // アルゴリズムの有効性チェック
    if (!in_array($algorithm, hash_algos())) {
        throw new InvalidArgumentException("サポートされていないハッシュアルゴリズム: {$algorithm}");
    }
    
    $hmac = hash_hmac_file($algorithm, $filename, $key);
    
    if ($hmac === false) {
        throw new RuntimeException("HMAC計算に失敗しました");
    }
    
    return $hmac;
}

パフォーマンス最適化

大容量ファイルでの効率的な処理

phpclass OptimizedFileProcessor {
    private $secretKey;
    
    public function __construct($secretKey) {
        $this->secretKey = $secretKey;
    }
    
    // 複数ファイルの並列処理
    public function processMultipleFiles($filePaths) {
        $results = [];
        
        foreach ($filePaths as $filePath) {
            $startTime = microtime(true);
            
            try {
                $hmac = hash_hmac_file('sha256', $filePath, $this->secretKey);
                $fileSize = filesize($filePath);
                $endTime = microtime(true);
                
                $results[$filePath] = [
                    'hmac' => $hmac,
                    'size' => $fileSize,
                    'processing_time' => ($endTime - $startTime),
                    'throughput' => $fileSize / ($endTime - $startTime) // bytes/second
                ];
                
            } catch (Exception $e) {
                $results[$filePath] = [
                    'error' => $e->getMessage()
                ];
            }
        }
        
        return $results;
    }
    
    // 処理統計の表示
    public function displayProcessingStats($results) {
        $totalFiles = count($results);
        $successfulFiles = 0;
        $totalSize = 0;
        $totalTime = 0;
        
        foreach ($results as $filePath => $result) {
            if (!isset($result['error'])) {
                $successfulFiles++;
                $totalSize += $result['size'];
                $totalTime += $result['processing_time'];
            }
        }
        
        echo "処理統計:\n";
        echo "総ファイル数: {$totalFiles}\n";
        echo "成功: {$successfulFiles}\n";
        echo "失敗: " . ($totalFiles - $successfulFiles) . "\n";
        echo "総データサイズ: " . $this->formatBytes($totalSize) . "\n";
        echo "総処理時間: " . number_format($totalTime, 2) . "秒\n";
        
        if ($totalTime > 0) {
            $avgThroughput = $totalSize / $totalTime;
            echo "平均スループット: " . $this->formatBytes($avgThroughput) . "/秒\n";
        }
    }
    
    private function formatBytes($size, $precision = 2) {
        $units = ['B', 'KB', 'MB', 'GB', 'TB'];
        
        for ($i = 0; $size > 1024 && $i < count($units) - 1; $i++) {
            $size /= 1024;
        }
        
        return round($size, $precision) . ' ' . $units[$i];
    }
}

実用的なユースケース

CDN配信ファイルの整合性確認

phpclass CDNFileValidator {
    private $secretKey;
    
    public function __construct($secretKey) {
        $this->secretKey = $secretKey;
    }
    
    // CDN配信前のファイル署名
    public function signFileForCDN($localFilePath) {
        $hmac = hash_hmac_file('sha256', $localFilePath, $this->secretKey);
        $fileInfo = [
            'filename' => basename($localFilePath),
            'size' => filesize($localFilePath),
            'hmac' => $hmac,
            'signed_at' => time()
        ];
        
        return $fileInfo;
    }
    
    // CDNからダウンロードしたファイルの検証
    public function verifyCDNFile($downloadedFilePath, $expectedSignature) {
        $actualHmac = hash_hmac_file('sha256', $downloadedFilePath, $this->secretKey);
        
        return hash_equals($expectedSignature['hmac'], $actualHmac);
    }
}

まとめ

hash_hmac_file関数は、ファイルベースの認証と整合性確認において非常に強力なツールです。以下の特徴により、様々な場面で活用できます：

主な利点：

• メモリ効率的な大容量ファイル処理
• 強力なセキュリティ保証
• 簡単な API
• 高いパフォーマンス

適用場面：

• ファイルアップロードの整合性確認
• バックアップファイルの検証
• CDN配信ファイルの認証
• ソフトウェア配布パッケージの署名

適切な秘密鍵管理とエラーハンドリングを組み合わせることで、堅牢なファイル認証システムを構築できます。大容量ファイルを扱うWebアプリケーションでは、この関数を活用して安全で効率的なファイル処理を実装しましょう。