安全功能应用指南

[English]

一、工具下载

相关工具 下载地址

二、安全相关配置文件

用于自动化编译生成安全相关镜像的配置文件在middleware/boards/bk7256下：

  1. security_ctrl.csv

    该文件控制安全相关镜像是否编译生成。

    “#Project”列对应所编译的project工程名称，”Enable”列对应自动编译状态，配置为”TRUE”时会生成安全相关镜像，配置为”FALSE”时不生成。 “#Project”列第一项”security”为总开关，配置为”FALSE”时所有工程都不编译生成安全相关镜像。

    默认”app”、”customization/bk7256_configa”、”customization/bk7256_configb”三个工程会生成安全相关的镜像。

    客户自定义project且需要生成安全镜像时，可将project工程名称添加到”#Project”列中并配置为”TRUE”。

    #Project

    Enable

    security

    TRUE

    app

    TRUE

    customization/bk7256_configa

    TRUE

    customization/bk7256_configa

    TRUE

  2. key_pair_selection.csv

    该文件用于指定bootloader和app签名的密钥对。

    编译系统在对镜像进行签名时，会按照以下路径优先级查找”key_pair”中指定的密钥对文件，当查找失败时会默认使用tools/env_tools/beken_packager下的用于测试的ecdsa384.der密钥对。

    支持bootloader和app使用不同的密钥对进行签名，首先配置”key_pair”为不同名称如ecdsa384_bootloader.der和ecdsa384_app.der， 然后使用签名工具生成同名密钥对文件并放置到指定路径下。

编译系统查找密钥文件指定路径和优先级：

  1. projects/”project”/config/bk7256

  2. middleware/boards/bk7256

  3. tools/env_tools/beken_packager （默认放置了测试使用的密钥文件）

firmware

key_pair

bootloader

ecdsa384.der

app

ecdsa384.der

  1. version_anti_rollback.csv

    该文件用于版本防回滚功能的固件版本管理。

    “version”取值范围为0–255，默认版本号为0. 开启安全之后，当前bootloader不支持版本升级，因此bootloader的版本号固定为0.

    firmware

    version

    bootloader

    0

    app

    0

三、安全镜像生成步骤

生成安全镜像需要以下四个步骤，为方便开发，以下步骤1到4已经集成到编译系统当中：

  • 1.镜像签名

  • 2.镜像打包

  • 3.镜像加密

  • 4.添加CRC

以”app”工程为例，执行”make bk7256”命令编译结束后，会在build/app/bk7256/encrypt路径下生成用于安全的bin文件：

all_app_pack_enc_crc.bin      //包含bootloader，用于仅开启flash加密时烧写
all_app_pack_sign_crc.bin     //包含bootloader，用于仅开启secureboot时首次烧写
all_app_pack_sign_enc_crc.bin //包含bootloader，用于开启secureboot和flash加密时首次烧写
app_pack.rbl                  //用于未开启安全后的OTA升级
app_pack_sign.rbl             //用于开启安全后的OTA升级
app_pack_sign_enc_crc.bin     //不包含bootloader，用于开启了secureboot和flash加密后通过uart更新app
bootloader_sign_enc_crc.bin   //经过签名和加密后的bootloader镜像

工具使用方法

本小节为使用工具手动生成安全镜像的方法，当使用编译系统自动生成安全镜像时只需要关心签名密钥对和flash加密密钥生成方法。

重要

为方便开发，以上步骤1到4已经集成到编译系统当中，编译系统优先去middleware/boards/bk7256寻找签名的密钥对文件ecdsa384.der和flash加密的key文件config.json， 如果middleware/boards/bk7256下没有相关的密钥文件，会使用/tools/env_tools/beken_packager下放置的测试用密钥文件。3.2和3.3章节是生成安全镜像主要步骤的详细说明， 用户自定义密钥时，只需要根据3.2和3.3章节运行密钥生成脚本，生成的密钥文件ecdsa384.der和flash加密的key文件config.json，然后放置到middleware/boards/bk7256下， 直接编译，会在build/app/bk7256/encrypt路径下生成用于安全的bin文件。

1. 镜像签名

签名算法

  • ECDSA P384

  • SHA384

签名指令

提供签名工具SignTool.exe和示例脚本，用于生成ECDSA密钥对和镜像签名，相关指令如下表。

Command

Options

Value

Description

sign

-prikey

file.der

File containing ECDSA keypair

-infile

infile.img

Input file with the image to sign

-outfile

outfile.img

Output file containing the signed image

-length

hex

Size of image for ECDSA process

getkey

-type

BLKey BLKeyC

As binary or C array

-key

file.der

File containing ECDSA keypair (or pubkey)

-outfile

outfile

Output file containing exported public key

genkeypair

-algo

ecdsa384

ECDSA bit-length

-outfile

outfile.der

Output file containing ECDSA keypair

version

To print the current version of this utility

help

To print this help message

签名过程

  • 运行脚本Signtool_GenKeypair.bat生成ECDSA密钥对。

  • 运行脚本Signtool_GetKey.bat获取该密钥对中的公钥。

  • 将需要签名的镜像和签名工具放置在同一目录下，运行脚本Signtool_Sign.bat，使用生成的密钥对对镜像签名。

//从密钥对中获取到的公钥
uint32_t secure_boot_public_key[] =
{
 /* the Qall value */
 6ce8840b90c31a00542e07e9d608920eee7b8b363123d706c668bc1127b6b4a6278d2eddb7ccd83d32d6d094b528213e0bf6907209a13d6ecaa312a59c622372bfc511faab9b0f291b2cb7b17a7259c63d8453946a0969e0a070770973bd47e6,
}
BK_SignTool

BK_SignTool

举例说明:

生成密钥对：SignTool.exe genkeypair -algo ecdsa384 -outfile ecdsa384.der
获取公钥：SignTool.exe getkey -type BLKeyC -key ecdsa384.der -outfile ecdsa384.c
镜像签名：SignTool.exe sign -prikey ecdsa384.der -infile bootloader.bin  -outfile bootloader_sign.bin -len 0x10000

重要

ECDSA密钥对生成脚本执行一次则生成一组密钥对，生成的密钥对请妥善保管； 获取的公钥存储在ecdsa384.c文件中，需要拷贝到otp_efuse_config.json中供BKFIL工具烧写密钥到OTP时使用。

客户自定义签名的密钥对时，请将生成的密钥对文件ecdsa384.der放在 指定路径 下，编译系统会按照路径优先级查找密钥对文件； 当系统在指定路径下找不到密钥文件时，默认使用tool下的测试密钥对文件。

2. 镜像打包

镜像打包是根据flash分区文件configuration.json将2个或者多个镜像打包成一个镜像。

镜像打包指令

提供镜像打包工具cmake_Gen_image.exe用于打包。

Command

Options

Value

Description

genfile

-injsonfile

configuration.json

input json file

-infile

xx1.bin xx2.bin

input bin file

-outfile

all bin

Output all bin file

version

To print the current version of this utility

help

To print this help message

重要

镜像可以在签名之后进行打包，也可以在签名、加密和添加CRC完成后再进行打包； 对没有添加CRC的镜像进行打包，configuration.json文件请使用逻辑地址； 对添加CRC后的镜像进行打包，configuration.json文件请使用物理地址。

举例说明:

将bootloader_sign.bin和app_sign.bin打包成all_app.bin：
cmake_Gen_image.exe  genfile -injsonfile configuration.json -infile bootloader_sign.bin app_sign.bin -outfile all_app.bin

3. 镜像加密

镜像加密使用AES-XTS256加密方式，保证镜像的机密性。

加密算法

AES-XTS256

加密指令

提供加密工具beken_aes.exe，用于密钥生成和镜像加密。

Command

Options

Value

Description

genkey

-outfile

aes_encrypt_key.json

falsh encrypt key is saved in aes_encrypt_key.json

-aes_cbc

aes_encrypt_key.json

Key and IV for OTA are saved in aes_encrypt_key.json

encrypt

-keyfile

aes_encrypt_key.json

File containing AES key

-infile

infile

the image to be encrypted

-startaddress

Hex

encrypt with logical start address

-outfile

outfile

encrypted image

version

To print the current version of this utility

help

To print this help message

加密过程

  • 运行脚本genkey_random.bat，生成用于flash加密的密钥；

  • 将需要加密的镜像和加密工具放置在同一目录下，运行脚本encrypt_bin_in_aes_file.bat完成对镜像的加密。

举例说明:

生成AES密钥：beken_aes.exe genkey -aes_cbc -outfile aes_encrypt_key.json
app镜像加密：beken_aes.exe encrypt -infile app.bin -startaddress 0x10000 -keyfile aes_encrypt_key.json -outfile app_enc.bin
all_app.bin加密：beken_aes.exe encrypt -infile all_app.bin -startaddress 0x0 -keyfile aes_encrypt_key.json -outfile all_app_enc.bin

生成的密钥内容：

{
    "name":               "aes_key",   //flash加密密钥的密文，将data部分复制到otp_efuse_config.json的Security_data的aes_key的data中
    "mode":              "write",
    "start_addr":         "",
    "last_valid_addr":    "",
    "byte_len":           "0x20",
    "data":              "cbdzcdbwdscacjdyccbxbzbwdzducddvbxeeeecjedcgceeeegeecfehclcleacgciebckcledclecefcibobpbpbobibpboeienbgeibjeoejeneobkenepbnbgbten",
    "data_type":          "ascii",
    "status":            "true"
},
{
    "name":               "aes_key_plaintext", //flash加密密钥的明文
    "mode":              "write",
    "start_addr":         "",
    "last_valid_addr":    "",
    "byte_len":           "0x20",
    "data":              "6d34d08c3756ad0d6dd4b31fdf2d33d61d31e1db38998298ad2b1dbfb0ab258c",
    "data_type":          "ascii",
    "status":            "true"
},
{
    "name":               "OTA_key", //用于OTA升级的密钥的密文，将data部分复制到otp_efuse_config.json的Security_data的OTA_key的data中
    "mode":              "write",
    "start_addr":         "",
    "last_valid_addr":    "",
    "byte_len":           "0x20",
    "data":              "cbbwbxctcadgbxdibzcjccdicteadsbzejeccicqcqddeachetdyelcucredcuce",
    "data_type":          "ascii",
    "status":            "true"
},
{
    "name":               "OTA_key_plaintext", //用于OTA升级的密钥的明文
    "mode":              "write",
    "start_addr":         "",
    "last_valid_addr":    "",
    "byte_len":           "0x20",
    "data":              "632C0P5S683PAng4vb4LMXa1qlxCNgD4",
    "data_type":          "ascii",
    "status":            "true"
},
{
    "name":               "OTA_IV", ////用于OTA升级的IV的密文，将data部分复制到otp_efuse_config.json的Security_data的OTA_IV的data中
    "mode":              "write",
    "start_addr":         "",
    "last_valid_addr":    "",
    "byte_len":           "0x10",
    "data":              "dcemcdcybwcnbydrccckcuccewdwdtcl",
    "data_type":          "ascii",
    "status":            "true"
},
{
    "name":               "OTA_IV_plaintext", //用于OTA升级的IV的明文
    "mode":              "write",
    "start_addr":         "",
    "last_valid_addr":    "",
    "byte_len":           "0x10",
    "data":              "Sw3H4D7Z38N0xcf7",
    "data_type":          "ascii",
    "status":            "true"
},

重要

AES-XTS模式加密结果与被加密文件的地址相关，在需要手动单独加密app镜像时-startaddress应设置为该镜像的逻辑地址。

客户自定义flash加密密钥时，请将生成的密钥文件aes_encrypt_key.json放在 指定路径 下，编译系统会按照路径优先级查找密钥文件； 当系统在指定路径下找不到密钥文件时，默认使用tool下的测试密钥文件。

4. 添加CRC校验

CPU在读取FLASH上镜像时硬件会进行CRC校验，因此镜像需要添加CRC之后才可以烧写到flash中。

CRC插入规则：每32个字节计算出2个字节的CRC值，插入到该32字节之后；插入CRC之前的地址对应逻辑地址，插入CRC之后的地址对应物理地址。

上一步镜像加密后会输出对应添加CRC后的版本，可直接用于烧写。

提供工具cmake_encrypt_crc.exe用于添加CRC。

  • 将需要添加CRC镜像和工具放置在同一目录下，运行脚本add_crc.bat即可。

举例说明:

添加CRC： cmake_encrypt_crc.exe -crc all_enc.bin

四、烧写安全镜像和密钥，使能安全功能

重要

Note：OTP和eFuse只能烧写一次，一但烧写后不可更改，需要谨慎操作！ 在使能efuse的secure boot和encrypt之前，请确保flash中烧写有经过加签、加密、加CRC后的镜像，否则该芯片将无法更新镜像。

1. 配置otp_efuse_config.json

生成的密钥对文件和flash加密密钥文件，除了用于生成安全镜像，还需要烧写到芯片的OTP中。

将3.1节生成的 ecdsa384.c 中的publickey和3.3节生成的 aes_encrypt_key.json 中的aes_key、OTA_key、OTA_IV拷贝到otp_efuse_config.json的安全数据配置区，方法见 OTP和eFuse的配置及读写方法 中安全数据配置区参数说明。

BKFIL.exe会根据配置文件otp_efuse_config.json，将其中的签名的公钥、加密的密钥烧写到OTP中，并根据eFuse的配置来使能安全功能。

2. 烧写安全镜像并使能安全

  • 1.BKFIL工具选择配置界面

  • 2.选择第一次烧写对应的安全镜像

  • 3.选择”eFuse密钥”文件选择按钮,选择配置好的otp_efuse_config.json

  • 4.勾选”OTP”或者”烧录eFuse”选项

  • 5.BKFIL工具选择主界面，点击”烧录”按钮

BKFIL download step

首次烧写安全镜像

四、开启安全后镜像升级方式

开启安全后，当前bootloader将不可更新，只能对app镜像进行更新升级。

  • 方式一：使用BKFIL.exe工具将build/app/project/encrypt下的app_pack_sign_enc_crc.bin烧写到对应的物理分区上。

  • 方式二: 使用OTA升级方式，使用build/app/project/encrypt下的app_pack_sign.rbl升级，升级方法和非安全版本一样，见OTA升级。

反馈该文档建议