양자 내성 암호(PQC) MCP 서버

License: MIT Python 3.10+ liboqs MCP

연구 및 프로토타이핑 전용. 이 서버는 liboqs를 사용하며, 프로덕션 환경이나 민감한 데이터 보호용으로는 명시적으로 권장되지 않습니다. store_as 모드(권장)를 사용하면 비밀 키가 도구 출력에서 삭제되고 세션 범위의 키링에 보관됩니다. store_as를 사용하지 않으면 비밀 키와 공유 비밀이 도구 출력에 나타나며, 이는 모델 컨텍스트, 클라이언트 로그 또는 대화 기록에 포함될 수 있습니다. 모든 비밀 키 작업에 대해 핸들 전용 모드를 강제하려면 PQC_REQUIRE_KEY_HANDLES=1을 설정하십시오. 실험, 교육 및 상호 운용성 테스트에 적합합니다.

Open Quantum Safe의 liboqs를 사용하여 양자 내성 암호 작업을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. Claude와 같은 AI 어시스턴트가 키 생성, 암호화, 서명 및 검증을 포함한 양자 내성 암호 작업을 수행할 수 있도록 합니다.

왜 양자 내성 암호인가?

현재의 암호 시스템(RSA, ECC, ECDSA)은 쇼어 알고리즘을 실행하는 양자 컴퓨터에 의해 해독될 것입니다. NIST는 새로운 양자 내성 알고리즘을 표준화했습니다:

표준	알고리즘	유형	상태
FIPS 203	ML-KEM (구 CRYSTALS-Kyber)	키 캡슐화	2024년 확정
FIPS 204	ML-DSA (구 CRYSTALS-Dilithium)	디지털 서명	2024년 확정
FIPS 205	SLH-DSA (구 SPHINCS+)	해시 기반 서명	2024년 확정

이 MCP 서버는 AI 에이전트가 연구, 개발 및 통합을 위해 이러한 알고리즘에 접근할 수 있도록 합니다.

기능

liboqs를 통한 키 캡슐화 메커니즘(KEM) 사용 가능: ML-KEM, FrodoKEM, HQC, BIKE, Classic McEliece
liboqs를 통한 서명 알고리즘 사용 가능: ML-DSA, Falcon, SLH-DSA, MAYO, CROSS, UOV
완벽한 MCP 통합: Claude Desktop, Claude Code, Cursor 및 모든 MCP 클라이언트와 호환
NIST 표준 알고리즘 지원: FIPS 203, 204, 205 알고리즘 구현
보안 분석: 고전적 보안 수준과 양자 보안 수준 비교

빠른 시작

사전 요구 사항

Python 3.10+
liboqs 공유 라이브러리
uv (권장) 또는 pip

설치

1. liboqs 설치

macOS (공유 라이브러리가 포함된 Homebrew):

# Homebrew only provides static library, build from source for shared:
git clone --depth 1 --branch 0.15.0 https://github.com/open-quantum-safe/liboqs.git
cd liboqs && mkdir build && cd build
cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
make -j4 && make install

Ubuntu/Debian:

sudo apt-get install liboqs-dev

대안: 위 과정을 자동화하는 번들 설치 스크립트 사용:

bash scripts/install-liboqs.sh

2. 복제 및 설치

git clone https://github.com/scottdhughes/post-quantum-mcp.git
cd post-quantum-mcp

# Install all dependencies (creates .venv automatically)
uv sync --all-extras

3. Claude Code / Claude Desktop 구성

MCP 구성에 추가:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "pqc": {
      "type": "stdio",
      "command": "/path/to/post-quantum-mcp/run.sh",
      "args": [],
      "env": {}
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "pqc": {
      "command": "/path/to/post-quantum-mcp/run.sh"
    }
  }
}

서버는 python -m pqc_mcp_server를 통해 직접 실행할 수도 있습니다.

사용 가능한 도구

`pqc_list_algorithms`

사용 가능한 모든 양자 내성 알고리즘을 나열합니다.

Input: { "type": "kem" | "sig" | "all" }
Output: List of available algorithms with NIST standard mappings

`pqc_algorithm_info`

특정 알고리즘에 대한 자세한 정보를 가져옵니다.

Input: { "algorithm": "ML-KEM-768" }
Output: Key sizes, security level, performance characteristics

`pqc_generate_keypair`

양자 내성 키 쌍을 생성합니다.

Input: { "algorithm": "ML-DSA-65" }
Output: Base64-encoded public and secret keys

`pqc_encapsulate`

키 캡슐화를 수행합니다(공유 비밀 생성).

Input: { "algorithm": "ML-KEM-768", "public_key": "<base64>" }
Output: Ciphertext and shared secret

`pqc_decapsulate`

암호문에서 공유 비밀을 복구합니다.

Input: { "algorithm": "ML-KEM-768", "secret_key": "<base64>", "ciphertext": "<base64>" }
Output: Shared secret

`pqc_sign`

양자 내성 서명으로 메시지에 서명합니다.

Input: { "algorithm": "ML-DSA-65", "secret_key": "<base64>", "message": "Hello, quantum world!" }
Output: Base64-encoded signature

`pqc_verify`

양자 내성 서명을 검증합니다.

Input: { "algorithm": "ML-DSA-65", "public_key": "<base64>", "message": "...", "signature": "<base64>" }
Output: { "valid": true/false }

`pqc_hash`

양자 안전 해시 함수를 사용하여 메시지를 해싱합니다.

Input: { "message": "data", "algorithm": "SHA3-256" | "SHA3-512" | "SHAKE128" | "SHAKE256" }
Output: Digest in hex and base64

`pqc_security_analysis`

알고리즘의 보안 속성을 분석합니다.

Input: { "algorithm": "ML-KEM-768" }
Output: NIST level, classical/quantum security equivalents, Grover/Shor resistance

하이브리드 키 교환 (X25519 + ML-KEM-768)

제품군: mlkem768-x25519-sha3-256 — LAMPS 복합 ML-KEM 초안(id-MLKEM768-X25519-SHA3-256)의 KEM 결합기를 차용합니다. 제품군 이름의 sha3-256은 KEM 결합기 해시를 의미하며, HKDF 키 유도는 SHA-256(cryptography HKDF 사용)을 사용합니다. 봉인된 봉투 계층은 해당 결합기 위에 구축된 이 프로젝트 고유의 프로토콜입니다.

이것은 암호문 무결성을 갖춘 하이브리드 기밀성을 제공하는 익명 봉인 상자(anonymous sealed-box) 구조입니다. 수신자 키 손상에 대한 전방향 보안(forward-secret)은 제공하지 않으며, 송신자 인증도 수행하지 않습니다.

`pqc_hybrid_keygen`

하이브리드 키 쌍 번들을 생성합니다.

권장: store_as 사용 (비밀 키 삭제됨)

// Input
{"store_as": "alice"}

// Output — no secret keys
{
  "suite": "mlkem768-x25519-sha3-256",
  "handle": "alice",
  "classical": {"algorithm": "X25519", "public_key": "DeRN3xLbEglMdXKO7P98cAvc...", "fingerprint": "a1b2c3d4..."},
  "pqc": {"algorithm": "ML-KEM-768", "public_key": "gDsL8UgEVcMeJgUOQgSlAotx...", "fingerprint": "e5f6a7b8..."}
}

store_as 미사용 (원시 키 반환 — 권장하지 않음):

// Input
{}

// Output — secret keys exposed in tool output
{
  "suite": "mlkem768-x25519-sha3-256",
  "classical": {
    "algorithm": "X25519",
    "public_key": "DeRN3xLbEglMdXKO7P98cAvc...",
    "secret_key": "YEYD9j5c2hpTei0ferXWbAFb..."
  },
  "pqc": {
    "algorithm": "ML-KEM-768",
    "public_key": "gDsL8UgEVcMeJgUOQgSlAotx...",
    "secret_key": "MQB2U0EzNGmloLuiTYG3BTcr..."
  }
}

`pqc_hybrid_encap` / `pqc_hybrid_decap`

빌딩 블록 키 캡슐화. 제품군의 SHA3-256 결합기를 통해 파생된 결합 공유 비밀을 반환합니다.

`pqc_hybrid_seal` / `pqc_hybrid_open`

하이브리드 캡슐화 + AES-256-GCM을 사용하여 일반 텍스트를 암호화/복호화합니다. 전체 헤더 AAD 바인딩. 결정론적 논스(봉투에 전송되지 않음).

// Seal input
{
  "plaintext": "Hello, quantum world!",
  "recipient_classical_public_key": "<base64 X25519 public key>",
  "recipient_pqc_public_key": "<base64 ML-KEM-768 public key>"
}

// Seal output
{
  "envelope": {
    "version": "pqc-mcp-v3",
    "mode": "anon-seal",
    "suite": "mlkem768-x25519-sha3-256",
    "x25519_ephemeral_public_key": "6+b1Y8AkgEycKL5wL2cIeSMv...",
    "pqc_ciphertext": "DF+PYy4zx+OmnW8wLD3EL+4M...",
    "ciphertext": "NnEap2fDq5+xTCwvHdKfy5Xj..."
  }
}

// Open input
{
  "envelope": { "...envelope from seal..." },
  "classical_secret_key": "<base64 X25519 secret key>",
  "pqc_secret_key": "<base64 ML-KEM-768 secret key>"
}

// Open output
{
  "suite": "mlkem768-x25519-sha3-256",
  "plaintext": "Hello, quantum world!",
  "plaintext_base64": "SGVsbG8sIHF1YW50dW0gd29ybGQh"
}

하이브리드 예시 프롬프트

"하이브리드 키 쌍을 생성하고 메시지를 봉인해 줘"

"하이브리드 키 교환을 수행하고 공유 비밀을 보여줘"

"하이브리드 PQC를 사용하여 '기밀 데이터'를 암호화하고 복호화해 줘"

인증된 하이브리드 봉투

ML-DSA-65(FIPS 204) 서명을 사용하여 하이브리드 기밀성 계층에 송신자 인증을 추가합니다. 송신자는 전체 봉투를 포괄하는 정규화된 바이너리 기록에 서명합니다. 수신자는 복호화 전에 송신자 신원을 확인합니다.

이것은 송신자 인증 봉인 봉투(sender-authenticated sealed-envelope) 구조입니다. 나중에 수신자의 장기 키가 손상될 경우에 대한 전방향 보안은 여전히 제공하지 않습니다. 봉인된 봉투 계층은 이 프로젝트 고유의 프로토콜입니다.

`pqc_hybrid_auth_seal`

암호화 + 서명. 송신자의 ML-DSA-65 서명 키 + 수신자의 하이브리드 키가 필요합니다.

권장: 키 핸들 사용

// Input
{
  "plaintext": "Authenticated message",
  "recipient_key_store_name": "bob",
  "sender_key_store_name": "alice-signing"
}

// Output
{
  "envelope": {
    "version": "pqc-mcp-v3",
    "mode": "auth-seal",
    "suite": "mlkem768-x25519-sha3-256",
    
    "sender_signature_algorithm": "ML-DSA-65",
    "sender_public_key": "0ji6POTItnZUX8rELwVwWSOV...",
    "sender_key_fingerprint": "0f617ece2f1d04c0...",
    "recipient_classical_key_fingerprint": "c1deade4a5300a9a...",
    "recipient_pqc_key_fingerprint": "bb0e084213d6ac74...",
    "x25519_ephemeral_public_key": "5LEikNANeJNhZSiq...",
    "pqc_ciphertext": "ybgWc3ruG3JwXmr4...",
    "ciphertext": "6OYdADdh0eH/LviD...",
    "signature": "BOniPALs1kfhWcRh..."
  }
}

대안: 원시 키 사용 (권장하지 않음)

// Input
{
  "plaintext": "Authenticated message",
  "recipient_classical_public_key": "<base64 X25519 public key>",
  "recipient_pqc_public_key": "<base64 ML-KEM-768 public key>",
  "sender_secret_key": "<base64 ML-DSA-65 secret key>",
  "sender_public_key": "<base64 ML-DSA-65 public key>"
}

`pqc_hybrid_auth_open`

송신자 검증 + 복호화. expected_sender_public_key 또는 expected_sender_fingerprint가 필요합니다. 복호화 전에 서명이 검증되며, 인증 실패는 복호화 실패와 구분됩니다.

// Open with expected sender public key
{
  "envelope": { "...envelope from auth_seal..." },
  "classical_secret_key": "<base64 X25519 secret key>",
  "pqc_secret_key": "<base64 ML-KEM-768 secret key>",
  "expected_sender_public_key": "<base64 ML-DSA-65 public key>"
}

// Or open with expected sender fingerprint
{
  "envelope": { "...envelope from auth_seal..." },
  "classical_secret_key": "...",
  "pqc_secret_key": "...",
  "expected_sender_fingerprint": "0f617ece2f1d04c0481aa0fe..."
}

// Output
{
  "suite": "mlkem768-x25519-sha3-256",
  "plaintext": "Authenticated message",
  "plaintext_base64": "QXV0aGVudGljYXRlZCBtZXNzYWdl",
  "sender_key_fingerprint": "0f617ece2f1d04c0481aa0fe...",
  "sender_signature_algorithm": "ML-DSA-65",
  "authenticated": true
}

`pqc_hybrid_auth_verify`

복호화 없이 인증된 봉투의 송신자 서명을 검증합니다. 비밀 키가 필요하지 않습니다. 송신자 바인딩, 지문 일관성, ML-DSA-65 서명 및 타임스탬프 신선도를 확인합니다.

// Input
{
  "envelope": { "...envelope from auth_seal..." },
  "expected_sender_fingerprint": "0f617ece2f1d04c0..."
}

// Output
{
  "verified": true,
  "sender_key_fingerprint": "0f617ece2f1d04c0...",
  "sender_signature_algorithm": "ML-DSA-65",
  "version": "pqc-mcp-v3",
  "mode": "auth-seal",
  "replay_seen": false,
  "timestamp": "1711929600"
}

`pqc_envelope_inspect`

복호화 없이 봉투 메타데이터를 검사합니다. 비밀 키가 필요하지 않습니다. 버전, 제품군, 지문 및 필드 크기를 반환합니다.

// Input
{"envelope": { "...any sealed or authenticated envelope..." }}

// Output
{
  "version": "pqc-mcp-v3",
  "mode": "auth-seal",
  "suite": "mlkem768-x25519-sha3-256",
  "authenticated": true,
  "sender_key_fingerprint": "0f617ece2f1d04c0...",
  
  
  "ciphertext_size": 1234,
  "plaintext_size_approx": 1218,
  "pqc_ciphertext_size": 1088,
  "signature_size": 3309
}

`pqc_fingerprint`

공개 키의 SHA3-256 지문을 계산합니다. 소문자 16진수를 반환합니다.

// Input
{"public_key": "<base64-encoded public key>"}

// Output
{"fingerprint": "a1b2c3d4e5f6...", "algorithm": "SHA3-256"}

`pqc_benchmark`

PQC 알고리즘 벤치마크: 키 생성, 캡슐화/서명, 복호화/검증 시간 및 키/암호문/서명 크기 측정.

// Input
{"algorithm": "ML-KEM-768", "iterations": 10}

// Output — timing and size measurements

키 생성 흐름

1. Sender: generate ML-DSA-65 signing keys via pqc_generate_keypair
2. Recipient: generate hybrid keys via pqc_hybrid_keygen
3. Exchange public keys out-of-band
4. Sender: pqc_hybrid_auth_seal with both key sets
5. Recipient: pqc_hybrid_auth_open with expected sender identity

인증된 예시 프롬프트

"ML-DSA-65 서명 키 쌍과 하이브리드 수신자 키 쌍을 생성한 다음, 인증된 암호화 메시지를 보내줘"

"이 인증된 봉투를 열고 예상된 송신자로부터 온 것인지 확인해 줘"

"밥에게 메시지를 봉인하고 내 ML-DSA 키로 서명한 다음, 밥이 내 지문을 사용하여 열 수 있게 해 줘"

키 핸들 (비밀 삭제)

비밀 키가 프로세스 로컬에 저장되고 도구 출력에 절대 나타나지 않는 옵트인 모드입니다. 핸들은 프로세스 전역이며 서버 재시작 시 손실됩니다.

핸들로 생성하기

// pqc_hybrid_keygen with store_as
{"store_as": "alice"}

// Output — no secret keys
{
  "suite": "mlkem768-x25519-sha3-256",
  "handle": "alice",
  "classical": {"algorithm": "X25519", "public_key": "...", "fingerprint": "..."},
  "pqc": {"algorithm": "ML-KEM-768", "public_key": "...", "fingerprint": "..."}
}

하위 도구에서 핸들 사용하기

// pqc_hybrid_seal with store name instead of raw keys
{
  "plaintext": "Hello via handle!",
  "recipient_key_store_name": "alice"
}

// pqc_hybrid_auth_seal with two store names
{
  "plaintext": "Authenticated via handles",
  "recipient_key_store_name": "alice",
  "sender_key_store_name": "bob-signing"
}

일반 PQC 도구(pqc_sign, pqc_verify, pqc_encapsulate, pqc_decapsulate)도 key_store_name을 허용합니다.

동일한 역할에 대해 저장소 이름과 원시 키를 모두 제공하는 것은 오류입니다.

키 저장소 관리

pqc_key_store_save: 편리한 참조를 위해 키 생성 출력을 이름으로 저장합니다. 세션 범위이며 영구적이지 않습니다.
pqc_key_store_load: 이름으로 저장된 키를 로드합니다. 핸들 항목에 대해서는 공개 자료만 반환합니다.
pqc_key_store_list: 메타데이터(이름, 유형, 지문)와 함께 저장된 모든 키를 나열합니다. 비밀 자료는 표시되지 않습니다.
pqc_key_store_delete: 이름으로 저장된 키를 삭제합니다.

보안 기능

v3 봉투 프로토콜

v3 봉투는 모드 바인딩됩니다: 모든 봉투는 HKDF 정보, AAD 및 인증 기록에 바인딩되는 명시적 mode 필드(anon-seal 또는 auth-seal)를 포함합니다. 이는 진정한 모드 간 분리를 제공하며, 한 모드에서 생성된 암호문은 다른 모드에서 복호화할 수 없어 AEAD 계층에서 인증 제거 다운그레이드 공격을 차단합니다. v3의 AAD는 길이 접두사가 붙은 프레이밍(자기 구분)을 사용합니다. 인증된 봉투는 정규화된 기록에 서명된 timestamp 필드를 포함하며, 검증/열기 시 서버는 신선도를 확인합니다(기본값: 24시간, max_age_seconds를 통해 구성 가능). 시계 오차 허용 범위는 5분입니다.

재전송 방지

서버는 TTL이 있는 서명 다이제스트 캐시(봉투 서명 바이트의 SHA3-256)를 유지합니다. pqc_hybrid_auth_verify는 읽기 전용 재전송 확인을 수행합니다. pqc_hybrid_auth_open은 복호화 전 확인 및 성공 후 표시를 수행합니다. 캐시는 ~/.pqc/state/replay-cache.json에 유지되며 서버 재시작 후에도 지속됩니다. 최대 50,000개 항목, 오래된 항목부터 삭제.

봉투 크기 검증

모든 봉투는 암호화 처리 전에 검증됩니다: base64 필드당 최대 1MB(ciphertext, pqc_ciphertext, signature, sender_public_key, x25519_ephemeral_public_key), 총 최대 50개 필드. 메모리 폭탄 및 리소스 고갈을 방지합니다.

서버 보안 정책

PQC_REQUIRE_KEY_HANDLES=1을 설정하여 핸들 전용 모드를 강제합니다: 서버는 원시 비밀 키를 전달하는 모든 도구 호출을 거부하며, 모든 비밀 키 작업(키 생성, 서명, 복호화 및 하이브리드 봉투 작업)에 대해 store_as/key_store_name 사용을 강제합니다. 이는 잘못된 에이전트가 우회할 수 없는 서버 측 검사입니다.

v1/v2 하위 호환성

v1 봉투(pqc-mcp-v1)는 하위 호환성을 위해 열기/검증 시 허용되지만 경고가 표시됩니다. v1 봉투는 서명된 타임스탬프가 없으므로 신선도 확인을 건너뛰며 재전송 방지 기능을 제공하지 않습니다. v2 봉투(pqc-mcp-v2)는 허용되지만 모드 바인딩이 부족하며, 응답에 폐기 경고가 포함됩니다.

릴레이 전송

이 프로젝트에는 기계 간 A2A 메시징을 위한 Cloudflare Worker 릴레이가 포함되어 있습니다.

라이브: https://quantum-seal-relay.novoamorx1.workers.dev

릴레이는 불투명한 봉투 사서함으로, 암호화 작업을 수행하거나 개인 키에 접근하지 않고 JSON 블롭을 저장하고 전달합니다.

엔드포인트	메서드	목적
`/mailboxes/:fp`	POST	수신자의 사서함에 봉투 입금
`/mailboxes/:fp

양자 내성 암호(PQC) MCP 서버

왜 양자 내성 암호인가?

기능

빠른 시작

사전 요구 사항

설치

1. liboqs 설치

2. 복제 및 설치

3. Claude Code / Claude Desktop 구성

사용 가능한 도구

pqc_list_algorithms

pqc_algorithm_info

pqc_generate_keypair

pqc_encapsulate

pqc_decapsulate

pqc_sign

pqc_verify

pqc_hash

pqc_security_analysis