stm32g4xx_hal_cryp.c

转到该文件的文档。

/**
  ******************************************************************************
  * @file    stm32g4xx_hal_cryp.c
  * @author  MCD Application Team
  * @brief   CRYP HAL模块驱动。
  *          本文件提供固件功能来管理加密（CRYP）外设的以下功能：
  *           + 初始化、去初始化、设置配置和获取配置功能
  *           + AES处理功能
  *           + DMA回调功能
  *           + CRYP中断处理程序管理
  *           + 外设状态功能
  *
  ******************************************************************************
  * @attention
  *
  * Copyright (c) 2019 STMicroelectronics.
  * All rights reserved.
  *
  * This software is licensed under terms that can be found in the LICENSE file
  * in the root directory of this software component.
  * If no LICENSE file comes with this software, it is provided AS-IS.
  *
  ******************************************************************************
  @verbatim
  ==============================================================================
                     ##### 如何使用此驱动 #####
  ==============================================================================
    [..]
      CRYP HAL驱动可用于CRYP或TinyAES外设，如下所示：

      (#)通过实现HAL_CRYP_MspInit()初始化CRYP底层资源：
         (##) 使用__HAL_RCC_CRYP_CLK_ENABLE()启用CRYP接口时钟
              或TinyAES外设的__HAL_RCC_AES_CLK_ENABLE()
         (##) 如果使用中断（例如HAL_CRYP_Encrypt_IT()）
             (+++) 使用HAL_NVIC_SetPriority()配置CRYP中断优先级
             (+++) 使用HAL_NVIC_EnableIRQ()启用CRYP IRQ处理程序
             (+++) 在CRYP IRQ处理程序中调用HAL_CRYP_IRQHandler()
         (##) 如果使用DMA控制数据传输（例如HAL_CRYP_Encrypt_DMA()）
             (+++) 使用__RCC_DMAx_CLK_ENABLE()启用DMAx接口时钟
             (+++) 配置并启用两个DMA流，一个用于管理从内存到外设的数据传输
                 （输入流），另一个用于管理从外设到内存的数据
                 传输（输出流）
             (+++) 使用__HAL_LINKDMA()将初始化的DMA句柄关联到CRYP DMA句柄
             (+++) 配置优先级并在两个DMA通道上启用传输完成
                 中断的NVIC。输出通道应具有比输入通道更高的
                 优先级HAL_NVIC_SetPriority()和HAL_NVIC_EnableIRQ()。 

      (#)根据指定参数初始化CRYP：
         (##) 数据类型：1位、8位、16位或32位。
         (##) 密钥大小：128、192或256。
         (##) 算法模式：DES/TDES算法ECB/CBC或AES算法ECB/CBC/CTR/GCM或CCM。
         (##) 初始化向量（计数器）。在ECB模式下不使用。
         (##) 用于加密/解密的密钥缓冲区。
             (+++) 在某些特定配置中，密钥由应用程序在HAL范围外编写。
                   在这种情况下，用户仍可以照常使用HAL API，但必须确保pKey指针设置为NULL。
         (##) DataWidthUnit字段。它指定数据长度（或认证的数据长度）。
               算法）是按字还是按字节。
         (##) 仅在AES GCM和CCM算法中用于认证的头部。
         (##) HeaderSize字段，提供头部缓冲区的大小（按字或字节），
              取决于HeaderWidthUnit字段。
         (##) HeaderWidthUnit字段。它指定头部长度（对于认证算法）
              是按字还是按字节。
         (##) B0块是仅在AES CCM模式下使用的第一个认证块。
         (##) KeyIVConfigSkip用于连续处理多条消息（请参阅下面的更多信息）。

      (#)提供三种处理（加密/解密）函数：
         (##) 轮询模式：加密和解密API是阻塞函数
              即它们处理数据并等待处理完成，
              例如HAL_CRYP_Encrypt和HAL_CRYP_Decrypt
         (##) 中断模式：加密和解密API是非阻塞函数
              即它们在中断下处理数据，
              例如HAL_CRYP_Encrypt_IT和HAL_CRYP_Decrypt_IT
         (##) DMA模式：加密和解密API是非阻塞函数
              即数据传输由DMA确保，
              例如HAL_CRYP_Encrypt_DMA和HAL_CRYP_Decrypt_DMA

      (#)当在HAL_CRYP_Init()之后首次调用处理函数时
         配置CRYP外设并处理输入缓冲区。
         第二次调用时，无需初始化CRYP，用户需要通过
         HAL_CRYP_GetConfig() API获取当前配置，然后只需
         HAL_CRYP_SetConfig()设置新参数，最后可以开始加密/解密。

       (#)调用HAL_CRYP_DeInit()去初始化CRYP外设。

       (#)要使用HAL_CRYP_Encrypt()或HAL_CRYP_Decrypt()连续调用处理单个消息
          而无需在每个API调用之间重新配置密钥或初始化向量，
          初始化结构中的字段KeyIVConfigSkip必须设置为CRYP_KEYIVCONFIG_ONCE。
          HAL_CRYP_Encrypt_IT()、HAL_CRYP_Decrypt_IT()、HAL_CRYP_Encrypt_DMA()
          或HAL_CRYP_Decrypt_DMA()的连续调用也是如此。

    [..]
      加密处理器支持以下标准：
      (#) 数据加密标准（DES）和三重DES（TDES）仅由CRYP1外设支持：
         (##) 64位数据块处理
         (##) 支持的链接模式：
             (+++) 电子密码本（ECB）
             (+++) 密码块链接（CBC）
         (##) 支持的密钥长度：64位、128位和192位。
      (#) 高级加密标准（AES）由CRYP1和TinyAES外设支持：
         (##) 128位数据块处理
         (##) 支持的链接模式：
             (+++) 电子密码本（ECB）
             (+++) 密码块链接（CBC）
             (+++) 计数器模式（CTR）
             (+++) Galois/计数器模式（GCM/GMAC）
             (+++) 带密码块链接的消息认证码计数器（CCM）
         (##) 支持的密钥长度：
             (+++) CRYP1外设：128位、192位和256位。
             (+++) TinyAES外设：128位和256位

    [..]
    (@) 必须特别注意密钥和初始化向量IV的格式！

    [..] 如果密钥定义为128位长数组key[127..0] = {b127 ... b0}，其中
         b127是MSB，b0是LSB，则必须将密钥存储在MCU内存中
         (+) 作为字序列，其中MSB字先出现（占据
           最低内存地址）
          (++)   地址n+0：0b b127 .. b120 b119 .. b112 b111 .. b104 b103 .. b96
          (++)   地址n+4：0b b95 .. b88 b87 .. b80 b79 .. b72 b71 .. b64
          (++)   地址n+8：0b b63 .. b56 b55 .. b48 b47 .. b40 b39 .. b32
          (++)   地址n+C：0b b31 .. b24 b23 .. b16 b15 .. b8 b7 .. b0
     [..] 下面，另一个图示，考虑由16字节{B15..B0}组成的128位长密钥。
         组成密钥的4个32位字必须按以下方式存储在MCU内存中：
          (+)    地址n+0：0x B15 B14 B13 B12
          (+)    地址n+4：0x B11 B10 B9 B8
          (+)    地址n+8：0x B7 B6 B5 B4
          (+)    地址n+C：0x B3 B2 B1 B0
     [..]  这导致预期的设置
       (+)       AES_KEYR3 = 0x B15 B14 B13 B12
       (+)       AES_KEYR2 = 0x B11 B10 B9 B8
       (+)       AES_KEYR1 = 0x B7 B6 B5 B4
       (+)       AES_KEYR0 = 0x B3 B2 B1 B0

    [..]  256位长密钥（由32字节{B31..B0}组成）也必须应用相同的格式。
          组成密钥的8个32位字必须按以下方式存储在MCU内存中：
          (+)    地址n+00：0x B31 B30 B29 B28
          (+)    地址n+04：0x B27 B26 B25 B24
          (+)    地址n+08：0x B23 B22 B21 B20
          (+)    地址n+0C：0x B19 B18 B17 B16
          (+)    地址n+10：0x B15 B14 B13 B12
          (+)    地址n+14：0x B11 B10 B9 B8
          (+)    地址n+18：0x B7 B6 B5 B4
          (+)    地址n+1C：0x B3 B2 B1 B0
     [..]  这导致预期的设置
       (+)       AES_KEYR7 = 0x B31 B30 B29 B28
       (+)       AES_KEYR6 = 0x B27 B26 B25 B24
       (+)       AES_KEYR5 = 0x B23 B22 B21 B20
       (+)       AES_KEYR4 = 0x B19 B18 B17 B16
       (+)       AES_KEYR3 = 0x B15 B14 B13 B12
       (+)       AES_KEYR2 = 0x B11 B10 B9 B8
       (+)       AES_KEYR1 = 0x B7 B6 B5 B4
       (+)       AES_KEYR0 = 0x B3 B2 B1 B0

    [..] 初始化向量IV（4个32位字）的格式必须与
         128位长密钥相同。

    [..] 请注意，密钥和IV寄存器对交换模式选择不敏感。

    [..]  本节描述CRYP1和TinyAES外设支持的AES Galois/计数器模式（GCM）：
      (#)  支持的算法：
         (##) Galois/计数器模式（GCM）
         (##) Galois消息认证码（GMAC）：与仅由头部组成的GCM算法完全相同。
      (#)  GCM执行四个阶段：
         (##) 初始化阶段：外设准备GCM哈希子密钥（H）并进行IV处理
         (##) 头部阶段：外设处理附加认证数据（AAD），仅进行哈希
          计算。
         (##) 负载阶段：外设处理明文（P），包括哈希计算+密钥流
          加密+数据异或。对于密文（C）的工作方式类似。
         (##) 最终阶段：外设使用最后一块数据生成认证标签（T）。
      (#)  GCM中的消息结构定义如下：
         (##) 由IV和计数器组成的16字节初始计数器块（ICB）
         (##) 认证头A（也称为附加认证数据AAD）
          这部分消息仅被认证，不加密。
         (##) 明文消息P既被认证又被加密为密文。
          GCM标准规定密文与明文具有相同的位长度。
         (##) 最后一块由A的长度（64位）和密文的长度
          （64位）组成

    [..]  下面提供了GCM消息结构的更详细描述。

    [..]  本节描述CRYP1和TinyAES外设支持的AES计数器与密码块链接-消息
          认证码（CCM）：
      (#)  CCM的特定参数：

         (##) B0块：遵循NIST特别出版物800-38C，
         (##) B1块（头部）
         (##) CTRx块：控制块

    [..]  下面提供了CCM消息结构的详细描述。

      (#)  CRYP1外设的CCM执行四个阶段：
         (##) 初始化阶段：外设准备GCM哈希子密钥（H）并进行IV处理
         (##) 头部阶段：外设处理附加认证数据（AAD），仅进行哈希
          计算。
         (##) 负载阶段：外设处理明文（P），包括哈希计算+密钥流
          加密+数据异或。对于密文（C）的工作方式类似。
         (##) 最终阶段：外设使用最后一块数据生成认证标签（T）。
      (#)    TinyAES外设中的CCM：
         (##) 为了执行消息负载加密或解密，AES配置为CTR模式。
         (##) 认证执行两个阶段：
          - 头部阶段：外设首先处理附加认证数据（AAD），然后处理明文消息
          仅使用明文负载（不是密文负载），不产生输出。
         (##) 最终阶段：外设使用最后一块数据生成认证标签（T）。

  *** 回调注册 ***
  =============================

  [..]
  编译定义USE_HAL_CRYP_REGISTER_CALLBACKS设置为1时
  允许用户动态配置驱动回调。
  使用函数HAL_CRYP_RegisterCallback()或HAL_CRYP_RegisterXXXCallback()
  注册中断回调。

  [..]
  函数HAL_CRYP_RegisterCallback()允许注册以下回调：
    (+) In