se050-wireguard/README.md

# SE050 WireGuard - Clean Room Implementation

MIT ライセンスで実装された NXP SE050 用 WireGuard クリーンルームライブラリ。

## 機能

- **X25519 ECDH**: 鍵交換のための楕円曲線 Diffie-Hellman
- **TRNG**: SE050 の真性乱数生成器
- **Platform SCP03**: 通信経路の暗号化（Session 統合済み）
- **I2C HAL**: ハードウェア抽象化レイヤ

## 進捗状況

### 実装済み (2026-03-26)

- ✅ セッションと SCP03 の統合 (`se050_session_scp03_*` API)
- ✅ PlatformSCP03 認証フロー
- ✅ 42/42 テスト合格 (基本テスト)
- ✅ 41/45 テスト合格 (ハードウェアテスト - 4 つはモックレスポンス形式の問題)
- ✅ AN12436 デフォルトキー実装
- ✅ キー管理 API (`se050_scp03_load_keys_from_file`)
- ✅ 安全なメモリ操作 (`memzero_explicit`, `crypto_memneq`, `secure_memcpy`)
- ✅ **SE050 ハードウェア接続テスト** (chip 選択可能)

### 対応チップ

- **SE050C1**, **SE050C2**, **SE050E2**（すべて X25519/Montgomery 曲線サポート）

### ハードウェアテスト

```bash
# SE050C1 でテスト
make SE050_CHIP=SE050C1 test_se050

# SE050E2 でテスト
make SE050_CHIP=SE050E2 test_se050

# 別の I2C バス指定
make SE050_CHIP=SE050C1 test_se050 I2C_OPTS="-b /dev/i2c-2"
```

### 参照ドキュメント

- [NXP AN12413](https://www.nxp.com/docs/en/application-note/AN12413.pdf) - Platform SCP03
- [NXP AN12436](https://www.nxp.com/docs/en/application-note/AN12436.pdf) - SE050 Configurations

## ディレクトリ構成

```
se050-wireguard/
├── include/
│   └── se050_wireguard.h    # メイン API ヘッダー
├── src/
│   ├── se050_i2c_hal.c      # I2C ハードウェア抽象化
│   ├── se050_session.c      # セッション管理
│   ├── se050_keystore.c     # 鍵ストア
│   ├── se050_rng.c          # 乱数生成
│   ├── se050_x25519.c       # X25519 ECDH
│   └── se050_scp03.c        # SCP03 暗号化
└── README.md
```

## ビルド

### 依存関係

- Linux (I2C サポート)
- GCC/Clang
- CMake 3.10+

```bash
mkdir build && cd build
cmake ..
make
```

## 使用方法

### 初期化

```c
#include "se050_wireguard.h"

se050_i2c_hal_t hal;
se050_session_ctx_t *session;
se050_keystore_ctx_t *keystore;
se050_rng_ctx_t *rng;

// I2C HAL 初期化
se050_i2c_init(&hal, "/dev/i2c-1", 0x90);

// WireGuard サブシステム初期化
se050_wireguard_init(&hal, &session, &keystore, &rng);
```

### 鍵生成

```c
se050_x25519_keypair_t keypair;

// 鍵ペア生成（SE050 内で秘密鍵が生成・保存）
se050_wireguard_generate_key(keystore, rng, &keypair, 0x12345678);

// 公開鍵をエクスポート
se050_x25519_export_public_key(keystore, 0x12345678, keypair.public_key);
```

### 共有秘密計算

```c
uint8_t peer_public[32];  // ピアから取得した公開鍵
uint8_t shared_secret[32];

// ECDH 共有秘密計算（SE050 内で計算）
se050_wireguard_compute_shared(keystore, 0x12345678, peer_public, shared_secret);
```

### SCP03 暗号化

```c
se050_scp03_ctx_t *scp03;
uint8_t enc_key[16];  // 暗号化キー
uint8_t mac_key[16];  // MAC キー
uint8_t dek_key[16];  // データ暗号化キー（鍵導出用）

// SCP03 初期化
se050_scp03_init(&scp03, session);

// キー設定（ENC + MAC + DEK の 3 つ）
se050_scp03_set_keys(scp03, enc_key, mac_key, dek_key);

// コマンド暗号化
uint8_t cmd[256];
size_t cmd_len = 100;
se050_scp03_encrypt_command(scp03, cmd, &cmd_len);

// レスポンス復号
uint8_t rsp[256];
size_t rsp_len = 200;
uint16_t sw = se050_scp03_decrypt_response(scp03, cmd_len, rsp, &rsp_len);
```

### クリーンアップ

```c
se050_wireguard_cleanup(session, keystore, rng);
se050_scp03_free(scp03);
se050_i2c_close(&hal);
```

## API リファレンス

### I2C HAL

| 関数 | 説明 |
|------|------|
| `se050_i2c_init()` | I2C デバイスを初期化 |
| `se050_i2c_close()` | I2C デバイスを閉じる |
| `se050_i2c_read()` | I2C から読み取り |
| `se050_i2c_write()` | I2C に書き込み |
| `se050_i2c_wakeup()` | SE050 をウェイクアップ |

### セッション管理

| 関数 | 説明 |
|------|------|
| `se050_session_create()` | セッションを作成 |
| `se050_session_open()` | セッションを開く |
| `se050_session_close()` | セッションを閉じる |
| `se050_session_delete()` | セッションを削除 |

### 鍵ストア

| 関数 | 説明 |
|------|------|
| `se050_keystore_init()` | 鍵ストアを初期化 |
| `se050_keystore_free()` | 鍵ストアを解放 |

### 乱数生成

| 関数 | 説明 |
|------|------|
| `se050_rng_init()` | RNG  контекстを初期化 |
| `se050_rng_generate()` | 乱数を生成 |
| `se050_rng_free()` | RNG  контекстを解放 |

### X25519 ECDH

| 関数 | 説明 |
|------|------|
| `se050_x25519_generate_keypair()` | 鍵ペアを生成 |
| `se050_x25519_compute_shared_secret()` | 共有秘密を計算 |
| `se050_x25519_export_public_key()` | 公開鍵をエクスポート |

### SCP03

| 関数 | 説明 |
|------|------|
| `se050_scp03_init()` | SCP03  контекстを初期化 |
| `se050_scp03_set_keys()` | ENC/MAC/DEK キーを設定 |
| `se050_scp03_encrypt_command()` | コマンドを暗号化 |
| `se050_scp03_decrypt_response()` | レスポンスを復号 |
| `se050_scp03_free()` | SCP03  контекстを解放 |

## 注意

- 秘密鍵は SE050 内で生成・保存され、外部にエクスポートされません
- 共有秘密計算は SE050 内で実行されます
- **Platform SCP03 キーは 3 つ必要です**:
  - **ENC (Encryption Key)**: コマンド暗号化/レスポンス復号用（16 バイト）
  - **MAC (Message Authentication Code Key)**: 通信認証用 ICV 計算（16 バイト）
  - **DEK (Data Encryption Key)**: セッション鍵導出用（16 バイト）
- SCP03 キーは事前に取得しておく必要があります
- **PlatformSCP03 の設定方法**:
  1. NXP の管理ツールで SE050 に PlatformSCP03 キーをプロビジョニング
  2. キーは安全な経路でホストに配送（鍵ファイルまたは安全なストレージ）
  3. アプリケーション起動時にキーをロード
  4. `se050_scp03_set_keys()` または `se050_scp03_load_keys_from_file()` で設定

## ライセンス

MIT License

## 参考文献

- [NXP SE050 Datasheet](https://www.nxp.com/products/:SE050)
- [WireGuard Protocol](https://www.wireguard.com/protocol/)
- [X25519 RFC 7748](https://tools.ietf.org/html/rfc7748)
- [SCP03 Specification](https://globalplatform.org/)
- [NXP AN12413 - Platform SCP03](https://www.nxp.com/docs/en/application-note/AN12413.pdf)
- [NXP AN12436 - SE050 Configurations](https://www.nxp.com/docs/en/application-note/AN12436.pdf)

## PlatformSCP03 設定ガイド

### キーの生成とプロビジョニング

PlatformSCP03 を使用する場合は、以下の手順でキーを設定します：

1. **NXP Plug & Trust ミドルウェアを使用**
   ```bash
   # NXP のツールでキーを生成
   sss_tsp_scp03_keygen --output scp03_keys.bin
   ```

2. **キーファイルを安全に保存**
   - キーファイルは 48 バイト（ENC 16 + MAC 16 + DEK 16）
   - 暗号化されたストレージに保存推奨

3. **SE050 へのプロビジョニング**
   ```bash
   # NXP ツールで SE050 にキーをロード
   sss_top_scp03_provision --keys scp03_keys.bin --device /dev/i2c-1
   ```

### キーのロード

アプリケーションからキーをロード：

```c
se050_scp03_ctx_t *scp03;
se050_scp03_init(&scp03, session);

// キーファイルからロード（48 バイト）
se050_scp03_load_keys_from_file(scp03, "/secure/path/to/scp03_keys.bin");

// または個別にキーを設定
se050_scp03_set_keys(scp03, enc_key, mac_key, dek_key);
```

### キーの管理

- キーファイルの権限：`chmod 600`（所有者のみ読み取り可能）
- メモリ上のキーは使用後に `memzero_explicit()` でクリア
- キーのバックアップは安全な場所に保管