Crypto Interface (CryIf)

使用

同步函数 CryIf_Init 用于根据 AUTOSAR Classic Platform 完整初始化 Crypto Interface（CryIf）模块 [SWS_CryIf_91000]。该函数在头文件 CryIf.h 中声明，且具备服务 ID 0x00 [SWS_CryIf_91000]。作为唯一的输入参数，接口需要 configPtr，即指向所选类型为 CryIf_ConfigType 的配置结构的指针 [SWS_CryIf_91000]。该函数不返回返回值（void），且既无 inout 参数也无 out 参数 [SWS_CryIf_91000]。

语义与并发性

对 CryIf_Init 的调用以同步方式执行 [SWS_CryIf_91000]。因此，该模块在将执行控制权返回给调用方之前完成所有必需的初始化工作。关于并发性，该函数被归类为不可重入（Non Reentrant）[SWS_CryIf_91000]。因此，任何时候都不得并行或嵌套调用该例程。

限制与集成

Interpretation：对 CryIf_Init 的调用通常可能在系统启动期间的基础软件初始化阶段集中执行，随后才允许调用下游的加密接口服务。 问题 Q-31b82ca9b144c843 (未决)由于载荷中未提及具体的错误处理、DET 报告或 DEM 事件，调用方必须预先确保指向配置的指针有效。相关需求在载荷中未作定义。

通过头文件CryIf.h提供的函数CryIf_ProcessJob（服务 ID 0x03）将加密处理任务转发给相应配置的加密驱动对象[SWS_CryIf_91003]。它接受加密通道标识符（channelId）以及指向任务配置的指针（job）作为参数[SWS_CryIf_91003]。结构体job包含对用户以及特定加密原语重要的所有信息[SWS_CryIf_91003]。任务处理根据配置以同步或异步方式进行；此外，该接口被实现为可重入[SWS_CryIf_91003]。

在正确接收时，函数返回E_OK [SWS_CryIf_91003]。如果请求失败，返回值将指示E_NOT_OK或驱动程序的特定错误状态：CRYPTO_E_BUSY（驱动对象忙）、CRYPTO_E_QUEUE_FULL（队列已满）、关于密钥状态的错误例如CRYPTO_E_KEY_NOT_VALID、CRYPTO_E_KEY_SIZE_MISMATCH、CRYPTO_E_KEY_NOT_AVAILABLE、CRYPTO_E_KEY_EMPTY、CRYPTO_E_KEY_READ_FAIL或CRYPTO_E_KEY_WRITE_FAIL，以及在同步任务中止时的CRYPTO_E_JOB_CANCELED和CRYPTO_E_ENTROPY_EXHAUSTED [SWS_CryIf_91003]。

此外，该接口还对密钥标识符执行预检查：

• 如果job->jobPrimitiveInfo->primitiveInfo->service设置为CRYPTO_KEYSETVALID、CRYPTO_KEYSETINVALID、CRYPTO_RANDOMSEED、CRYPTO_KEYGENERATE、CRYPTO_KEYDERIVE、CRYPTO_KEYEXCHANGECALCPUBVAL或CRYPTO_KEYEXCHANGECALCSECRET，则job->cryIfKeyId必须位于有效值范围内[SWS_CryIf_00134]。否则，函数向 DET 报告错误CRYPTO_E_PARAM_HANDLE，并以E_NOT_OK中止[SWS_CryIf_00134]。
• 如果请求服务CRYPTO_KEYDERIVE，则目标密钥标识符job->cryIfTargetKeyId还必须位于有效范围内；否则同样向 DET 报告CRYPTO_E_PARAM_HANDLE并返回E_NOT_OK [SWS_CryIf_00135]。

函数 CryIf_CancelJob 用于将加密作业的中止请求转发给已配置的加密驱动程序对象 [SWS_CryIf_91014]。它提供了 Crypto Interface 的标准化接口，通过头文件 CryIf.h 进行声明，其服务 ID 为 0x0e [SWS_CryIf_91014]。

调用时必须传递目标通道的标识符以及作业的配置 [SWS_CryIf_91014]：

• channelId（输入，uint32）：保存相应加密通道的标识 [SWS_CryIf_91014]。
• job（输入/输出，Crypto_JobType*）：指向作业配置的指针，该配置包含具有用户相关和原语相关信息的结构体 [SWS_CryIf_91014]。

该执行以同步方式进行，并向调用方返回类型为 Std_ReturnType 的状态 [SWS_CryIf_91014]：

• E_OK：请求成功，且作业已从驱动程序中移除 [SWS_CryIf_91014]。
• E_NOT_OK：请求失败，因为无法移除作业 [SWS_CryIf_91014]。
• CRYPTO_E_JOB_CANCELED：用于确认作业中止的指定加密返回值 [SWS_CryIf_91014]。

关于并发行为，CryIf_CancelJob 被指定为可重入（reentrant）[SWS_CryIf_91014]。这允许并行调用以取消作业，其中处理过程被阻塞式委托给底层驱动程序对象 [SWS_CryIf_91014]。

同步函数 CryIf_KeyElementSet（服务 ID 0x04）将设置密钥元素的请求转发至配置的加密驱动对象 [SWS_CryIf_91004]。函数声明通过头文件 CryIf.h 提供 [SWS_CryIf_91004]。

调用通过四个输入参数进行 [SWS_CryIf_91004]：

• cryIfKeyId：标识需要更新其密钥元素的密钥的标识符。
• keyElementId：标识需要设置的具体密钥元素的标识符。
• keyPtr：指向包含拟作为元素载入的密钥数据的缓冲区的指针。
• keyLength：以字节为单位指定要设置的密钥元素的长度。

该函数被指定为不可重入（Non Reentrant）[SWS_CryIf_91004]。因此，调用方必须确保调用不会在未经协调的情况下并发发生。

类型为 Std_ReturnType 的返回值指示转发或执行的结果 [SWS_CryIf_91004]：

• E_OK：请求成功。
• E_NOT_OK：请求失败。
• CRYPTO_E_BUSY：关联的加密驱动对象当前正忙。
• CRYPTO_E_KEY_WRITE_FAIL：对密钥元素的写访问被拒绝。
• CRYPTO_E_KEY_NOT_AVAILABLE：请求的密钥不可用。
• CRYPTO_E_KEY_SIZE_MISMATCH：密钥元素的大小与所提供数据的长度不匹配。

使用

同步接口 CryIf_KeySetValid（服务 ID 0x05）通过头文件 CryIf.h 提供，并将使密钥生效的请求转发至相应配置的加密驱动对象 [SWS_CryIf_91005]。作为唯一的参数，传入的标识符 cryIfKeyId 用于确定目标密钥，该密钥的密钥元素应被标记为有效 [SWS_CryIf_91005]。该函数不存在额外的输入/输出或输出参数 [SWS_CryIf_91005]。

返回值与错误处理

类型为 Std_ReturnType 的返回值向调用方通知驱动中转发和处理的结果 [SWS_CryIf_91005]：

• E_OK：操作已成功转发至加密驱动对象并成功完成 [SWS_CryIf_91005]。
• E_NOT_OK：请求的转发或执行失败 [SWS_CryIf_91005]。
• CRYPTO_E_BUSY：由于负责的加密驱动对象当前正忙，无法执行该请求 [SWS_CryIf_91005]。

并发性与限制

该函数在规范中被明确指定为不可重入（Non Reentrant）[SWS_CryIf_91005]。因此，调用实例必须确保绝不并发或中断性地执行对 CryIf_KeySetValid 的调用，以可靠地防止转发至驱动对象时发生冲突。

同步接口 CryIf_KeySetInvalid（服务 ID 0x14）将通过参数 cryIfKeyId 识别的密钥的状态设置为无效 [SWS_CryIf_91021]。该函数的声明通过头文件 CryIf.h 提供 [SWS_CryIf_91021]。

使用该函数适用以下参数及返回值 [SWS_CryIf_91021]：

• 传入参数：通过类型为 uint32 的输入参数 cryIfKeyId 传递要使其失效的密钥标识符。不存在输入输出参数。
• 返回值（Std_ReturnType）：
  • E_OK：状态更改请求成功。
  • E_NOT_OK：请求失败。
  • CRYPTO_E_BUSY：执行失败，因为负责的 Crypto Driver Object 处于占用状态。

关于并发性和执行上下文，CryIf_KeySetInvalid 被指定为不可重入（Non Reentrant）[SWS_CryIf_91021]。因此，调用实体必须确保调用按顺序进行且不会相互重叠。如果出现返回值 CRYPTO_E_BUSY，则表示 Crypto Driver Object 被临时阻塞 [SWS_CryIf_91021]；在这种情况下，调用方应负责稍后重试状态失效操作。 问题 Q-4377065d4d4eecab (未决)

用法与调用上下文

函数 CryIf_KeyGetStatus 用于在 Crypto Interface 内部同步查询加密密钥的状态 [SWS_CryIf_91012]。它可通过头文件 CryIf.h 使用，服务 ID 为 0x13 [SWS_CryIf_91012]。调用时会传递以下参数：

• cryIfKeyId（输入）：待确定状态的密钥的唯一标识符 [SWS_CryIf_91012]。
• keyStatusPtr（输出）：指向 Crypto_KeyStatusType 类型变量的指针，密钥状态将写入该变量 [SWS_CryIf_91012]。

错误处理与返回值

类型为 Std_ReturnType 的返回值指示执行结果 [SWS_CryIf_91012]：

• E_OK：状态查询成功，且状态已存入目标内存 [SWS_CryIf_91012]。
• E_NOT_OK：请求失败 [SWS_CryIf_91012]。

元素规范中未列出特定的错误代码、DET 报告或 DEM 事件；调用方的错误处理主要依赖于对返回值的评估。

并发性与限制

该函数被指定为不可重入（Non Reentrant）[SWS_CryIf_91012]。因此，调用方必须确保不会对相同或不同的密钥实例发生并发或中断调用。此外，调用方可能需要为输出指针 keyStatusPtr 提供有效的内存区域，因为该函数会直接对其进行写入。 问题 Q-da3a034d4f2e9442 (未决)

同步函数 CryIf_KeyElementGet 将对密钥元素的查询转发至配置的 Crypto Driver Object [SWS_CryIf_91006]。它通过头文件 CryIf.h 声明，并被指定为可重入 [SWS_CryIf_91006]。

用法与参数

在调用时，cryIfKeyId 标识相关密钥，keyElementId 标识要获取的密钥元素 [SWS_CryIf_91006]。有效载荷数据存放在缓冲区 resultPtr 中 [SWS_CryIf_91006]。指针 resultLengthPtr 用作长度控制的组合输入和输出参数 [SWS_CryIf_91006]：

• 在执行前，调用方在其中传入 resultPtr 的可用缓冲区大小 [SWS_CryIf_91006]。
• 如果密钥元素允许部分访问，则该值改为定义要获取的数据量，该数据量不必与缓冲区大小一致 [SWS_CryIf_91006]。
• 操作完成后，函数会将实际写入的数据量存储在该存储位置 [SWS_CryIf_91006]。

错误处理与返回值

类型为 Std_ReturnType 的返回值指示成功或错误状态 [SWS_CryIf_91006]：

• E_OK：请求已成功完成 [SWS_CryIf_91006]。
• E_NOT_OK：执行失败[SWS_CryIf_91006]。
• CRYPTO_E_BUSY：Crypto Driver Object 正忙 [SWS_CryIf_91006]。
• CRYPTO_E_KEY_NOT_AVAILABLE：请求的密钥元素不可用 [SWS_CryIf_91006]。
• CRYPTO_E_KEY_READ_FAIL：对密钥元素的读取访问被拒绝 [SWS_CryIf_91006]。
• CRYPTO_E_KEY_EMPTY：源密钥元素未初始化 [SWS_CryIf_91006]。

根据 [SWS_CryIf_91015]，同步函数 CryIf_KeyElementCopy 用于将密钥元素从源密钥复制到目标密钥。该服务可通过头文件 CryIf.h 使用。

调用时，通过输入参数传递源密钥（cryIfKeyId）、待复制的源元素（keyElementId）以及目标密钥（targetCryIfKeyId）和目标元素（targetKeyElementId）[SWS_CryIf_91015]。该函数设计为可重入，但明确不适用于同一个 cryIfKeyId [SWS_CryIf_91015]。合理的解释应当是，为了避免数据冲突，调用方还应对同一目标密钥（targetCryIfKeyId）的并发写访问进行同步。 问题 Q-cba3554c537dd498 (未决)

Std_ReturnType 类型的返回值指示操作的结果 [SWS_CryIf_91015]：

• 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：源密钥元素未初始化。

通过头文件 CryIf.h 提供的同步函数 CryIf_KeyElementCopyPartial 将某个密钥元素的部分区域复制到另一个密钥元素中 [SWS_CryIf_91018]。源密钥和目标密钥以及各自的元素通过参数 cryIfKeyId、keyElementId、targetCryIfKeyId 和 targetKeyElementId 指定 [SWS_CryIf_91018]。两个元素内的起始位置由 keyElementSourceOffset 和 keyElementTargetOffset 确定，而 keyElementCopyLength 决定要传输的确切字节数 [SWS_CryIf_91018]。

关于并发性，该例程设计为可重入，但明确指出对于相同的源密钥（cryIfKeyId）不可重入 [SWS_CryIf_91018]。因此，使用相同源密钥 ID 的并行调用必须由调用方进行同步或予以避免。

返回值报告同步请求的详细执行状态 [SWS_CryIf_91018]：

• 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：源密钥元素未初始化。

使用

同步函数 CryIf_KeyCopy 将所有密钥元素从源密钥复制到指定的目标密钥（[SWS_CryIf_91016]）。它通过头文件 CryIf.h 提供，且具备服务 ID 0x10（[SWS_CryIf_91016]）。

该函数需要两个输入参数（[SWS_CryIf_91016]）：

• cryIfKeyId：密钥元素用作源的密钥标识符。
• targetCryIfKeyId：接收密钥元素作为目标的密钥标识符。

并发性与限制

该接口被指定为可重入，但不得针对相同的源密钥标识符（cryIfKeyId）同时调用（[SWS_CryIf_91016]）。

错误处理

类型为 Std_ReturnType 的返回值指示操作结果（[SWS_CryIf_91016]）：

• E_OK：复制过程已成功完成。
• E_NOT_OK：请求失败。
• CRYPTO_E_BUSY：失败，因为底层的 Crypto-Driver-Objekt 正忙。
• CRYPTO_E_KEY_NOT_AVAILABLE：请求的密钥元素不可用。
• CRYPTO_E_KEY_READ_FAIL：不允许读取该密钥元素。
• CRYPTO_E_KEY_WRITE_FAIL：写入目标密钥元素是不允许的。
• CRYPTO_E_KEY_SIZE_MISMATCH：密钥元素的大小彼此不兼容。
• CRYPTO_E_KEY_EMPTY：源密钥元素未初始化。

函数 CryIf_RandomSeed 用于将随机种子（Random Seed）的生成或馈入转发给配置的加密驱动对象 [SWS_CryIf_91007]。该函数可通过头文件 CryIf.h 获取，其服务 ID 为 0x07 [SWS_CryIf_91007]。

该接口需要三个输入参数 [SWS_CryIf_91007]：

• cryIfKeyId：要为其生成新种子的密钥的标识符。
• seedPtr：指向包含用于馈入种子的数据的内存区域的指针。
• seedLength：种子的字节长度。

执行行为（同步或异步）并非固定指定，而是取决于各自的配置 [SWS_CryIf_91007]。在并发性方面，该函数被指定为可重入 [SWS_CryIf_91007]。

作为返回值，该函数提供一个 Std_ReturnType，具有以下状态值 [SWS_CryIf_91007]：

• E_OK：请求成功。
• E_NOT_OK：请求失败。
• CRYPTO_E_KEY_NOT_VALID：请求失败，因为该密钥的密钥状态为“invalid”。

Interpretation：在返回 CRYPTO_E_KEY_NOT_VALID 时，校验可能针对所传入的密钥 cryIfKeyId，尽管规范文本中有差异地提到了 cryptoKeyId [SWS_CryIf_91007]。 问题 Q-22b20256f21f131b (未决)

使用

函数 CryIf_KeyGenerate 将用于密钥生成的函数调用转发至配置的 Crypto-Driver-Objekt [SWS_CryIf_91008]。通过输入参数 cryIfKeyId 传递密钥的唯一标识符，该密钥将使用新生成的密钥值进行更新 [SWS_CryIf_91008]。该接口的声明通过头文件 CryIf.h 提供 [SWS_CryIf_91008]。

同步行为与并发性

执行根据底层配置以同步或异步方式进行 [SWS_CryIf_91008]。关于调用上下文和并发性，该函数被指定为可重入 [SWS_CryIf_91008]。

返回值与错误处理

调用返回类型为 Std_ReturnType 的状态值 [SWS_CryIf_91008]：

• E_OK：密钥生成请求已成功执行 [SWS_CryIf_91008]。
• E_NOT_OK：请求失败 [SWS_CryIf_91008]。
• CRYPTO_E_BUSY：请求失败，因为所寻址的 Crypto-Driver-Objekt 当前正忙 [SWS_CryIf_91008]。
• CRYPTO_E_KEY_EMPTY：请求失败，因为所需的源密钥元素未初始化 [SWS_CryIf_91008]。
• CRYPTO_E_KEY_NOT_VALID：请求失败，因为由密钥标识符引用的密钥状态无效 [SWS_CryIf_91008]。

使用

函数CryIf_KeyDerive用于将密钥派生请求同步转发给相应配置的 Crypto Driver Object [SWS_CryIf_91009]。该接口通过头文件CryIf.h以服务 ID 0x09进行声明[SWS_CryIf_91009]。

调用时会传入两个密钥标识符[SWS_CryIf_91009]：

• cryIfKeyId：用作派生基础的密钥标识符。
• targetCryIfKeyId：存放派生密钥的密钥标识符。

错误处理与返回值

操作结果通过返回类型Std_ReturnType传递[SWS_CryIf_91009]：

• E_OK：请求已成功执行[SWS_CryIf_91009]。
• E_NOT_OK：执行失败[SWS_CryIf_91009]。
• CRYPTO_E_KEY_EMPTY：源密钥元素未初始化 [SWS_CryIf_91009]。
• CRYPTO_E_KEY_NOT_VALID：所引用密钥的密钥状态无效[SWS_CryIf_91009]。
• CRYPTO_E_BUSY：下层 Crypto Driver Object 已报告 CRYPTO_E_BUSY [SWS_CryIf_91009]。

并发性与边界条件

该接口被指定为可重入（reentrant）[SWS_CryIf_91009]。由于该流程同步执行，调用方可能需要在各自的调用上下文中考虑驱动程序的执行时间。 问题 Q-2b2fd50249878177 (未决)

同步且可重入的函数 CryIf_KeyExchangeCalcPubVal 将计算密钥交换公钥值的操作转发至配置的 Crypto-Driver-Objekt [SWS_CryIf_91010]。该服务可通过头文件 CryIf.h 获取 [SWS_CryIf_91010]。

在函数调用时处理以下参数 [SWS_CryIf_91010]：

• cryIfKeyId：用于密钥交换协议的密钥标识符。
• publicValuePtr：指向用于存放计算出的公钥值的内存区域的指针。
• publicValueLengthPtr：指向长度信息的指针。调用时该参数必须包含所提供的缓冲区大小；完成后它存储计算值的实际长度。

该函数返回类型为 Std_ReturnType 的状态 [SWS_CryIf_91010]：

• E_OK：请求成功。
• E_NOT_OK：请求失败。
• CRYPTO_E_BUSY：错误，因为负责的 Crypto-Driver-Objekt 正忙。
• CRYPTO_E_KEY_EMPTY：由于源密钥元素未初始化而导致的错误。
• CRYPTO_E_KEY_NOT_VALID：错误，因为寻址的密钥处于无效状态。

同步函数 CryIf_KeyExchangeCalcSecret 将密钥交换中共享秘密的计算转发至配置的 Crypto-Driver-Objekt [SWS_CryIf_91011]。向该服务传递密钥的标识符（cryIfKeyId）、指向通信伙伴公钥值的指针（partnerPublicValuePtr）以及其以字节为单位的长度（partnerPublicValueLength）[SWS_CryIf_91011]。

错误处理：该函数通过 Std_ReturnType 返回结果 [SWS_CryIf_91011]：

• E_OK：计算已成功执行 [SWS_CryIf_91011]。
• CRYPTO_E_BUSY：Crypto-Driver-Objekt 正忙 [SWS_CryIf_91011]。
• CRYPTO_E_KEY_EMPTY：源密钥元素未初始化 [SWS_CryIf_91011]。
• CRYPTO_E_KEY_NOT_VALID：指定密钥的密钥状态无效 [SWS_CryIf_91011]。
• E_NOT_OK：请求失败 [SWS_CryIf_91011]。

并发性：该接口被指定为可重入 [SWS_CryIf_91011]。由于该流程以同步方式执行，调用通常可能在任务上下文中进行。 问题 Q-b3bca3645b0ef468 (未决)该服务通过头文件 CryIf.h 提供 [SWS_CryIf_91011]。

根据 [SWS_CryIf_91013]，函数 CryIf_CallbackNotification 用于通知 Crypto Interface (CryIf) 加密操作的完成情况及其结果。该声明可通过头文件 CryIf.h 获取，其服务 ID 为 0x0d [SWS_CryIf_91013]。

该调用以同步方式进行，并处理两个必选输入参数 [SWS_CryIf_91013]：

• job（输入，Crypto_JobType*）：指向已完成作业的信息结构体，并包含用于关联已终止作业的回调 ID [SWS_CryIf_91013]。
• result（输入，Crypto_ResultType）：传递已执行加密操作的结果 [SWS_CryIf_91013]。

未为此服务定义特定的错误代码或错误消息（DET/DEM）；功能性错误检查通过参数 result 进行，该参数反映操作的成功或错误状态 [SWS_CryIf_91013]。

关于并发性，根据 [SWS_CryIf_91013]，该函数被指定为不可重入（Non Reentrant），且没有返回值（void）。因此，调用方必须确保调用按顺序进行，并且不会发生嵌套或并行执行。Interpretation：该通知通常由底层加密驱动程序调用，以将异步处理的加密作业的结果返回给 Crypto Interface。 问题 Q-ae17af188a970e00 (未决)