SHA-384 と SRI による CDN の完全性検証
CDN スクリプトを信頼できるバイト列に固定するには、承認済みのリリースファイルから
SHA-384 ダイジェストを生成し、スクリプトの integrity 属性に設定します。この手順では、入力がない場合に失敗するハッシュコマンドと、変更されたスクリプトが実行されないことを実証するローカルブラウザーデモを紹介します。sha384sum は正しいアルゴリズムで計算しますが、その16進数出力を
Subresource Integrity(SRI)で使うには、別のエンコードが必要です。
サブリソース完全性(SRI)の仕組み
ブラウザーはスクリプトをダウンロードして内容をハッシュ化し、実行前に HTML 内の期待値と比較します。一致しなければ実行をブロックします。ハッシュは、信頼できるビルド、または独立して検証済みのリリースから取得する必要があります。侵害された CDN レスポンスをハッシュ化してその値を採用すると、置き換えられた内容を承認することになります。HTML もこの信頼境界の一部です。スクリプトと期待するハッシュの両方を変更できる攻撃者は、この検証を回避できます。
SRI は SHA-256、SHA-384、SHA-512 に対応しています。SHA-384 は SHA-512 よりダイジェストが短く、基本的な選択肢として有用です。複数のアルゴリズムを指定すると、ブラウザーは対応する最も強いものを使用し、不一致でも弱いものにフォールバックしません。SRI 仕様を参照してください。
コマンドラインでのハッシュ生成
コマンドには Bash と OpenSSL を、以下のローカルサーバーには Node.js を使用します。この例は Linux 上の Bash 5.3.15、OpenSSL 3.6.4、Node.js 26.8.1、Chromium 152 でテスト済みです。パッケージのインストールや CDN アカウントは不要です。サンプルファイルは、新しい空のディレクトリに保存してください。
次の内容を demo.js として保存してください。通常はビルドや配布元から取得する承認済みリリースファイルの代わりになります。
document.getElementById('status').textContent = 'Trusted script executed'
次の内容を sri.sh として保存してください。成功時には SRI 値を一つ出力し、失敗時には診断情報を stderr に書き込みます。入力ファイルは一切変更しません。
#!/usr/bin/env bash
set -o pipefail
if [[ $# -ne 1 || ! -f "$1" || ! -r "$1" ]]; then
printf 'Usage: bash sri.sh readable-file\n' >&2
exit 1
fi
if digest=$(openssl dgst -sha384 -binary < "$1" | openssl base64 -A); then
printf 'sha384-%s\n' "$digest"
else
printf 'Could not generate SRI for %s\n' "$1" >&2
exit 1
fi
OpenSSL の -binary オプションでダイジェストのバイト列を生成し、base64 -Aで改行なしにエンコードします。sha384sum が出力するテキストを base64 エンコードしないでください。そのテキストは、ダイジェストを16進数で表したものです。
終了ステータスの確認は、エンコードと同じくらい重要です。cat missing.js | openssl … のようなパイプラインでは、cat の失敗後に空のストリームをハッシュ化する場合があります。この例では、Bash の
pipefail と代入時のチェックにより、読み取りや OpenSSL コマンドが失敗した場合に使用可能な値が出力されるのを防ぎます。入力リダイレクトにより、ハイフンで始まるファイル名が OpenSSL のオプションとして解釈されることも防ぎます。読み取り可能な空のファイルは有効な入力で、固有のダイジェストがあります。ファイルが存在しない場合はエラーです。
Bash でスクリプトを直接実行してください。
bash sri.sh ./demo.js
出力は sha384- で始まり、その後に64文字の base64 文字列が続きます。demo.js 内の空白や改行も結果に影響するため、実際に配信するバイト列をそのままハッシュ化してください。
HTML または JSX への SRI の埋め込み
クロスオリジンのクラシックスクリプトには、integrity と
crossorigin="anonymous" の両方を設定してください。アセットサーバーも適切な
Access-Control-Allow-Origin ヘッダーを送信する必要があります。どちらかの条件が欠けると、バイト列が一致していてもスクリプトがブロックされる場合があります。MDN の CORS 要件の解説を参照してください。JSX では属性名を crossOrigin と記述します。
次の内容を server.ts として保存してください。ページとスクリプトをループバックの異なる二つのポートで配信し、ブラウザーに異なるオリジンとして扱わせます。空いているポートは OS が選択します。ハッシュはシェルから取得し、変更後のレスポンスでも意図的に元の期待ハッシュを維持します。
import type { Server } from 'node:http'
import { once } from 'node:events'
import { readFile } from 'node:fs/promises'
import { createServer } from 'node:http'
async function listen(server: Server, port = 0): Promise<string> {
server.listen(port, '127.0.0.1')
await once(server, 'listening')
const address = server.address()
if (!address || typeof address === 'string') throw new Error('Missing listening address')
return `http://127.0.0.1:${address.port}`
}
async function main(): Promise<void> {
const integrity = process.env.SRI
if (!integrity || !/^sha384-[A-Za-z0-9+/]{64}$/.test(integrity)) {
throw new Error('Set SRI to the trusted value from sri.sh')
}
const pagePort = Number(process.env.PAGE_PORT ?? 0)
if (!Number.isInteger(pagePort) || pagePort < 0 || pagePort > 65535) {
throw new Error('PAGE_PORT must be an integer from 0 to 65535')
}
const trusted = await readFile('./demo.js')
const changed = Buffer.concat([trusted, Buffer.from('\n// Changed after release\n')])
const assets = createServer((request, response) => {
response.setHeader('Cache-Control', 'no-store')
if (!['/demo.js', '/changed.js', '/no-cors.js'].includes(request.url ?? '')) {
response.writeHead(404).end()
return
}
if (request.url !== '/no-cors.js') response.setHeader('Access-Control-Allow-Origin', '*')
response.setHeader('Content-Type', 'text/javascript; charset=utf-8')
response.end(request.url === '/changed.js' ? changed : trusted)
})
const assetOrigin = await listen(assets)
const pages = createServer((request, response) => {
response.setHeader('Cache-Control', 'no-store')
if (request.method === 'POST' && request.url === '/api/security-alerts') {
request.resume()
console.log('Local SRI alert received')
response.writeHead(204).end()
return
}
const file = request.url === '/changed' ? 'changed.js' : request.url === '/no-cors' ? 'no-cors.js' : 'demo.js'
const cors = request.url === '/no-attribute' ? '' : 'crossorigin="anonymous"'
response.setHeader('Content-Type', 'text/html; charset=utf-8')
response.end(`<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>SRI demo</title>
<h1>SRI demo</h1>
<nav aria-label="Test cases">
<a href="/">Trusted</a> | <a href="/changed">Changed bytes</a> |
<a href="/no-cors">Missing CORS header</a> | <a href="/no-attribute">Missing crossorigin</a>
</nav>
<p id="status" role="status">Waiting for script</p>
<script src="${assetOrigin}/${file}" integrity="${integrity}" ${cors}></script>
</html>`)
})
const pageOrigin = await listen(pages, pagePort)
console.log(`Open ${pageOrigin}`)
}
main().catch((error: unknown) => {
console.error('SRI demo failed:', error instanceof Error ? error.message : 'Unknown error')
process.exit(1)
})
三つのファイルがあるディレクトリから起動してください。&& により、ハッシュ化に失敗すると起動しません。これらのコマンドは、出力ファイルの書き込みもサンプルの上書きも行いません。
expected_sri=$(bash sri.sh ./demo.js) &&
SRI="$expected_sri" node server.ts
出力された URL をブラウザーで開いてください。Trusted ページには Trusted script executed と表示されます。それ以外のリンクでは、いずれも画面に Waiting for script が残ります。
- Changed bytes はコメントを追加して配信します。この無害な変更だけでもダイジェストが不一致となり、スクリプト全体の実行が阻止されます。
- Missing CORS header は元のバイト列を配信しますが、クロスオリジンでの読み取りを許可する情報をアセットサーバーから送信しません。
- Missing crossorigin は要素の CORS 属性を省略しますが、アセットサーバーは許可ヘッダーを引き続き送信します。
ブラウザーのコンソールを開き、完全性の不一致と CORS エラーを区別してください。HTTP レスポンスの成功だけでは、スクリプトの実行成功は確認できません。Ctrl+C で両方のサーバーを停止してください。デモは起動時に
demo.js を一度読み取り、何も保存しません。アラート用エンドポイントは、後述する任意の監視サンプル向けのローカル受信先にすぎません。実際のページと CDN には HTTPS を使用してください。攻撃者が書き換えられる接続で配信された HTML は、SRI では保護できません。
Web Crypto API によるブラウザー内でのハッシュ生成
診断用に、この関数をデモページの開発者コンソールに貼り付けてください。取得したバイト列をハッシュ化し、エラーページをスクリプトとして読み取る前に HTTP エラーを拒否します。
async function generateSRIHash(url) {
const response = await fetch(url, {
cache: 'no-store',
signal: AbortSignal.timeout(10_000),
})
if (!response.ok) throw new Error(`Unable to fetch resource: HTTP ${response.status}`)
const buffer = await response.arrayBuffer()
const hashBuffer = await crypto.subtle.digest('SHA-384', buffer)
const hashArray = Array.from(new Uint8Array(hashBuffer))
const binaryString = String.fromCharCode.apply(null, hashArray)
return `sha384-${btoa(binaryString)}`
}
Trusted ページで、次を実行してください。
const resource = document.querySelector('script[integrity]')
console.log(await generateSRIHash(resource.src) === resource.integrity)
true が出力されます。Changed bytes ページで同じ比較を行うと、false が出力されます。信頼できるリリースの期待ハッシュを保持し、この関数が取得した内容のハッシュで置き換えないでください。この別個の取得処理では、先行するスクリプトリクエストでどのバイト列が実行されたかは証明できません。その強制的な検証は、要素の integrity 属性が行います。
crypto.subtle.digest()には、HTTPS やこのループバックデモのようなセキュアコンテキストが必要です。リソース全体をメモリにバッファリングします。任意で使用する JavaScript ヘルパーには
AbortSignal.timeout()も必要です。これは本文の読み取りを含む各取得処理を、アクティブな時間で十秒以内に制限します。ドキュメントが中断されると、このタイムアウトも一時停止する場合があります。古いブラウザーを対象とする場合は、SRI 対応とは別にこれらの API を確認してください。SRI 非対応のブラウザーは、この属性による検証を行いません。
スクリプトの動的読み込み
ページの読み込み後にスクリプトを追加する場合は、挿入前に完全性と CORS のプロパティを設定してください。このヘルパーを同じコンソールに貼り付けるか、アプリケーションの JavaScript に含めてください。
async function loadScript(src, integrity) {
return new Promise((resolve, reject) => {
const script = document.createElement('script')
Object.assign(script, { src, integrity, crossOrigin: 'anonymous' })
script.addEventListener('load', () => resolve())
script.addEventListener('error', () => reject(new Error(`Failed to load or verify ${src}`)))
document.head.append(script)
})
}
フォールバックの実装
バイト単位で同一の信頼できるミラーを使用し、フォールバックでも同じ期待ハッシュを維持してください。次のコードはバックアップを一度試し、その失敗を呼び出し元に伝えます。
async function loadWithFallback(primary, backup, integrity) {
try {
await loadScript(primary, integrity)
} catch {
console.warn(`Primary failed, switching to ${backup}`)
await loadScript(backup, integrity)
}
}
両方のヘルパーを定義し、上記の比較で得た resource を使用すると、次のコードはプライマリへのリクエストに失敗した後、デモの元のアセットを検証して読み込みます。
await loadWithFallback(
new URL('/changed.js', resource.src).href,
new URL('/demo.js', resource.src).href,
resource.integrity,
)
本番環境での CDN アセットの監視
定期的なチェックで、信頼できるハッシュからの変更を報告できますが、ブラウザーのタブは閉じられたり中断されたりします。運用監視には独立した定期実行ジョブを使用してください。ブラウザーでの診断用に、このヘルパーは同時に一つだけポーリングを実行し、リソースごとに失敗を分離し、アラートの HTTP ステータスを確認し、ポーリングの停止と再開に対応します。stop() は以後のポーリングを防ぎますが、実行中のポーリングは完了します。
class SRIMonitor {
#entries = new Map()
#intervalId
#checking = false
constructor(interval = 5 * 60_000) {
this.interval = interval
}
add(url, expectedHash) {
this.#entries.set(url, expectedHash)
}
async #check(url, expected) {
const actual = await generateSRIHash(url)
if (actual !== expected) {
console.warn(`[SRI] Mismatch for ${url}`)
const response = await fetch('/api/security-alerts', {
method: 'POST',
signal: AbortSignal.timeout(10_000),
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ url, expected, actual }),
})
if (!response.ok) throw new Error(`Alert delivery failed: HTTP ${response.status}`)
}
}
async #poll() {
if (this.#checking) return
this.#checking = true
try {
for (const [url, hash] of this.#entries) {
try {
await this.#check(url, hash)
} catch (error) {
console.error('SRI monitor check failed:', error)
}
}
} finally {
this.#checking = false
}
}
start() {
if (this.#intervalId !== undefined) return
this.#intervalId = setInterval(() => {
void this.#poll()
}, this.interval)
}
stop() {
clearInterval(this.#intervalId)
this.#intervalId = undefined
}
}
generateSRIHash、resource、クラスを定義した後、デモのコンソールで次を試してください。
const monitor = new SRIMonitor(1000)
monitor.add(new URL('/changed.js', resource.src).href, resource.integrity)
monitor.start()
// Run monitor.stop() when finished.
ブラウザーは不一致をログに記録し、サーバーは Local SRI alert received と出力します。ループバック受信先はアラートの受信を応答で確認してから破棄します。認証、保存、外部通知は提供しません。本番環境では、認証とレート制限を備えたエンドポイントを用意し、レポートに認証情報を含む URL を載せないでください。ネットワークエラーや CORS の失敗はチェックの失敗であり、内容が変更された証拠ではありません。
CI/CD パイプラインでの SRI の自動化
信頼できるビルドの最終ミニファイ処理後、HTML のレンダリング前にハッシュを生成してください。対象のスクリプトまたはスタイルシートごとに sri.sh を実行し、終了ステータスが一つでもゼロ以外ならビルドを失敗させてください。想定するアセット一覧が空の場合も失敗させます。各ファイル名と SRI 値をビルドマニフェストに保存し、そのマニフェストのアセットとレンダリング済み HTML を一緒にデプロイしてください。この統合方法はビルドシステムによって異なります。上記のローカルデモは
CI ワークフローをインストールしません。
latest のような変更可能なエイリアスよりも、バージョン付きのアセット URL を優先してください。依存関係を意図的に更新する場合は、新しいリリースをレビューしたうえで、新しいアセット URL とその新しい期待ハッシュを使用する必要があります。完全性チェックが失敗した際に、期待値を自動更新しないでください。
よくある問題のトラブルシューティング
| 症状 | 確認事項 |
|---|---|
| ハッシュコマンドの失敗 | パス、権限、OpenSSL のインストールを確認してください。入力がない場合に、空のファイルのハッシュを生成してはいけません。 |
| ブラウザーが完全性の不一致を報告 | レスポンスを承認済みリリースまたはビルド成果物と比較してください。予期しない変更を調査し、新しいバイト列を承認した後にのみハッシュを更新してください。 |
| ローカルハッシュと CDN のバイト列が不一致 | ミニファイ、挿入されたバナー、改行を確認してください。通常の HTTP 圧縮は、完全性チェックの前に展開されます。 |
| ブラウザーが CORS の失敗を報告 | crossorigin="anonymous" を維持し、CDN の Access-Control-Allow-Origin をページに合わせて設定してください。公開された匿名アクセス用アセットには * を設定してください。 |
| 保護なしでスクリプトが実行される | 実際の要素に有効な完全性メタデータがあるか調べ、ブラウザーの対応を確認してください。空のメタデータや非対応のメタデータでは、意図したチェックは行われません。 |
