# 加密接口规范 (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 中文术语库常用译法。