Security User Guide: Intel® FPGA Programmable Acceleration Card D5005

Download PDF
ID 683877
Date 8/25/2020
Public
Document Table of Contents
Document Table of Contents x
1. Overview 2. Intel® FPGA PAC Security Features 3. Intel FPGA PAC Security Flow 4. Using fpgasupdate 5. Document Revision History for Security User Guide
1. Overview x
1.1. About This Document 1.2. Prerequisites 1.3. Related Documentation 1.4. Glossary
2. Intel® FPGA PAC Security Features x
2.1. Secure Image Updates 2.2. Anti-Rollback Capability 2.3. Key Management 2.4. Authentication 2.5. Encryption
3. Intel FPGA PAC Security Flow x
3.1. Installing PACSign 3.2. PACSign Tool 3.3. Creating Unsigned Images 3.4. Using an HSM Manager 3.5. Creating Keys 3.6. Root Entry Hash Bitstream Creation 3.7. Signing Images 3.8. Creating a CSK ID Cancellation Bitstream 3.9. PACSign PKCS11 Manager *.json Reference 3.10. Creating a Custom HSM Manager 3.11. PACSign Man Page
3.5. Creating Keys x
3.5.1. OpenSSL Key Creation 3.5.2. HSM Key Creation
3.7. Signing Images x
3.7.1. Signing OpenCL* Images
3.10. Creating a Custom HSM Manager x
3.10.1. HSM_MANAGER.get_public_key(public_key) 3.10.2. HSM_MANAGER.sign(data, key) 3.10.3. Signing Operation Flow
3.10.1. HSM_MANAGER.get_public_key(public_key) x
3.10.1.1. PUBLIC_KEY.get_X_Y() 3.10.1.2. PUBLIC_KEY.get_permission() 3.10.1.3. PUBLIC_KEY.get_ID() 3.10.1.4. PUBLIC_KEY.get_content_type()
4. Using fpgasupdate x
4.1. Troubleshooting
1. Overview
2. Intel® FPGA PAC Security Features
3. Intel FPGA PAC Security Flow
4. Using fpgasupdate
5. Document Revision History for Security User Guide

4.1. Troubleshooting

fpgasupdate provides descriptive errors when it cannot complete the requested operation.

When using fpgasupdate to program bitstreams created or signed with PACSign, the tool may reject the bitstream if, for example, there was an error in the signing process or if the signed bitstream is corrupted. The OPAE driver reports the BMC doorbell and authentication status register values into the system messages log. You may find this log file in a location such as /var/log/messages or /etc/syslog depending on the OS you are using. The error entry contains the keywords intel-max10. An example of output in the log file might look something like this:

[ 4971.546624] intel-max10 spi2.0: RSU error status: 8'h10022104

[ 4971.548681] intel-max10 spi2.0: RSU auth result: 8'h00000011

In this example the error status value, bit[23:16] is the RSU error value to reference in the BMC Doorbell Register Values and Error Descriptions table.

You may use the following tables to decode the authentication status and associated errors.

Table 7.  BMC Doorbell Register Values and Error Descriptions
RSU-error [23:16] Value Status Name Status Description Corrective Action
8'h00 Normal status - Not applicable.
8'h01 Host timeout Flow Error: Host timeout sending bitstream. Possible OS or system issue. Attempt sending bitstream again.
8'h02 Authentication failure - Ensure bitstream is properly signed with the correct keys.
8'h03 Image copy failure Flow Error: Image copy failure Attempt copy again. If issue persists, contact Intel® support.
8'h04 Fatal, error, Nios® boot-up failure - Contact Intel® support.
8'h05 Reserved - -
8'h06 Staging area non-incremental write failure - Contact Intel® support.
8'h07 Staging area erase failure - Contact Intel® support.
8'h08 Staging area write wearout - Contact Intel® support.
8'h80 Nios® boot OK - Not applicable.
8'h81 Update OK Update image okay Not applicable.
8'h82 Factory OK Factory image okay Not applicable.
8'h83 Update Failure - Contact Intel® support.
8'h84 Factory Failure - Contact Intel® support.
8'h85 Nios® Flash Open Error - Contact Intel® support.
8'h86 FPGA Flash Open Error - Contact Intel® support.
Others Reserved - -
The errors in the following Authentication Status Register table are for failures that occur when programming the root entry hash bitstream or the cancellation key bitstream. These error types might occur if, for example, a root entry hash bitstream is signed with the incorrect key. These registers and the log files do not capture errors for signed AFU bitstream programming. If you run fpgasupdate and encounter errors, you must verify your AFU bitstream was signed with a CSK that is compatible with the root entry hash that is programmed on the Intel® FPGA PAC. When an AFU fails to load on the Intel® FPGA PAC you see this error message: 
Error output: 
sudo fpgasupdate hw/samples/dma_afu/bin/dma_afu_unsigned.gbs 
[sudo] password for amrutha: 
[2019-11-01 18:23:25,406] [WARNING ] Update starting. Please do not interrupt.
libopae-c reconf.c:427:fpgaReconfigureSlot() **ERROR** : Failed to reconfigure bitstream: Input/output error
libopae-c reconf.c:455:fpgaReconfigureSlot() **ERROR** : PR IP protocol error detected
Error writing bitstream to FPGA: reconfiguration error
[2019-11-01 18:23:40,172] [ERROR   ] 
Partial Reconfiguration failed
To recover from this error, you must power cycle the Intel® FPGA PAC by power cycling the server.
Table 8.  Authentication Status Register Values and Error Descriptions
Authentication Status Value Error Name Error Description Corrective Action
32'h00000000 Authenticate Pass Authenticate Pass Not applicable.
32'h00000001 Block0 Magic value error Bitstream Format Error: Block 0 bad magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000002 Block0 ConLen error Bitstream Format Error: Block 0 content length error. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000003 Block0 ConType B[7:0] > 2 Bitstream Format Error: Block 0 content type error. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000004 Block1 Magic value error Bitstream Format Error: Block 1 bad magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000005 Root Entry Magic value error Bitstream Format Error: Root entry bad magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000006 Root Entry Curve Magic value error Bitstream Format Error: Root entry bad curve magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000007 Root Entry Permission error Root entry bad permissions. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000008 Root Entry Key ID error Bitstream Format Error: Root entry bad key ID. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000009 CSK Entry Magic value error Bitstream Format Error: CSK bad magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h0000000A CSK Entry Curve Magic value error Bitstream Format Error: CSK bad curve magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h0000000B CSK Entry Permission error Authentication Error: CSK bad permission. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h0000000C CSK Entry Key ID error Bitstream Format Error: CSK invalid key ID, Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h0000000D CSK Entry Signature Magic value error Bitstream Format Error: CSK bad signature magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h0000000E Block0 Entry Magic value error Bitstream Format Error: Block 0 entry bad magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h0000000F Block0 Entry Signature Magic value error Bitstream Format Error: Block 0 entry bad signature magic number. Indicates bitstream corruption. Ensure bitstream is properly signed with the correct keys.
32'h00000010 Root Entry Hash bitstream not programmed for RSU and Cancellation Authentication error: Cancellation attempted with no root entry hash bitstream programmed. Program root entry hash bitstream.
32'h00000011 Root Entry verify SHA failed Authentication Error: Root hash mismatch. Ensure bitstream is properly signed with the correct keys.
32'h00000012 CSK Entry verify ECDSA and SHA failed Authentication Error: CSK signature invalid. Indicates CSK or root entry hash tampering. Ensure bitstream is properly signed with the correct keys.
32'h00000013 Block0 Entry verify ECDSA and SHA failed Authentication Error: Block 0 entry signature invalid. May indicate image tampering. Ensure bitstream is properly signed with the correct keys.
32'h00000014 KEY ID of authenticate blob is invalid Bitstream Format Error: CSK invalid key ID. Indicates you are using an ID value greater than what is allowed. Ensure bitstream is properly signed with the correct keys.
32'h00000015 KEY ID is cancelled Authentication Error: CSK canceled. Indicates you are attempting to program an image with a cancelled CSK. Ensure bitstream is properly signed with the correct keys.
32'h00000016 Update content SHA verify failed Authentication Error: Payload SHA mismatch. May indicate tampering of the bitstream. Verify correctness of bitstream; may need to resign.
8'h00000017 Cancellation content SHA verify failed Authentication Error: Payload SHA mismatch. May indicate tampering of the cancellation certificate. Verify correctness of bitstream; may need to resign.
8'h00000018 HASH Programming content SHA verify failed Authentication Error: Payload SHA mismatch. May indicate tampering of the root key. Verify correctness of bitstream; may need to resign.
8'h00000019 Invalid cancellation ID of cancellation certificate Bitstream Format Error: CSK invalid key ID Verify correctness of bitstream; may need to resign.
8'h0000001A KEY hash has been programmed for KEY hash programming certificate Authentication Error: Attempt to program root entry hash when the root entry hash bitstream has already been programmed. You may only program root entry hash bitstream one time.
8'h0000001B Invalid operation of Block0 ConType - Contact Intel® support.
8'h000000FF Generic Authentication Failure - Contact Intel® support.
Level Two Title