[processor-sdk/pdk.git] / packages / ti / drv / sciclient / soc / sysfw / binaries / system-firmware-public-documentation / 6_topic_user_guides / dkek_management.html
3 <!DOCTYPE html>
4 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
5 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
6 <head>
7 <meta charset="utf-8">
9 <meta name="viewport" content="width=device-width, initial-scale=1.0">
11 <title>Using Derived KEK on HS devices — TISCI User Guide</title>
16 <link rel="shortcut icon" href="../_static/favicon.ico"/>
29 <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
33 <link rel="stylesheet" href="../_static/theme_overrides.css" type="text/css" />
37 <link rel="index" title="Index"
38 href="../genindex.html"/>
39 <link rel="search" title="Search" href="../search.html"/>
40 <link rel="top" title="TISCI User Guide" href="../index.html"/>
41 <link rel="up" title="Chapter 6: Topic User Guides" href="index.html"/>
42 <link rel="next" title="Firewall FAQ" href="firewall_faq.html"/>
43 <link rel="prev" title="Using Extended OTP on HS devices" href="extended_otp.html"/>
46 <script src="../_static/js/modernizr.min.js"></script>
48 </head>
50 <body class="wy-body-for-nav" role="document">
51 <header id="tiHeader">
52 <div class="top">
53 <ul>
54 <li id="top_logo">
55 <a href="http://www.ti.com">
56 <img src="../_static/img/ti_logo.png"/>
57 </a>
58 </li>
59 </ul>
60 </div>
61 <div class="nav"></div>
62 </header>
63 <div class="wy-grid-for-nav">
66 <nav data-toggle="wy-nav-shift" class="wy-nav-side">
67 <div class="wy-side-scroll">
68 <div class="wy-side-nav-search">
72 <a href="../index.html" class="icon icon-home"> TISCI
76 </a>
81 <div class="version">
82 20.00.00
83 </div>
88 <div role="search">
89 <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
90 <input type="text" name="q" placeholder="Search docs" />
91 <input type="hidden" name="check_keywords" value="yes" />
92 <input type="hidden" name="area" value="default" />
93 </form>
94 </div>
97 </div>
99 <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
103 <ul class="current">
104 <li class="toctree-l1"><a class="reference internal" href="../1_intro/index.html">Chapter 1: Introduction</a></li>
105 <li class="toctree-l1"><a class="reference internal" href="../2_tisci_msgs/index.html">Chapter 2: TISCI Message Documentation</a></li>
106 <li class="toctree-l1"><a class="reference internal" href="../3_boardcfg/index.html">Chapter 3: Board Configuration</a></li>
107 <li class="toctree-l1"><a class="reference internal" href="../4_trace/index.html">Chapter 4: Interpreting Trace Data</a></li>
108 <li class="toctree-l1"><a class="reference internal" href="../5_soc_doc/index.html">Chapter 5: SoC Family Specific Documentation</a></li>
109 <li class="toctree-l1 current"><a class="reference internal" href="index.html">Chapter 6: Topic User Guides</a><ul class="current">
110 <li class="toctree-l2"><a class="reference internal" href="devgrp_usage.html">Device Group Primer</a></li>
111 <li class="toctree-l2"><a class="reference internal" href="domgrp_usage.html">Domain Group Primer</a></li>
112 <li class="toctree-l2"><a class="reference internal" href="secure_boot_signing.html">Signing binaries for Secure Boot on HS Devices</a></li>
113 <li class="toctree-l2"><a class="reference internal" href="hs_boardcfg_signing.html">Signing Board Configuration on HS devices</a></li>
114 <li class="toctree-l2"><a class="reference internal" href="extended_otp.html">Using Extended OTP on HS devices</a></li>
115 <li class="toctree-l2 current"><a class="current reference internal" href="#">Using Derived KEK on HS devices</a><ul>
116 <li class="toctree-l3"><a class="reference internal" href="#key-derivation-method">Key Derivation Method</a></li>
117 <li class="toctree-l3"><a class="reference internal" href="#using-derived-kek">Using Derived KEK</a><ul>
118 <li class="toctree-l4"><a class="reference internal" href="#approach-1-dkek-programmed-into-sa2ul">Approach 1 - DKEK programmed into SA2UL</a></li>
119 <li class="toctree-l4"><a class="reference internal" href="#approach-2-dkek-supplied-via-tisci">Approach 2 - DKEK supplied via TISCI</a></li>
120 <li class="toctree-l4"><a class="reference internal" href="#comparing-the-two-approaches">Comparing the two approaches</a></li>
121 </ul>
122 </li>
123 </ul>
124 </li>
125 <li class="toctree-l2"><a class="reference internal" href="firewall_faq.html">Firewall FAQ</a></li>
126 <li class="toctree-l2"><a class="reference internal" href="sa2ul_access.html">SA2UL Access Outside of SYSFW</a></li>
127 <li class="toctree-l2"><a class="reference internal" href="security_handover.html">Performing Security Handover</a></li>
128 <li class="toctree-l2"><a class="reference internal" href="secure_debug.html">Secure Debug User Guide</a></li>
129 </ul>
130 </li>
131 </ul>
135 </div>
136 </div>
137 </nav>
139 <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
142 <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
143 <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
144 <a href="../index.html">TISCI</a>
145 </nav>
149 <div class="wy-nav-content">
150 <div class="rst-content">
157 <div role="navigation" aria-label="breadcrumbs navigation">
158 <ul class="wy-breadcrumbs">
159 <li><a href="../index.html">Docs</a> »</li>
161 <li><a href="index.html">Chapter 6: Topic User Guides</a> »</li>
163 <li>Using Derived KEK on HS devices</li>
164 <li class="wy-breadcrumbs-aside">
168 </li>
169 </ul>
170 <hr/>
171 </div>
172 <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
173 <div itemprop="articleBody">
175 <div class="section" id="using-derived-kek-on-hs-devices">
176 <h1>Using Derived KEK on HS devices<a class="headerlink" href="#using-derived-kek-on-hs-devices" title="Permalink to this headline">¶</a></h1>
177 <div class="admonition note">
178 <p class="first admonition-title">Note</p>
179 <p class="last">This document is only applicable to HS devices.</p>
180 </div>
181 <p>K3 HS devices have a randomly generated 256 bit key written into the efuses in
182 TI Factory.
183 This key is called a Key Encryption Key (KEK) and is unique to each device.
184 The characteristics of KEK are listed below.</p>
185 <ul class="simple">
186 <li>KEK is a randomly generated symmetric key</li>
187 <li>KEK is made using NIST certified tester routine</li>
188 <li>KEK is different for each device and is not correlated in any ways with keys issued on others devices.</li>
189 <li>KEK is not stored in any database or retained in any manufacturing tester</li>
190 <li>KEK is burnt in TI factory.</li>
191 </ul>
192 <p>KEK is fed in hardware into the AES engine inside DMSC.
193 The efuses carrying the KEK are marked as read and write protected.
194 As a result, KEK is only accessible via the AES engine in DMSC.
195 The DMSC AES engine has only a register interface and no DMA interface.
196 The DMSC AES engine has lower throughput compared to the AES engine in SA2UL.
197 Instead of exposing the DMSC AES engine to all cores, System Firmware provides API to
198 obtain a key derived from KEK(DKEK) for encryption/decryption.
199 DKEK can be used with SA2UL or with CPU acceleration to perform
200 encryption/decryption operations.</p>
201 <p>This document describes the usage of the Derived KEK(DKEK) API.
202 This document must be read along side</p>
203 <ol class="arabic simple">
204 <li><a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html"><span class="doc">Derived KEK TISCI Description</span></a> and</li>
205 <li><a class="reference internal" href="../3_boardcfg/BOARDCFG_SEC.html"><span class="doc">Security Board Configuration</span></a>, specifically <a class="reference internal" href="../3_boardcfg/BOARDCFG_SEC.html#pub-boardcfg-dkek-config"><span class="std std-ref">Derived KEK Management</span></a></li>
206 </ol>
207 <div class="section" id="key-derivation-method">
208 <h2>Key Derivation Method<a class="headerlink" href="#key-derivation-method" title="Permalink to this headline">¶</a></h2>
209 <p>System Firmware uses CMAC as the Pseudo Random Function(PRF) in counter mode as
210 described in Section 5.1 of NIST SP 800 108
211 “Recommendation for Key Derivation Using Pseudorandom Functions”.
212 The user can provide the following inputs as defined in the above
213 document.</p>
214 <ol class="arabic simple">
215 <li>Label - A string that identifies the purpose for the derived keying material,
216 which is encoded as a binary string.</li>
217 <li>Context - A binary string containing the information related to the derived
218 keying material.</li>
219 </ol>
220 <p>The total length of the Label and Context fields is limited by the size of the
221 TISCI messages(see <a class="reference internal" href="../2_tisci_msgs/general/TISCI_header.html#pub-secure-msg-header"><span class="std std-ref">Secure Messaging Header</span></a>) to 41 bytes.</p>
222 <p>System Firmware adds additional context containing the ID of the host requesting the
223 DKEK into the input. As a result, each host requesting the DKEK receives a
224 unique value.</p>
225 <p>DKEK computation is deterministic on each device. For a given host, label and
226 context, the derived KEK is the same even across reboots on the same device.</p>
227 <p>On different devices, derived KEK is different for the same input. This is due
228 to a random KEK being programmed into each device in TI factory.</p>
229 <p>System Firmware always computes a 256 bit key. It is up to the host to use the desired
230 length out of the 256 bits of the key.</p>
231 <div class="admonition note">
232 <p class="first admonition-title">Note</p>
233 <p class="last">Derived KEK does not describe a single key.
234 The key derivation procedure produces different keys per host.
235 The host can derive different keys based on the label and context provided as input.</p>
236 </div>
237 </div>
238 <div class="section" id="using-derived-kek">
239 <h2>Using Derived KEK<a class="headerlink" href="#using-derived-kek" title="Permalink to this headline">¶</a></h2>
240 <p>There are two ways to use the derived KEK for encryption/decryption.</p>
241 <ol class="arabic simple">
242 <li>System Firmware programs SA2UL with DKEK. Host performs encryption/decryption with
243 SA2UL.</li>
244 <li>System Firmware computes DKEK and returns it to the host. Host can perform
245 encryption/decryption with SA2UL or via CPU.</li>
246 </ol>
247 <div class="admonition note">
248 <p class="first admonition-title">Note</p>
249 <p class="last">This section assumes that the user is familiar with using SA2UL for
250 performing encryption/decryption.</p>
251 </div>
252 <div class="section" id="approach-1-dkek-programmed-into-sa2ul">
253 <h3>Approach 1 - DKEK programmed into SA2UL<a class="headerlink" href="#approach-1-dkek-programmed-into-sa2ul" title="Permalink to this headline">¶</a></h3>
254 <p>In this approach, host requests System Firmware to derive a DKEK and program it into the
255 SA2UL DKEK registers using the <a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html#sec-api-sa2ul-set-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_SET_DKEK</span></a> API.</p>
256 <div class="figure">
257 <img alt="../_images/dkek_approach1_set_dkek.svg" src="../_images/dkek_approach1_set_dkek.svg" /></div>
258 <p>DKEK is not directly made available to the host. The host can use DKEK for
259 encryption/decryption by setting the <code class="docutils literal"><span class="pre">USE_DKEK</span></code> flag in the SA2UL security
260 context.</p>
261 <div class="figure">
262 <img alt="../_images/dkek_approach1_use_dkek.svg" src="../_images/dkek_approach1_use_dkek.svg" /></div>
263 <p>When the host is done with the use of DKEK, it can release the DKEK registers
264 by using the <a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html#sec-api-sa2ul-release-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_RELEASE_DKEK</span></a>
265 API.</p>
266 <div class="figure">
267 <img alt="../_images/dkek_approach1_release_dkek.svg" src="../_images/dkek_approach1_release_dkek.svg" /></div>
268 <div class="section" id="caveat-on-approach-1">
269 <h4>Caveat on Approach 1<a class="headerlink" href="#caveat-on-approach-1" title="Permalink to this headline">¶</a></h4>
270 <p>When the <code class="docutils literal"><span class="pre">USE_DKEK</span></code> flag is used in SA2UL security context, SA2UL checks if the
271 privid of the initiator is present in the SA2UL DKEK privid register.
272 SA2UL <strong>only</strong> checks the privid of the initiator against the SA2UL DKEK privid register
273 and ignores any attributes such as user/priviliged and secure/non-secure in the transaction.</p>
274 <p>This creates a tricky situation when secure and non-secure software are running on the same core.
275 Software running on the same core share the same privid but differ in other attributes.
276 It is possible for non-secure software to encrypt or decrypt data with DKEK configured
277 by the secure software.</p>
278 <p>This can be mitigated by setting the DKEK only when required and releasing the DKEK
279 as soon as the encryption/decryption operation is complete.
280 Alternatively approach 2 described below can be used.</p>
281 </div>
282 </div>
283 <div class="section" id="approach-2-dkek-supplied-via-tisci">
284 <h3>Approach 2 - DKEK supplied via TISCI<a class="headerlink" href="#approach-2-dkek-supplied-via-tisci" title="Permalink to this headline">¶</a></h3>
285 <p>In this approach, host requests System Firmware to derive a DKEK and supply it in the
286 response using the <a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html#sec-api-sa2ul-get-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_GET_DKEK</span></a> API.
287 The host is responsible for maintaining the secrecy of the DKEK supplied by System Firmware.</p>
288 <div class="figure">
289 <img alt="../_images/dkek_approach2_get_dkek.svg" src="../_images/dkek_approach2_get_dkek.svg" /></div>
290 <p>Once DKEK is available, the host can perform encryption/decryption with it in
291 the same manner as any other symmetric key.</p>
292 <div class="figure">
293 <img alt="../_images/dkek_approach2_use_dkek.svg" src="../_images/dkek_approach2_use_dkek.svg" /></div>
294 <p>As the SA2UL DKEK registers are not being used, there is no release DKEK API
295 required in this approach.</p>
296 </div>
297 <div class="section" id="comparing-the-two-approaches">
298 <h3>Comparing the two approaches<a class="headerlink" href="#comparing-the-two-approaches" title="Permalink to this headline">¶</a></h3>
299 <table border="1" class="docutils" id="id1">
300 <caption><span class="caption-number">Table 1 </span><span class="caption-text">Comparison</span><a class="headerlink" href="#id1" title="Permalink to this table">¶</a></caption>
301 <colgroup>
302 <col width="50%" />
303 <col width="50%" />
304 </colgroup>
305 <thead valign="bottom">
306 <tr class="row-odd"><th class="head">Option 1</th>
307 <th class="head">Option 2</th>
308 </tr>
309 </thead>
310 <tbody valign="top">
311 <tr class="row-even"><td>DKEK programmed directly into SA2UL DKEK registers.</td>
312 <td>DKEK is provided to host as a response to a TISCI message.</td>
313 </tr>
314 <tr class="row-odd"><td>No separate firewalling is required for DKEK.</td>
315 <td>Host must firewall memory where it is storing DKEK.</td>
316 </tr>
317 <tr class="row-even"><td>DKEK can only be used through SA2UL. Host must set the <code class="docutils literal"><span class="pre">USE_DKEK</span></code>
318 flag to true in the SA2UL security context. Key must not be populated
319 in the SA2UL security context.</td>
320 <td><p class="first">DKEK can be used in two ways</p>
321 <ul class="last simple">
322 <li>Through SA2UL - Host must program the key in its possession into
323 the SA2UL security context.</li>
324 <li>Using CPU - If hardware acceleration is not required,
325 encryption/decryption can be performed using CPU and the DKEK
326 in the possession of the host.</li>
327 </ul>
328 </td>
329 </tr>
330 <tr class="row-odd"><td>Only one host can use this approach at a time. There is only one set of
331 SA2UL DKEK registers.
332 Access to these registers for encryption/decryption is controlled by DKEK
333 privid register.
334 System Firmware programs the DKEK privid register with the privid of the host who
335 has invoked the <a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html#sec-api-sa2ul-set-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_SET_DKEK</span></a>
336 API.
337 Only this host can use DKEK via the SA2UL DKEK registers until DKEK
338 is released via <a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html#sec-api-sa2ul-release-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_RELEASE_DKEK</span></a></td>
339 <td>Multiple hosts can use DKEK at the same time using this approach.
340 Each host manages its own DKEK.</td>
341 </tr>
342 <tr class="row-even"><td><a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html#sec-api-sa2ul-set-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_SET_DKEK</span></a> and
343 <a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html#sec-api-sa2ul-release-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_RELEASE_DKEK</span></a>
344 API are used in this approach.</td>
345 <td><a class="reference internal" href="../2_tisci_msgs/security/dkek_management.html#sec-api-sa2ul-get-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_GET_DKEK</span></a> is used
346 in this approach.</td>
347 </tr>
348 </tbody>
349 </table>
350 <p>We recommend using Approach 1 wherever possible to maintain the secrecy of DKEK.</p>
351 </div>
352 </div>
353 </div>
356 </div>
357 </div>
358 <footer>
360 <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
362 <a href="firewall_faq.html" class="btn btn-neutral float-right" title="Firewall FAQ" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
365 <a href="extended_otp.html" class="btn btn-neutral" title="Using Extended OTP on HS devices" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
367 </div>
370 <hr/>
372 <div role="contentinfo">
373 <p>
374 <a href="http://www.ti.com/corp/docs/legal/copyright.shtml">© Copyright 2016-2020</a>, Texas Instruments Incorporated. All rights reserved. <br>
375 <a href="http://www.ti.com/corp/docs/legal/trademark/trademrk.htm">Trademarks</a> | <a href="http://www.ti.com/corp/docs/legal/privacy.shtml">Privacy policy</a> | <a href="http://www.ti.com/corp/docs/legal/termsofuse.shtml">Terms of use</a> | <a href="http://www.ti.com/lsds/ti/legal/termsofsale.page">Terms of sale</a>
377 </p>
378 </div>
380 </footer>
382 </div>
383 </div>
385 </section>
387 </div>
393 <script type="text/javascript">
394 var DOCUMENTATION_OPTIONS = {
395 URL_ROOT:'../',
396 VERSION:'20.00.00',
397 COLLAPSE_INDEX:false,
398 FILE_SUFFIX:'.html',
399 HAS_SOURCE: true
400 };
401 </script>
402 <script type="text/javascript" src="../_static/jquery.js"></script>
403 <script type="text/javascript" src="../_static/underscore.js"></script>
404 <script type="text/javascript" src="../_static/doctools.js"></script>
405 <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
407 <script src="http://www.ti.com/assets/js/headerfooter/analytics.js" type="text/javascript" charset="utf-8"></script>
413 <script type="text/javascript" src="../_static/js/theme.js"></script>
418 <script type="text/javascript">
419 jQuery(function () {
420 SphinxRtdTheme.StickyNav.enable();
421 });
423 var menuHeight = window.innerHeight;
425 var contentOffset = $(".wy-nav-content-wrap").offset();
426 var contentHeight = $(".wy-nav-content-wrap").height();
427 var contentBottom = contentOffset.top + contentHeight;
429 function setNavbarTop() {
430 var scrollTop = $(window).scrollTop();
431 var maxTop = scrollTop + menuHeight;
433 // If past the header
434 if (scrollTop > contentOffset.top && maxTop < contentBottom) {
435 stickyTop = scrollTop - contentOffset.top;
436 } else if (maxTop > contentBottom) {
437 stickyTop = scrollTop - contentOffset.top - (maxTop - contentBottom);
438 } else {
439 stickyTop = 0;
440 }
442 $(".wy-nav-side").css("top", stickyTop);
443 }
445 $(document).ready(function() {
446 setNavbarTop();
447 $(window).scroll(function () {
448 setNavbarTop();
449 });
451 $('body').on("mousewheel", function () {
452 // Remove default behavior
453 event.preventDefault();
454 // Scroll without smoothing
455 var wheelDelta = event.wheelDelta;
456 var currentScrollPosition = window.pageYOffset;
457 window.scrollTo(0, currentScrollPosition - wheelDelta);
458 });
459 });
460 </script>
463 </body>
464 </html>