加密引擎接口规范书

加密引擎接口规范书一、接口概述加密引擎接口是实现数据加密、解密、签名、验签等密码学操作的核心组件，为上层应用提供标准化的密码服务调用方式。本规范定义了加密引擎接口的功能范围、调用方式、参数格式、返回结果及安全要求，确保不同应用系统在集成加密引擎时具备一致性、兼容性和安全性。接口设计遵循模块化、可扩展原则，支持对称加密、非对称加密、哈希运算、数字签名等多种密码学算法，满足金融、政务、医疗等多领域的数据安全需求。二、接口分类与功能定义2.1对称加密接口对称加密接口采用单密钥体系，同一密钥同时用于加密和解密，具有加密速度快、资源消耗低的特点，适用于大规模数据加密场景。2.1.1加密接口功能描述：接收明文数据和对称密钥，通过指定对称加密算法将明文转换为密文。支持算法：AES-128、AES-256、SM4、3DES等。参数说明：plaintext：待加密的明文数据，支持字符串、字节数组等格式，最大长度不超过10MB。key：对称加密密钥，需符合对应算法的密钥长度要求（如AES-128密钥为16字节），密钥需经过Base64编码传输。algorithm：指定加密算法，取值范围为"AES-128"、"AES-256"、"SM4"、"3DES"。mode：加密模式，支持ECB、CBC、GCM等，默认值为CBC。iv：初始化向量，仅在CBC、GCM等模式下必填，长度与算法分组长度一致（如AES为16字节），需经过Base64编码传输。返回结果：ciphertext：加密后的密文数据，采用Base64编码格式返回。tag：GCM模式下生成的认证标签，用于解密时验证数据完整性，可选返回。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如密钥长度错误、算法不支持等。2.1.2解密接口功能描述：接收密文数据、对称密钥及相关参数，通过对应对称加密算法将密文还原为明文。支持算法：与加密接口一致，需保证解密算法、模式与加密时完全匹配。参数说明：ciphertext：待解密的密文数据，采用Base64编码格式。key：对称加密密钥，与加密时使用的密钥一致，经过Base64编码传输。algorithm：指定解密算法，需与加密算法一致。mode：解密模式，需与加密模式一致。iv：初始化向量，需与加密时使用的iv一致，经过Base64编码传输。tag：GCM模式下的认证标签，与加密时生成的tag一致，可选参数。返回结果：plaintext：解密后的明文数据，支持字符串、字节数组等格式。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如密钥不匹配、密文损坏等。2.2非对称加密接口非对称加密接口采用公钥和私钥配对体系，公钥用于加密，私钥用于解密，适用于密钥交换、身份认证等场景。2.2.1公钥加密接口功能描述：接收明文数据和公钥，通过指定非对称加密算法将明文加密，仅能通过对应私钥解密。支持算法：RSA-2048、RSA-4096、SM2等。参数说明：plaintext：待加密的明文数据，由于非对称加密效率较低，明文长度需符合算法要求（如RSA-2048加密明文长度不超过245字节），支持字符串、字节数组等格式。public_key：公钥数据，采用PEM格式或Base64编码的DER格式，需符合对应算法的公钥标准。algorithm：指定加密算法，取值范围为"RSA-2048"、"RSA-4096"、"SM2"。返回结果：ciphertext：加密后的密文数据，采用Base64编码格式返回。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如公钥格式错误、明文过长等。2.2.2私钥解密接口功能描述：接收密文数据和私钥，通过对应非对称加密算法将密文还原为明文。支持算法：与公钥加密接口一致，需保证解密算法与加密时完全匹配。参数说明：ciphertext：待解密的密文数据，采用Base64编码格式。private_key：私钥数据，采用PEM格式或Base64编码的DER格式，需符合对应算法的私钥标准，部分算法需提供私钥密码（如RSA私钥加密存储时）。algorithm：指定解密算法，需与加密算法一致。passphrase：私钥密码，可选参数，当私钥经过加密存储时必填。返回结果：plaintext：解密后的明文数据，支持字符串、字节数组等格式。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如私钥不匹配、密文格式错误等。2.3哈希运算接口哈希运算接口将任意长度的输入数据转换为固定长度的哈希值，用于数据完整性校验、数字签名等场景。2.3.1哈希计算接口功能描述：接收输入数据，通过指定哈希算法计算对应的哈希值。支持算法：SHA-256、SHA-512、SM3、MD5（仅用于兼容性场景，不推荐用于安全需求高的场景）等。参数说明：data：待计算哈希值的输入数据，支持字符串、字节数组等格式，无长度限制。algorithm：指定哈希算法，取值范围为"SHA-256"、"SHA-512"、"SM3"、"MD5"。返回结果：hash_value：计算得到的哈希值，采用十六进制编码格式返回。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如算法不支持等。2.3.2HMAC计算接口功能描述：结合密钥和输入数据，通过指定哈希算法计算HMAC值，用于消息认证，防止数据篡改和伪造。支持算法：HMAC-SHA-256、HMAC-SHA-512、HMAC-SM3等。参数说明：data：待计算HMAC值的输入数据，支持字符串、字节数组等格式。key：HMAC密钥，长度需符合对应哈希算法的要求，经过Base64编码传输。algorithm：指定HMAC算法，取值范围为"HMAC-SHA-256"、"HMAC-SHA-512"、"HMAC-SM3"。返回结果：hmac_value：计算得到的HMAC值，采用十六进制编码格式返回。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如密钥长度错误等。2.4数字签名接口数字签名接口通过私钥对数据进行签名，接收方通过公钥验证签名，实现身份认证和数据完整性校验。2.4.1签名接口功能描述：接收原始数据和私钥，通过指定签名算法生成数字签名。支持算法：RSA-SHA256、ECDSA-SHA256、SM2等。参数说明：data：待签名的原始数据，支持字符串、字节数组等格式。private_key：私钥数据，采用PEM格式或Base64编码的DER格式，部分算法需提供私钥密码。algorithm：指定签名算法，取值范围为"RSA-SHA256"、"ECDSA-SHA256"、"SM2"。返回结果：signature：生成的数字签名，采用Base64编码格式返回。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如私钥无效、算法不支持等。2.4.2验签接口功能描述：接收原始数据、公钥和数字签名，通过对应签名算法验证签名的合法性。支持算法：与签名接口一致，需保证验签算法与签名时完全匹配。参数说明：data：原始数据，需与签名时的原始数据一致，支持字符串、字节数组等格式。public_key：公钥数据，采用PEM格式或Base64编码的DER格式，需与签名时使用的私钥配对。signature：待验证的数字签名，采用Base64编码格式。algorithm：指定验签算法，需与签名算法一致。返回结果：verify_result：验签结果，"true"表示签名合法，"false"表示签名不合法。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如公钥不匹配、签名格式错误等。2.5密钥管理接口密钥管理接口用于生成、存储、查询和销毁密码学密钥，确保密钥的安全性和生命周期管理。2.5.1密钥生成接口功能描述：根据指定算法和密钥长度生成对称密钥或非对称密钥对。支持算法：对称密钥算法（AES-128、AES-256、SM4等）、非对称密钥算法（RSA-2048、RSA-4096、SM2等）。参数说明：algorithm：指定密钥生成算法，取值范围包括对称和非对称算法标识。key_length：密钥长度，对称密钥需符合对应算法的密钥长度要求，非对称密钥如RSA-2048对应密钥长度为2048位。key_type：密钥类型，"symmetric"表示对称密钥，"asymmetric"表示非对称密钥对。返回结果：key：生成的对称密钥或非对称私钥，采用Base64编码格式返回，非对称密钥对同时返回公钥。public_key：非对称密钥对中的公钥，采用Base64编码格式返回，仅当key_type为"asymmetric"时返回。key_id：密钥唯一标识，用于后续密钥查询、销毁等操作。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如算法不支持、密钥长度错误等。2.5.2密钥查询接口功能描述：根据密钥唯一标识查询密钥的基本信息，包括算法、长度、创建时间、状态等，部分场景可返回密钥明文（需严格权限控制）。参数说明：key_id：密钥唯一标识，由密钥生成接口返回。return_plaintext：是否返回密钥明文，"true"表示返回，"false"表示仅返回密钥元数据，默认值为"false"。返回结果：key_info：密钥元数据，包括key_id、algorithm、key_length、create_time、status等字段。key：密钥明文，采用Base64编码格式返回，仅当return_plaintext为"true"且用户具备权限时返回。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如key_id不存在、权限不足等。2.5.3密钥销毁接口功能描述：根据密钥唯一标识销毁指定密钥，销毁后密钥无法再用于密码学操作。参数说明：key_id：密钥唯一标识，由密钥生成接口返回。返回结果：destroy_result：销毁结果，"success"表示销毁成功，"failed"表示销毁失败。status：接口调用状态，"success"表示调用成功，"failed"表示调用失败。error_msg：调用失败时的错误信息，如key_id不存在、密钥已销毁等。三、接口调用方式3.1HTTPRESTful接口加密引擎接口提供HTTPRESTful调用方式，支持GET、POST请求方法，推荐使用POST方法传输敏感数据。接口地址：基础URL为/crypto-engine，各功能接口路径如下：对称加密：/symmetric/encrypt对称解密：/symmetric/decrypt公钥加密：/asymmetric/encrypt私钥解密：/asymmetric/decrypt哈希计算：/hash/calculateHMAC计算：/hash/hmac签名：/signature/sign验签：/signature/verify密钥生成：/key/generate密钥查询：/key/query密钥销毁：/key/destroy请求头：Content-Type：请求数据格式，支持application/json、application/x-www-form-urlencoded，推荐使用application/json。Authorization：身份认证信息，采用BearerToken方式，格式为Bearer<token>，Token由认证系统颁发，用于验证调用者身份。请求参数：所有参数需按照JSON格式封装在请求体中，敏感数据如密钥、明文等需经过Base64编码。响应格式：返回结果采用JSON格式，包含状态码、响应信息及业务数据，HTTP状态码200表示请求成功，400表示请求参数错误，401表示身份认证失败，500表示服务器内部错误。3.2本地SDK调用针对Java、Python、Go等主流开发语言，提供加密引擎SDK，开发者可通过SDK直接调用加密引擎接口，简化集成流程。SDK安装：JavaSDK可通过Maven仓库引入，PythonSDK可通过pip安装，GoSDK可通过goget命令获取。调用示例（Java）：//初始化加密引擎客户端CryptoEngineClientclient=newCryptoEngineClient("/crypto-engine","your_token");//对称加密示例SymmetricEncryptRequestencryptRequest=newSymmetricEncryptRequest();encryptRequest.setPlaintext("Hello,World!");encryptRequest.setKey(Base64.getEncoder().encodeToString("aes128key1234567".getBytes()));encryptRequest.setAlgorithm("AES-128");encryptRequest.setMode("CBC");encryptRequest.setIv(Base64.getEncoder().encodeToString("initialvector123".getBytes()));SymmetricEncryptResponseencryptResponse=client.symmetricEncrypt(encryptRequest);if("success".equals(encryptResponse.getStatus())){System.out.println("密文："+encryptResponse.getCiphertext());}else{System.out.println("加密失败："+encryptResponse.getErrorMsg());}四、安全要求4.1身份认证与授权所有接口调用必须经过身份认证，采用OAuth2.0或JWT等认证机制，验证调用者身份合法性。基于角色的访问控制（RBAC），根据调用者角色分配不同权限，如密钥销毁接口仅允许管理员角色调用。认证Token需设置有效期，过期后需重新获取，Token传输过程中需采用HTTPS加密，防止被窃取。4.2数据传输安全所有接口通信必须采用HTTPS协议，使用TLS1.2及以上版本，配置合法的SSL证书，防止数据在传输过程中被窃听或篡改。敏感数据如密钥、明文、密文等需经过Base64编码或加密后传输，避免明文暴露。4.3密钥安全密钥生成需采用密码学安全的随机数生成器（CSPRNG），确保密钥的随机性和不可预测性。对称密钥和非对称私钥需加密存储，采用硬件安全模块（HSM）或密钥管理服务（KMS）进行密钥保护，禁止明文存储密钥。密钥生命周期管理，定期轮换密钥，对于不再使用的密钥及时销毁，防止密钥泄露后造成长期安全风险。4.4接口安全防护接口需实现请求频率限制，防止暴力破解和DDoS攻击，如每分钟调用次数不超过100次。输入参数校验，对所有输入参数进行合法性检查，包括数据格式、长度、范围等，防止注入攻击和非法参数调用。日志记录，记录所有接口调用请求和响应信息，包括调用者身份、请求时间、参数、返回结果等，日志需加密存储，保存期限不少于6个月，便于安全审计和故障排查。五、兼容性与版本管理5.1版本标识接口采用版本化管理，版本号格式为主版本号.次版本号.修订号，如1.0.0。主版本号变更表示接口功能发生重大变化，不兼容旧版本；次版本号变更表示新增功能，兼容旧版本；修订号变更表示修复漏洞或优化性能，完全兼容旧版本。5.2兼容性策略旧版本接口在新版本发布后需保留至少6个月的过渡期，便于开发者进行系统升级。接口参数和返回结果的新增字段需采用可选方式，避免影响旧版本客户端的正常调用。算法支持需兼顾兼容性和安全性，对于MD5、3DES等安全性较低的算法，仅保留兼容性支持，推荐使用SHA-256、AES-256、SM2等安全算法。5.3版本升级开发者可通过接口版本号指定调用的接口版本，在请求URL中添加版本标识，如/crypto-engine/v1/symmetric/encrypt。新版本发布后，需提供详细的升级文档，包括功能变更、参数变化、迁移步骤等，帮助开发者快速完成系统升级。六、异常处理与错误码6.1异常分类接口异常分为参数错误、业务逻辑错误、系统错误三类，不同类型异常返回对应的错误码和错误信息。参数错误：输入参数格式不正确、缺失必填参数、参数值超出范围等。业务逻辑错误：密钥不匹配、签名验证失败、密钥不存在等业务规则相关错误。系统错误：服务器内部故障、算法不支持、依赖服务不可用等系统层面错误。6.2错误码定义错误码错误类型错误描述40001参数错误