User Tools

Site Tools


manual:security

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:security [2015/05/22 18:03]
127.0.0.1 external edit
manual:security [2022/02/10 19:10] (current)
voorburg [Building on Windows with MinGW]
Line 2: Line 2:
 The OpenBLT bootloader is an open source project, allowing everyone to access the sources. One downside of this is that if someone knows the OpenBLT bootloader is used in your product, it is relatively easy for them to figure out how to update the firmware in your product. Although this could be a feature of your product, in most cases it is not desirable. The OpenBLT bootloader is an open source project, allowing everyone to access the sources. One downside of this is that if someone knows the OpenBLT bootloader is used in your product, it is relatively easy for them to figure out how to update the firmware in your product. Although this could be a feature of your product, in most cases it is not desirable.
  
-For this reason the bootloader contains a seed/key security module. If this security module is enabled in the bootloader'​s configuration,​ updates can only be made by users that have the correct ​seed/​key ​DLL on their PC. If not, then firmware updates are not allowed and the following message appears if it is attempted:+For this reason the bootloader contains a seed/key security module. If this security module is enabled in the bootloader'​s configuration,​ updates can only be made by users that have the seed/​key ​shared library (*.dll, *.so) with the correct security algorithm ​on their PC. If not, then firmware updates are not allowed and the bootloader will simply not allow a connection to be established,​ regardless of how many times the microcontroller ​is reset:
  
-{{:manual:microboot_security_error.gif?511|}}+{{:manual:microboot_seedkey_security_noconnection.png?|}}
  
 ===== Configuration ===== ===== Configuration =====
-The demo programs are prepared to use the seed/key security module. All that has to be done to enable it, is to set the configuration macro BOOT_XCP_SEED_KEY_ENABLE to a value of 1 in "​blt_conf.h"​. Once changed the bootloader should be rebuild an programmed into the flash memory of your microcontroller.+==== Bootloader ==== 
 +The demo bootloader ​programs are prepared to use the seed/key security module. All that has to be done to enable it, is to set the configuration macro BOOT_XCP_SEED_KEY_ENABLE to a value of 1 in "​blt_conf.h"​. Once changed the bootloader should be rebuild an programmed into the flash memory of your microcontroller. 
 <​code>​ <​code>​
 #define BOOT_XCP_SEED_KEY_ENABLE ​       (1) #define BOOT_XCP_SEED_KEY_ENABLE ​       (1)
 </​code>​ </​code>​
  
-The next step is to configure the location of the seed/​key ​DLL in Microboot. The demo programs are preconfigured to work with the one called "FeaserKey.dll". This file is located in the same directory as Microboot. Follow these steps:+==== MicroBoot ==== 
 +The next step is to configure the location of the seed/​key ​shared library ​in Microboot. The demo programs are preconfigured to work with the one called "libseednkey.dll". This file is located in the same directory as Microboot. Follow these steps:
  
-  * Start Microboot by double-clicking "​\Host\**MicroBoot.exe**"​. +  * Start Microboot by double-clicking "​\Host\**MicroBoot.exe**" ​(on Linux it is "​\Host\**MicroBoot**"​)
-  * Click the "​**Settings**"​-button and, on the newly appeared dialog, ​click the "**Options**"-button+  * Click the "​**Settings**"​-button and, on the newly appeared dialog, ​go to the "Session Protocol"-tab
-  * On the "XCP Protection"​-tab ​Click the "​**Browse**"​-button and select the file "FeaserKey.dll"​. +  * Click the "​**Browse**"​-button and select the file "libseednkey.dll"​. 
-  * Click "​**OK**" ​twice to save the settings.+  * Click "​**OK**"​ to save the settings.
  
-{{:manual:microboot_xcp_protection.gif?515|}}+{{:manual:microboot_xcp_seedkey_protection.png?|}}
  
-If you now perform a firmware update, everything will work as usual. The moment you remove the "FeaserKey.dll"​-file or if it contains an invalid security unlock algorithm, firmware updates will be rejected by the bootloader.+If you now perform a firmware update, everything will work as usual. The moment you remove the "libseednkey.dll"​-file or if it contains an invalid security unlock algorithm, firmware updates will be rejected by the bootloader. 
 + 
 +==== BootCommander ==== 
 +When using the BootCommander command-line program for making firmware updates, you can specify the filename of the Seed and Key shared library on the command-line using the **-sk=** option. If the shared library is in the same directory as the BootCommander program, then there is no need to specify the full path.  
 + 
 +Example on Windows: 
 +<​code>​ 
 +BootCommander -t=xcp_usb -sk=libseednkey.dll demoprog_olimex_stm32h103.srec 
 +</​code>​ 
 + 
 +Example on Linux: 
 +<​code>​ 
 +./​BootCommander -t=xcp_usb -sk=libseednkey.so demoprog_olimex_stm32h103.srec 
 +</​code>​
  
 ===== Customization ===== ===== Customization =====
 Once the security feature is configured and working, you will want to change the security algorithm. The way is works is that to unsecure the bootloader, the Microboot tool obtains a so-called **seed** from the bootloader. This seed is typically a sequence of up to 6 bytes. Microboot then passes this seed to the function **XCP_ComputeKeyFromSeed()** in the seed/key DLL to run your security algorithm, resulting in a so-called **key**. This key is typically a sequence of up to 6 bytes. Next, Microboot sends this key back to the bootloader. The bootloader runs the same security algorithm to verify the key. If okay, memory operations on memory will be allowed, otherwise rejected. Once the security feature is configured and working, you will want to change the security algorithm. The way is works is that to unsecure the bootloader, the Microboot tool obtains a so-called **seed** from the bootloader. This seed is typically a sequence of up to 6 bytes. Microboot then passes this seed to the function **XCP_ComputeKeyFromSeed()** in the seed/key DLL to run your security algorithm, resulting in a so-called **key**. This key is typically a sequence of up to 6 bytes. Next, Microboot sends this key back to the bootloader. The bootloader runs the same security algorithm to verify the key. If okay, memory operations on memory will be allowed, otherwise rejected.
 +
  
 ==== Bootloader ==== ==== Bootloader ====
 The bootloader calls two hook-functions during the security unlock procedure: one for obtaining the seed (**XcpGetSeedHook()**) and one for verifying the key (**XcpVerifyKeyHook()**). The default example implementation in the demo programs is very simply. The seed is always just one byte with the hexadecimal value of 55h. The security algorithm is such that the value of the key is the value of the seed, minus 1: The bootloader calls two hook-functions during the security unlock procedure: one for obtaining the seed (**XcpGetSeedHook()**) and one for verifying the key (**XcpVerifyKeyHook()**). The default example implementation in the demo programs is very simply. The seed is always just one byte with the hexadecimal value of 55h. The security algorithm is such that the value of the key is the value of the seed, minus 1:
 +
 <​code>​ <​code>​
 blt_int8u XcpGetSeedHook(blt_int8u resource, blt_int8u *seed) blt_int8u XcpGetSeedHook(blt_int8u resource, blt_int8u *seed)
Line 37: Line 55:
   return 1;   return 1;
 } }
- 
  
 blt_int8u XcpVerifyKeyHook(blt_int8u resource, blt_int8u *key, blt_int8u len) blt_int8u XcpVerifyKeyHook(blt_int8u resource, blt_int8u *key, blt_int8u len)
 { {
-  /* the example key algorithm in "FeaserKey.dll" works as follows:+  /* the example key algorithm in "libopenblt.dll" works as follows:
    ​* ​ - programming resource will be unlocked if key = seed - 1    ​* ​ - programming resource will be unlocked if key = seed - 1
    */    */
Line 56: Line 73:
 } }
 </​code>​ </​code>​
-To customize, change the code in these two functions and use your creativity to change the seed generation and the key verification algorithm. One good approach is to use a seed that changes, such as the value of a free running counter of the timer system. Don't forget to rebuild the bootloader and program it into the flash memory of your microcontroller after making changes. 
  
-==== Seed/​Key ​DLL ==== +To customize, change the code in these two functions and use your creativity to change the seed generation and the key verification algorithm. One good approach is to use a seed that changes, ideally using a random number generator peripheral, if your microcontroller offers one. Otherwise, you can use a software solution such as the on available in [[https://​github.com/​feaser/​microtbx|MicroTBX]]. Don't forget to rebuild the bootloader and program it into the flash memory of your microcontroller after making changes. 
-Microsoft Visual C++ project is included in the OpenBLT download package for building the example ​"​FeaserKey.dll". If is located in the \Host\Source\MicroBoot\seedkey\ directory. ​Open the project in Microsoft Visual C++ by double-clicking the "​SeedNKey.sln"​-file. Next, open the "SeedNKey.cpp" ​file, which contains ​the **XCP_ComputeKeyFromSeed()** function. The example implementation matches the security algorithm from the bootloader, where the **key** is computed by subtracting the value 1 from every byte in the **seed**:+ 
 +==== Seed/​Key ​Shared Library ​==== 
 +CMake project is included in the OpenBLT download package for building the example ​XCP Seed and Key shared libraryThe CMake project ​is located in the \Host\Source\SeedNKey\ directory. ​ 
 + 
 +To customize ​the security algorithm, open the source-file ​"seednkey.c" ​for editing. The security algorithm is implemented in the **XCP_ComputeKeyFromSeed()** function. The example implementation matches the security algorithm from the bootloader, where the **key** is computed by subtracting the value 1 from every byte in the **seed**: 
 <​code>​ <​code>​
-DWORD XCP_DLL_EXPORT ​XCP_ComputeKeyFromSeed( ​BYTE  ​resource, ​BYTE  ​seedLen, ​BYTE *seedPtr,  +LIBOPENBLT_EXPORT uint32_t ​XCP_ComputeKeyFromSeed(uint8_t ​resource, ​uint8_t ​seedLen, ​ 
-                                             BYTE *keyLenPtr, ​BYTE *keyPtr)+                                                  uint8_t const * seedPtr,  
 +                                                  ​uint8_t ​* keyLenPtr, 
 +                                                  uint8_t ​* keyPtr)
 { {
-  ​BYTE i;+  ​uint32_t result = XCP_RESULT_ERROR;​ 
 +  uint8_t idx;
   ​   ​
-  /* Feaser XCP driver ​example key algorithm for PGM simply +  /* This example ​implementation of the key algorithm for PGM simply decrements the value 
-   ​* ​decrements the value of each seed by 1+   ​* ​of each seed byte by 1. This coincides with the default implementation of the hook- 
 +   * function XcpVerifyKeyHook() in the OpenBLT demo bootloaders.
    */    */
-  if ( resource == kXcpResPGM ​)+  if (resource == XCP_RESOURCE_PGM)
   {   {
-    /* compute ​the key */ +    /* Compute ​the key*/ 
-    for ( i=0; i<​seedLen; ​i++)+    for (idx = 0; idx < seedLen; ​idx++)
     {     {
-      keyPtr[i] = seedPtr[i] - 1;+      keyPtr[idx] = seedPtr[idx] - 1;
     }     }
- +    ​/* Set the key length*/
-    ​/* set the key length */+
     *keyLenPtr = seedLen;     *keyLenPtr = seedLen;
-   +    ​/* Update the result value. ​*/ 
-    ​/* done */ +    ​result = XCP_RESULT_OK;
-    ​return 0;+
   }   }
- +  ​/* Give the result back to the caller. ​*/ 
-  ​/* still here, so the resource was unsupported ​*/ +  return ​result;
-  return ​1;+
 } }
 </​code>​ </​code>​
-Customize the key generation algorithm to match the one you implemented in **XcpVerifyKeyHook()**. Once done, generate the new seed/key DLL by selecting Build->​Rebuild Solution from the Visual C++ menu. This will create a new "​FeaserKey.dll"​ file. 
  
-In the Visual C++ project linker settings you can change ​the name of the seed/key DLL file, if you desireJust make sure to update this as well in the Microboot settings.+Customize ​the key generation algorithm to match the one you implemented in **XcpVerifyKeyHook()**. Once done, rebuild the XCP Seed and Key shared library. Instructions for building the shared library are located towards the bottom of this page. Under Windows the output is "​libseednkey.dll",​ and under Linux it is "​libseednkey.so"​. 
 + 
 +===== Building the XCP Seed and Key shared library from sources ===== 
 + 
 +SeedNKey relies on [[http://​www.cmake.org|CMake]] to automatically detect the build tools on your system and to generate the build environment for it. The following instructions assume that CMake is installed on your system and is available on the path. Windows users can download the installer from http://​www.cmake.org/​. Mainstream Linux distributions have CMake in their software repository and it can be installed from there. Example for Ubuntu based distributions:​  
 +<​code>​sudo apt-get install cmake</​code>​ 
 + 
 +==== Building on Linux with GCC ==== 
 + 
 +This method assumes that the basic tools needed for building software are installed. At least the GCC compiler and Make are needed. On Ubuntu based distributions,​ the tools can be installed via command: 
 +<​code>​sudo apt-get install build-essential</​code>​ 
 + 
 +Using the terminal, set the working directory to **./​Host/​Source/​SeedNKey/​build**. Next, type the following two commands to detect and generate the Unix Makefiles based build environment and then build the shared SeedNKey library: 
 + 
 +<​code>​ 
 +cmake .. 
 +make 
 +</​code>​ 
 + 
 +{{:​manual:​seednkey_build_linux_gcc.png?​nolink&​|}} 
 + 
 +After a successful build, the shared library **libseednkey.so** is located in the **./Host** directory. 
 + 
 +==== Building on Windows with Microsoft ​Visual C++ ==== 
 + 
 +This method assumes that Microsoft Visual C++ is installed. During ​the SeedNKey development,​ Microsoft Visual Studio 2019 was used. The method outlined here should work just fine with both older and newer versions ​of Microsoft Visual Studio. 
 + 
 +Using the Command Prompt in Windows, set the working directory to **.\Host\Source\SeedNKey\build** and type the command: 
 +<​code>​ 
 +cmake .. 
 +</code> 
 + 
 +A solution ​file for Microsoft Visual C++ is then automatically generated, called seednkey.sln. Open the solution in Microsoft Visual C++ and build the program from there, by selecting Build→Rebuild Solution from the menu.  
 + 
 +{{:​manual:​seednkey_build_windows_msvc.png?​nolink&​|}} 
 + 
 +After a successful build, the shared library **libseednkey.dll** is located in the **./Host** directory. 
 + 
 +Note that this builds a 64-bit version of **libseednkey.dll**,​ which only works together with 64-bit versions of the PC binaries (MicroBoot, BootCommander and LibOpenBLT). This is the default starting with OpenBLT version 1.14. 
 + 
 +When using the PC binaries from before OpenBLT version 1.14or if you rebuilt them yourself as 32-bit, then you should build **libseednkey.dll** as 32-bit as well. To build a 32-bit version of **libseednkey.dll**,​ generate the build environment with command "​**cmake -A Win32..**"​.  
 + 
 + 
 +==== Building on Windows with MinGW ==== 
 + 
 +This method assumes that the MinGW compiler toolchain is installed on your PC. A convenient way to install it, is by downloading the installer that bundles the Code::​Blocks IDE together with MinGW. When using OpenBLT version 1.14 or newer, it is recommended to download the [[https://​sourceforge.net/​projects/​codeblocks/​files/​Binaries/​20.03/​Windows/​codeblocks-20.03mingw-setup.exe/​download|64-bit installer version]], because the included PC binaries (MicroBoot, BootCommander and LibOpenBLT) are 64-bit ​as well. Otherwise you can download the [[https://​sourceforge.net/​projects/​codeblocks/​files/​Binaries/​20.03/​Windows/​32bit/​codeblocks-20.03-32bit-mingw-32bit-setup.exe/​download|32-bit installer version]]. 
 + 
 +Make sure the **.\bin** directory of the MinGW installation directory is added to your path in Windows. A quick way to verify that this is the case, run the following command from the Command Prompt in Windows and make sure the program could be found:  
 +<​code>​ 
 +mingw32-make 
 +</​code>​ 
 + 
 +Using the Command Prompt in Windows, set the working directory to **.\Host\Source\SeedNKey\build**. Next, type the following two commands to detect and generate the MinGW Makefiles based build environment and then build shared SeedNKey library:  
 + 
 +<​code>​ 
 +cmake -G "​CodeBlocks - MinGW Makefiles"​ .. 
 +mingw32-make 
 +</​code>​ 
 + 
 +{{:​manual:​seednkey_build_windows_mingw.png?​nolink&​|}} 
 + 
 +After a successful build, the shared library **libseednkey.dll** is located in the **.\Host** directory. 
  
manual/security.1432310585.txt.gz · Last modified: 2019/09/24 22:11 (external edit)