ChipWhisperer API完全参考：Python接口与脚本开发实战

戴策峥Homer

418人浏览 · 2026-03-01 01:09:12

戴策峥Homer · 2026-03-01 01:09:12 发布

ChipWhisperer API完全参考：Python接口与脚本开发实战

【免费下载链接】chipwhisperer ChipWhisperer - the complete open-source toolchain for side-channel power analysis and glitching attacks 项目地址: https://gitcode.com/gh_mirrors/ch/chipwhisperer

ChipWhisperer是一款开源的侧信道功率分析与故障注入工具链，其Python API为硬件控制、数据采集和攻击分析提供了完整的编程接口。本文将详细介绍ChipWhisperer的核心API组件、使用流程和实战案例，帮助开发者快速掌握脚本开发技巧。

一、API架构概览

ChipWhisperer的Python API采用模块化设计，主要包含四大核心模块：

Scope模块：控制捕获硬件（如ChipWhisperer Lite/Pro/Husky），负责配置采样参数、触发条件和数据采集
Target模块：与目标设备通信，支持SimpleSerial等协议
Analyzer模块：提供侧信道分析功能，包括CPA、DPA等攻击算法
Trace模块：处理和存储捕获的波形数据

ChipWhisperer Lite硬件架构示意图，展示了API控制的主要硬件组件

核心API路径

Scope控制：software/chipwhisperer/capture/scopes/OpenADC.py
攻击分析：software/chipwhisperer/analyzer/attacks/
目标通信：software/chipwhisperer/capture/targets/SimpleSerial.py

二、环境准备与基础配置

快速安装与初始化

import chipwhisperer as cw

# 连接设备
scope = cw.scope()
target = cw.target(scope)

# 基础配置
scope.default_setup()

关键参数配置

Scope模块的default_setup()方法提供了常用配置，主要包括：

采样率：默认29.53MHz
采样点数：5000点
增益：25dB
触发方式：上升沿触发

如需自定义配置，可直接修改相关属性：

# 配置采样参数
scope.adc.samples = 10000  # 设置采样点数
scope.gain.db = 30         # 设置增益为30dB
scope.clock.clkgen_freq = 7.37e6  # 设置时钟频率

# 配置触发
scope.trigger.triggers = "tio4"  # 使用TIO4作为触发源
scope.adc.basic_mode = "rising_edge"  # 上升沿触发

ChipWhisperer Pro的触发设置界面，对应API中的trigger属性配置

三、数据采集核心API

基本采集流程

# 武装示波器
scope.arm()

# 发送明文并触发采集
target.simpleserial_write('p', b'00112233445566778899aabbccddeeff')

# 等待采集完成
scope.capture()

# 获取波形数据
waveform = scope.get_last_trace()

高级采集功能

1. 连续采集与分段模式

Husky设备支持分段采集模式，可在单次采集中捕获多个触发事件：

# 配置分段采集
scope.adc.segments = 4  # 4个分段
scope.adc.samples = 2500  # 每段2500点

# 采集分段数据
scope.arm()
for _ in range(4):
    target.simpleserial_write('p', b'0011223344556677')
scope.capture()

# 获取分段数据
segments = scope.get_last_trace_segmented()

2. 流模式采集

对于需要长时间连续采集的场景，可使用流模式：

# 配置流模式
scope.adc.stream_mode = True
scope.adc.samples = 100000  # 总采样点数

# 开始流采集
scope.arm()
scope.capture(poll_done=True)
stream_data = scope.get_last_trace()

Husky设备的流模式采集示意图，适用于长时间数据记录

四、侧信道攻击API实战

CPA攻击基础流程

from chipwhisperer.analyzer import Attack, aes

# 创建攻击对象
attack = Attack(None, aes)
attack.model = aes.leakage_models.sbox_output

# 配置攻击参数
attack.set_trace_source(traces)
attack.config.set("subkey", 0)  # 攻击第0个子密钥

# 执行攻击
results = attack.run()

# 显示结果
print(results)

系数分析与可视化

Analyzer模块提供了系数随迹数变化的分析工具：

from chipwhisperer.analyzer.attacks.coefficient_vs_trace_number import CoefficientVsTracesNumber

# 创建系数分析对象
coefficient_analyzer = CoefficientVsTracesNumber(
    traces=project.traces,
    subkey_index=0,
    interval=100,
    leak_model=aes.leakage_models.sbox_output
)

# 计算系数变化
results = coefficient_analyzer.get_effecient()

# 绘制结果
coefficient_analyzer.plot_and_save(results, figsize=[20,8], save_path="coefficient_plot.png")

不同子密钥猜测的相关系数随迹数变化曲线

五、故障注入控制API

电压故障注入

# 配置电压故障
scope.glitch_setup("voltage")
scope.glitch.output = "glitch_only"
scope.glitch.trigger_src = "ext_single"
scope.glitch.repeat = 10  # 故障重复次数

# 执行故障注入
scope.arm()
target.simpleserial_write('p', b'0011223344556677')
scope.capture()

时钟故障注入

# 配置时钟故障
scope.glitch_setup("clock")
scope.glitch.clk_src = "pll"
scope.glitch.width = 20  # 故障宽度(ns)
scope.glitch.offset = 10  # 故障偏移(ns)

# 执行故障注入
scope.arm()
target.simpleserial_write('p', b'0011223344556677')
scope.glitch.manual_trigger()

Husky设备的故障注入参数配置界面

六、实用脚本示例

1. 自动采集脚本

import chipwhisperer as cw
import numpy as np

# 初始化设备
scope = cw.scope()
target = cw.target(scope)
scope.default_setup()

# 准备明文和密钥
key = bytearray([0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6, 0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c])
traces = []

# 采集100条迹
for i in range(100):
    # 生成随机明文
    plaintext = np.random.randint(0, 256, 16, dtype=np.uint8)
    
    # 采集迹
    scope.arm()
    target.simpleserial_write('k', key)
    target.simpleserial_write('p', plaintext)
    scope.capture()
    
    # 保存迹
    traces.append({
        'wave': scope.get_last_trace(),
        'plaintext': plaintext,
        'key': key
    })
    print(f"Captured trace {i+1}/100")

# 保存数据
np.save('traces.npy', traces)

2. 批量攻击脚本

from chipwhisperer.analyzer import Attack, aes
import numpy as np

# 加载数据
traces = np.load('traces.npy', allow_pickle=True)

# 配置攻击
attack = Attack(None, aes)
attack.model = aes.leakage_models.sbox_output
attack.set_trace_source(traces)

# 攻击所有16个子密钥
results = []
for subkey in range(16):
    attack.config.set("subkey", subkey)
    res = attack.run()
    results.append(res)
    print(f"Subkey {subkey}: {res.key_guess}")

# 保存结果
np.save('attack_results.npy', results)

七、API高级应用技巧

1. 多设备同步控制

对于多设备协同实验，可通过指定序列号连接多个设备：

# 连接多个设备
scope1 = cw.scope(sn="CW314000000")
scope2 = cw.scope(sn="CW314000001")

# 同步配置
for scope in [scope1, scope2]:
    scope.default_setup()
    scope.clock.clkgen_freq = 10e6

2. 自定义触发条件

Husky设备支持复杂的触发条件配置：

# 配置SAD触发
scope.SAD.enabled = True
scope.SAD.reference = reference_waveform  # 设置参考波形
scope.SAD.threshold = 0.8  # 设置阈值
scope.trigger.module = "SAD"  # 使用SAD触发

ChipWhisperer Pro的SAD触发配置界面

八、常见问题与解决方案

设备连接问题

若无法连接设备，可尝试重置USB连接：

# 重置USB设备
scope.dis()
scope.con()

采样率配置

不同设备支持的最大采样率不同：

Lite: 约45MHz
Pro: 约105MHz
Husky: 最高200MHz

# 配置Husky最高采样率
scope.clock.adc_mul = 8
scope.clock.clkgen_freq = 25e6  # 25MHz * 8 = 200MHz

性能优化

对于大规模数据采集，建议使用二进制格式存储迹数据：

# 高效存储迹数据
import h5py

with h5py.File('traces.h5', 'w') as f:
    f.create_dataset('waves', data=np.array([t['wave'] for t in traces]))
    f.create_dataset('plaintexts', data=np.array([t['plaintext'] for t in traces]))

九、总结与资源

ChipWhisperer Python API提供了灵活而强大的硬件控制和数据分析能力，通过本文介绍的核心接口和实战示例，开发者可以快速构建自定义的侧信道分析与故障注入实验。

官方资源

完整API文档：docs/source/index.rst
示例脚本：jupyter/目录下的Jupyter notebooks
硬件规格：docs/source/Capture/ChipWhisperer-Lite.md

通过掌握这些API，您可以充分发挥ChipWhisperer的潜力，开展从基础研究到高级安全评估的各类实验。无论是学术研究、产品测试还是安全教学，ChipWhisperer的Python API都能为您提供可靠而高效的工具支持。

要开始使用ChipWhisperer API，只需克隆仓库并安装依赖：

git clone https://gitcode.com/gh_mirrors/ch/chipwhisperer
cd chipwhisperer
pip install -r requirements.txt

立即开始您的侧信道分析之旅吧！

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

Windows部署OpenClaw：PowerShell安装、自定义模型与远程访问实测

AI Agent技术社区

深入理解 AI Agent · MEMORY #02：记忆的工程机制

AI Agent技术社区

DeepSeek V4 Pro正式版上线：AI Agent能力跃升背后的行业趋势

AI Agent技术社区

所有评论(0)

查看更多评论

戴策峥Homer

@gitblog_00720

已为社区贡献42条内容

ChipWhisperer API完全参考：Python接口与脚本开发实战

戴策峥Homer

ChipWhisperer API完全参考：Python接口与脚本开发实战

一、API架构概览

核心API路径

二、环境准备与基础配置

快速安装与初始化

关键参数配置

三、数据采集核心API

基本采集流程

高级采集功能

1. 连续采集与分段模式

2. 流模式采集

四、侧信道攻击API实战

CPA攻击基础流程

系数分析与可视化

五、故障注入控制API

电压故障注入

时钟故障注入

六、实用脚本示例

1. 自动采集脚本

2. 批量攻击脚本

七、API高级应用技巧

1. 多设备同步控制

2. 自定义触发条件

八、常见问题与解决方案

设备连接问题

采样率配置

性能优化

九、总结与资源

官方资源

所有评论(0)

温馨提示：您尚未绑定手机号

戴策峥Homer