Security User Guide: Intel® FPGA Programmable Acceleration Card N3000 Variants

Download PDF
ID 683519
Date 9/08/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 A. bitstreaminfo Tool Examples
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.12. Accessing Intel® FPGA PAC N3000 Version and Authentication Information
3.5. Creating Keys x
3.5.1. OpenSSL Key Creation 3.5.2. HSM Key Creation
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()
3.12. Accessing Intel® FPGA PAC N3000 Version and Authentication Information x
3.12.1. Using fpgainfo security Command 3.12.2. Reading sysfs Files for Identifying Information 3.12.3. Using bitstreaminfo Tool
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
A. bitstreaminfo Tool Examples

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 11.  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 Reject C827 Retimer EEPROM update - Ensure installed retimer version is actually older than the attempted updated version.
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 key 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 do not capture errors for signed FPGA SR user image bitstream programming.

Table 12.  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