How to Generate PKI Files¶
ESP-AT provides python script AtPKI.py
to convert SSL server certificates, SSL client certificates, MQTT certificates, and WPA2 certificates files (including CA
, cert
, and private key
files) into bin files.
Certificate Bin Files Format¶
In addition to converting the certificate file into a bin file, the script AtPKI.py
adds some additional information to the bin file.
When converting a single certificate file, the script will add 12 bytes in little-endian format to the header and 4 bytes aligned at the end.
Field
Description
magic code (2 bytes)
0xF1 0xF1
list size (2 bytes)
the number of certificate files
length (4 bytes)
remaining file size = total file size - magic code size - list size - length size
type (1 bytes)
ca: 0x01certificate: 0x02key: 0x03ID (1 bytes)
used to match certificate files
content len (2 bytes)
the size of the certificate file converted to the bin file
Taking the client_cert.bin
generated in the Generate Certificate Bin Files section as an example, the 12 bytes in little-endian format at the beginning of the file are:
Field
Description
magic code (2 bytes)
0xF1 0xF1
list size (2 bytes)
0x02 0x00
length (4 bytes)
0x20 0x09 0x00 0x00
type (1 bytes)
0x02
ID (1 bytes)
0x00
content len (2 bytes)
0x8C 0x04
When converting multiple certificate files, the script AtPKI.py
inserts 4 bytes at the beginning of every file except the first one. The 4 bytes in little-endian format at the beginning of the file are:
Field
Description
type (1 bytes)
ca: 0x01certificate: 0x02key: 0x03ID (1 bytes)
used to match certificate files
content len (2 bytes)
the size of the certificate file converted to the bin file
Taking the client_cert.bin
generated in the Generate Certificate Bin Files section as an example, the 4 bytes in little-endian format at the beginning of the file are:
Field
Description
type (1 bytes)
certificate: 0x02
ID (1 bytes)
0x01
content len (2 bytes)
0x8C 0x04
Generate Certificate Bin Files¶
Select one of the following ways to generate certificate bin files.
Script Generation¶
The path of AtPKI.py
is tools/AtPKI.py. You can get help information of the script through the -h
option. You can also generate bin files directly through the following commands.
python <SCRIPT_PATH> generate_bin [-b OUTPUT_BIN_NAME] <PKI_LIST> <source_file>
SCRIPT_PATH
: the path the script. If you’re in “tools” folder of ESP-AT project,SCRIPT_PATH
isAtPKI.py
.OUTPUT_BIN_NAME
: the target file which you want to save the generated bin (absolute address or relative address of the target file); if-b OUTPUT_BIN_NAME
is omitted, it will generatePKI.bin
in the current directory.PKI_LIST
: must be equal to one ofca
,cert
,key
.source_file
: the certificate source file which you want to convert (absolute address or relative address of the source file).
Taking the SSL client certificate files of ESP-AT as an example, you can execute the following command to generate client_cert.bin
in the tools directory:
python AtPKI.py generate_bin -b ./client_cert.bin cert ../components/customized_partitions/raw_data/client_cert/client_cert_00.crt cert ../components/customized_partitions/raw_data/client_cert/client_cert_01.crt
Generation During Compilation¶
The storage path of certificate files in ESP-AT is components/customized_partitions/raw_data.
Taking the SSL client certificate files of ESP-AT as an example. If you want to generate your own SSL client certificates files, you must replace the CA
certificate in the client_ca
directory with your own CA
certificate, the cert certificate in the client_cert
directory with your own cert
certificate, and the private key
in the client_ key
directory with your own private key
.
If you have multiple sets of certificate files, please place them in the corresponding directory according to your certificate chain. It is recommended that you end the file name with a number to ensure the parsing order of the certificate files.
After replacement, You can refer to Compile ESP-AT Project to compile the ESP-AT project.
Download or Update Certificate Bin Files¶
The script AtPKI.py
is only responsible for converting the certificate files to bin files. You can download bin files to the corresponding flash partition in one of the following ways:
Download with Tools¶
Windows
Please download Flash Download Tools for Windows.
For more details about the Tools, please see
readme.pdf
or thedoc
folder in the zip folder.Linux or macOS
Please use esptool.py.
You can execute the following command in the root directory of ESP-AT to download bin files.
esptool.py --chip auto --port PORTNAME --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB ADDRESS FILEDIRECTORY
Replace
PORTNAME
with your port name. ReplaceADDRESS
with the the download address. ReplaceFILEDIRECTORY
with the file directory of the bin.
Update with Commands¶
-
Taking
ESP32
module as an example, you can execute the following command to upgrade theclient_cert
partition. Please refer to AT+SYSFLASH for more details.Query user partitions in flash
Command:
AT+SYSFLASH?
Response:
+SYSFLASH:"ble_data",64,1,0x21000,0x3000 +SYSFLASH:"server_cert",64,2,0x24000,0x2000 +SYSFLASH:"server_key",64,3,0x26000,0x2000 +SYSFLASH:"server_ca",64,4,0x28000,0x2000 +SYSFLASH:"client_cert",64,5,0x2a000,0x2000 +SYSFLASH:"client_key",64,6,0x2c000,0x2000 +SYSFLASH:"client_ca",64,7,0x2e000,0x2000 +SYSFLASH:"factory_param",64,8,0x30000,0x1000 +SYSFLASH:"wpa2_cert",64,9,0x31000,0x2000 +SYSFLASH:"wpa2_key",64,10,0x33000,0x2000 +SYSFLASH:"wpa2_ca",64,11,0x35000,0x2000 +SYSFLASH:"mqtt_cert",64,12,0x37000,0x2000 +SYSFLASH:"mqtt_key",64,13,0x39000,0x2000 +SYSFLASH:"mqtt_ca",64,14,0x3b000,0x2000 +SYSFLASH:"fatfs",1,129,0x70000,0x90000 OK
Erase
client_cert
sector
Command:
AT+SYSFLASH=0,"client_cert"
Response:
OK
Update
client_cert
sector
Command:
AT+SYSFLASH=1,"client_cert",0,2344
Response:
>
If the
operator
iswrite
, wrap return>
after the write command, then you can send the data that you want to write. The length should be parameter<length>
. When the write operation is completed, the system will prompt the following information.OK
-
For example, you can execute the following command to upgrade the
client_ca
partition. Please refer to AT+CIUPDATE for more details.Important
If you want to update the
client_ca
partition in this way, you must implement your own OTA device, please refer to How to Implement OTA Upgrade.AT+CIUPDATE=1,"v2.2.0.0","client_ca"
Note
You must ensure that the download address is correct, otherwise the ESP-AT firmware may not work. The simplest way to view the download address is to execute the command AT+SYSFLASH?.