# セキュリティ設計書

## 概要

本ドキュメントは、Hack Standard Library（HSL）のセキュリティ設計について記載する。HSLはHack言語のための標準ライブラリであり、配列操作、文字列処理、ファイルI/O、ネットワーク通信などの基本機能を提供する。Webアプリケーションフレームワークではなく基盤ライブラリであるため、認証・認可、CSRF、XSSなどのアプリケーションレベルのセキュリティ機能は含まれない。代わりに、ライブラリ利用者がセキュアなアプリケーションを構築するための安全なAPI設計を重視している。

## 認証設計

### 認証方式

本ライブラリは認証機能を提供しない。HSLは基盤ライブラリとして位置づけられており、認証機能は利用者のアプリケーション層で実装される想定である。

### セッション管理

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| セッション有効期限 | 該当なし | ライブラリレベルではセッション管理を行わない |
| セッション固定化対策 | 該当なし | アプリケーション層で実装 |

## 認可設計

### 権限体系

| ロール | 権限 | 説明 |
| --- | --- | --- |
| 該当なし | 該当なし | HSLは認可機能を提供しない |

### アクセス制御

HSLは認可・アクセス制御機能を提供しない。ファイルシステムアクセスにおいては、OSレベルのパーミッションに依存する。

## 通信セキュリティ

| 項目 | 対策 |
| --- | --- |
| HTTPS | ライブラリレベルでは未対応（アプリケーション層で実装） |
| HSTS | ライブラリレベルでは未対応（アプリケーション層で実装） |
| TCP通信 | `HH\Lib\TCP`名前空間でIPv4/IPv6両対応のソケット通信を提供 |
| Unix Socket | `HH\Lib\Unix`名前空間でUnixドメインソケット通信を提供 |

### ネットワーク通信の設計

HSLはTCP/UnixSocketレベルの低レベル通信APIを提供する。TLS/SSL暗号化は本ライブラリのスコープ外であり、上位レイヤーでの実装が必要である。

- **TCP接続**（`src/tcp/connect.php`）: IPv6優先でIPv4にフォールバックする設計
- **サーバー実装**（`src/tcp/Server.php`）: バインド、リッスン、接続受付を提供
- **接続タイムアウト**: オプションで`timeout_ns`パラメータを指定可能

## データセキュリティ

### 暗号化

| 対象 | 暗号化方式 |
| --- | --- |
| 通信 | TLS/SSLは本ライブラリのスコープ外 |
| 保存データ | 暗号化機能は提供しない |

### 機密情報管理

HSLは機密情報管理機能を直接提供しない。ただし、以下のセキュリティ関連機能を提供する：

1. **暗号論的セキュア乱数生成**（`HH\Lib\SecureRandom`）
   - `SecureRandom\int()`: 暗号論的にセキュアな整数を生成
   - `SecureRandom\float()`: 暗号論的にセキュアな浮動小数点数を生成
   - `SecureRandom\string()`: 暗号論的にセキュアな文字列を生成
   - 内部的に`random_bytes()`および`_Private\Native\random_int()`を使用

2. **疑似乱数生成**（`HH\Lib\PseudoRandom`）
   - 暗号用途には**使用不可**であることが明記されている
   - ドキュメントで「This is NOT suitable for cryptographic uses」と警告

### ファイルセキュリティ

| 機能 | 実装 | セキュリティ考慮 |
| --- | --- | --- |
| 一時ファイル作成 | `File\temporary_file()` | モード0600で作成、自動削除 |
| 排他ロック | `File\Lock` | `flock()`によるファイルロック |
| 書き込みモード | `WriteMode::MUST_CREATE` | `O_EXCL`による排他的作成 |

## 入出力対策

| 脅威 | 対策 |
| --- | --- |
| XSS | ライブラリレベルでは未対応（出力時エスケープはアプリケーション層の責務） |
| SQLインジェクション | ライブラリレベルでは未対応（データベースアクセス機能を提供しない） |
| CSRF | ライブラリレベルでは未対応（Webフレームワーク機能を提供しない） |
| ReDoS | 正規表現機能はPCREライブラリに依存 |

### 入力検証

HSLは入力検証ユーティリティを直接提供しないが、型安全なAPIにより不正な入力を防止する：

1. **型システムによる保護**: Hackの強い型システムを活用
2. **不変条件チェック**: `invariant()`による実行時検証
3. **オフセット検証**: 正規表現処理での`_Private\validate_offset()`

### 例外処理

HSLはセキュリティ関連の例外を体系的に定義している（`src/os/ErrnoException.php`）：

| 例外クラス | 対応するエラー | 用途 |
| --- | --- | --- |
| `PermissionException` | `EACCES`, `EPERM` | 権限不足エラー |
| `NotFoundException` | `ENOENT` | ファイル/リソース不在 |
| `AlreadyExistsException` | `EEXIST` | リソース重複 |
| `TimeoutException` | `ETIMEDOUT` | 接続タイムアウト |
| `ConnectionRefusedException` | `ECONNREFUSED` | 接続拒否 |

## 監査ログ

| ログ種別 | 記録内容 | 保持期間 |
| --- | --- | --- |
| 該当なし | HSLはログ機能を提供しない | 該当なし |

HSLは基盤ライブラリとしてログ機能を提供しない。監査ログの実装はアプリケーション層の責務である。

## 備考

### ライブラリとしてのセキュリティ設計方針

HSLは以下の設計方針に基づいてセキュリティを考慮している：

1. **型安全性**: Hackの型システムを最大限活用し、実行時エラーを防止
2. **明示的なAPI**: セキュリティ上の区別を明確に（例：`SecureRandom` vs `PseudoRandom`）
3. **最小権限**: 一時ファイルは0600パーミッションで作成
4. **フェイルセーフ**: 例外の体系的な設計による適切なエラーハンドリング

### 依存関係

- ライセンス: MIT License
- 著作権: Copyright (c) 2013-present, Facebook, Inc.
- 現在のステータス: HHVMに組み込まれる形式に移行中

### セキュリティ上の推奨事項

HSLを使用するアプリケーション開発者への推奨：

1. トークン生成やセッションIDには必ず`SecureRandom`を使用する
2. `PseudoRandom`はシミュレーションやテストなど非セキュリティ用途のみに使用する
3. TLS/SSL暗号化は上位レイヤーで実装する
4. 一時ファイルの自動削除機能（`temporary_file()`）を活用する
5. ファイル作成時は`WriteMode::MUST_CREATE`で競合状態を防止する
