15.4.7 Key Rotation

Key rotation flow enables the user to securely update user keys (UPK1, UEK1, UPK2, UEK2, DPK and UEK3) in SmartFusion 2 and IGLOO 2 devices.

The key rotation flow is as follows:

  1. The Libero SoC tool is used to create the design and export the JDC file.

  2. Job Manager uses the JDC file to generate the master and key rotation update bitstreams.

  3. Program devices with initial master bitstream that does not lock user key segments so it can update user keys in future.

  4. Program key rotation bitstreams in sequence, which updates the user keys.

15.4.7.1 Master Bitstream Job Flow

Users can generate the Master Bitstream Job for Hardware Security Modules (HSM) or Non-HSM flow. The parameter enable_key_rotation in init_bitstream Tcl command is used to allow updating user keys in future.

Note:

When the key rotation is enabled, the master bit stream generated does not lock User Lock-Bit, User Key1, and User Key2 segments to allow user keys to be updated in the future.

When key rotation is enabled, Job Manager checks for the following:

  • If Design version is set in JDC file.

  • Verify that no permanent security setting is selected.

  • If more than one keysets are being programmed.

Note:

The Key Rotation Flow is not supported for UNIQUE_KEY protocol.

15.4.7.2 Update Bitstream Job Flow

Using Job Manager you can generate a stand-alone bit stream file (STAPL/SPI/DAT), which will update the user keys that are already programmed on device using the Master Bitstream Flow. Since multiple Key Sets need to be updated, there will be multiple key rotation bit stream files (one for each key set). The multiple key rotation bit stream files need to be programmed in a specific order. The order in which they need to be programmed is embedded as part of the file name.

Users can specify the new key values, which are used to replace old keys programmed in the device using the set_new_keys_for_rotation Tcl command. Depending on whether HSM is being used, the user specifies the key values:

  • If it is an HSM flow, then the user must create a new keyset file with new keys values and use the keyset file as input to the Tcl command.
  • If it is a non-HSM flow, then the user must specify new keys values, which must be updated in this Tcl command. Any key that is not specified will retain its original value.

User can use the init_bitstream Tcl command to initialize bit stream that allows users to specify the key rotation parameters.

15.4.7.3 HSM Flow

If the Master Bitstream Flow was run using HSM, then in the Update Bitstream File Flow, user must create a new key set using the create_keyset Tcl command and set the new keyset file as input in the set_new_keys_for_rotation Tcl command. User then specifies the bit stream type as KEY_ROTATION in the init_bitstream Tcl command and then exports the file using the export_bitstream_file Tcl command. This generates multiple bit stream files, one for each user key set.

set_new_keys_for_rotation -data_name "design data name" \
                          [-keyset_file "keyset file name"]

init_bitstream -data_name "design data name" \
               -bitstream_type "bitstream name" \
               -bitstream_type "KEY_ROTATION" \
               [-auto_inc_design_version] \
               [-first_keymode "UEK1 | UEK2 | UEK3"]

export_bitstream_file -data_name "design data name" \
                      -bitstream_name "bitstream name" \
                      -formats "[STAPL | SPI | DAT]" \
                      -export_path "export_file"

15.4.7.4 Non-HSM Flow

If the Master Bitstream Flow was run without HSM, then in the update bitstream file flow user specifies new values for keys via TCL command. Any key that is not specified will retain the original value (from Master Bitstream Flow). Details about each key is logged while running set_new_keys_for_rotation TCL command.

set_new_keys_for_rotation -data_name "design data name" \
                                   [-upk1 "security key value (UPK1)"] \                                  
                                   [-uek1 "security key value (UEK1)"] \
                                   [-upk2 "security key value (UPK2)"] \
                                   [-uek2 "security key value (UEK2)"] \
                                   [-dpk "security key value (DPK)"] \
                                   [-uek3 "security key value (UEK3)"] \

 init_bitstream -data_name "design data name" \
                -bitstream_type "bitstream name" \
                -bitstream_type "KEY_ROTATION" \
                [-auto_inc_design_version] \
                [-first_keymode "UEK1 | UEK2 | UEK3"]

export_bitstream_file -data_name "design data name" \
                      -bitstream_name "bitstream name" \
                      -formats "[SPI | DAT]" \
                      -export_path "export_file"

Details About Key Log On Running set_new_keys_for_rotation TCL Command

Info: UEK1 will not be updated during key rotation as no new key value is specified.
Info: UEK2 will not be updated during key rotation as it is absent in JDC.
Info: UEK3 will not change during key rotation as the old and new values are same.
Info: UPK1 will not change during key rotation as the old and new values are same.
Info: UPK2 will not be updated during key rotation as it is absent in JDC.
Info: DPK will be updated during key rotation.
Note:

Key rotation files for each user key set are always exported (UKS1, UKS2, and UEK3) even if the key value is same. For example, if user does not specify new key value for UPK1 and UEK1, then original key values are used to generate the key rotation bitstream, so that it amounts to reprogramming, same key value.

15.4.7.5 Key Rotation Bitstream Files

When export_bitstream_file Tcl command is run for KEY_ROTATION bit stream type, multiple files will be generated, one file for each user key set used in JDC.

The key rotation bit stream files are named in the following format:

<user_specified_filename>_rotate_{1|2|3}_uks{1|2|3}

Where:

  • <user_specified_filename> is the file name specified in the export_path of export_bitstream_file command.

  • Number after rotate_ is the file order in which it must be programmed.

  • Number after uks is the user key set that is being modified by this key rotation file.

Example to Explain the Key Rotation Bitstream File Format

If exported file name is myUpdateProgFile_rotate_1_uks3.spi, then myUpdateProgFile is the same as user specified in the export_bitstream_file. rotate_1 denotes it is the first file that needs to be programmed, uks3 denotes that the SPI file will update User Key Set 3 (UEK3).

If the JDC design has all the three keysets being programmed and the key rotation bitstream files are being generated with name myUpdateProgFile then one set of possible key rotation bitstream files can be: myUpdateProgFile_rotate_1_uks3.spi, myUpdateProgFile_rotate_2_uks1.spi, and myUpdateProgFile_rotate_3_uks2.spi.

If the JDC file has Auto-Update enabled, then design version is automatically incremented for each key rotation bitstream file and info messages log this during bitstream generation.

Example of Message Log Showing Successful Generation Of Key Rotation Bitstream File

Info: Successfully generated key rotation bitstream file 'myprogfile2_rotate_1_uks3.spi'. This will update the design version to 1435.
Info: Successfully generated key rotation bitstream file 'myprogfile2_rotate_2_uks1.spi'. This will update the design version to 1436.
Info: Successfully generated key rotation bitstream file 'myprogfile2_rotate_3_uks2.spi'. This will update the design version to 1437.

15.4.7.6 Export SPI Directories

User must export multiple SPI directory files, one for each key rotation bitstream file and use it in the Auto-Update flow using the export_spi_directory TCL command.