1. 密码API全景认知
密码API（Cryptographic API）是操作系统、语言运行时或第三方库向应用开发者暴露的一组用于实现机密性、完整性、身份认证与不可否认性的编程接口。它把复杂的数学运算（如大数模幂、椭圆曲线点乘、分组密码轮函数）封装成可调用的函数、类或服务，使开发者无需自行实现密码算法，也能在业务系统中正确使用密码能力。理解密码API，关键不是记住某个函数名，而是建立"算法—模式—填充—密钥—接口"这条完整链路的心智模型。
一、密码API的定义与边界
从工程视角看，密码API至少包含四类要素：算法标识（如AES、RSA、SM4、SHA-256）、工作模式与填充（如GCM、CBC、PKCS#7）、密钥与参数（密钥长度、IV、Nonce、盐值）、以及调用契约（输入输出格式、错误码、线程安全性）。密码API与普通业务API最大的区别在于：它的错误往往不是"功能不可用"，而是"安全属性被静默破坏"。例如CBC模式若未做完整性校验，攻击者可通过篡改密文影响明文；ECB模式会泄露明文分组结构。因此，密码API的使用必须建立在"先明确安全目标，再选择算法与模式"的顺序上，而不是反过来。
二、密码API的分类
按功能划分，密码API通常分为五类：
- 对称加密API：AES、SM4、ChaCha20等，用于批量数据加密，速度快，适合大数据量场景。
- 非对称加密API：RSA、ECC、SM2等，用于密钥交换、数字信封和签名验证，计算开销较大。
- 哈希与消息认证API：SHA-2、SHA-3、SM3、HMAC，用于完整性校验和密钥派生。
- 密钥派生与协商API：PBKDF2、scrypt、Argon2、HKDF、ECDH，用于从口令或共享秘密生成密钥。
- 随机数与密钥管理API：CSPRNG、KeyStore、KMS接口，负责生成、存储、轮换和销毁密钥。
按抽象层次划分，又可分为底层原语API（如OpenSSL EVP、Java JCA）、高层封装API（如Google Tink、libsodium）和云服务API（如AWS KMS、阿里云KMS）。底层API灵活但易误用，高层API通过"安全默认值"降低误用概率，云KMS则把密钥托管与访问控制交给基础设施。
三、典型应用场景
密码API在真实系统中无处不在，典型场景包括：
- 传输安全：TLS/HTTPS握手使用ECDHE做密钥协商、RSA/ECDSA做身份认证、AES-GCM做记录层加密。
- 数据存储加密：数据库字段加密常用AES-GCM或SM4-GCM，密钥由KMS托管，密文与IV、Tag一起存储。
- 身份认证与令牌：JWT签名使用HMAC-SHA256或RS256/ES256，密码存储使用PBKDF2、bcrypt或Argon2加盐哈希。
- 数字签名与验签：电子合同、代码签名、区块链交易使用ECDSA或SM2签名，验签方用公钥验证。
- 密钥交换与信封加密：大文件加密采用"随机生成数据密钥→对称加密数据→非对称加密数据密钥"的数字信封模式。
四、开发挑战与常见误区
密码API的难点不在"会不会调用"，而在"是否用对"。常见挑战包括：
- 模式与填充误用：CBC需要随机IV且必须做完整性保护；ECB不应加密超过一个分组的结构化数据；GCM的Nonce绝不能重复。
- 密钥管理薄弱：硬编码密钥、密钥与密文同库存储、长期不轮换，都会让加密形同虚设。
- 随机数不安全：使用
Math.random()或时间戳生成IV/盐值，会导致可预测性漏洞。 - 错误处理泄露信息：填充 oracle、时序差异可能被利用进行旁路攻击。
- 算法过时：MD5、SHA-1、DES、RC4已不应在新系统中使用。
五、课程实践目标与工具链
本课程以"能正确调用、能验证结果、能排查问题"为目标，围绕以下工具链展开实践：
| 层次 | 工具/库 | 用途 |
|---|---|---|
| 语言运行时 | Java JCA/JCE、Python cryptography、Go crypto | 调用标准算法API |
| 底层库 | OpenSSL 3.x、BouncyCastle | 命令行验证与算法实验 |
| 高层封装 | Google Tink、libsodium | 安全默认值实践 |
| 密钥管理 | 本地KeyStore、云KMS模拟 | 密钥生命周期管理 |
| 验证工具 | openssl命令行、jwt.io、测试向量 | 结果比对与排障 |
实践环境建议统一使用OpenSSL 3.x与Python 3.11+，所有示例参数（密钥长度、IV、盐值、迭代次数）均明确标注为教学示例，实际生产需根据合规要求与性能预算调整。例如AES-256-GCM的Nonce建议12字节随机生成，PBKDF2迭代次数在2024年建议不低于600,000次（OWASP建议值），Argon2id推荐内存64MB、迭代3次、并行度4。这些参数不是固定答案，而是需要结合场景权衡的起点。