288 lines
19 KiB
HTML
Raw Normal View History

2025-09-28 09:58:38 +08:00
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<!-- BEGIN opengraph metadata -->
<meta property="og:title" content="Doxygen Awesome" />
<meta property="og:image" content="https://repository-images.githubusercontent.com/348492097/4f16df80-88fb-11eb-9d31-4015ff22c452" />
<meta property="og:description" content="Custom CSS theme for doxygen html-documentation with lots of customization parameters." />
<meta property="og:url" content="https://jothepro.github.io/doxygen-awesome-css/" />
<!-- END opengraph metadata -->
<!-- BEGIN twitter metadata -->
<meta name="twitter:image:src" content="https://repository-images.githubusercontent.com/348492097/4f16df80-88fb-11eb-9d31-4015ff22c452" />
<meta name="twitter:title" content="Doxygen Awesome" />
<meta name="twitter:description" content="Custom CSS theme for doxygen html-documentation with lots of customization parameters." />
<!-- END twitter metadata -->
<title>User Guide: SecureBoot</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link rel="icon" type="image/svg+xml" href="logo.drawio.svg"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript" src="doxygen-awesome-fragment-copy-button.js"></script>
<script type="text/javascript" src="doxygen-awesome-paragraph-link.js"></script>
<script type="text/javascript" src="doxygen-awesome-interactive-toc.js"></script>
<script type="text/javascript" src="doxygen-awesome-tabs.js"></script>
<script type="text/javascript" src="toggle-alternative-theme.js"></script>
<script type="text/javascript">
DoxygenAwesomeFragmentCopyButton.init()
DoxygenAwesomeDarkModeToggle.init()
DoxygenAwesomeParagraphLink.init()
DoxygenAwesomeInteractiveToc.init()
DoxygenAwesomeTabs.init()
</script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
<link href="custom.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only-darkmode-toggle.css" rel="stylesheet" type="text/css"/>
<link href="custom-alternative.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- https://tholman.com/github-corners/
<a href="https://github.com/jothepro/doxygen-awesome-css" class="github-corner" title="View source on GitHub" target="_blank">
<svg viewBox="0 0 250 250" width="40" height="40" style="position: absolute; top: 0; border: 0; right: 0; z-index: 99;" aria-hidden="true">
<path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>
-->
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="Logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">User Guide
</div>
<div id="projectbrief">Bluetooth Low Energy 5.3</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.6 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('SECUREBOOT.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">SecureBoot </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md_docs_doxygen_om6626_user_guides_secureboot"></a></p>
<h1><a class="anchor" id="autotoc_md36"></a>
Feature</h1>
<ul>
<li>Integrity verification of the firmware image(s)</li>
<li>Authenticity verification of the firmware image(s) using ECDSA</li>
<li>Support firmware anti-rollback</li>
<li>Limited times secure on/off</li>
<li>Limited times swd on/off</li>
<li>Secure debug</li>
</ul>
<h1><a class="anchor" id="autotoc_md37"></a>
Memory Layout</h1>
<h2><a class="anchor" id="autotoc_md38"></a>
EFUSE</h2>
<div class="image">
<img src="sc_efuse_partition.png" alt=""/>
</div>
<ol type="1">
<li><b>Image Version</b>: the version information of the firmware is recorded here, which contains a total of 64 bits, and the number of 1 in this area is taken as the version number. Therefore, the maximum version that the anti-rollback can record is 64. Once the value exceeds, the anti-rollback function is no longer effective, and it is recommended that users increase each version by 1 when upgrading the program.</li>
<li><b>SWD Switch</b>: when the chip is reset and restarted, the swd interface will be turned on or off according to the number of 1 in this area. If the number is odd, the swd interface will be turned off, otherwise, the swd interface will be turned on. In order to ensure that the final state of this region is swd off, no more data can be written after 7 bits of 1 have been written, In ISP Mode, you can choose to temporarily turn on or off the swd interface for debugging purposes, which does not require modifications to efuse.</li>
<li><b>Secure Switch</b>: when the chip is reset and restarted, the security function will be turned on or off according to the number of 1 in this area, if the number is odd, the security function will be turned on, otherwise, the security function will be turned off. In order to ensure that the final state of the region after it has been filled with 1 is the security feature on state, no more data can be written after 7 bits of 1 have been written.</li>
</ol>
<h2><a class="anchor" id="autotoc_md39"></a>
FLASH</h2>
<div class="image">
<img src="sc_flash_partition.png" alt=""/>
</div>
<ol type="1">
<li><b>OTP</b>: this area holds the 32-byte public key hash and the 32-byte HUK. When the security function is enabled, the public key hash here will be used to verify the public key in the MBR or from the user. Other keys can be derived through HUK for various purposes.</li>
<li><b>Protected Area</b>: the first 64K area of Flash is protected, which is used to store SecureBoot programs and other important data, and is not allowed to be erased or written.</li>
<li><b>MBR</b>: the MBR contains the manifest of the firmware and the flash configuration parameters, which are described in detail in the following section. MBR0 is used for program startup and MBR1 is used for program upgrade.</li>
<li><b>Application Code</b>: the execution area of the application</li>
</ol>
<h2><a class="anchor" id="autotoc_md40"></a>
MBR</h2>
<div class="image">
<img src="sc_mbr_partition.png" alt=""/>
</div>
<ol type="1">
<li><b>MANIFEST</b>: It stores the description information of the firmware, including the version, hash, length and other content of the firmware, which is used to verify the authenticity and integrity of the firmware in the secure boot process. The tool to generate the manifest can be found <a class="el" href="SECUREBOOT.html#SC_gen_mbr_exe">here</a></li>
<li><b>IFLASH CFG</b>: when the chip is powered on and restarted, the flash will be configured according to the flash parameter here.</li>
</ol>
<h1><a class="anchor" id="autotoc_md41"></a>
ISP and BOOT Mode</h1>
<p>There are two modes in SecureBoot: ISP Mode and BOOT Mode</p>
<ul>
<li><b>ISP Mode</b>: a set of commands is provided to the user in ISP Mode. Based on these commands, flash program burning, SWD switch, authentication and other operations can be realized.</li>
<li><b>BOOT Mode</b>: when the security verification for the specified firmware passes, jump to the specified location to execute the program.</li>
</ul>
<p>When the chip is reset and restarted, the boot pin level will be checked. If the boot pin is low, the chip will enter ISP Mode, otherwise, it will enter boot mode. In SecureBoot, GPIO7 is selected as the boot pin.</p>
<h1><a class="anchor" id="autotoc_md42"></a>
Secure Boot Flow</h1>
<div class="image">
<img src="sc_boot_flow.png" alt=""/>
</div>
<p>The process of secure boot is as follows:</p>
<ol type="1">
<li>Check the status of the boot pin and enter ISP Mode if the level is low, otherwise enter BOOT Mode.</li>
<li>In BOOT Mode, the number of 1 is obtained from the <code>Secure Switch</code> area in efuse to determine whether the security function is enabled. When the security function is not enabled, the program in the specified area will be directly executed, otherwise a series of security checks will be carried out.</li>
<li>The public key is obtained from the MANIFEST in MBR0, and the corresponding hash is calculated, then compared with the public key hash stored in the FLASH OTP area. When the comparison is inconsistent, the system restarts and repeats the above process.</li>
<li>When the public key verification passes, the public key will be used to verify the digital signature in the MBR0 MANIFEST. If the digital signature verification passes, the whole image manifest is trusted, otherwise the system restarts and repeats the above process.</li>
<li>The number of 1 is obtained from the <code>Image Version</code> area in efuse as the version number and compared with the version number in the MBR0 MANIFEST. When the version number in efuse is less than that in the image manifest, the system is restarted and the above process is repeated.</li>
<li>The hash of the image in the specified area is calculated and compared with the <code>Image Hash</code> in MBR0 MANIFEST. If the comparison is consistent, the integrity check of the firmware passes, otherwise the system restarts and e above process is repeated.</li>
<li>When the above checks are passed, the program of the specified region is executed.</li>
</ol>
<h1><a class="anchor" id="autotoc_md43"></a>
Secure Debug</h1>
<h2><a class="anchor" id="autotoc_md44"></a>
Get ROOT Privilege</h2>
<p>When the security feature is enabled, the user is in Normal privilege after power on, and the way to obtain root privileges is as follows:</p>
<div class="image">
<img src="sc_debug.png" alt=""/>
</div>
<ol type="1">
<li>User sends swicth root request.</li>
<li>Boards send challenge(random numbers) to User.</li>
<li>User signs random numbers with a private key.</li>
<li>User sends response(signature of random numbers) to boards.</li>
<li>Boards verify the signature and provide root privilege.</li>
</ol>
<h2><a class="anchor" id="autotoc_md45"></a>
Control SWD Interface</h2>
<ol type="1">
<li>The SWD interface is closed by default after the chip is powered on.</li>
<li>In SecureBoot, the swd interface is turned on or off by the contents of the swd_switch area in efuse.</li>
<li>Once in ISP Mode, the SWD interface can be turned on or off temporarily or permanently if root access is obtained.</li>
<li>The SWD debug interface can be turned on or off according to the situation in the application.</li>
</ol>
<p>The tool to get root privilege and control swd interface can be found <a class="el" href="SECUREBOOT.html#SC_OmBleIspStudioSC_exe">here</a></p>
<h2><a class="anchor" id="autotoc_md46"></a>
Develop in keil</h2>
<p>When using keil tool to debug, it is necessary to turn off the security function of the chip, otherwise the program to be debugged cannot be executed after restart. The tool to turn off the security function can be found <a class="el" href="SECUREBOOT.html#SC_OmBleIspStudioSC_exe">here</a></p>
<p>The steps to change a normal project to one that supports SecureBoot are as follows:</p>
<h3><a class="anchor" id="autotoc_md47"></a>
Scatter File</h3>
<div class="image">
<img src="sc_sct1.png" alt=""/>
</div>
<div class="image">
<img src="sc_sct2.png" alt=""/>
</div>
<h3><a class="anchor" id="autotoc_md48"></a>
Debug.ini</h3>
<div class="image">
<img src="sc_ini1.png" alt=""/>
</div>
<div class="image">
<img src="sc_ini2.png" alt=""/>
</div>
<h3><a class="anchor" id="autotoc_md49"></a>
Flash algorithm</h3>
<div class="image">
<img src="sc_algo1.png" alt=""/>
</div>
<div class="image">
<img src="sc_algo2.png" alt=""/>
</div>
<div class="image">
<img src="sc_algo3.png" alt=""/>
</div>
<dl class="section note"><dt>Note</dt><dd>The user must use the flash algorithm file that supports SecureBoot specified above, otherwise there is a risk that SecureBoot will be permanently disabled.</dd></dl>
<p>After the above changes are made, debugging can be performed on the chip with SecureBoot. In addition, a demo project supporting SecureBoot is provided at the path <code>sdk/examples/ble_app_simple_secure_boot/</code> for user reference.</p>
<h1><a class="anchor" id="autotoc_md50"></a>
Tools</h1>
<h2><a class="anchor" id="SC_gen_mbr_exe"></a>
1. gen_mbr.exe</h2>
<p>A tool to help users generate image manifest is provided at the path <code>tools/dev/</code>, which provides a windows version and a linux version. Both are used the same way. The linux version of the tool is described below.</p>
<h3><a class="anchor" id="autotoc_md51"></a>
Help</h3>
<p>To take a closer look at the various parameters provided by the tool, use the following command:</p>
<div class="fragment"><div class="line">./gen_mbr -h</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md52"></a>
Generate key pairs</h3>
<div class="fragment"><div class="line">./gen_mbr -g 0x0</div>
</div><!-- fragment --><p>Running the preceding command will produce the following files in the current directory:</p>
<div class="image">
<img src="sc_pk_file.png" alt=""/>
</div>
<p>These three files store the generated private key, the corresponding public key and the public key hash, respectively. The private key is used for signing and needs to be kept by the user. The public key and public key hash are used in mass production, debugging and other scenarios. Note that when the value after the <code>-g</code> command is <code>0x0</code>, the private key generated will be random each time, otherwise the specified value will be used as the private key and the corresponding public key and public key hash will be generated.</p>
<h3><a class="anchor" id="autotoc_md53"></a>
Generate image manifest</h3>
<div class="fragment"><div class="line">./gen_mbr -f ./app.bin -v 0 -x 0x412000 -k private_key.txt -o ./app_manifest.bin</div>
</div><!-- fragment --><p>After running the above command, the file <code>app_manifest.bin</code> corresponding to <code>app.bin</code> will be generated in the current path. <code>-f</code> specifies the application bin file path, <code>-v</code> specifies the version number set by the user for the application, <code>-x</code> specifies the application execution address, <code>-k</code> specifies the private key file. <code>-o</code> specifies the path to the generated manifest file.</p>
<h2><a class="anchor" id="SC_OmBleIspStudioSC_exe"></a>
2. OmBleIspStudioSC-XX.exe</h2>
<p>This tool helps users debug chips with SecureBoot, providing functions such as obtaining root privileges, downloading applications, switching SWD interfaces, turning on/off security function, etc. Users can obtain the tool and how to use it from the FAE. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.9.1-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
</div>
</body>
</html>