美人鱼到普罗里夫
- 作者仓库星标 0
- 作者更新于 2026年8月24日 23:09
- 作者仓库 skills
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @trailofbits · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
从美人鱼图中:提取每个`participant`或`actor`声明。每个都成为一个 ProVerif 流程。计算消息箭头(`->>`、`-->>`、`-x`、`--x`)。每个不同的`A ->> B: label`都会在通道上创建一个通信步骤。
浏览每个`Note over`注释和消息标签。构建所使用的所有不同操作的列表。将每个映射到 ProVerif 声明类别: Mermaid 注释 · ProVerif 类别 `keygen() → sk, pk` · 新名称 (`new sk`),通过函数 `DH(sk_A, pk_B)` 派生的公钥 · DH 函数或带有组的 `exp`
按此顺序构建加密序言: 类型 — 声明用于区分密钥材料的自定义类型: 常量 — 用于用作域分隔符或标签的固定字符串: 函数 — 构造函数和析构函数。析构函数使用内联`reduc`,以便进程在验证或解密失败时中止:
事件标志着协议执行中与安全相关的时刻。通过识别来提取它们: 开始事件 (`event beginRole(params)`):在一方发送依赖于长期身份承诺的消息之前立即触发(例如,在发送签名消息或 MAC 消息之前)。
为每个安全属性编写一个查询。选择:可达性(始终首先添加 - 结构健全性检查):验证成功事件实际上是可达的。如果 ProVerif 将其中任何一个报告为`false`,则该模型存在结构性错误(死接收、类型不匹配、不可能的防护),并且不应信任其他查询结果。一旦模型
为每个参与者编写一个`let`流程。按顺序构建每个流程以反映美人鱼图。两方协议的模板: 编写流程的规则: 图中的每个`A ->> B: msg_contents` 变为:
主要流程: 使用`new`生成长期密钥 通过`out(c, pk(sk))`向攻击者发布公钥 在复制(`!`)下并行运行参与者进程以允许多个会话
在写入文件之前: [ ] 图中的每个参与者都有一个匹配的 `let` 进程 [ ] 每个 `out(c, ...)` 在另一侧都有一个匹配的 `in(c, ...)` 且类型兼容 [ ] 进程中使用的每个函数都在序言中声明
# Mermaid to ProVerif
Reads a Mermaid `sequenceDiagram` describing a cryptographic protocol and
produces a ProVerif model (`.pv` file) that can be passed directly to the
ProVerif verifier.
**Tools used:** Read, Write, Grep, Glob.
The typical input is the output of the `crypto-protocol-diagram` skill — a
Mermaid `sequenceDiagram` annotated with cryptographic operations (`Sign`,
`Verify`, `DH`, `HKDF`, `Enc`, `Dec`, etc.) and message arrows.
## When to Use
- User asks to formally verify a cryptographic protocol described as a Mermaid sequenceDiagram
- User wants to generate a ProVerif model (.pv file) from a protocol diagram
- User wants to prove secrecy, authentication, or forward secrecy properties
- Input is the output of the `crypto-protocol-diagram` skill
## When NOT to Use
- No Mermaid sequenceDiagram exists yet — use `crypto-protocol-diagram` first to generate one
- User wants to verify properties of non-cryptographic systems (state machines, access control)
- User wants to run ProVerif on an existing .pv file — just run `proverif model.pv` directly
## Rationalizations to Reject
| Rationalization | Why It's Wrong | Required Action |
|-----------------|----------------|-----------------|
| "Reachability queries are just busywork" | If events aren't reachable, all other query results are meaningless | Always add reachability queries first as a sanity check |
| "Public channels are fine for all messages" | Private channels for internal state prevent false attacks | Use private channels for intra-process state threading |
| "I'll skip the forward secrecy test" | Ephemeral keys demand forward secrecy verification | Add the ForwardSecrecyTest process whenever the diagram shows ephemeral keys |
| "Unused declarations are harmless" | ProVerif may report spurious results from orphan declarations | Clean up all unused types, functions, and events |
| "The model compiles, so it's correct" | A compiling model can have dead receives, type mismatches, or impossible guards that make queries vacuously true | Validate reachability before trusting any security query |
| "I don't need to check the example first" | The example defines the expected output quality bar | Study `examples/simple-handshake/` before working on unfamiliar protocols |
---
## Workflow
```
ProVerif Model Progress:
- [ ] Step 1: Parse participants and channels
- [ ] Step 2: Inventory cryptographic operations
- [ ] Step 3: Declare types, functions, and equations
- [ ] Step 4: Identify and declare events
- [ ] Step 5: Formulate security queries
- [ ] Step 6: Write participant processes
- [ ] Step 7: Write main process and finalize
- [ ] Step 8: Verify and deliver
```
### Step 1: Parse Participants and Channels
From the Mermaid diagram:
1. Extract every `participant` or `actor` declaration. Each becomes a
ProVerif process.
2. Count message arrows (`->>`, `-->>`, `-x`, `--x`). Each distinct
`A ->> B: label` creates a communication step on a channel.
3. Decide channel model:
- **Public channel** for any message sent over the network before a
secure channel is established (e.g., ClientHello, ephemeral keys,
ciphertext to be decrypted by the peer).
- **Private channel** only for internal state threading within a single
party process (not for cross-party messages).
- Default: declare one shared public channel `c` for all cross-party
messages. Add per-flow channels only when two distinct parallel sessions
must be independent.
```proverif
free c: channel.
```
### Step 2: Inventory Cryptographic Operations
Walk through every `Note over` annotation and message label. Build a list of
all distinct operations used. Map each to a ProVerif declaration category:
| Mermaid annotation | ProVerif category |
|--------------------|-------------------|
| `keygen() → sk, pk` | New name (`new sk`), public key derived via function |
| `DH(sk_A, pk_B)` | DH function or `exp` with group |
| `Sign(sk, msg) → σ` | Signature function |
| `Verify(pk, msg, σ)` | Equation or destructor |
| `Enc(key, msg) → ct` | Symmetric or asymmetric encryption function |
| `Dec(key, ct) → msg` | Destructor (equation) |
| `HKDF(ikm, info) → k` | PRF/KDF function |
| `HMAC(key, msg) → tag` | MAC function |
| `H(msg) → digest` | Hash function |
| `Commit(v, r) → C` | Commitment function |
| `Open(C, v, r)` | Commitment equation |
Consult [references/crypto-to-proverif-mapping.md](references/crypto-to-proverif-mapping.md)
for exact ProVerif syntax for each.
### Step 3: Declare Types, Functions, and Equations
Build the cryptographic preamble in this order:
1. **Types** — declare custom types used to distinguish key material:
```proverif
type key.
type pkey. (* public key *)
type skey. (* secret key *)
type nonce.
```
2. **Constants** — for fixed strings used as domain separators or labels:
```proverif
const msg1_label: bitstring.
const msg2_label: bitstring.
const info_session_key: bitstring.
```
3. **Functions** — constructors and destructors. Destructors use inline `reduc`
so that the process aborts on verification or decryption failure:
```proverif
(* Asymmetric encryption *)
fun aenc(bitstring, pkey): bitstring.
fun adec(bitstring, skey): bitstring
reduc forall m: bitstring, k: skey;
adec(aenc(m, pk(k)), k) = m.
fun pk(skey): pkey.
(* Symmetric encryption / AEAD *)
fun aead_enc(bitstring, key): bitstring.
fun aead_dec(bitstring, key): bitstring
reduc forall m: bitstring, k: key;
aead_dec(aead_enc(m, k), k) = m.
(* Digital signatures — verify returns the message on success, aborts on failure *)
fun sign(bitstring, skey): bitstring.
fun verify(bitstring, bitstring, pkey): bitstring
reduc forall m: bitstring, k: skey;
verify(sign(m, k), m, pk(k)) = m.
(* KDF — first arg is key (from DH), second is bitstring (info/context) *)
fun hkdf(key, bitstring): key.
(* MAC *)
fun mac(bitstring, key): bitstring.
(* Hash *)
fun hash(bitstring): bitstring.
(* DH *)
fun dh(skey, pkey): key.
fun dhpk(skey): pkey.
(* Serialization — ProVerif is strongly typed: pkey cannot appear
* where bitstring is expected. Use these to build signed payloads. *)
fun pkey2bs(pkey): bitstring.
fun concat(bitstring, bitstring): bitstring.
```
4. **Equations** — algebraic identities on constructors only (not on destructors,
which already have their rewrite rules inline):
```proverif
equation forall sk_a: skey, sk_b: skey;
dh(sk_a, dhpk(sk_b)) = dh(sk_b, dhpk(sk_a)).
```
Only declare what the diagram actually uses. Do not add functions for
operations not present.
### Step 4: Identify and Declare Events
Events mark security-relevant moments in the protocol execution. Extract them
by identifying:
- **Begin events** (`event beginRole(params)`): triggered immediately before a
party sends a message that depends on a long-term identity commitment (e.g.,
right before sending a signed message or a MAC'd message).
- **End events** (`event endRole(params)`): triggered immediately after a party
successfully verifies the peer's identity (e.g., after `Verify(...)` or MAC
check passes, session key confirmed).
- **Secrecy markers**: any key or nonce that should remain unknown to the
attacker after the handshake.
```proverif
event beginI(pkey, pkey). (* pk_I, pk_R — fired before sending the signed message *)
event endI(pkey, pkey, key). (* pk_I, pk_R, session_key — fired after accepting *)
event beginR(pkey, pkey).
event endR(pkey, pkey, key).
```
Parameters should uniquely identify the session: the parties' public keys,
plus the session key or a transcript hash.
### Step 5: Formulate Security Queries
Write one query per security property. Choose from:
**Reachability (always add first — structural sanity check):**
Verify that the success events are actually reachable. If ProVerif reports any
of these as `false`, the model has a structural bug (dead receive, type mismatch,
impossible guard) and no other query result should be trusted. Once the model
is validated, comment them out if they slow down the main property checks:
```proverif
(* Sanity: both endpoints must be reachable — comment out once validated. *)
(*
query pk_i: pkey, pk_r: pkey, k: key; event(endI(pk_i, pk_r, k)).
query pk_i: pkey, pk_r: pkey, k: key; event(endR(pk_i, pk_r, k)).
*)
```
**Secrecy** (key not derivable by attacker):
Declare a private free name and encrypt it under the session key. The attacker
knowing `private_I` is equivalent to breaking the session key:
```proverif
free private_I: bitstring [private].
(* In process, after deriving sk_session: *)
out(c, aead_enc(private_I, sk_session));
(* Query: *)
query attacker(private_I).
```
**Weak authentication** (if B accepted, A ran at some point with matching
params — does not prevent replay):
```proverif
query pk_i: pkey, pk_r: pkey, k: key;
event(endR(pk_i, pk_r, k)) ==> event(beginI(pk_i, pk_r)).
```
**Injective authentication** (prevents replay — each B-accept corresponds to
a distinct A-run):
```proverif
query pk_i: pkey, pk_r: pkey, k: key;
inj-event(endR(pk_i, pk_r, k)) ==>
inj-event(beginI(pk_i, pk_r)).
```
**Forward secrecy**: add a `ForwardSecrecyTest` process to the main process
that leaks both long-term secret keys to the attacker, then check that a past
session key remains secret. Pair it with a `free fs_witness: key [private]`
declaration and `query attacker(fs_witness)`. See
[references/security-properties.md](references/security-properties.md) →
Forward Secrecy, and the worked example in
`examples/simple-handshake/sample-output.pv`.
Choose the strongest applicable query for each property. See
[references/security-properties.md](references/security-properties.md) for
the full decision tree.
### Step 6: Write Participant Processes
Write one `let` process per participant. Structure each process to mirror the
Mermaid diagram step-by-step, in order.
**Template for a two-party protocol:**
```proverif
let Initiator(sk_I: skey, pk_R: pkey) =
(* Step: generate ephemeral key *)
new ek_I: skey;
let epk_I = dhpk(ek_I) in
(* Step: sign and send msg1 — pkey2bs casts pkey to bitstring *)
let sig_I = sign(concat(msg1_label, pkey2bs(epk_I)), sk_I) in
event beginI(pk(sk_I), pk_R);
out(c, (epk_I, sig_I));
(* Step: receive msg2 *)
in(c, (epk_R: pkey, sig_R: bitstring));
(* Step: verify responder signature — destructor aborts on failure *)
let transcript = concat(pkey2bs(epk_I), pkey2bs(epk_R)) in
let _ = verify(sig_R, concat(msg2_label, transcript), pk_R) in
(* Step: derive session key *)
let dh_val = dh(ek_I, epk_R) in
let sk_session = hkdf(dh_val, concat(info_session_key, transcript)) in
event endI(pk(sk_I), pk_R, sk_session);
(* Secrecy witness: encrypt private_I under the session key.
* Declared as: free private_I: bitstring [private].
* The query attacker(private_I) checks the attacker cannot derive it. *)
out(c, aead_enc(private_I, sk_session)).
```
**Rules for writing processes:**
- Each `A ->> B: msg_contents` in the diagram becomes:
- `out(c, msg_contents)` in A's process
- `in(c, x)` (with matching destructuring) in B's process
- Each `Note over A: op → result` becomes a `let result = op in` binding
- Each `Note over A: Verify(...)` becomes a `let _ = verify(...) in`
binding (the destructor aborts on failure — no explicit else needed,
modeling abort)
- Use `alt` blocks in the diagram as `if/then/else` in the process
- Long-term keys are process parameters; ephemeral values use `new`
**N-party or MPC protocols:** write one process per distinct role. For
threshold protocols, write a single role process and replicate it `!N` times
in the main process.
### Step 7: Write Main Process and Finalize
The main process:
1. Generates long-term keys with `new`
2. Publishes public keys to the attacker via `out(c, pk(sk))`
3. Runs participant processes in parallel under replication (`!`) to allow
multiple sessions
4. Optionally leaks long-term keys for forward-secrecy analysis
```proverif
process
new sk_I: skey; let pk_I = pk(sk_I) in out(c, pk_I);
new sk_R: skey; let pk_R = pk(sk_R) in out(c, pk_R);
(
!Initiator(sk_I, pk_R)
| !Responder(sk_R, pk_I)
)
```
Place the full file in this order:
```
(* 1. Channel declarations (free c: channel. / free ch: channel [private].) *)
(* 2. noselect directives (if needed for termination) *)
(* 3. Type declarations *)
(* 4. Constants *)
(* 5. Function declarations *)
(* 6. Equations (algebraic identities on constructors only) *)
(* 7. Table declarations *)
(* 8. Events *)
(* 9. Queries *)
(* 10. Let processes *)
(* 11. Main process *)
```
### Step 8: Verify and Deliver
Before writing the file:
- [ ] Every participant in the diagram has a matching `let` process
- [ ] Every `out(c, ...)` has a matching `in(c, ...)` on the other side with
compatible types
- [ ] Every function used in a process is declared in the preamble
- [ ] Every destructor uses inline `reduc` (not a separate `equation` block)
- [ ] Every event in a query is declared and triggered in a process
- [ ] Long-term public keys are output to channel `c` in the main process
(attacker can see them — that is the Dolev-Yao model)
- [ ] No unused declarations (clean up anything added speculatively)
- [ ] If `table` declarations are present: every `insert T(...)` has a
corresponding `get T(...)` with compatible column types and matching
pattern constraints (`=key` vs bare name)
- [ ] If `noselect` is used: its tuple structure matches the actual message
shapes sent on `c` (e.g., pairs → `mess(c, (x, y))`)
- [ ] If the Key Exposure Oracle pattern is used: `event key_exposed(sk_type)`
is declared, the oracle `in(c, guess: sk_type); if pk(guess) = pk_new then
event key_exposed(guess)` appears at the end of the process that holds the
secret, and the query is `query x: sk_type; event(key_exposed(x))`
**Write the model to a `.pv` file.** Choose a filename from the protocol name,
e.g. `noise-xx-handshake.pv` or `x3dh-key-agreement.pv`.
After writing, print a brief summary:
```
Protocol: <Name>
Output: <filename>
Queries: <list each query and what property it tests>
Assumptions: <list modeling decisions and simplifications>
```
---
## Decision Tree
```
├─ No Mermaid diagram provided?
│ └─ Ask the user: "Please provide the Mermaid sequenceDiagram,
│ or run the crypto-protocol-diagram skill first."
│
├─ Diagram uses DH (not just symmetric crypto)?
│ └─ Use dh/dhpk with commutativity equation
│ See references/crypto-to-proverif-mapping.md → DH section
│
├─ Diagram uses asymmetric signatures (Sign/Verify)?
│ └─ Use sign/verify with inline reduc (not equation)
│ verify returns the message on success; let _ = verify(...) in to abort on failure
│ Distinguish signing key (skey) from verification key (pkey)
│
├─ Diagram has an "alt" block (abort path)?
│ └─ Model as if/then only — the else branch aborts (process terminates)
│ Do NOT add out(c, error_message) unless the diagram shows it
│
├─ Protocol has N > 2 parties?
│ └─ Write one process per role, use ! for replication
│ Pass participant index as a parameter if roles differ by index only
│
├─ Forward secrecy requested?
│ └─ Add a ForwardSecrecy variant in the main process that leaks
│ long-term sk after session; add secrecy query for past session_key
│ See references/security-properties.md → Forward Secrecy
│
├─ Type-checker rejects the model?
│ └─ ProVerif is typed: check every function arg type matches declaration.
│ bitstring is the catch-all; key/pkey/skey/nonce are stricter.
│ Cast with explicit constructors when needed.
│
├─ Protocol has cross-process state coordination (e.g., one process must wait
│ for another to record acceptance before proceeding)?
│ └─ Use ProVerif tables (table/insert/get)
│ See references/proverif-syntax.md → Tables
│
├─ Verification does not terminate after several minutes?
│ └─ Add noselect directive matching the message tuple structure on c
│ See references/proverif-syntax.md → noselect
│
├─ Protocol generates a private-type key (type sk [private]) that is never
│ output directly but whose secrecy should be verified?
│ └─ Use the Key Exposure Oracle pattern instead of query attacker(sk)
│ See references/security-properties.md → Key Exposure Oracle
│
└─ Unsure which security properties to verify?
└─ Default set: secrecy of session key + injective authentication
(both directions). Add forward secrecy if diagram shows ephemeral keys.
```
---
## Example
`examples/simple-handshake/` contains a worked example:
- **`diagram.md`** — Mermaid sequenceDiagram for a two-party authenticated key
exchange (X25519 DH + Ed25519 signing + HKDF)
- **`sample-output.pv`** — exact ProVerif model the skill should produce,
with secrecy and injective authentication queries
Study this before working on an unfamiliar protocol.
---
## Supporting Documentation
- **[references/crypto-to-proverif-mapping.md](references/crypto-to-proverif-mapping.md)** —
Mapping table from Mermaid cryptographic annotations to ProVerif function
declarations, equations, and process patterns
- **[references/proverif-syntax.md](references/proverif-syntax.md)** —
ProVerif language reference: types, functions, equations, processes, events,
queries, and common pitfalls
- **[references/security-properties.md](references/security-properties.md)** —
Decision guide for choosing the right queries: secrecy, authentication
(weak vs injective), forward secrecy, unlinkability, and how to model them
按说明文件中的顺序排列。
何时使用
何时不使用
拒绝的理由
第1步:解析参与者和渠道
第 2 步:盘点加密操作
文件/命令 -> sequenceDiagram · .pv · crypto-protocol-diagram · Sign · Verify · HKDF · Enc · Dec
内容校验值 -> 72ea4a4bea9a
当前原文的自动摘译,尚未人工审校。
何时使用
用户要求正式验证描述为 Mermaid 序列图的加密协议 用户想要从协议图生成 ProVerif 模型(.pv 文件) 用户想要证明保密、身份验证或前向保密属性 输入是
crypto-protocol-diagram技能的输出何时不使用
尚不存在 Mermaid 序列图 — 首先使用
crypto-protocol-diagram生成一个 用户想要验证非加密系统的属性(状态机、访问控制) 用户想要在现有 .pv 文件上运行 ProVerif — 只需直接运行proverif model.pv拒绝的理由
合理化 · 错误的原因 · 所需的操作 “可达性查询只是无用的工作” · 如果事件不可到达,所有其他查询结果都毫无意义 · 始终首先添加可达性查询作为完整性检查 “公共通道适用于所有消息” · 用于内部状态的专用通道可防止错误攻击 · 使用专用通道进行进程内状态线程 “我将跳过前向保密测试” · 临时密钥需要前向保密验证 · 添加 ForwardSecrecyTest每当图表显示临时密钥时就进行处理