Creating an Encryption Key and Encrypted Bitstream

The bitstream generator (write_bitstream), provided with the Vivado tools, can generate encrypted as well as non-encrypted bitstreams. For AES bitstream encryption, set the write_bitstream property to enable bitstream encryption. You can either specify a custom 256-bit key as an input to the bitstream generator, which is the Xilinx recommendation and the most secure approach, or you can have the Vivado tool generate a pseudo-random key for you (not recommended).

RECOMMENDED: For SSI devices, you should assign a .NKY file which has unique keys for each SLR. Vivado Hardware Manager issues a critical warning when you try to assign a single AES key for all SLRs:
-Reusing the same key/IV pair across all SLRs
-Reusing the same key across all SLRs.
Both of these are security vulnerabilities. For more information, see AR: 71558 and also see AR: 000033700 for important updates on using the unique set of encryption keys.

The bitstream generator in turn generates an encrypted bitstream file (.BIT) and an encryption key file (.NKY). Table: Write_bitstream Properties identifies the write_bitstream properties available to be defined in the XDC file and their corresponding descriptions. For a Vivado GUI example of key creation and bitstream encryption, see the Vivado Design Suite User Guide: Programming and Debugging (UG908) [Ref 4] .

Table 6: Write_bitstream Properties
Write_bitstream Property	Default Values	Possible Values	Description
BITSTREAM.ENCRYPTION.ENCRYPT	No	No or Yes	Encrypts the bitstream.
BITSTREAM.ENCRYPTION.ENCRYPTKEYSELECT	bbram	bbram or eFUSE	Determines the location of the AES encryption key to be used, either from the battery-backed RAM (BBRAM) or the eFUSE register. Note: This property is only available when the Encrypt option is set to True .
BITSTREAM.ENCRYPTION.KEYLIFE	32	4 to 2,147,483,647	The number of 128-bit encryption blocks over which a single key should be used for AES-GCM authenticated bitstreams. A default of 32 increases the bitstream size or bitstream length by about 2x. Used when BITSTREAM.AUTHENTICATION. AUTHENTICATE = No
BITSTREAM.ENCRYPTION.KEY0	Pick	Pick or <256 bit hex string>	Key0 sets the AES encryption key for bitstream encryption. To use this option, you must first set Encrypt to Yes .
BITSTREAM.ENCRYPTION.KEYFILE	None	<string>	Specifies the name of the input encryption file (with a .nky file extension). To use this option, you must first set Encrypt to Yes .
BITSTREAM.ENCRYPTION.RSAKEYLIFEFRAMES	8	8 to 2,147,483,647	Specifies how many configuration frames should be used for any given AES-256 key when RSA Public Key Authentication is specified. A value of 8 configuration frames is equivalent to using the key for 246 encryption blocks. Used when BITSTREAM.AUTHENTICATION. AUTHENTICATE = Yes
BITSTREAM.ENCRYPTION.STARTIV0	Pick	Pick or <128 bit hex string>	The initialization vector used to specify the initial GCM count value in the first AES-GCM message. 128-bit hex value. Only first 96 bits of 128 hex values are used. The last 32 bits are discarded.
BITSTREAM.ENCRYPTION.STARTIVOBFUSCATE	Pick	Pick or <128 bit hex string>	Starting obfuscate initial vector (Obfuscate IV0) value. Only first 96 bits of 128 hex values are used. The last 32 bits are discarded.
BITSTREAM.AUTHENTICATION.AUTHENTICATE	No	Yes or No	Indicates whether or not to use RSA authentication. If No, then the authentication intrinsic to AES-GCM is used.
BITSTREAM.AUTHENTICATION.RSAPRIVATEKEYFILE	None	<string>	Specifies the OpenSSL .pem file that contains the key pairs that should be used to sign the RSA-2048 authenticated bitstream.
BITSTREAM.ENCRYPTION.OBFUSCATEKEY	Disable	Enable or Disable	Creates a bitstream whereby the key used to encrypt the bitstream is obfuscated before it is written to eFUSE or battery-backed RAM (BBRAM). This allows the user to provide the device programmer with an obfuscated key rather than the original customer key. The device programmer can then write the obfuscated key to the eFUSE or BBRAM and mark it as obfuscated using the obfuscated-key flag in the selected storage location.

RECOMMENDED: See AR: 000033701 for bitstream parameters for ensuring an adequate level of Side-Channel Analysis (SCA) resistance.

The following specific XDC file code snippet shows BBRAM key storage and a custom key defined. If you want the tools to generate a pseudo-random key then you need to comment out the BITSTREAM.ENCRYPTION.KEY0 property. This also shows RSA authentication enabled and the RSA key life frames set to the default of 8. Comment out these to disable the RSA authentication features. All of the properties shown are also selectable and editable via the Edit Device Properties GUI.

#Encryption settings

set_property BITSTREAM.ENCRYPTION.ENCRYPT YES [current_design]

#set_property BITSTREAM.ENCRYPTION.ENCRYPTKEYSELECT EFUSE [current_design]

set_property BITSTREAM.ENCRYPTION.ENCRYPTKEYSELECT BBRAM [current_design]

set_property BITSTREAM.ENCRYPTION.OBFUSCATEKEY Enable [current_design]

set_property BITSTREAM.ENCRYPTION.KEYLIFE 32 [current_design]

set_property BITSTREAM.ENCRYPTION.KEY0

256'h1234567812345678123456781234567812345678123456781234567812345678 [current_design]

set_property BITSTREAM.ENCRYPTION.STARTIV0 128'h87654321876543218765432187654321

[current_design]

set_property BITSTREAM.ENCRYPTION.STARTIVOBFUSCATE

128'hABCDABCDABCDABCDABCDABCDABCDABCD[current_design]

set_property BITSTREAM.ENCRYPTION.FAMILY_KEY_FILEPATH

C:/<any directory>/familyKey_us.cfg [current_design]

#Authentication settings

set_property BITSTREAM.AUTHENTICATION.AUTHENTICATE YES [current_design]

set_property BITSTREAM.ENCRYPTION.RSAKEYLIFEFRAMES 8 [current_design]

set_property BITSTREAM.AUTHENTICATION.RSAPRIVATEKEYFILE

{C:config/ultrascale/encryption/encryption_test/encryption_test.runs/impl_1/rsa.pem}

[current_design]

The NKY file generation occurs at the same time as bitstream generation. This file takes the same top-level name as the bit file and is placed in the same implementation directory as the encrypted bitstream. The NKY file format is:

Device <type>;

EncryptKeySelect <type>;

StartIvObfuscate 00000000000000000000000000000000;

RsaPublicKeyDigest 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000;

Key0 0000000000000000000000000000000000000000000000000000000000000000;

StartIV0 00000000000000000000000000000000;

Table 7: Vector Size
Parameter	Vector Size (in hex)
StartIVObfuscate	128'h
RsaPublicKeyDigest	384'h
Key0	256'h
StartIV0	32'h

For example: (top.nky)

Device xcvu095;

EncryptKeySelect BBRAM;

StartIvObfuscate abcdabcdabcdabcdabcdabcdabcdabcd;

RsaPublicKeyDigest 6DF61AA1636F1FF8A35D064CED96918A6D4820D3CAEEFFA47F64F5C58AC2E539CA3A53103C86450EC576AD595AB3A528;

Key0 1234567812345678123456781234567812345678123456781234567812345678;

StartIV0 876543218765432187654321000003f8;

Key1 44a619e399910767e68cb81bcbae831bd5d10a96e5a348420e9384eb0df06111;

StartIV1 b152ef23b9481138af45a21a000003d8;

Key4063 ddd9955fae4847a54d10a1c06a52171cf69e3593220018c2cac4ca56bf359f5c;

StartIV4063 7d94e42bf79ab77cce1a1d8300000382;

RSA authentication PEM file, example syntax:

-----BEGIN RSA PRIVATE KEY-----

MIIEpQIBAAKCAQEAvCMmT6/MM9LxXs7ZxybE4wKACvp0S2EpWy/q+wFkjeev/oT1EZkyRkeCLWKwLaTUeGxFYeWCVFhpHH7PU9d/5HudIsVr/uJ8k/V7GASsj/8EL3O+RFoMdpsv6AFFD8desse3svR2d3yWlnrWLKfSd25DLqOg5fHMauV5DwDpsrbUvBf/ZOW5JWd4iyi0oeK1/Dw/91AYiJoRWmKt6s3IH1ZkX4OfoXMBJ+SnVgV9NIm59lOb0vd0ZZtNOqo1oX/Ekn93jwoD1UbHAWN90TfZSIAqsv2c4aeC342jKrHUq4cykK

xuTbhBadZaq8u8TGsXO3oPvI+p2tee5sNNoleJj3/gnkPtF9od5bqo8=

-----END RSA PRIVATE KEY-----