Security User Guide: Intel® Programmable Acceleration Card with Intel® Arria® 10 GX FPGA

Download PDF
ID 683453
Date 3/06/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
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. Creating OpenCL* Bitstreams
3.7.1. Creating OpenCL* Bitstreams x
3.7.1.1. Sourcing the init_env.sh Script 3.7.1.2. Creating the OpenCL* Bitstream 3.7.1.3. Programming the Image File
3.7.1.2. Creating the OpenCL* Bitstream x
3.7.1.2.1. Example: Creating a Signed .aocx File Using OpenSSL Manager 3.7.1.2.2. Example: Creating an Unsigned .aocx File Using OpenSSL Manager 3.7.1.2.3. Example: Creating a Signed .aocx File Using PKCS11 Manager 3.7.1.2.4. Example: Creating an Unsigned .aocx File Using PKCS11 Manager
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

3.10. Creating a Custom HSM Manager

PACSign is a Python tool that uses a plugin architecture for the HSM interface. PACSign is distributed with managers for both OpenSSL and PKCS #11. This section describes the functionality required by PACSign from the HSM interface and shows how to construct a plugin.

The distribution of PACSign uses the following directory structure: 

├───hsm_managers
│ ├───openssl_manager
│ │ └───library
│ └───pkcs11_manager
└───source

The top level contains PACSign.py with the generic signing code in source. The HSM managers reside each in their own subdirectory under hsm_managers as packages. The directory name is what is given to PACSign’s --HSM_MANAGER command-line option. If the specific manager requires additional information, you can provide it using the optional --HSM_config command-line option. For example, the PKCS #11 plugin requires a *.json file describing the tokens and keys available on the HSM.

You must place each plugin that is to be supported in a subdirectory of the hsm_managers directory. Use a descriptive name for the directory that clearly describes the supported HSM. This subdirectory may have an __init__.py file whose contents import the modules needed by the plugin. The names of the plugin modules are not important to the proper functioning of PACSign.

The newly-created plugin must be able to export one attribute named HSM_MANAGER that is invoked by PACSign with an optional configuration file name provided on the command-line. Invocation of HSM_MANAGER(config_file) returns a class with certain methods exposed, which are described in later sections.

Current implementations of HSM_MANAGER define it as a Python class object. The initialization function of the class reads and parses the configuration file (if present) and performs HSM initialization. For the PKCS #11 implementation, the class looks like this: 
class HSM_MANAGER(object):
	def __init__(self, cfg_file = None):
		common_util.assert_in_error(cfg_file, \
			PKCS11 HSM manager requires a configuration file")
		self.session = None
		with open(cfg_file, "r") as read_file:
			self.j_data = json.load(read_file)
		j_data = self.j_data

		lib = pkcs11.lib(j_data['lib_path'])
		token = lib.get_token(token_label=j_data['token']['label'])
		self.session = token.open(user_pin=j_data['token']['user_password'])
		self.curve = j_data['curve']

		self.ecparams = self.session.create_domain_parameters( \
		pkcs11.KeyType.EC, {pkcs11.Attribute: \
		pkcs11.util.ec.encode_named_curve_parameters(self.curve)}, \
		local=True)
Error handling code has been omitted for clarity. This code does the following:
  • Opens and parses the *.json configuration file.
  • Loads the vendor-supplied PKCS #11 library into the program.
  • Sets up a session with the correct token.
  • Retrieves the proper elliptic curve parameters for the curve you select.

The following sections describe the required exported methods of this class.

Level Two Title