feifei.xu/autosar_standard_spec_v4.4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
79acbf4cbe671a8bd5cb83a7916a8c40e14a559d
autosar_standard_spec_v4.4/Crypto/AUTOSAR_SWS_CryptoInterface.md
T

1009 lines
56 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 加密接口规范 (Specification of Crypto Interface)
**AUTOSAR CP Release 4.4.0**
> 翻译说明：本文档为 AUTOSAR 经典平台 (CP) Release 4.4.0 中 SWS 文档 806《Specification of Crypto Interface》的中文翻译版本。原始英文文档中的 AUTOSAR 方框符 `⌈⌋`、API 标识符（如 `CryIf_ProcessJob`）、模块缩写（Crypto、CryIf、Csm、KeyM 等）、加密算法名（AES、SHA、RSA、ECC 等）以及需求 ID（如 `SWS_CryIf_xxxxx`）均予以保留。
## 文档标识
| 项目 | 内容 |
|---|---|
| 文档标题 (Document Title) | Specification of Crypto Interface（加密接口规范） |
| 文档所有者 (Document Owner) | AUTOSAR |
| 文档责任方 (Document Responsibility) | AUTOSAR |
| 文档标识号 (Document Identification No) | 806 |
| 文档状态 (Document Status) | Final |
| 所属 AUTOSAR 标准 | Classic Platform |
| 所属标准版本 (Part of Standard Release) | 4.4.0 |
## 文档变更历史 (Document Change History)
| 日期 | 版本 | 变更者 | 变更描述 |
|---|---|---|---|
| 2018-10-31 | 4.4.0 | AUTOSAR Release Management | 移除安全计数器；对齐接口函数的返回值；支持加密驱动内加密操作的源缓冲区和目标缓冲区；支持异步模式下的密钥管理操作 |
| 2017-12-08 | 4.3.1 | AUTOSAR Release Management | 小修正、澄清和编辑性修订；详细信息请参阅 ChangeDocumentation |
| 2016-11-30 | 4.3.0 | AUTOSAR Release Management | 初始发布 |
---
## 目录 (Table of Contents)
- [1 引言与功能概述](#1-引言与功能概述)
- [2 缩略语和缩写](#2-缩略语和缩写)
- [2.1 术语表](#21-术语表)
- [3 相关文档](#3-相关文档)
- [3.1 输入文档](#31-输入文档)
- [3.2 相关标准和规范](#32-相关标准和规范)
- [3.3 相关规范](#33-相关规范)
- [4 约束和假设](#4-约束和假设)
- [4.1 限制](#41-限制)
- [4.2 对汽车域的适用性](#42-对汽车域的适用性)
- [5 对其他模块的依赖](#5-对其他模块的依赖)
- [5.1 文件结构](#51-文件结构)
- [5.1.1 代码文件结构](#511-代码文件结构)
- [6 需求可追溯性](#6-需求可追溯性)
- [7 功能规范](#7-功能规范)
- [7.1 错误分类](#71-错误分类)
- [7.1.1 开发错误](#711-开发错误)
- [7.1.2 运行时错误](#712-运行时错误)
- [7.1.3 瞬态故障](#713-瞬态故障)
- [7.1.4 生产错误](#714-生产错误)
- [7.1.5 扩展生产错误](#715-扩展生产错误)
- [8 API 规范](#8-api-规范)
- [8.1 导入类型](#81-导入类型)
- [8.2 类型定义](#82-类型定义)
- [8.3 函数定义](#83-函数定义)
- [8.3.1 通用 API](#831-通用-api)
- [8.3.2 作业处理接口](#832-作业处理接口)
- [8.3.3 作业取消接口](#833-作业取消接口)
- [8.3.4 密钥管理接口](#834-密钥管理接口)
- [8.4 回调通知](#84-回调通知)
- [8.5 预期接口](#85-预期接口)
- [9 序列图](#9-序列图)
- [10 配置规范](#10-配置规范)
---
## 1 引言与功能概述
本规范规定了 AUTOSAR 基础软件模块 Crypto Interface (CRYIF) 的功能、API 和配置。
Crypto Interface 模块位于低层加密解决方案（Crypto Driver [4] 和基于软件的 CDD）与上层服务层（Crypto Service Manager [5]）之间。它表示上层服务层到 Crypto Driver 服务的接口。AUTOSAR 分层视图见图 7.1。
Crypto Interface 模块提供一个统一的接口来管理不同的加密硬件和软件解决方案，如 HSM、SHE 或基于软件的 CDD。因此，多个底层内部和外部加密硬件以及软件解决方案可由 Crypto Service Manager 模块基于 Crypto Interface 维护的映射方案加以使用。
---
## 2 缩略语和缩写
下表包含 AUTOSAR 术语表 [7] 中未涉及的、但与 Crypto Interface 模块相关的缩略语和缩写：
| 缩写 | 描述 |
|---|---|
| CDD | 复杂驱动 (Complex Device Driver) |
| CSM | 加密服务管理器 (Crypto Service Manager) |
| CRYIF | 加密接口 (Crypto Interface) |
| CRYPTO | 加密驱动 (Crypto Driver) |
| DET | 默认错误追踪器 (Default Error Tracer) |
| HSM | 硬件安全模块 (Hardware Security Module) |
| HW | 硬件 (Hardware) |
| SHE | 安全硬件扩展 (Security Hardware Extension) |
| SW | 软件 (Software) |
### 2.1 术语表
| 术语 | 描述 |
|---|---|
| Crypto Driver Object (加密驱动对象) | Crypto Driver Object 是加密模块（硬件或软件）的一个实例，能够执行一种或多种不同的加密操作。 |
| Key (密钥) | 密钥可由 CSM 中的作业引用。在 Crypto Driver 中，密钥引用特定的密钥类型。 |
| Key Type (密钥类型) | 密钥类型由对若干密钥元素的引用构成。密钥类型通常由 Crypto Driver 的供应商预配置。 |
| Key Element (密钥元素) | 密钥元素用于存储数据。该数据可以是例如密钥材料，或 AES 加密所需的 IV。它也可用于配置密钥管理功能的行为。 |
| Channel (通道) | 通道是从 CSM 队列经 Crypto Interface 到特定 Crypto Driver Object 的路径。 |
| Job (作业) | 作业是已配置的加密原语的一个实例。 |
| Crypto Primitive (加密原语) | 加密原语是已配置加密算法的一个实例。 |
| Operation (操作) | 加密原语的操作声明应执行该加密原语的哪一部分。有三种不同的操作： **START**：表示加密原语的全新请求，并应取消之前的所有请求； **UPDATE**：表示加密原语期望输入数据； **FINISH**：表示在此部分之后所有数据均已完全送入，加密原语可以完成计算。也可以通过将 operation mode 参数的对应位串接在一起，一次执行多个操作。 |
| Priority (优先级) | 作业的优先级定义其重要性。优先级越高（值越大），作业被越立即地执行。加密作业的优先级是配置的一部分。 |
| Processing (处理模式) | 指示作业的处理方式。 **异步 (Asynchronous)**：调用对应函数时作业不会立即被处理。通常，当作业完成时通过回调函数通知调用者。 **同步 (Synchronous)**：调用对应函数时作业被立即处理。函数返回时即可获得结果。 |
---
## 3 相关文档
### 3.1 输入文档
- [1] AUTOSAR Layered Software Architecture — `AUTOSAR_EXP_LayeredSoftwareArchitecture.pdf`
- [2] AUTOSAR General Requirements on Basic Software Modules — `AUTOSAR_SRS_BSWGeneral.pdf`
- [3] AUTOSAR General Specification for Basic Software Modules — `AUTOSAR_SWS_BSWGeneral.pdf`
- [4] AUTOSAR Specification of Crypto Driver — `AUTOSAR_SWS_CryptoDriver.pdf`
- [5] AUTOSAR Specification of Crypto Service Manager — `AUTOSAR_SWS_CryptoServiceManager.pdf`
- [6] AUTOSAR Requirements on Crypto Modules — `AUTOSAR_SRS_CryptoStack.pdf`
- [7] Glossary — `AUTOSAR_TR_Glossary`
### 3.2 相关标准和规范
- [8] IEC 7498-1 The Basic Model, IEC Norm, 1994
### 3.3 相关规范
AUTOSAR 提供了基础软件通用规范 (SWS BSW General) [3]，该规范同样适用于 Crypto Interface。因此，SWS BSW General [3] 应被视为 Crypto Interface 的附加且必需的规范。
---
## 4 约束和假设
### 4.1 限制
Crypto Interface 被专门设计为可与一个或多个底层 Crypto Driver 一起工作。覆盖不同硬件处理单元或核心的若干 Crypto Driver 模块仅由 Crypto Driver 规范 [4] 中规定的通用接口表示。任何基于软件的 Crypto Driver 都应实现为具有相同接口的 CDD。
### 4.2 对汽车域的适用性
Crypto Interface 可在需要使用安全功能的所有域应用中使用。
---
## 5 对其他模块的依赖
**[SWS_CryIf_00001]** ⌈ Crypto Interface (CRYIF) 应能够由 Crypto Service Manager (CSM) 调用，并将其服务请求转发到底层 Crypto Driver。⌋()
**[SWS_CryIf_00002]** ⌈ CRYIF 应能够访问底层 Crypto Driver，以使用其加密服务计算结果。这些结果应由 CRYIF 返回给 CSM。⌋()
### 5.1 文件结构
#### 5.1.1 代码文件结构
**[SWS_CryIf_00003]** ⌈ 代码文件结构不应在本规范中完整定义。⌋()
**[SWS_CryIf_00004]** ⌈ 代码文件结构应包含一个源文件 `CryIf.c`，其中包含整个 CRYIF 代码。⌋()
---
## 6 需求可追溯性
> 完整可追溯性表（涵盖 SRS_BSW_00101、SRS_BSW_00358、SRS_BSW_00359、SRS_BSW_00360、SRS_BSW_00407、SRS_BSW_00414、SRS_CryptoStack_00034、SRS_CryptoStack_00086、SWS_BSW_00050、SWS_BSW_00216 等到 SWS_CryIf_xxx 的映射）请参阅原始 PDF 文档第 11-12 页。
---
## 7 功能规范
Crypto Interface 位于 Crypto Service Manager 与底层加密驱动之间，是所有上层 (BSW) 访问加密操作的唯一接口。Crypto Interface 也是加密驱动的唯一使用者，并提供统一的接口来管理不同的加密硬件和软件解决方案。抽象层封装了不同的硬件和软件访问机制，因此 Crypto Interface 的实现独立于底层可由硬件或软件实现的 Crypto Driver。
它还确保对加密服务的并发访问，以使同时处理多个加密任务成为可能。
> **图 7.1：AUTOSAR 分层视图中加密接口的位置**
### 7.1 错误分类
#### 7.1.1 开发错误
**[SWS_CryIf_00009]** 开发错误类型 ⌈
| 错误类型 | 相关错误代码 | 值（十六进制） |
|---|---|---|
| 在 CRYIF 模块初始化之前调用 API 请求 | CRYIF_E_UNINIT | 0x00 |
| CRYIF 模块初始化失败 | CRYIF_E_INIT_FAILED | 0x01 |
| 使用无效参数（空指针）调用 API 请求 | CRYIF_E_PARAM_POINTER | 0x02 |
| 使用无效参数（超出范围）调用 API 请求 | CRYIF_E_PARAM_HANDLE | 0x03 |
| 使用无效参数（无效值）调用 API 请求 | CRYIF_E_PARAM_VALUE | 0x04 |
| 源密钥元素大小与目标密钥元素大小不匹配 | CRYIF_E_KEY_SIZE_MISMATCH | 0x05 |
⌋ (SRS_CryptoStack_00086)
#### 7.1.2 运行时错误
无运行时错误。
#### 7.1.3 瞬态故障
无瞬态故障。
#### 7.1.4 生产错误
无生产错误。
#### 7.1.5 扩展生产错误
无扩展生产错误。
---
## 8 API 规范
### 8.1 导入类型
**[SWS_CryIf_00011]** ⌈ 导入的类型
| 模块 | 头文件 | 导入的类型 |
|---|---|---|
| Csm | `<none>` | Crypto_JobType |
| | `<none>` | Crypto_VerifyResultType |
| | Rte_Csm_Type.h | Csm_ResultType |
| Std_Types | StandardTypes.h | Std_ReturnType |
| | StandardTypes.h | Std_VersionInfoType |
⌋()
加密栈 API 使用 Std_ReturnType 的以下扩展：
**[SWS_CryIf_00012]** ⌈
| 范围 | 描述 |
|---|---|
| `CRYPTO_E_BUSY` = 0x02 | 服务请求失败，因为服务仍然繁忙 |
| `CRYPTO_E_SMALL_BUFFER` = 0x03 | 服务请求失败，因为提供的缓冲区太小，无法存储结果 |
| `CRYPTO_E_ENTROPY_EXHAUSTION` = 0x04 | 服务请求失败，因为随机数生成器的熵已用尽 |
| `CRYPTO_E_QUEUE_FULL` = 0x05 | 服务请求失败，因为队列已满 |
| `CRYPTO_E_KEY_READ_FAIL` = 0x06 | 服务请求失败，因为不允许提取密钥元素 |
| `CRYPTO_E_KEY_WRITE_FAIL` = 0x07 | 服务请求失败，因为写入访问失败 |
| `CRYPTO_E_KEY_NOT_AVAILABLE` = 0x08 | 服务请求失败，因为密钥不可用 |
| `CRYPTO_E_KEY_NOT_VALID` = 0x09 | 服务请求失败，因为密钥无效 |
| `CRYPTO_E_KEY_SIZE_MISMATCH` = 0x0A | 服务请求失败，因为密钥大小不匹配 |
| `CRYPTO_E_JOB_CANCELED` = 0x0C | 服务请求失败，因为作业已被取消 |
| `CRYPTO_E_KEY_EMPTY` = 0x0D | 服务请求失败，因为源密钥元素未初始化 |
| Description | -- |
| Available via | CryIf.h |
⌋()
加密栈 API 使用 CSM 模块中的密钥元素索引定义。
### 8.2 类型定义
**[SWS_CryIf_91118]** ⌈
| 字段 | 内容 |
|---|---|
| Name | `CryIf_ConfigType` |
| Type | Structure |
| Range | implementation specific — 配置数据结构的内容是实现特定的 |
| Description | CryIf 模块的配置数据结构 |
| Available via | CryIf.h |
⌋ (SWS_BSW_00216)
没有其他类型定义。
### 8.3 函数定义
这是为上层模块提供的函数列表。
#### 8.3.1 通用 API
##### 8.3.1.1 CryIf_Init
**[SWS_CryIf_91000]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_Init` |
| Syntax | `void CryIf_Init(const CryIf_ConfigType* configPtr)` |
| Service ID[hex] | 0x00 |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant |
| Parameters (in) | `configPtr` — 指向所选配置结构的指针 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | None |
| Description | 初始化 CRYIF 模块。 |
| Available via | CryIf.h |
⌋ (SRS_BSW_00101, SRS_BSW_00358, SRS_BSW_00414)
**[SWS_CryIf_91019]** ⌈ 配置指针 `configPtr` 应始终为空指针值。⌋ (SWS_BSW_00050)
配置指针 `configPtr` 当前未使用，因此应设置为空指针值。
**[SWS_CryIf_00014]** ⌈ 如果 CRYIF 模块的初始化失败，CRYIF 应向 DET 报告 `CRYIF_E_INIT_FAILED`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00015]** ⌈ 服务 `CryIf_Init()` 应初始化 CRYIF 的全局变量和数据结构，包括标志和缓冲区。⌋()
##### 8.3.1.2 CryIf_GetVersionInfo
**[SWS_CryIf_91001]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_GetVersionInfo` |
| Syntax | `void CryIf_GetVersionInfo(Std_VersionInfoType* versioninfo)` |
| Service ID[hex] | 0x01 |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant |
| Parameters (in) | `versioninfo` — 指向存储本模块版本信息的位置的指针 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | void — -- |
| Description | 返回本模块的版本信息。 |
| Available via | CryIf.h |
⌋ (SRS_BSW_00407)
**[SWS_CryIf_00016]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_GetVersionInfo` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00017]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_GetVersionInfo` 应在参数 `versioninfo` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER`。⌋ (SRS_CryptoStack_00034)
#### 8.3.2 作业处理接口
##### 8.3.2.1 CryIf_ProcessJob
为了统一单次调用函数和加密服务的流式方法，存在一个接口 `CryIf_ProcessJob()`。其 `Crypto_JobType job` 参数包含 `Crypto_OperationModeType` 标志字段（`job->jobPrimitiveInputOutput.mode`），可设置为 "START"、"UPDATE"、"FINISH" 或其组合。它显式声明应执行哪些操作。这些操作模式可以混合，并可一次执行多个操作。
要使用 `Crypto_ProcessJob()` 一次调用处理加密服务，操作模式是 3 种模式 "START|UPDATE|FINISH" 的析取。
**[SWS_CryIf_91003]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_ProcessJob` |
| Syntax | `Std_ReturnType CryIf_ProcessJob(uint32 channelId, Crypto_JobType* job)` |
| Service ID[hex] | 0x03 |
| Sync/Async | Sync 或 Async，取决于配置 |
| Reentrancy | Reentrant |
| Parameters (in) | `channelId` — 保存加密通道的标识符 |
| Parameters (inout) | `job` — 指向作业配置的指针。包含与用户和原语相关信息的结构。 |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`CRYPTO_E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_KEY_NOT_VALID`：请求失败，密钥无效；`CRYPTO_E_KEY_SIZE_MISMATCH`：请求失败，密钥元素大小错误；`CRYPTO_E_QUEUE_FULL`：请求失败，队列已满；`CRYPTO_E_KEY_READ_FAIL`：服务请求失败，因为不允许提取密钥元素；`CRYPTO_E_KEY_WRITE_FAIL`：服务请求失败，因为写入访问失败；`CRYPTO_E_KEY_NOT_AVAILABLE`：服务请求失败，因为密钥不可用；`CRYPTO_E_SMALL_BUFFER`：提供的缓冲区太小，无法存储结果；`CRYPTO_E_JOB_CANCELED`：服务请求失败，因为同步作业已被取消；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此接口将接收到的作业分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00027]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_ProcessJob` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00028]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_ProcessJob` 应在参数 `channelId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00029]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_ProcessJob` 应在参数 `job` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00044]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_ProcessJob()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_ProcessJob()` 并传递返回值。⌋()
**[SWS_CryIf_00136]** ⌈ 如果对某个作业使用了作业处理重定向，则 Crypto Interface 需要将传入的 Crypto Interface 密钥引用和密钥元素引用调整为相应 Crypto Driver 的对应密钥引用和密钥元素引用。⌋()
##### 8.3.2.2 分派密钥 ID
**[SWS_CryIf_00133]** ⌈ 如果参数 `job->jobPrimitiveInfo->primitiveInfo->service` 设置为 `CRYPTO_KEYSETVALID`、`CRYPTO_RANDOMSEED`、`CRYPTO_KEYGENERATE`、`CRYPTO_KEYDERIVE`、`CRYPTO_KEYEXCHANGECALCPUBVAL`、`CRYPTO_KEYEXCHANGECALCSECRET`、`CRYPTO_CERTIFICATEPARSE` 或 `CRYPTO_CERTIFICATEVERIFY` 之一，则必须设置参数 `job->cryptoKeyId`，并在适用的情况下设置 `job->targetCryptoKeyId`。⌋()
**[SWS_CryIf_00134]** ⌈ 如果参数 `job->jobPrimitiveInfo->primitiveInfo->service` 设置为 `CRYPTO_KEYSETVALID`、`CRYPTO_RANDOMSEED`、`CRYPTO_KEYGENERATE`、`CRYPTO_KEYDERIVE`、`CRYPTO_KEYEXCHANGECALCPUBVAL`、`CRYPTO_KEYEXCHANGECALCSECRET`、`CRYPTO_CERTIFICATEPARSE` 或 `CRYPTO_CERTIFICATEVERIFY` 之一，则参数 `job->cryIfKeyId` 必须处于范围内；否则函数 `CryIf_ProcessJob` 应向 DET 报告 `CRYPTO_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋()
**[SWS_CryIf_00135]** ⌈ 如果参数 `job->jobPrimitiveInfo->primitiveInfo->service` 设置为 `CRYPTO_KEYDERIVE` 或 `CRYPTO_CERTIFICATEVERIFY` 之一，则参数 `job->cryIfTargetKeyId` 必须处于范围内；否则函数 `CryIf_ProcessJob` 应向 DET 报告 `CRYPTO_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋()
#### 8.3.3 作业取消接口
##### 8.3.3.1 CryIf_CancelJob
**[SWS_CryIf_91014]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_CancelJob` |
| Syntax | `Std_ReturnType CryIf_CancelJob(uint32 channelId, Crypto_JobType* job)` |
| Service ID[hex] | 0x0e |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant |
| Parameters (in) | `channelId` — 保存加密通道的标识符 |
| Parameters (inout) | `job` — 指向作业配置的指针。包含与用户和原语相关信息的结构。 |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功，作业已被移除；`E_NOT_OK`：请求失败，无法移除作业 |
| Description | 此接口将作业取消功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00129]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_CancelJob` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00130]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_CancelJob` 应在参数 `channelId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00131]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_CancelJob` 应在参数 `job` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00132]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_CancelJob()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_CancelJob()` 并传递返回值。⌋()
#### 8.3.4 密钥管理接口
##### 8.3.4.1 密钥设置接口
###### 8.3.4.1.1 CryIf_KeyElementSet
**[SWS_CryIf_91004]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyElementSet` |
| Syntax | `Std_ReturnType CryIf_KeyElementSet(uint32 cryIfKeyId, uint32 keyElementId, const uint8* keyPtr, uint32 keyLength)` |
| Service ID[hex] | 0x04 |
| Sync/Async | Synchronous |
| Reentrancy | Non Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存要设置其密钥元素的密钥的标识符；`keyElementId` — 保存要设置的密钥元素的标识符；`keyPtr` — 保存要设置为密钥元素的密钥数据的指针；`keyLength` — 包含密钥元素的字节长度 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`CRYPTO_E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_KEY_WRITE_FAIL`：请求失败，因为写入访问被拒绝；`CRYPTO_E_KEY_NOT_AVAILABLE`：请求失败，因为密钥不可用；`CRYPTO_E_KEY_SIZE_MISMATCH`：请求失败，密钥元素大小与所提供数据的大小不匹配 |
| Description | 此函数应将设置密钥元素功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00049]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyElementSet` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00050]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyElementSet` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00052]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyElementSet` 应在参数 `keyPtr` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00053]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_KeyElementSet` 应在 `keyLength` 为零时向 DET 报告 `CRYIF_E_PARAM_VALUE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00055]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_KeyElementSet()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyElementSet()` 并传递返回值。⌋()
###### 8.3.4.1.2 CryIf_KeySetValid
**[SWS_CryIf_91005]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeySetValid` |
| Syntax | `Std_ReturnType CryIf_KeySetValid(uint32 cryIfKeyId)` |
| Service ID[hex] | 0x05 |
| Sync/Async | Synchronous |
| Reentrancy | Non Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存其密钥元素应设置为有效的密钥的标识符 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`CRYPTO_E_BUSY`：请求失败，Crypto Driver Object 繁忙 |
| Description | 此函数应将设置密钥有效功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00056]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeySetValid` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00057]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeySetValid` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00058]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_KeySetValid()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeySetValid()` 并传递返回值。⌋()
##### 8.3.4.2 密钥提取接口
###### 8.3.4.2.1 CryIf_KeyElementGet
**[SWS_CryIf_91006]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyElementGet` |
| Syntax | `Std_ReturnType CryIf_KeyElementGet(uint32 cryIfKeyId, uint32 keyElementId, uint8* resultPtr, uint32* resultLengthPtr)` |
| Service ID[hex] | 0x06 |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存要返回其密钥元素的密钥的标识符；`keyElementId` — 保存要返回的密钥元素的标识符 |
| Parameters (inout) | `resultLengthPtr` — 指向存储长度信息的内存位置的指针。调用此函数时，此参数应包含 `resultPtr` 提供的缓冲区大小。如果密钥元素被配置为允许部分访问，则此参数包含要从密钥元素读取的数据量。大小可能不再等于提供的缓冲区的大小。请求完成后，应存储已存储的数据量。 |
| Parameters (out) | `resultPtr` — 指向用于返回密钥元素的缓冲区的指针 |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`CRYPTO_E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_KEY_NOT_AVAILABLE`：请求失败，请求的密钥元素不可用；`CRYPTO_E_KEY_READ_FAIL`：请求失败，因为读取访问被拒绝；`CRYPTO_E_SMALL_BUFFER`：提供的缓冲区太小，无法存储结果；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此函数应将获取密钥元素功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00059]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyElementGet` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00060]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyElementGet` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00062]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyElementGet` 应在参数 `resultPtr` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00063]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyElementGet` 应在参数 `resultLengthPtr` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00064]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyElementGet` 应在由 `resultLengthPtr` 指向的值为零时向 DET 报告 `CRYIF_E_PARAM_VALUE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00065]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_KeyElementGet()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyElementGet()` 并传递返回值。⌋()
##### 8.3.4.3 密钥复制接口
###### 8.3.4.3.1 CryIf_KeyElementCopy
**[SWS_CryIf_91015]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyElementCopy` |
| Syntax | `Std_ReturnType CryIf_KeyElementCopy(uint32 cryIfKeyId, uint32 keyElementId, uint32 targetCryIfKeyId, uint32 targetKeyElementId)` |
| Service ID[hex] | 0x0f |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant, but not for the same cryIfKeyId |
| Parameters (in) | `cryIfKeyId` — 保存要作为源元素的密钥的标识符；`keyElementId` — 保存要用作复制操作源的密钥元素的标识符；`targetCryIfKeyId` — 保存要作为目标元素的密钥的标识符；`targetKeyElementId` — 保存要用作复制操作目标的密钥元素的标识符 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`CRYPTO_E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_KEY_NOT_AVAILABLE`：请求失败，请求的密钥元素不可用；`CRYPTO_E_KEY_READ_FAIL`：请求失败，不允许提取密钥元素；`CRYPTO_E_KEY_WRITE_FAIL`：请求失败，不允许写入密钥元素；`CRYPTO_E_KEY_SIZE_MISMATCH`：请求失败，密钥元素大小不兼容；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此函数应将一个密钥的元素复制到目标密钥。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00110]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_KeyElementCopy` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00111]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_KeyElementCopy` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00112]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_KeyElementCopy` 应在参数 `targetCryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00113]** ⌈ 如果 CRYIF 未检测到错误，并且 `cryIfKeyId` 和 `targetCryIfKeyId` 位于同一 Crypto Driver 中，则服务 `CryIf_KeyElementCopy()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyElementCopy()` 并传递返回值。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00114]** ⌈ 如果 CRYIF 未检测到错误，并且 `cryIfKeyId` 和 `targetCryIfKeyId` 位于不同的 Crypto Driver 中，则服务 `CryIf_KeyElementCopy()` 应通过使用 `Crypto_<vi>_<ai>_KeyElementGet()` 获取元素并通过 `Crypto_<vi>_<ai>_KeyElementSet()` 设置目标密钥元素来复制所提供的密钥元素。⌋()
**[SWS_CryIf_00115]** ⌈ 如果为 CRYIF 启用了开发错误检测：如果 `cryIfKeyId` 请求的密钥元素在 `targetCryIfKeyId` 中可用，并且源元素大小与目标密钥元素大小不匹配，则 `CryIf_KeyElementCopy()` 应向 DET 报告 `CRYIF_E_KEY_SIZE_MISMATCH`。⌋ (SRS_CryptoStack_00034)
###### 8.3.4.3.2 CryIf_KeyElementCopyPartial
**[SWS_CryIf_91018]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyElementCopyPartial` |
| Syntax | `Std_ReturnType CryIf_KeyElementCopyPartial(uint32 cryIfKeyId, uint32 keyElementId, uint32 keyElementSourceOffset, uint32 keyElementTargetOffset, uint32 keyElementCopyLength, uint32 targetCryIfKeyId, uint32 targetKeyElementId)` |
| Service ID[hex] | 0x12 |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant, but not for the same cryIfKeyId |
| Parameters (in) | `cryIfKeyId` — 保存要作为源元素的密钥的标识符；`keyElementId` — 保存要用作复制操作源的密钥元素的标识符；`keyElementSourceOffset` — 源密钥元素的偏移量，指示复制操作的起始索引；`keyElementTargetOffset` — 目标密钥元素的偏移量，指示复制操作的起始索引；`keyElementCopyLength` — 指定应复制的字节数；`targetCryIfKeyId` — 保存要作为目标元素的密钥的标识符；`targetKeyElementId` — 保存要用作复制操作目标的密钥元素的标识符 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_KEY_NOT_AVAILABLE`：请求失败，请求的密钥元素不可用；`CRYPTO_E_KEY_READ_FAIL`：请求失败，不允许提取密钥元素；`CRYPTO_E_KEY_WRITE_FAIL`：请求失败，不允许写入密钥元素；`CRYPTO_E_KEY_SIZE_MISMATCH`：请求失败，密钥元素大小不兼容；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 将一个密钥元素复制到另一个密钥元素。`keyElementOffsets` 和 `keyElementCopyLength` 允许仅将源密钥元素的一部分复制到目标密钥元素。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00137]** ⌈ 如果 Crypto Interface 尚未初始化，并且为 Crypto Interface 启用了开发错误检测，则函数 `CryIf_KeyElementCopyPartial` 应向 DET 报告 `CRYPTO_E_UNINIT` 并返回 `E_NOT_OK`。⌋()
**[SWS_CryIf_00138]** ⌈ 如果 `cryIfKeyId`、`keyElementId`、`targetKeyElementId` 或 `targetCryIfKeyId` 超出范围，并且为 Crypto Interface 启用了开发错误检测，则函数 `CryIf_KeyElementCopyPartial` 应向 DET 报告 `CRYPTO_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋()
**[SWS_CryIf_00139]** ⌈ 如果 CRYIF 未检测到错误，并且 `cryIfKeyId` 和 `targetCryIfKeyId` 位于同一 Crypto Driver 中，则服务 `CryIf_KeyElementCopyPartial()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyElementCopyPartial()` 并传递返回值。⌋(SRS_CryptoStack_00034)
**[SWS_CryIf_00140]** ⌈ 如果 CRYIF 未检测到错误，并且 `cryIfKeyId` 和 `targetCryIfKeyId` 位于不同的 Crypto Driver 中，则服务 `CryIf_KeyElementCopyPartial()` 应通过使用 `Crypto_<vi>_<ai>_KeyElementGet()` 获取元素、将部分数据复制到目标，然后通过 `Crypto_<vi>_<ai>_KeyElementSet()` 设置目标密钥元素来复制所提供的密钥元素。⌋()
###### 8.3.4.3.3 CryIf_KeyCopy
**[SWS_CryIf_91016]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyCopy` |
| Syntax | `Std_ReturnType CryIf_KeyCopy(uint32 cryIfKeyId, uint32 targetCryIfKeyId)` |
| Service ID[hex] | 0x10 |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant, but not for the same cryIfKeyId |
| Parameters (in) | `cryIfKeyId` — 保存要作为源元素的密钥的标识符；`targetCryIfKeyId` — 保存要作为目标元素的密钥的标识符 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_KEY_NOT_AVAILABLE`：请求失败，请求的密钥元素不可用；`CRYPTO_E_KEY_READ_FAIL`：请求失败，不允许提取密钥元素；`CRYPTO_E_KEY_WRITE_FAIL`：请求失败，不允许写入密钥元素；`CRYPTO_E_KEY_SIZE_MISMATCH`：请求失败，密钥元素大小不兼容；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此函数应将源密钥的所有密钥元素复制到目标密钥。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00116]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_KeyCopy` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00117]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_KeyCopy` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00118]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_KeyCopy` 应在参数 `targetCryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00119]** ⌈ 如果 CRYIF 未检测到错误，并且 `cryIfKeyId` 和 `targetCryIfKeyId` 位于同一 Crypto Driver 中，则服务 `CryIf_KeyCopy()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyCopy()` 并传递返回值。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00120]** ⌈ 如果 CRYIF 未检测到错误，并且 `cryIfKeyId` 和 `targetCryIfKeyId` 位于不同的 Crypto Driver 中，则服务 `CryIf_KeyCopy()` 应通过使用 `Crypto_<vi>_<ai>_KeyElementGet()` 获取元素并通过 `Crypto_<vi>_<ai>_KeyElementSet()` 设置目标密钥元素来复制所提供的密钥元素。⌋()
**[SWS_CryIf_00121]** ⌈ 如果为 CRYIF 启用了开发错误检测：对于 `cryIfKeyId` 中所有在 `targetCryIfKeyId` 中可用的密钥元素，如果源元素大小与目标密钥元素大小不匹配，则 `CryIf_KeyCopy()` 应向 DET 报告 `CRYIF_E_KEY_SIZE_MISMATCH`。⌋ (SRS_CryptoStack_00034)
##### 8.3.4.4 密钥生成接口
###### 8.3.4.4.1 CryIf_RandomSeed
**[SWS_CryIf_91007]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_RandomSeed` |
| Syntax | `Std_ReturnType CryIf_RandomSeed(uint32 cryIfKeyId, const uint8* seedPtr, uint32 seedLength)` |
| Service ID[hex] | 0x07 |
| Sync/Async | Sync 或 Async，取决于配置 |
| Reentrancy | Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存应为其生成新种子的密钥的标识符；`seedPtr` — 保存指向包含用于喂入种子的数据的内存位置的指针；`seedLength` — 包含种子的字节长度 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败 |
| Description | 此函数应将随机种子功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00068]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_RandomSeed` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00069]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_RandomSeed` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00070]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_RandomSeed` 应在参数 `seedPtr` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00071]** ⌈ 如果为 CRYIF 启用了开发错误检测：函数 `CryIf_RandomSeed` 应在 `seedLength` 为零时向 DET 报告 `CRYIF_E_PARAM_VALUE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00072]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_RandomSeed()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_RandomSeed()` 并传递返回值。⌋()
###### 8.3.4.4.2 CryIf_KeyGenerate
**[SWS_CryIf_91008]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyGenerate` |
| Syntax | `Std_ReturnType CryIf_KeyGenerate(uint32 cryIfKeyId)` |
| Service ID[hex] | 0x08 |
| Sync/Async | Sync 或 Async，取决于配置 |
| Reentrancy | Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存应使用生成值更新的密钥的标识符 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此函数应将密钥生成功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00073]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyGenerate` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00074]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyGenerate` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00075]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_KeyGenerate()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyGenerate()` 并传递返回值。⌋()
##### 8.3.4.5 密钥派生接口
###### 8.3.4.5.1 CryIf_KeyDerive
**[SWS_CryIf_91009]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyDerive` |
| Syntax | `Std_ReturnType CryIf_KeyDerive(uint32 cryIfKeyId, uint32 targetCryIfKeyId)` |
| Service ID[hex] | 0x09 |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存用于密钥派生的密钥的标识符；`targetCryIfKeyId` — 保存用于存储派生密钥的密钥的标识符 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此函数应将密钥派生功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00076]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyDerive` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00077]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyDerive` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00122]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyDerive` 应在参数 `targetCryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00081]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_KeyDerive()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyDerive()` 并传递返回值。⌋()
密钥派生服务需要 salt 和 password 来派生新密钥。因此，salt 和 password 作为密钥元素存储在由 `cryIfKeyId` 引用的密钥中。
##### 8.3.4.6 密钥交换接口
###### 8.3.4.6.1 CryIf_KeyExchangeCalcPubVal
**[SWS_CryIf_91010]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyExchangeCalcPubVal` |
| Syntax | `Std_ReturnType CryIf_KeyExchangeCalcPubVal(uint32 cryIfKeyId, uint8* publicValuePtr, uint32* publicValueLengthPtr)` |
| Service ID[hex] | 0x0a |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存应用于密钥交换协议的密钥的标识符 |
| Parameters (inout) | `publicValueLengthPtr` — 指向存储公钥长度信息的内存位置的指针。调用此函数时，此参数应包含 `publicValuePtr` 提供的缓冲区大小。请求完成后，应存储返回值的实际长度。 |
| Parameters (out) | `publicValuePtr` — 包含指向应存储公钥的数据的指针 |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_SMALL_BUFFER`：提供的缓冲区太小，无法存储结果；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此函数应将密钥交换公钥值计算功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00082]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcPubVal` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00083]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcPubVal` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00084]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcPubVal` 应在参数 `publicValuePtr` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00085]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcPubVal` 应在参数 `pubValueLengthPtr` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00086]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcPubVal` 应在由 `pubValueLengthPtr` 指向的值为零时向 DET 报告 `CRYIF_E_PARAM_VALUE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00087]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_KeyExchangeCalcPubVal()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyExchangeCalcPubVal()` 并传递返回值。⌋()
###### 8.3.4.6.2 CryIf_KeyExchangeCalcSecret
**[SWS_CryIf_91011]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_KeyExchangeCalcSecret` |
| Syntax | `Std_ReturnType CryIf_KeyExchangeCalcSecret(uint32 cryIfKeyId, const uint8* partnerPublicValuePtr, uint32 partnerPublicValueLength)` |
| Service ID[hex] | 0x0b |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存应用于密钥交换协议的密钥的标识符；`partnerPublicValuePtr` — 保存指向包含对方公钥的内存位置的指针；`partnerPublicValueLength` — 包含对方公钥的字节长度 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_SMALL_BUFFER`：提供的缓冲区太小，无法存储结果；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此函数应将密钥交换共享密钥计算功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00090]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcSecret` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00091]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcSecret` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00092]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcSecret` 应在参数 `partnerPublicValuePtr` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00094]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_KeyExchangeCalcSecret` 应在 `partnerPubValueLength` 为零时向 DET 报告 `CRYIF_E_PARAM_VALUE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00095]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_KeyExchangeCalcSecret()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_KeyExchangeCalcSecret()` 并传递返回值。⌋()
##### 8.3.4.7 证书接口
###### 8.3.4.7.1 CryIf_CertificateParse
**[SWS_CryIf_91012]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_CertificateParse` |
| Syntax | `Std_ReturnType CryIf_CertificateParse(uint32 cryIfKeyId)` |
| Service ID[hex] | 0x0c |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant |
| Parameters (in) | `cryIfKeyId` — 保存应解析的密钥的标识符 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`E_BUSY`：请求失败，Crypto Driver Object 繁忙；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 此函数应将证书解析功能分派给已配置的 Crypto Driver Object。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00098]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CertificateParse` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00099]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CertificateParse` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00104]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_CertificateParse()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_CertificateParse()` 并传递返回值。⌋ (SRS_CryptoStack_00034)
###### 8.3.4.7.2 CryIf_CertificateVerify
**[SWS_CryIf_91017]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_CertificateVerify` |
| Syntax | `Std_ReturnType CryIf_CertificateVerify(uint32 cryIfKeyId, uint32 verifyCryIfKeyId, Crypto_VerifyResultType* verifyPtr)` |
| Service ID[hex] | 0x11 |
| Sync/Async | Synchronous |
| Reentrancy | Reentrant, but not for the same cryIfKeyId |
| Parameters (in) | `cryIfKeyId` — 保存用于验证证书的密钥的标识符；`verifyCryIfKeyId` — 保存包含待验证证书的密钥的标识符 |
| Parameters (inout) | None |
| Parameters (out) | `verifyPtr` — 保存指向将包含证书验证结果的内存位置的指针 |
| Return value | `Std_ReturnType` — `E_OK`：请求成功；`E_NOT_OK`：请求失败；`CRYPTO_E_KEY_EMPTY`：由于源密钥元素未初始化而请求失败 |
| Description | 使用由 `cryIfKeyId` 引用的密钥存储的证书验证由 `verifyCryIfKeyId` 引用的密钥存储的证书。 |
| Available via | CryIf.h |
⌋()
**[SWS_CryIf_00123]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CertificateVerify` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00124]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CertificateVerify` 应在参数 `cryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00125]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CertificateVerify` 应在参数 `validateCryIfKeyId` 超出范围时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00126]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CertificateVerify` 应在由 `validateCryIfKeyId` 和 `cryIfKeyId` 标识的密钥不在同一 Crypto Driver 中时向 DET 报告 `CRYIF_E_PARAM_HANDLE` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00127]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CertificateVerify` 应在参数 `verifyPtr` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER` 并返回 `E_NOT_OK`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00128]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_CertificateVerify()` 应调用映射到该服务的驱动配置的 `Crypto_<vi>_<ai>_CertificateVerify()` 并传递返回值。⌋()
### 8.4 回调通知
这是为其他模块提供的函数列表。
#### 8.4.1 CryIf_CallbackNotification
**[SWS_CryIf_91013]** ⌈
| 字段 | 内容 |
|---|---|
| Service name | `CryIf_CallbackNotification` |
| Syntax | `void CryIf_CallbackNotification(Crypto_JobType* job, Std_ReturnType result)` |
| Service ID[hex] | 0x0d |
| Sync/Async | Synchronous |
| Reentrancy | Non Reentrant |
| Parameters (in) | `job` — 指向已完成作业的信息结构。它包含一个 callbackID 用于标识已完成的作业；`result` — 包含加密操作的结果 |
| Parameters (inout) | None |
| Parameters (out) | None |
| Return value | void -- |
| Description | 通知 CRYIF 关于带加密操作结果的请求的完成。 |
| Available via | CryIf.h |
⌋ (SRS_BSW_00359, SRS_BSW_00360)
**[SWS_CryIf_00107]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CallbackNotification` 应在模块尚未初始化时向 DET 报告 `CRYIF_E_UNINIT`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00108]** ⌈ 如果为 CRYIF 模块启用了开发错误检测：函数 `CryIf_CallbackNotification` 应在参数 `job` 为空指针时向 DET 报告 `CRYIF_E_PARAM_POINTER`。⌋ (SRS_CryptoStack_00034)
**[SWS_CryIf_00109]** ⌈ 如果 CRYIF 未检测到错误，服务 `CryIf_CallbackNotification()` 应调用 `Csm_CallbackNotification()` 并传递结果。⌋()
### 8.5 预期接口
#### 8.5.1 必需接口
本章定义了满足 CryIf 模块核心功能所需的所有接口。
| API 函数 | 头文件 | 描述 |
|---|---|---|
| `Csm_CallbackNotification` | `Csm.h` | 通知 CSM 一个作业已完成。此函数由底层 (CRYIF) 使用。 |
| | | **变体**： `{ecuc(Csm/CsmJob/CsmJobUsePort == false)} && {ecuc(Csm/CsmJobs/CsmJob.CsmJobPrimitiveRef->CsmPrimitives/{Primitive}Config/{Primitive}Processing == CRYPTO_PROCESSING_ASYNC)}` |
#### 8.5.2 可选接口
本章定义了满足 CryIf 模块可选功能所需的所有接口。
> 无。
---
## 9 序列图
无。
---
## 10 配置规范
第 10.1 章规定 CRYIF 模块的结构（容器）和参数。第 10.2 章另外规定 CRYIF 模块的发布信息。
### 10.1 容器和配置参数
以下各章总结了所有配置参数。参数的详细含义在第 7 章和第 8 章中描述。
**注意**：配置容器中的 ID 应是连续的、无间隔的，并应从零开始。
#### 10.1.1 变体
有关详细信息，请参阅 SWS_BSWGeneral 中的第 10.1.2 章"变体"。
#### 10.1.2 CryIf
| SWS Item | `ECUC_CryIf_00001` |
|---|---|
| Module Name | `CryIf` |
| Module Description | 加密接口的配置 |
| Post-Build Variant Support | false |
| 包含的容器 | 多重性 | 范围 / 依赖 |
|---|---|---|
| `CryIfChannel` | 0..* | 用于纳入 `CryIfChannel` 的容器 |
| `CryIfGeneral` | 1 | 用于纳入 `CryIfGeneral` 的容器 |
| `CryIfKey` | 0..* | 用于纳入 `CryIfKey` 的容器 |
#### 10.1.3 CryIfGeneral
| SWS Item | `ECUC_CryIf_00009` |
|---|---|
| Container Name | `CryIfGeneral` |
| Description | 用于纳入 `CryIfGeneral` 的容器 |
**配置参数**
`ECUC_CryIf_00010`：
| 字段 | 内容 |
|---|---|
| Name | `CryIfDevErrorDetect` |
| Parent Container | `CryIfGeneral` |
| Description | 启用或禁用开发错误检测和通知。`true`：启用检测和通知；`false`：禁用检测和通知 |
| Multiplicity | 1 |
| Type | `EcucBooleanParamDef` |
| Default value | false |
| Scope / Dependency | scope: local |
`ECUC_CryIf_00011`：
| 字段 | 内容 |
|---|---|
| Name | `CryIfVersionInfoApi` |
| Parent Container | `CryIfGeneral` |
| Description | 启用和禁用 API `CryIf_GetVersionInfo()` 可用性的预处理开关。`true`：API `CryIf_GetVersionInfo()` 可用；`false`：API `CryIf_GetVersionInfo()` 不可用 |
| Multiplicity | 1 |
| Type | `EcucBooleanParamDef` |
| Default value | false |
| Scope / Dependency | scope: local |
不包含子容器。
#### 10.1.4 CryIfChannel
| SWS Item | `ECUC_CryIf_00002` |
|---|---|
| Container Name | `CryIfChannel` |
| Description | 用于纳入 `CryIfChannel` 的容器 |
**配置参数**
`ECUC_CryIf_00004`：
| 字段 | 内容 |
|---|---|
| Name | `CryIfChannelId` |
| Parent Container | `CryIfChannel` |
| Description | 加密通道的标识符。指定 CSM 队列连接到哪个加密通道。 |
| Multiplicity | 1 |
| Type | `EcucIntegerParamDef`（为此参数生成的符号名称） |
| Range | 0 .. 4294967295 |
| Default value | -- |
| Post-Build Variant Multiplicity | false |
| Post-Build Variant Value | false |
| Scope / Dependency | scope: local |
`ECUC_CryIf_00005`：
| 字段 | 内容 |
|---|---|
| Name | `CryIfDriverObjectRef` |
| Parent Container | `CryIfChannel` |
| Description | 此参数引用一个 Crypto Driver Object。指定加密通道连接到哪个 Crypto Driver Object。 |
| Multiplicity | 1 |
| Type | 对 `[CryptoDriverObject]` 的符号名称引用 |
| Post-Build Variant Multiplicity | false |
| Post-Build Variant Value | false |
| Scope / Dependency | scope: local |
不包含子容器。
#### 10.1.5 CryIfKey
| SWS Item | `ECUC_CryIf_00003` |
|---|---|
| Container Name | `CryIfKey` |
| Description | 用于纳入 `CryIfKey` 的容器 |
**配置参数**
`ECUC_CryIf_00007`：
| 字段 | 内容 |
|---|---|
| Name | `CryIfKeyId` |
| Parent Container | `CryIfKey` |
| Description | CryIf 密钥的标识符。指定 CSM 密钥映射到哪个 CryIf 密钥。 |
| Multiplicity | 1 |
| Type | `EcucIntegerParamDef`（为此参数生成的符号名称） |
| Range | 0 .. 4294967295 |
| Default value | -- |
| Post-Build Variant Value | false |
| Scope / Dependency | scope: local |
`ECUC_CryIf_00008`：
| 字段 | 内容 |
|---|---|
| Name | `CryIfKeyRef` |
| Parent Container | `CryIfKey` |
| Description | 此参数引用 Crypto Driver 密钥。指定 CryIf 密钥映射到哪个 Crypto Driver 密钥。 |
| Multiplicity | 1 |
| Type | 对 `[CryptoKey]` 的符号名称引用 |
| Post-Build Variant Value | false |
| Scope / Dependency | scope: local |
不包含子容器。
### 10.2 发布信息
发布信息包含由 SW 模块实施者定义的数据，这些数据在模块适配（即配置）到实际硬件/软件环境时不会更改。因此它包含版本和制造商信息。
如适用，下面列出了其他模块特定的发布参数。
> 无。
---
## 翻译说明
- 本文档为 AUTOSAR SWS 806《Specification of Crypto Interface》(CP 4.4.0) 的中文翻译；
- 文档标识号：806；
- 文档共 41 页，已翻译所有 10 个章节，包括完整的 API 规范、所有函数声明以及配置规范；
- 保留了所有 AUTOSAR 方框符、API 标识符、模块缩写、算法名和需求 ID；
- 翻译以保证技术含义准确为前提，语句尽量贴近 AUTOSAR 中文术语库常用译法。
Reference in New Issue View Git Blame Copy Permalink