python PACSign.py [-h] {FIM,SR,SR_TEST,BBS,BMC,BMC_FW,BMC_FACTORY,AFU,PR,PR_TEST,GBS,FACTORY,PXE,THERM_SR,THERM_PR,SDM,SDM_TEST} ...
python PACSign.py <CMD> [-h] [-S] -t {UPDATE,CANCEL,RK_256,RK_384} -H HSM_MANAGER [-C HSM_CONFIG] [-s SLOT_NUM] [-r ROOT_KEY] [-k CODE_SIGNING_KEY] [-d CSK_ID] [-R ROOT_BITSTREAM] [-b BITSTREAM_VERSION] [-i INPUT_FILE] [-o OUTPUT_FILE] [-q QUARTUS_CERT] [-f FUSE_INFO] [-y] [-v]
The PACSign utility inserts authentication markers into bitstreams targeted for the following programmable
acceleration cards (PACs):
- Intel® PAC with Intel Arria® 10 GX FPGA
- Intel FPGA PAC D5005
- Intel PAC N3000
PACSignuses a root key and an optional code signing key to digitally sign the
bitstreams to validate their origin. The PACs will not program bitstreams without proper authentication.
The current PACs only support elliptical curve keys with the curve types secp256r1 (aka prime256v1)
or secp384r1, however PACSign supports 384-bit keys (secp384r1).
The PACSign command supports hardware security modules (HSMs) for both OpenSSL and PKCS #11.
To utilize PKCS #11, please ensure that the dummy fields lib_path,
token.label, and token.user_password in the configuration file
PKCS11_config.json are modified appropriately before proceeding.
The first required argument to PACSign is the bitstream type identifier.
{SR,SR_TEST,FIM,BBS,BMC,BMC_FW,BMC_FACTORY,PR,PR_TEST,AFU,GBS,FACTORY,PXE,THERM_SR,THERM_PR,SDM,SDM_TEST}
Supported image types. FIM and BBS are aliases for the static region (SR). BMC_FW is an alias for
the board management controller (BMC). AFU and GBS are aliases for the partial reconfiguration (PR) region.
SR (FIM, BBS)
Static FPGA image
SR_TEST
Static FPGA test image
BMC (BMC_FW)
BMC image, including firmware for some PACs
BMC_FACTORY
BMC Factory image
PR (AFU, GBS)
Reconfigurable FPGA image
PR_TEST
Reconfigurable FPGA test image
FACTORY
FPGA factory image
PXE
PXE or Option ROM image
THERM_SR
Thermal limits for static images (including FACTORY)
THERM_PR
Thermal limits for PR images
SDM
Secure Device Manager image
SDM_TEST
Test Secure Device Manager image
All bitstream types must specify the following information:
- An operation that the
PACSigncommand performs - The name and optional parameter file for a key signing module
-t, --cert_type <type>
The following operations are available:
`UPDATE` - add authentication data to the bitstream.
`CANCEL` - create a code signing key cancellation bitstream.
`RK_256` - create a bitstream to program a 256-bit root entry hash into the device.
`RK_384` - create a bitstream to program a 384-bit root entry hash into the device. Currently
available PACs do not support a 384-bit root entry hash.
-H, --HSM_manager <module>
The module name for a module that interfaces to a HSM. PACSign
includes both the openssl_manager and the pkcs11_manager to handle keys and signing
operations.
-C, --HSM_config <cfg> (optional)
The argument to this option is passed verbatim to the specified HSM.
For pkcs11_manager, this option specifies a JSON file describing the PKCS #11
capable HSM's parameters.
-r, --root_key <keyID>
The key identifier that the HSM uses to identify the root key to be used for the selected operation.
-k, --code_signing_key <keyID>
The key identifier that the HSM uses to identify the code signing key to be used for the selected operation.
-d, --csk_id <csk_num>
Only used for type CANCEL. Specifies the key number of the code signing key to
cancel.
-s, --slot_num <slot>
For bitstream types with multiple slots (i.e., multiple SR regions), this option specifies which of the slots to which this bitstream is to be acted upon.
-b, --bitstream_version <vers>
User-formatted version information. This can be any string up to 32 bytes in length.
-S, --SHA384
Used to specify that PACSign is to use 384-bit crypto. Default is 256-bit.
-R, --ROOT_BITSTREAM <root_bitstream>
Valid when verifying bitstreams. The verification step will ensure the generated bitstream is able to be loaded on a board with the specified root entry hash programmed.
-i, --input_file <file>
Only used for UPDATE operations. Specifies the file name containing the data
to be signed.
-o, --output_file <file>
Specifies the file name for the signed output bitstream.
-y, --yes
Silently answer all queries from PACSign in the affirmative.
-v, --verbose
Can be specified multiple times. Increases the verbosity of PACSign. Once
enables non-fatal warnings to be displayed. Twice enables progress information.
Three or more occurrences enables very verbose debugging information.
-q, --quartus_cert <Quartus Cert>
Path to the quartus_sign cancelation certificate. Used with -t CANCEL.
-f, --fuse_info <Fuse info>
Path to the quartus fuse_info.txt file.
Different certification types require different sets of options. The table below describes the options required based on certification type.
| root_key | code_signing_key | csk_id | input_file | output_file | |
|---|---|---|---|---|---|
| SR | Optional1 | Optional1 | No | Yes | Yes |
| BMC | Optional1 | Optional1 | No | Yes | Yes |
| BMC_FACTORY | Optional1 | Optional1 | No | Yes | Yes |
| PR | Optional1 | Optional1 | No | Yes | Yes |
| FACTORY | Optional1 | Optional1 | No | Yes | Yes |
| PXE | Optional1 | Optional1 | No | Yes | Yes |
| THERMAL_SR | Optional1 | Optional1 | No | Yes | Yes |
| THERMAL_PR | Optional1 | Optional1 | No | Yes | Yes |
| SR_TEST | Optional1 | Optional1 | No | Yes | Yes |
| PR_TEST | Optional1 | Optional1 | No | Yes | Yes |
| SDM | Optional1 | Optional1 | No | Yes | Yes |
| SDM_TEST | Optional1 | Optional1 | No | Yes | Yes |
| root_key | code_signing_key | csk_id | input_file | output_file | |
|---|---|---|---|---|---|
| SR | Yes | No | Yes | No | Yes |
| BMC | Yes | No | Yes | No | Yes |
| BMC_FACTORY | Yes | No | Yes | No | Yes |
| PR | Yes | No | Yes | No | Yes |
| FACTORY | Yes | No | No | Yes | Yes |
| PXE | Yes | No | Yes | No | Yes |
| THERMAL_SR | Yes | No | Yes | No | Yes |
| THERMAL_PR | Yes | No | Yes | No | Yes |
| SR_TEST | Yes | No | Yes | No | Yes |
| PR_TEST | Yes | No | Yes | No | Yes |
| SDM | Yes | No | Yes | No | Yes |
| SDM_TEST | Yes | No | Yes | No | Yes |
| root_key | code_signing_key | csk_id | input_file | output_file | |
|---|---|---|---|---|---|
| SR | Yes | No | No | No | Yes |
| BMC | Yes | No | No | No | Yes |
| BMC_FACTORY | Yes | No | No | No | Yes |
| PR | Yes | No | No | No | Yes |
| FACTORY | Yes | No | No | No | Yes |
| PXE | Yes | No | No | No | Yes |
| THERMAL_SR | Yes | No | No | No | Yes |
| THERMAL_PR | Yes | No | No | No | Yes |
| SR_TEST | Yes | No | No | No | Yes |
| PR_TEST | Yes | No | No | No | Yes |
| SDM | Yes | No | No | No | Yes |
| SDM_TEST | Yes | No | No | No | Yes |
Key pairs are required to follow the naming format described in the table below.
| Material Type | Naming Convention |
|---|---|
| SR | * _fim_ * _private/public_ *.pem |
| FACTORY | * _fim2_ * _private/public_ *.pem OR * _factory_ * _private/public_ *.pem |
| SR_TEST | * _sr_test_ * _private/public_ *.pem |
| SR_CERT | * _sr_cert_ * _private/public_ *.pem |
| BMC | * _bmc_ * _private/public_ *.pem |
| BMC_FACTORY | * _bmc_factory_ * _private/public_ *.pem |
| PR | * _pr_ * _private/public_ *.pem |
| PR_TEST | * _pr_test_ * _private/public_ *.pem |
| PXE | * _pxe_ * _private/public_ *.pem |
| THERM_SR | * _therm_sr_ * _private/public_ *.pem |
| THERM_PR | * _therm_pr_ * _private/public_ *.pem |
| SDM | * _sdm_ * _private/public_ *.pem |
| SDM_TEST | * _sdm_test_ * _private/public_ *.pem |
The following command generates a root hash programming PR bitstream.
The generated file can be an input to the fpgasupdate command to program the root hash for
PR operations into the device flash. You can only program the root hash one time.
python PACSign.py PR -t RK_256 -o pr_rhp.bin -H openssl_manager -r key_pr_root_public_256.pem
The following command adds authentication blocks to hello_afu.gbs signed
by both provided keys and writes the result to s_hello_afu.gbs. For signed bitstreams,
the newly-generated block replaces the old signature block.
python PACSign.py PR -t update -H openssl_manager -i hello_afu.gbs -o s_hello_afu.gbs -r key_pr_root_public_256.pem -k key_pr_csk0_public_256.pem
The following command generates a code signing key cancellation bitstream to cancel code signing key number 4 for all BMC operations. After this command runs the PAC rejects BMC images that CSK 4 signed.
python PACSign.py BMC -t cancel -H openssl_manager -o csk4_cancel.gbs -r key_bmc_root_public_256.pem -d 4
| Document Version | Intel Acceleration Stack Version | Changes |
|---|---|---|
| 2019.07.08 | 1.2.1 Beta. (Supported with Intel Quartus Prime Pro Edition 19.2.) |
Initial revision. |
| 2019.10.04 | 2.0.1 Beta. (Supported with Intel Quartus Prime Pro Edition 19.2.) |
Editorial changes only. |
| 2020.12.16 | 2.0.1 Beta. (Supported with Intel Quartus Prime Pro Edition 19.2.) |
Added -S; default SHA384. |
| 2021.02.02 | 2.0.1 Beta. (Supported with Intel Quartus Prime Pro Edition 19.2.) |
Added -s, -b; Added more bitstream types. |
| 2021.02.17 | 2.0.1 Beta. (Supported with Intel Quartus Prime Pro Edition 19.2.) |
Default to 256-bit crypto. |
Footnotes
-
For
UPDATEtype, you must specify both keys to produce an authenticated bitstream. Omitting one key generates a valid, but unauthenticated bitstream. You can only load the unauthenticated bitstream on a PAC with no root entry hash programmed for that bitstream type. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 ↩17 ↩18 ↩19 ↩20 ↩21 ↩22 ↩23 ↩24