diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.rockchip | 1 | ||||
| -rw-r--r-- | doc/README.socfpga | 32 | ||||
| -rw-r--r-- | doc/README.splashprepare | 15 | ||||
| -rw-r--r-- | doc/uImage.FIT/signature.txt | 143 |
4 files changed, 153 insertions, 38 deletions
diff --git a/doc/README.rockchip b/doc/README.rockchip index 06ec80e..43cafc7 100644 --- a/doc/README.rockchip +++ b/doc/README.rockchip @@ -219,7 +219,6 @@ Immediate priorities are: - USB host - USB device - Run CPU at full speed (code exists but we only see ~60 DMIPS maximum) -- Ethernet - NAND flash - Support for other Rockchip parts - Boot U-Boot proper over USB OTG (at present only SPL works) diff --git a/doc/README.socfpga b/doc/README.socfpga index cfcbbfe..e717637 100644 --- a/doc/README.socfpga +++ b/doc/README.socfpga @@ -14,40 +14,8 @@ socfpga_dw_mmc Here are macro and detailed configuration required to enable DesignWare SDMMC controller support within SOCFPGA -#define CONFIG_MMC --> To enable the SD MMC framework support - -#define CONFIG_SDMMC_BASE (SOCFPGA_SDMMC_ADDRESS) --> The base address of CSR register for DesignWare SDMMC controller - #define CONFIG_GENERIC_MMC -> Enable the generic MMC driver #define CONFIG_SYS_MMC_MAX_BLK_COUNT 256 -> Using smaller max blk cnt to avoid flooding the limited stack in OCRAM - -#define CONFIG_DWMMC --> Enable the common DesignWare SDMMC controller framework - -#define CONFIG_SOCFPGA_DWMMC --> Enable the SOCFPGA specific driver for DesignWare SDMMC controller - -#define CONFIG_SOCFPGA_DWMMC_FIFO_DEPTH 1024 --> The FIFO depth for SOCFPGA DesignWare SDMMC controller - -#define CONFIG_SOCFPGA_DWMMC_DRVSEL 3 --> Phase-shifted clock of sdmmc_clk for controller to drive command and data to -the card to meet hold time requirements. SD clock is running at 50MHz and -drvsel is set to shift 135 degrees (3 * 45 degrees). With that, the hold time -is 135 / 360 * 20ns = 7.5ns. - -#define CONFIG_SOCFPGA_DWMMC_SMPSEL 0 --> Phase-shifted clock of sdmmc_clk used to sample the command and data from -the card - -#define CONFIG_SOCFPGA_DWMMC_BUS_WIDTH 4 --> Bus width of data line which either 1, 4 or 8 and based on board routing. - -#define CONFIG_SOCFPGA_DWMMC_BUS_HZ 50000000 --> The clock rate to controller. Do note the controller have a wrapper which -divide the clock from PLL by 4. diff --git a/doc/README.splashprepare b/doc/README.splashprepare index 56c1bef..f1418de 100644 --- a/doc/README.splashprepare +++ b/doc/README.splashprepare @@ -5,7 +5,7 @@ The splash_screen_prepare() function is a weak function defined in common/splash.c. It is called as part of the splash screen display sequence. It gives the board an opportunity to prepare the splash image data before it is processed and sent to the frame buffer by -U-Boot. Define your own version to use this feature. +U-Boot. Define your own version to use this feature. CONFIG_SPLASH_SOURCE @@ -20,7 +20,12 @@ splashsource works as follows: - If splashsource is undefined, use the first splash location as default. - If splashsource is set to an unsupported value, do not load a splash screen. -A splash source location can describe either storage with raw data, or storage -formatted with a file system. In case of a filesystem, the splash screen data is -loaded as a file. The name of the splash screen file can be controlled with the -environment variable "splashfile". +A splash source location can describe either storage with raw data, a storage +formatted with a file system or a FIT image. In case of a filesystem, the splash +screen data is loaded as a file. The name of the splash screen file can be +controlled with the environment variable "splashfile". + +To enable loading the splash image from a FIT image, CONFIG_FIT must be +enabled. Struct splash_location field 'name' should match the splash image +name within the FIT and the FIT should start at the 'offset' field address in +the specified storage. diff --git a/doc/uImage.FIT/signature.txt b/doc/uImage.FIT/signature.txt index e487401..7cdb7bf 100644 --- a/doc/uImage.FIT/signature.txt +++ b/doc/uImage.FIT/signature.txt @@ -385,6 +385,149 @@ Test Verified Boot Run: signed config with bad hash: OK Test passed +Hardware Signing with PKCS#11 +----------------------------- + +Securely managing private signing keys can challenging, especially when the +keys are stored on the file system of a computer that is connected to the +Internet. If an attacker is able to steal the key, they can sign malicious FIT +images which will appear genuine to your devices. + +An alternative solution is to keep your signing key securely stored on hardware +device like a smartcard, USB token or Hardware Security Module (HSM) and have +them perform the signing. PKCS#11 is standard for interfacing with these crypto +device. + +Requirements: +Smartcard/USB token/HSM which can work with the pkcs11 engine +openssl +libp11 (provides pkcs11 engine) +p11-kit (recommended to simplify setup) +opensc (for smartcards and smartcard like USB devices) +gnutls (recommended for key generation, p11tool) + +The following examples use the Nitrokey Pro. Instructions for other devices may vary. + +Notes on pkcs11 engine setup: + +Make sure p11-kit, opensc are installed and that p11-kit is setup to use opensc. +/usr/share/p11-kit/modules/opensc.module should be present on your system. + + +Generating Keys On the Nitrokey: + +$ gpg --card-edit + +Reader ...........: Nitrokey Nitrokey Pro (xxxxxxxx0000000000000000) 00 00 +Application ID ...: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +Version ..........: 2.1 +Manufacturer .....: ZeitControl +Serial number ....: xxxxxxxx +Name of cardholder: [not set] +Language prefs ...: de +Sex ..............: unspecified +URL of public key : [not set] +Login data .......: [not set] +Signature PIN ....: forced +Key attributes ...: rsa2048 rsa2048 rsa2048 +Max. PIN lengths .: 32 32 32 +PIN retry counter : 3 0 3 +Signature counter : 0 +Signature key ....: [none] +Encryption key....: [none] +Authentication key: [none] +General key info..: [none] + +gpg/card> generate +Make off-card backup of encryption key? (Y/n) n + +Please note that the factory settings of the PINs are + PIN = '123456' Admin PIN = '12345678' +You should change them using the command --change-pin + +What keysize do you want for the Signature key? (2048) 4096 +The card will now be re-configured to generate a key of 4096 bits +Note: There is no guarantee that the card supports the requested size. + If the key generation does not succeed, please check the + documentation of your card to see what sizes are allowed. +What keysize do you want for the Encryption key? (2048) 4096 +The card will now be re-configured to generate a key of 4096 bits +What keysize do you want for the Authentication key? (2048) 4096 +The card will now be re-configured to generate a key of 4096 bits +Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + <n>w = key expires in n weeks + <n>m = key expires in n months + <n>y = key expires in n years +Key is valid for? (0) +Key does not expire at all +Is this correct? (y/N) y + +GnuPG needs to construct a user ID to identify your key. + +Real name: John Doe +Email address: john.doe@email.com +Comment: +You selected this USER-ID: + "John Doe <john.doe@email.com>" + +Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o + + +Using p11tool to get the token URL: + +Depending on system configuration, gpg-agent may need to be killed first. + +$ p11tool --provider /usr/lib/opensc-pkcs11.so --list-tokens +Token 0: +URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29 +Label: OpenPGP card (User PIN (sig)) +Type: Hardware token +Manufacturer: ZeitControl +Model: PKCS#15 emulated +Serial: 000xxxxxxxxx +Module: (null) + + +Token 1: +URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%29 +Label: OpenPGP card (User PIN) +Type: Hardware token +Manufacturer: ZeitControl +Model: PKCS#15 emulated +Serial: 000xxxxxxxxx +Module: (null) + +Use the portion of the signature token URL after "pkcs11:" as the keydir argument (-k) to mkimage below. + + +Use the URL of the token to list the private keys: + +$ p11tool --login --provider /usr/lib/opensc-pkcs11.so --list-privkeys \ +"pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" +Token 'OpenPGP card (User PIN (sig))' with URL 'pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29' requires user PIN +Enter PIN: +Object 0: +URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29;id=%01;object=Signature%20key;type=private +Type: Private key +Label: Signature key +Flags: CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE; +ID: 01 + +Use the label, in this case "Signature key" as the key-name-hint in your FIT. + +Create the fitImage: +$ ./tools/mkimage -f fit-image.its fitImage + + +Sign the fitImage with the hardware key: + +$ ./tools/mkimage -F -k \ +"model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" \ +-K u-boot.dtb -N pkcs11 -r fitImage + + Future Work ----------- - Roll-back protection using a TPM is done using the tpm command. This can |