]> Gitweb @ Texas Instruments - Open Source Git Repositories - git.TI.com/gitweb - processor-sdk/pdk.git/blob - packages/ti/drv/sciclient/soc/sysfw/binaries/system-firmware-public-documentation/2_tisci_msgs/security/dkek_management.html
Migrating to SYSFW version v2020.08
[processor-sdk/pdk.git] / packages / ti / drv / sciclient / soc / sysfw / binaries / system-firmware-public-documentation / 2_tisci_msgs / security / 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">
8   
9   <meta name="viewport" content="width=device-width, initial-scale=1.0">
10   
11   <title>Derived KEK TISCI Description &mdash; TISCI User Guide</title>
12   
14   
15   
16     <link rel="shortcut icon" href="../../_static/favicon.ico"/>
17   
19   
21   
22   
23     
25   
27   
28   
29     <link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
30   
32   
33     <link rel="stylesheet" href="../../_static/theme_overrides.css" type="text/css" />
34   
36   
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 2: TISCI Message Documentation" href="../index.html"/>
42         <link rel="next" title="Security Handover Message Description" href="security_handover.html"/>
43         <link rel="prev" title="Extended OTP TISCI Description" href="extended_otp.html"/> 
45   
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">
65     
66     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
67       <div class="wy-side-scroll">
68         <div class="wy-side-nav-search">
69           
71           
72             <a href="../../index.html" class="icon icon-home"> TISCI
73           
75           
76           </a>
78           
79             
80             
81               <div class="version">
82                 20.00.03
83               </div>
84             
85           
87           
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>
96           
97         </div>
99         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
100           
101             
102             
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 current"><a class="reference internal" href="../index.html">Chapter 2: TISCI Message Documentation</a><ul class="current">
106 <li class="toctree-l2"><a class="reference internal" href="../general/TISCI_header.html">Texas Instruments System Controller Interface (TISCI)</a></li>
107 <li class="toctree-l2"><a class="reference internal" href="../index.html#general">General</a></li>
108 <li class="toctree-l2"><a class="reference internal" href="../index.html#power-management-pm">Power Management (PM)</a></li>
109 <li class="toctree-l2"><a class="reference internal" href="../index.html#resource-management-rm">Resource Management (RM)</a></li>
110 <li class="toctree-l2 current"><a class="reference internal" href="../index.html#secure-management">Secure Management</a><ul class="current">
111 <li class="toctree-l3"><a class="reference internal" href="sec_cert_format.html">Security X509 Certificate Documentation</a></li>
112 <li class="toctree-l3"><a class="reference internal" href="PROC_BOOT.html">Processor Boot Management TISCI Description</a></li>
113 <li class="toctree-l3"><a class="reference internal" href="firewall_api.html">Firewall TISCI Description</a></li>
114 <li class="toctree-l3"><a class="reference internal" href="sec_ap_data_transfer.html">Secure AP Command Interface</a></li>
115 <li class="toctree-l3"><a class="reference internal" href="runtime_debug.html">Runtime Debug TISCI Description</a></li>
116 <li class="toctree-l3"><a class="reference internal" href="extended_otp.html">Extended OTP TISCI Description</a></li>
117 <li class="toctree-l3 current"><a class="current reference internal" href="#">Derived KEK TISCI Description</a><ul>
118 <li class="toctree-l4"><a class="reference internal" href="#api-description">API Description</a></li>
119 </ul>
120 </li>
121 <li class="toctree-l3"><a class="reference internal" href="security_handover.html">Security Handover Message Description</a></li>
122 </ul>
123 </li>
124 </ul>
125 </li>
126 <li class="toctree-l1"><a class="reference internal" href="../../3_boardcfg/index.html">Chapter 3: Board Configuration</a></li>
127 <li class="toctree-l1"><a class="reference internal" href="../../4_trace/index.html">Chapter 4: Interpreting Trace Data</a></li>
128 <li class="toctree-l1"><a class="reference internal" href="../../5_soc_doc/index.html">Chapter 5: SoC Family Specific Documentation</a></li>
129 <li class="toctree-l1"><a class="reference internal" href="../../6_topic_user_guides/index.html">Chapter 6: Topic User Guides</a></li>
130 </ul>
132             
133           
134         </div>
135       </div>
136     </nav>
138     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
140       
141       <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
142         <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
143         <a href="../../index.html">TISCI</a>
144       </nav>
147       
148       <div class="wy-nav-content">
149         <div class="rst-content">
150           
152  
156 <div role="navigation" aria-label="breadcrumbs navigation">
157   <ul class="wy-breadcrumbs">
158     <li><a href="../../index.html">Docs</a> &raquo;</li>
159       
160           <li><a href="../index.html">Chapter 2: TISCI Message Documentation</a> &raquo;</li>
161       
162     <li>Derived KEK TISCI Description</li>
163       <li class="wy-breadcrumbs-aside">
164         
165           
166         
167       </li>
168   </ul>
169   <hr/>
170 </div>
171           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
172            <div itemprop="articleBody">
173             
174   <div class="section" id="derived-kek-tisci-description">
175 <h1>Derived KEK TISCI Description<a class="headerlink" href="#derived-kek-tisci-description" title="Permalink to this headline">¶</a></h1>
176 <p id="sec-dkek-tisci-desc">This chapter provides information on  System Firmware API for Derived Key Encryption
177 Key(DKEK) management. The available API are listed below.</p>
178 <table border="1" class="docutils">
179 <colgroup>
180 <col width="20%" />
181 <col width="80%" />
182 </colgroup>
183 <thead valign="bottom">
184 <tr class="row-odd"><th class="head">TISCI Message ID</th>
185 <th class="head">Message Name</th>
186 </tr>
187 </thead>
188 <tbody valign="top">
189 <tr class="row-even"><td>0x9003</td>
190 <td><a class="reference internal" href="#sec-api-sa2ul-set-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_SET_DKEK</span></a></td>
191 </tr>
192 <tr class="row-odd"><td>0x9004</td>
193 <td><a class="reference internal" href="#sec-api-sa2ul-release-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_RELEASE_DKEK</span></a></td>
194 </tr>
195 <tr class="row-even"><td>0x9029</td>
196 <td><a class="reference internal" href="#sec-api-sa2ul-get-dkek"><span class="std std-ref">TISCI_MSG_SA2UL_GET_DKEK</span></a></td>
197 </tr>
198 </tbody>
199 </table>
200 <p>This document must be read along side</p>
201 <ol class="arabic simple">
202 <li><a class="reference internal" href="../../6_topic_user_guides/dkek_management.html"><span class="doc">Using Derived KEK on HS devices</span></a> and</li>
203 <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>
204 </ol>
205 <div class="section" id="api-description">
206 <h2>API Description<a class="headerlink" href="#api-description" title="Permalink to this headline">¶</a></h2>
207 <div class="section" id="tisci-msg-sa2ul-set-dkek-set-dkek">
208 <span id="sec-api-sa2ul-set-dkek"></span><h3>TISCI_MSG_SA2UL_SET_DKEK - Set DKEK<a class="headerlink" href="#tisci-msg-sa2ul-set-dkek-set-dkek" title="Permalink to this headline">¶</a></h3>
209 <p><strong>Usage</strong>:</p>
210 <table border="1" class="docutils">
211 <colgroup>
212 <col width="75%" />
213 <col width="25%" />
214 </colgroup>
215 <tbody valign="top">
216 <tr class="row-odd"><td><strong>Message Type</strong></td>
217 <td>Normal</td>
218 </tr>
219 <tr class="row-even"><td><strong>Secure Queue Only?</strong></td>
220 <td>No</td>
221 </tr>
222 </tbody>
223 </table>
224 </div>
225 <div class="section" id="tisci-message-id">
226 <h3>TISCI Message ID<a class="headerlink" href="#tisci-message-id" title="Permalink to this headline">¶</a></h3>
227 <p><p><code class="docutils literal"><span class="pre">TISCI_MSG_SA2UL_SET_DKEK</span>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">(0x9003U)</span></code></p>
228 <p>Message to derive a KEK and set SA2UL DKEK register</p>
229 </p>
230 <p><p><strong>struct tisci_msg_sa2ul_set_dkek_req</strong></p>
231 <p>TISCI Request for setting DKEK in SA2UL registers</p>
232 <table border="1" class="docutils">
233 <colgroup>
234 <col width="13%" />
235 <col width="12%" />
236 <col width="75%" />
237 </colgroup>
238 <thead valign="bottom">
239 <tr class="row-odd"><th class="head">Parameter</th>
240 <th class="head">Type</th>
241 <th class="head">Description</th>
242 </tr>
243 </thead>
244 <tbody valign="top">
245 <tr class="row-even"><td>hdr</td>
246 <td>struct tisci_header</td>
247 <td>Generic TISCI message header.</td>
248 </tr>
249 <tr class="row-odd"><td>sa2ul_instance</td>
250 <td>u8</td>
251 <td>SA2UL instance number - set to 0</td>
252 </tr>
253 <tr class="row-even"><td>kdf_label_len</td>
254 <td>u8</td>
255 <td>Length of “Label” input to KDF</td>
256 </tr>
257 <tr class="row-odd"><td>kdf_context_len</td>
258 <td>u8</td>
259 <td>Length of “Context” input to KDF</td>
260 </tr>
261 <tr class="row-even"><td>kdf_label_and_context</td>
262 <td>u8</td>
263 <td>”Label” and “Context” bytes are stored in this array one after another. Maximum length of this field is KDF_LABEL_AND_CONTEXT_LEN_MAX</td>
264 </tr>
265 </tbody>
266 </table>
267 </p>
268 <p><p><strong>struct tisci_msg_sa2ul_set_dkek_resp</strong></p>
269 <p>TISCI Response for setting DKEK in SA2UL registers</p>
270 <table border="1" class="docutils">
271 <colgroup>
272 <col width="20%" />
273 <col width="32%" />
274 <col width="48%" />
275 </colgroup>
276 <thead valign="bottom">
277 <tr class="row-odd"><th class="head">Parameter</th>
278 <th class="head">Type</th>
279 <th class="head">Description</th>
280 </tr>
281 </thead>
282 <tbody valign="top">
283 <tr class="row-even"><td>hdr</td>
284 <td>struct tisci_header</td>
285 <td>Generic TISCI message header.</td>
286 </tr>
287 </tbody>
288 </table>
289 </p>
290 <p><code class="docutils literal"><span class="pre">KDF_LABEL_AND_CONTEXT_LEN_MAX</span>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">41</span></code></p>
291 <p>See <a class="reference internal" href="#pub-tisci-dkek-notes"><span class="std std-ref">API Notes</span></a> below.</p>
292 </div>
293 <div class="section" id="tisci-msg-sa2ul-release-dkek-release-dkek">
294 <span id="sec-api-sa2ul-release-dkek"></span><h3>TISCI_MSG_SA2UL_RELEASE_DKEK - Release DKEK<a class="headerlink" href="#tisci-msg-sa2ul-release-dkek-release-dkek" title="Permalink to this headline">¶</a></h3>
295 <p><strong>Usage</strong>:</p>
296 <table border="1" class="docutils">
297 <colgroup>
298 <col width="75%" />
299 <col width="25%" />
300 </colgroup>
301 <tbody valign="top">
302 <tr class="row-odd"><td><strong>Message Type</strong></td>
303 <td>Normal</td>
304 </tr>
305 <tr class="row-even"><td><strong>Secure Queue Only?</strong></td>
306 <td>No</td>
307 </tr>
308 </tbody>
309 </table>
310 </div>
311 <div class="section" id="id1">
312 <h3>TISCI Message ID<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
313 <p><p><code class="docutils literal"><span class="pre">TISCI_MSG_SA2UL_RELEASE_DKEK</span>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">(0x9004U)</span></code></p>
314 <p>Message to erase the DKEK register</p>
315 </p>
316 <p><p><strong>struct tisci_msg_sa2ul_release_dkek_req</strong></p>
317 <p>TISCI Request for releasing DKEK</p>
318 <table border="1" class="docutils">
319 <colgroup>
320 <col width="23%" />
321 <col width="30%" />
322 <col width="48%" />
323 </colgroup>
324 <thead valign="bottom">
325 <tr class="row-odd"><th class="head">Parameter</th>
326 <th class="head">Type</th>
327 <th class="head">Description</th>
328 </tr>
329 </thead>
330 <tbody valign="top">
331 <tr class="row-even"><td>hdr</td>
332 <td>struct tisci_header</td>
333 <td>Generic TISCI message header.</td>
334 </tr>
335 <tr class="row-odd"><td>sa2ul_instance</td>
336 <td>u8</td>
337 <td>SA2UL instance number - set to 0</td>
338 </tr>
339 </tbody>
340 </table>
341 </p>
342 <p><p><strong>struct tisci_msg_sa2ul_release_dkek_resp</strong></p>
343 <p>TISCI Response for Releasing DKEK</p>
344 <table border="1" class="docutils">
345 <colgroup>
346 <col width="20%" />
347 <col width="32%" />
348 <col width="48%" />
349 </colgroup>
350 <thead valign="bottom">
351 <tr class="row-odd"><th class="head">Parameter</th>
352 <th class="head">Type</th>
353 <th class="head">Description</th>
354 </tr>
355 </thead>
356 <tbody valign="top">
357 <tr class="row-even"><td>hdr</td>
358 <td>struct tisci_header</td>
359 <td>Generic TISCI message header.</td>
360 </tr>
361 </tbody>
362 </table>
363 </p>
364 <p>See <a class="reference internal" href="#pub-tisci-dkek-notes"><span class="std std-ref">API Notes</span></a> below.</p>
365 </div>
366 <div class="section" id="tisci-msg-sa2ul-get-dkek-get-dkek">
367 <span id="sec-api-sa2ul-get-dkek"></span><h3>TISCI_MSG_SA2UL_GET_DKEK - Get DKEK<a class="headerlink" href="#tisci-msg-sa2ul-get-dkek-get-dkek" title="Permalink to this headline">¶</a></h3>
368 <p><strong>Usage</strong>:</p>
369 <table border="1" class="docutils">
370 <colgroup>
371 <col width="75%" />
372 <col width="25%" />
373 </colgroup>
374 <tbody valign="top">
375 <tr class="row-odd"><td><strong>Message Type</strong></td>
376 <td>Normal</td>
377 </tr>
378 <tr class="row-even"><td><strong>Secure Queue Only?</strong></td>
379 <td>Yes</td>
380 </tr>
381 </tbody>
382 </table>
383 </div>
384 <div class="section" id="id2">
385 <h3>TISCI Message ID<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
386 <p><p><code class="docutils literal"><span class="pre">TISCI_MSG_SA2UL_GET_DKEK</span>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">(0x9029U)</span></code></p>
387 <p>Message to derive a KEK and return it via TISCI</p>
388 </p>
389 <p><code class="docutils literal"><span class="pre">SA2UL_DKEK_KEY_LEN</span>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">(32U)</span></code></p>
390 <p><p><strong>struct tisci_msg_sa2ul_get_dkek_req</strong></p>
391 <p>TISCI Request for getting DKEK via TISCI</p>
392 <table border="1" class="docutils">
393 <colgroup>
394 <col width="13%" />
395 <col width="12%" />
396 <col width="75%" />
397 </colgroup>
398 <thead valign="bottom">
399 <tr class="row-odd"><th class="head">Parameter</th>
400 <th class="head">Type</th>
401 <th class="head">Description</th>
402 </tr>
403 </thead>
404 <tbody valign="top">
405 <tr class="row-even"><td>hdr</td>
406 <td>struct tisci_header</td>
407 <td>Generic TISCI message header.</td>
408 </tr>
409 <tr class="row-odd"><td>sa2ul_instance</td>
410 <td>u8</td>
411 <td>SA2UL instance number - set to 0</td>
412 </tr>
413 <tr class="row-even"><td>kdf_label_len</td>
414 <td>u8</td>
415 <td>Length of “Label” input to KDF</td>
416 </tr>
417 <tr class="row-odd"><td>kdf_context_len</td>
418 <td>u8</td>
419 <td>Length of “Context” input to KDF</td>
420 </tr>
421 <tr class="row-even"><td>kdf_label_and_context</td>
422 <td>u8</td>
423 <td>”Label” and “Context” bytes are stored in this array one after another. Maximum length of this field is KDF_LABEL_AND_CONTEXT_LEN_MAX</td>
424 </tr>
425 </tbody>
426 </table>
427 </p>
428 <p><p><strong>struct tisci_msg_sa2ul_get_dkek_resp</strong></p>
429 <p>TISCI Response for requesting DKEK</p>
430 <table border="1" class="docutils">
431 <colgroup>
432 <col width="15%" />
433 <col width="25%" />
434 <col width="60%" />
435 </colgroup>
436 <thead valign="bottom">
437 <tr class="row-odd"><th class="head">Parameter</th>
438 <th class="head">Type</th>
439 <th class="head">Description</th>
440 </tr>
441 </thead>
442 <tbody valign="top">
443 <tr class="row-even"><td>hdr</td>
444 <td>struct tisci_header</td>
445 <td>Generic TISCI message header.</td>
446 </tr>
447 <tr class="row-odd"><td>dkek</td>
448 <td>u8</td>
449 <td>Array containing Derived KEK. Length is 32 bytes</td>
450 </tr>
451 </tbody>
452 </table>
453 </p>
454 <p>See <a class="reference internal" href="#pub-tisci-dkek-notes"><span class="std std-ref">API Notes</span></a> below.</p>
455 </div>
456 <div class="section" id="api-notes">
457 <span id="pub-tisci-dkek-notes"></span><h3>API Notes<a class="headerlink" href="#api-notes" title="Permalink to this headline">¶</a></h3>
458 <ul class="simple">
459 <li>The total length of the Label and Context fields below is limited by the size
460 of the TISCI messages(see <a class="reference internal" href="../general/TISCI_header.html#pub-secure-msg-header"><span class="std std-ref">Secure Messaging Header</span></a>) to 41 bytes.</li>
461 <li>System Firmware only support <code class="docutils literal"><span class="pre">sa2ul_instance</span></code> value of 0 in the API below.</li>
462 </ul>
463 </div>
464 </div>
465 </div>
468            </div>
469           </div>
470           <footer>
471   
472     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
473       
474         <a href="security_handover.html" class="btn btn-neutral float-right" title="Security Handover Message Description" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
475       
476       
477         <a href="extended_otp.html" class="btn btn-neutral" title="Extended OTP TISCI Description" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
478       
479     </div>
480   
482   <hr/>
484   <div role="contentinfo">
485     <p>
486       <a href="http://www.ti.com/corp/docs/legal/copyright.shtml">&copy; Copyright 2016-2020</a>, Texas Instruments Incorporated. All rights reserved. <br>
487       <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>
489     </p>
490   </div> 
492 </footer>
494         </div>
495       </div>
497     </section>
499   </div>
500   
503   
505     <script type="text/javascript">
506         var DOCUMENTATION_OPTIONS = {
507             URL_ROOT:'../../',
508             VERSION:'20.00.03',
509             COLLAPSE_INDEX:false,
510             FILE_SUFFIX:'.html',
511             HAS_SOURCE:  true
512         };
513     </script>
514       <script type="text/javascript" src="../../_static/jquery.js"></script>
515       <script type="text/javascript" src="../../_static/underscore.js"></script>
516       <script type="text/javascript" src="../../_static/doctools.js"></script>
517       <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
519     <script src="http://www.ti.com/assets/js/headerfooter/analytics.js" type="text/javascript" charset="utf-8"></script>
521   
523   
524   
525     <script type="text/javascript" src="../../_static/js/theme.js"></script>
526   
528   
529   
530   <script type="text/javascript">
531       jQuery(function () {
532           SphinxRtdTheme.StickyNav.enable();
533         });
535       var menuHeight = window.innerHeight;
537       var contentOffset = $(".wy-nav-content-wrap").offset();
538       var contentHeight = $(".wy-nav-content-wrap").height();
539       var contentBottom = contentOffset.top + contentHeight;
541       function setNavbarTop() {
542           var scrollTop = $(window).scrollTop();
543           var maxTop = scrollTop + menuHeight;
545           // If past the header
546           if (scrollTop > contentOffset.top && maxTop < contentBottom) {
547             stickyTop = scrollTop - contentOffset.top;
548           } else if (maxTop > contentBottom) {
549             stickyTop = scrollTop - contentOffset.top - (maxTop - contentBottom);
550           } else {
551             stickyTop = 0;
552           }
554           $(".wy-nav-side").css("top", stickyTop);
555       }
557       $(document).ready(function() {
558         setNavbarTop();
559         $(window).scroll(function () {
560           setNavbarTop();
561         });
563         $('body').on("mousewheel", function () {
564             // Remove default behavior
565             event.preventDefault();
566             // Scroll without smoothing
567             var wheelDelta = event.wheelDelta;
568             var currentScrollPosition = window.pageYOffset;
569             window.scrollTo(0, currentScrollPosition - wheelDelta);
570         });
571       });
572   </script>
573    
575 </body>
576 </html>