安全多方计算接口规范书

安全多方计算接口规范书一、接口概述安全多方计算（SecureMulti-PartyComputation,SMPC）接口是实现多方数据协同计算的核心组件，旨在让多个参与方在不泄露各自原始数据的前提下，共同完成特定的计算任务。本规范书所定义的接口，适用于金融风控、医疗数据联合分析、政务数据共享等需要隐私保护的跨机构协作场景，为不同参与方的系统对接提供标准化的交互方式，确保计算过程的安全性、准确性和高效性。1.1接口设计目标隐私保护：通过加密算法和协议设计，确保参与方的原始数据在计算过程中始终处于加密状态，任何参与方或第三方都无法获取其他参与方的敏感信息。功能完备性：支持常见的多方计算任务，包括但不限于求和、求平均值、比较大小、机器学习模型训练等，满足不同场景下的计算需求。兼容性：接口设计遵循通用的网络通信协议和数据格式，能够与不同技术栈的系统进行对接，降低系统集成的复杂度。可扩展性：预留扩展接口，支持后续新增计算功能和加密算法，适应不断变化的业务需求和技术发展。性能优化：通过优化协议流程和算法实现，减少计算和通信开销，提高接口的响应速度和处理能力。1.2接口适用范围本规范书所定义的接口适用于以下场景：金融领域：多家银行联合进行风险评估，在不泄露客户具体信贷数据的前提下，计算客户的综合信用评分。医疗领域：多个医疗机构联合开展疾病研究，在保护患者隐私的前提下，分析疾病的发病规律和治疗效果。政务领域：不同政府部门之间共享数据，在不泄露公民个人隐私的前提下，进行人口统计、经济分析等工作。电商领域：多个电商平台联合进行用户行为分析，在保护用户隐私的前提下，优化商品推荐策略。二、接口基础规范2.1通信协议接口采用基于TCP/IP的HTTP/2协议进行通信，利用HTTP/2的多路复用、头部压缩等特性，提高通信效率和安全性。同时，支持TLS1.3加密协议，对通信数据进行端到端加密，防止数据在传输过程中被窃取或篡改。2.2数据格式接口的数据交互采用JSON格式，JSON具有轻量级、易解析、跨平台等优点，能够方便地在不同系统之间进行数据传输和处理。数据字段的命名采用驼峰命名法，确保数据的可读性和规范性。以下是一个简单的JSON数据示例：{"taskId":"1234567890","partyId":"partyA","data":"encrypted_data","timestamp":1620000000}2.3错误码规范为了方便接口调用方识别和处理错误，定义了以下错误码：|错误码|错误描述|处理建议||----|----|----||400|请求参数错误|检查请求参数是否完整、格式是否正确||401|身份认证失败|检查身份认证信息是否正确，重新进行身份认证||403|权限不足|确认当前用户是否具有调用该接口的权限||404|接口不存在|检查接口地址是否正确||500|服务器内部错误|联系系统管理员进行排查||501|计算任务不支持|确认当前接口是否支持该计算任务，或等待系统升级||502|参与方响应超时|检查参与方的网络连接是否正常，或重新发起计算请求|三、接口核心功能3.1身份认证接口身份认证接口用于验证参与方的身份合法性，确保只有授权的参与方能够接入系统。参与方在调用其他接口之前，必须先通过身份认证接口获取访问令牌（Token），后续的接口请求都需要携带该令牌进行身份验证。3.1.1请求参数参数名类型是否必填描述partyIdString是参与方唯一标识publicKeyString是参与方的公钥，用于加密身份认证信息timestampLong是请求时间戳，防止请求重放signatureString是对请求参数进行签名，确保请求的完整性和真实性3.1.2响应参数参数名类型描述codeInteger响应状态码，200表示成功，其他表示失败messageString响应消息，描述响应结果tokenString访问令牌，有效期为1小时expireTimeLong令牌过期时间戳3.1.3接口示例请求示例：POST/api/auth/loginHTTP/2Host:Content-Type:application/json{"partyId":"partyA","publicKey":"-----BEGINPUBLICKEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxZ6X7Q...\n-----ENDPUBLICKEY-----","timestamp":1620000000,"signature":"abcdef1234567890"}响应示例：{"code":200,"message":"身份认证成功","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","expireTime":1620003600}3.2计算任务创建接口计算任务创建接口用于发起一个新的多方计算任务，定义计算任务的类型、参与方、计算参数等信息。3.2.1请求参数参数名类型是否必填描述taskNameString是计算任务名称taskTypeString是计算任务类型，如SUM（求和）、AVERAGE（求平均值）、COMPARE（比较大小）等partiesArray是参与方列表，包含参与方的唯一标识paramsObject是计算任务的参数，如求和任务的参数为需要求和的数据标识列表timeoutInteger否任务超时时间，单位为秒，默认值为36003.2.2响应参数参数名类型描述codeInteger响应状态码，200表示成功，其他表示失败messageString响应消息，描述响应结果taskIdString计算任务唯一标识statusString任务状态，如CREATED（已创建）、RUNNING（运行中）、COMPLETED（已完成）、FAILED（失败）等3.2.3接口示例请求示例：POST/api/task/createHTTP/2Host:Content-Type:application/jsonAuthorization:BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...{"taskName":"多方求和计算","taskType":"SUM","parties":["partyA","partyB","partyC"],"params":{"dataIds":["data1","data2","data3"]},"timeout":1800}响应示例：{"code":200,"message":"计算任务创建成功","taskId":"1234567890","status":"CREATED"}3.3数据上传接口数据上传接口用于参与方将加密后的数据上传到计算节点，为后续的多方计算任务提供数据支持。参与方需要对原始数据进行加密处理，确保数据在上传和存储过程中的安全性。3.3.1请求参数参数名类型是否必填描述taskIdString是计算任务唯一标识partyIdString是参与方唯一标识encryptedDataString是加密后的数据，采用Base64编码dataIdString是数据唯一标识，用于在计算任务中区分不同的数据3.3.2响应参数参数名类型描述codeInteger响应状态码，200表示成功，其他表示失败messageString响应消息，描述响应结果dataIdString数据唯一标识statusString数据上传状态，如SUCCESS（成功）、FAILED（失败）等3.3.3接口示例请求示例：POST/api/data/uploadHTTP/2Host:Content-Type:application/jsonAuthorization:BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...{"taskId":"1234567890","partyId":"partyA","encryptedData":"encrypted_data_base64","dataId":"data1"}响应示例：{"code":200,"message":"数据上传成功","dataId":"data1","status":"SUCCESS"}3.4计算任务执行接口计算任务执行接口用于触发计算任务的执行，计算节点根据任务类型和参与方上传的加密数据，执行相应的多方计算协议，得到计算结果。3.4.1请求参数参数名类型是否必填描述taskIdString是计算任务唯一标识partyIdString是参与方唯一标识3.4.2响应参数参数名类型描述codeInteger响应状态码，200表示成功，其他表示失败messageString响应消息，描述响应结果taskIdString计算任务唯一标识statusString任务状态，如RUNNING（运行中）、COMPLETED（已完成）、FAILED（失败）等resultString计算结果，仅当任务状态为COMPLETED时返回，采用Base64编码3.4.3接口示例请求示例：POST/api/task/executeHTTP/2Host:Content-Type:application/jsonAuthorization:BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...{"taskId":"1234567890","partyId":"partyA"}响应示例：{"code":200,"message":"计算任务执行中","taskId":"1234567890","status":"RUNNING"}3.5任务状态查询接口任务状态查询接口用于参与方查询计算任务的当前状态和执行进度，及时了解任务的执行情况。3.5.1请求参数参数名类型是否必填描述taskIdString是计算任务唯一标识partyIdString是参与方唯一标识3.5.2响应参数参数名类型描述codeInteger响应状态码，200表示成功，其他表示失败messageString响应消息，描述响应结果taskIdString计算任务唯一标识statusString任务状态，如CREATED（已创建）、RUNNING（运行中）、COMPLETED（已完成）、FAILED（失败）等progressInteger任务执行进度，取值范围为0-100，仅当任务状态为RUNNING时返回resultString计算结果，仅当任务状态为COMPLETED时返回，采用Base64编码3.5.3接口示例请求示例：GET/api/task/status?taskId=1234567890&partyId=partyAHTTP/2Host:Authorization:BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...响应示例：{"code":200,"message":"任务状态查询成功","taskId":"1234567890","status":"RUNNING","progress":50}四、安全规范4.1数据加密机制参与方在上传数据之前，需要采用对称加密算法（如AES-256）对原始数据进行加密，生成加密数据。同时，采用非对称加密算法（如RSA-2048）对对称加密密钥进行加密，确保密钥的安全性。计算节点在接收到加密数据和加密密钥后，使用自身的私钥解密得到对称加密密钥，再使用对称加密密钥解密得到原始数据的加密份额，用于后续的多方计算。4.2身份认证机制采用基于JSONWebToken（JWT）的身份认证机制，参与方在调用接口之前，需要先通过身份认证接口获取JWT令牌。JWT令牌包含参与方的身份信息和过期时间，使用数字签名算法（如HMAC-SHA256）进行签名，确保令牌的真实性和完整性。接口服务端在接收到请求后，验证JWT令牌的签名和过期时间，只有验证通过的请求才能被处理。4.3访问控制机制基于角色的访问控制（Role-BasedAccessControl,RBAC）机制，为不同的参与方分配不同的角色和权限。例如，系统管理员具有创建计算任务、管理参与方等全部权限，普通参与方仅具有上传数据、查询任务状态等权限。接口服务端在处理请求时，根据参与方的角色和权限，判断其是否具有调用该接口的权限。4.4数据完整性校验在数据上传和计算结果返回过程中，采用哈希算法（如SHA-256）对数据进行完整性校验。参与方在上传数据时，计算数据的哈希值并随数据一起上传；接口服务端在接收到数据后，重新计算数据的哈希值，并与上传的哈希值进行比较，确保数据在传输过程中没有被篡改。同样，在返回计算结果时，接口服务端计算结果的哈希值并随结果一起返回；参与方在接收到结果后，重新计算结果的哈希值，并与返回的哈希值进行比较，确保结果的完整性。4.5审计日志机制接口服务端记录所有的接口调用日志，包括请求时间、请求参数、响应结果、参与方标识等信息。审计日志采用加密存储的方式，确保日志数据的安全性。系统管理员可以通过审计日志查询接口的调用情况，及时发现异常行为和安全事件。五、性能优化规范5.1协议优化采用基于秘密共享的多方计算协议，减少参与方之间的通信次数和数据传输量。例如，在求和计算任务中，参与方只需要将自己数据的加密份额发送给计算节点，而不需要发送原始数据，大大减少了通信开销。同时，优化协议的执行流程，减少不必要的计算步骤，提高计算效率。5.2算法优化选择高效的加密算法和计算算法，提高接口的处理能力。例如，采用椭圆曲线加密算法（ECC）替代传统的RSA算法，在相同的安全级别下，ECC算法具有更短的密钥长度和更快的计算速度。在机器学习模型训练任务中，采用联邦学习算法，将模型训练任务分布到各个参与方本地进行，只需要传输模型参数的更新值，减少了数据传输量和计算开销。5.3资源调度优化采用分布式计算架构，将计算任务分配到多个计算节点上并行执行，提高计算任务的处理速度。同时，根据计算任务的类型和数据量，动态调整计算节点的资源分配，确保计算资源的高效利用。例如，对于数据量较大的计算任务，分配更多的计算节点和内存资源；对于计算复杂度较高的任务，分配更多的CPU资源。5.4缓存机制在接口服务端引入缓存机制，对频繁查询的数据和计算结果进行缓存，减少重复计算和数据查询的开销。例如，对于任务状态查询接口，将查询结果缓存一定的时间，当参与方再次查询时，直接返回缓存的结果，而不需要重新查询数据库。同时，采用缓存失效机制，确保缓存数据的时效性和准确性。六、接口测试规范6.1功能测试对接口的各项功能进行全面测试，确保接口能够按照设计要求完成相应的计算任务。测试内容包括身份认证、任务创建、数据上传、任务执行、任务状态查询等接口的功能正确性，以及不同计算任务类型的计算结果准确性。例如，在求和计算任务测试中，验证多个参与方上传的数据加密份额经过计算后，得到的求和结果与原始数据的求和结果是否一致。6.2性能测试对接口的性能进行测试，评估接口的响应时间、吞吐量和并发处理能力。测试内容包括在不同数据量、不同参与方数量的情况下，接口的响应时间和处理速度，以及在高并发场景下，接口的稳定性和可靠性。例如，模拟100个参与方同时上传数据和执行计算任务，测试接口的响应时间和错误率。6.3安全测试对接口的安全性进行测试，验证接口的加密机制、身份认证机制、访问控制机制等是否能够有效保护数据的安全。测试内容包括数据加密强度测试、身份认证绕过测试、权限越权测试、数据完整性篡改测试等。例如，尝试使用伪造的JWT令牌调用接口，测试接口是否能够正确识别并拒绝该请求。6.4兼容性测试对接口的兼容性进行测试，确保接口能够与不同技术栈的系统进行对接。测试内容包括在不同操作系统（如Windows、Linux、macOS）、不同编程语言（如Java、Python、Go）、不同Web服务器（如Nginx、Apache）环境下，接口的对接情况和功能正确性。例如，使用Python编写的客户端程序调用接口，测试接口是否能够正常响应并返回正确的结果。七、接口维护与升级规范7.1版本管理采用语义化版本控制（SemanticVersioning）对接口进行版本管理，版本号格式为“主版本号.次版本号.修订版本号”。主版本号的升级表示接口的不兼容变更，次版本号的升级表示接口的新增功能，修订版本号的升级表示接口的bug修复和性能优化。在接口URL中包含版本号信息，如“/api/v1/task/create”，确保不同版本的接口能够同时存在和使用。7.2变更通知在接口进行版本升级