Metadata-Version: 2.4
Name: pacsign
Version: 1.0.8
Summary: pacsign provides Python classes for interfacing with the OPAE PACSign tool
License: BSD-3-Clause
Project-URL: Homepage, https://opae.github.io
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# PACSign #

## SYNOPSIS ##
`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]`

## DESCRIPTION ##
The `PACSign` utility inserts authentication markers into bitstreams targeted for the following programmable
acceleration cards (PACs):
* Intel&reg; PAC with Intel Arria&reg; 10 GX FPGA
* Intel FPGA PAC D5005
* Intel PAC N3000
`PACSign` uses 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.

## BITSTREAM TYPES ##
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

## REQUIRED OPTIONS ##

All bitstream types must specify the following information:
* An operation that the `PACSign` command 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.

## OPTIONS ##

`-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.

## NOTES ##

Different certification types require different sets of options.  The table below
describes the options required based on certification type.

### UPDATE ###

| | root_key | code_signing_key | csk_id | input_file | output_file |
|---|---|---|---|---|---|
| SR | Optional[^2] | Optional[^2] | No | Yes | Yes |
| BMC | Optional[^2] | Optional[^2] | No | Yes | Yes |
| BMC_FACTORY | Optional[^2] | Optional[^2] | No | Yes | Yes |
| PR | Optional[^2] | Optional[^2] | No | Yes | Yes |
| FACTORY | Optional[^2] | Optional[^2] | No | Yes | Yes |
| PXE | Optional[^2] | Optional[^2] | No | Yes | Yes |
| THERMAL_SR | Optional[^2] | Optional[^2] | No | Yes | Yes |
| THERMAL_PR | Optional[^2] | Optional[^2] | No | Yes | Yes |
| SR_TEST | Optional[^2] | Optional[^2] | No | Yes | Yes |
| PR_TEST | Optional[^2] | Optional[^2] | No | Yes | Yes |
| SDM | Optional[^2] | Optional[^2] | No | Yes | Yes |
| SDM_TEST | Optional[^2] | Optional[^2] | No | Yes | Yes |

### CANCEL ###

| | 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 |


### RK_256 / RK_384[^1] ###

| | 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 |


[^2]: For `UPDATE` type, 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.

### Key Naming Convention ###

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 |

## EXAMPLES ##

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`

## Revision History ##

 | Document Version |  Intel Acceleration Stack Version  | Changes  |
 | ---------------- |------------------------------------|----------|
 | 2019.07.08 | 1.2.1 Beta. <br>(Supported with Intel Quartus Prime Pro Edition 19.2.) | Initial revision.  | 
 | 2019.10.04 | 2.0.1 Beta. <br>(Supported with Intel Quartus Prime Pro Edition 19.2.) | Editorial changes only. |
 | 2020.12.16 | 2.0.1 Beta. <br>(Supported with Intel Quartus Prime Pro Edition 19.2.) | Added -S; default SHA384. |
 | 2021.02.02 | 2.0.1 Beta. <br>(Supported with Intel Quartus Prime Pro Edition 19.2.) | Added -s, -b; Added more bitstream types. |
 | 2021.02.17 | 2.0.1 Beta. <br>(Supported with Intel Quartus Prime Pro Edition 19.2.) | Default to 256-bit crypto. |
