blob: d06d3a232332ddbd1abe2ba58fd6988632c643d3 [file] [log] [blame]
<!DOCTYPE html>
<!--
Copyright 2019 NXP
This software is owned or controlled by NXP and may only be used
strictly in accordance with the applicable license terms. By expressly
accepting such terms or by downloading, installing, activating and/or
otherwise using the software, you are agreeing that you have read, and
that you agree to comply with and are bound by, such license terms. If
you do not agree to be bound by the applicable license terms, then you
may not retain, install, activate or otherwise use the software.
-->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>7.3. SEMS Lite Agent Usage &#8212; Plug &amp; Trust MW v03.00.05 documentation</title>
<link rel="stylesheet" href="../../_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../../_static/graphviz.css" />
<script id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/underscore.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/language_data.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="7.4. SEMS Lite management APIs" href="sems_lite_mgmt_api.html" />
<link rel="prev" title="7.2. Update Package" href="sems_lite_package.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="../../_static/js/jquery-1.11.0.min.js "></script>
<script type="text/javascript" src="../../_static/js/jquery-fix.js "></script>
<script type="text/javascript" src="../../_static/bootstrap-3.3.7/js/bootstrap.min.js "></script>
<script type="text/javascript" src="../../_static/bootstrap-sphinx.js "></script>
</head><body>
<div id="navbar" class="navbar navbar-inverse navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../../toc.html"><span><img src="../../_static/NXP_logo_JPG.jpg"></span>
MW</a>
<span class="navbar-text navbar-version pull-left"><b>v03.00.05</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="../../toc.html">TOC <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../index.html">1. NXP Plug &amp; Trust Middleware</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../organization-of-documentation.html">1.1. Organization of Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../folder-structure.html">1.2. Folder Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sw-prerequisites.html">1.3. List of Platform Prerequisites</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../changes/index.html">2. Changes</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../changes/pending.html">2.1. Pending Refactoring items</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/pending.html#known-limitations">2.2. Known limitations</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v03_00_05.html">2.3. Release <code class="docutils literal notranslate"><span class="pre">v03.00.05</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v03_00_04.html">2.4. Release <code class="docutils literal notranslate"><span class="pre">v03.00.04</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v03_00_03.html">2.5. Release <code class="docutils literal notranslate"><span class="pre">v03.00.03</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v03_00_02.html">2.6. Release <code class="docutils literal notranslate"><span class="pre">v03.00.02</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_16_01.html">2.7. Release <code class="docutils literal notranslate"><span class="pre">v02.16.01</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_16_00.html">2.8. Release <code class="docutils literal notranslate"><span class="pre">v02.16.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_15_00.html">2.9. Release <code class="docutils literal notranslate"><span class="pre">v02.15.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_14_00.html">2.10. Release <code class="docutils literal notranslate"><span class="pre">v02.14.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_12_00.html">2.11. Release <code class="docutils literal notranslate"><span class="pre">v02.12.05</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_12_00.html#release-v02-12-04">2.12. Release <code class="docutils literal notranslate"><span class="pre">v02.12.04</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_12_00.html#release-v02-12-03">2.13. Release <code class="docutils literal notranslate"><span class="pre">v02.12.03</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_12_00.html#release-v02-12-02">2.14. Release <code class="docutils literal notranslate"><span class="pre">v02.12.02</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_12_00.html#release-v02-12-01">2.15. Release <code class="docutils literal notranslate"><span class="pre">v02.12.01</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_12_00.html#release-v02-12-00">2.16. Release <code class="docutils literal notranslate"><span class="pre">v02.12.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_11_03.html">2.17. Release <code class="docutils literal notranslate"><span class="pre">v02.11.03</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_11_01.html">2.18. Internal Release <code class="docutils literal notranslate"><span class="pre">v02.11.01</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_11_00.html">2.19. Release <code class="docutils literal notranslate"><span class="pre">v02.11.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_10_00.html">2.20. Release <code class="docutils literal notranslate"><span class="pre">v02.10.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_09_00.html">2.21. Release <code class="docutils literal notranslate"><span class="pre">v02.09.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_07_00.html">2.22. Release <code class="docutils literal notranslate"><span class="pre">v02.07.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_06_00.html">2.23. Release <code class="docutils literal notranslate"><span class="pre">v02.06.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_05_00_to_v02_03_00.html">2.24. Release <code class="docutils literal notranslate"><span class="pre">v02.05.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_05_00_to_v02_03_00.html#release-v02-04-00">2.25. Release <code class="docutils literal notranslate"><span class="pre">v02.04.00</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../changes/v02_05_00_to_v02_03_00.html#release-02-03-00">2.26. Release <code class="docutils literal notranslate"><span class="pre">02.03.00</span></code></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../stack/index.html">3. Plug &amp; Trust MW Stack</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../stack/features.html">3.1. Features</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/features.html#plug-trust-mw-block-diagram">3.2. Plug &amp; Trust MW : Block Diagram</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sss-apis.html">3.3. SSS APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/se05xfeatures.html">3.4. SSS APIs: SE051 vs SE050</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/param_checks.html">3.5. Parameter Check &amp; Conventions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/i2cm.html">3.6. I2CM / Secure Sensor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/logging.html">3.7. Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/feature-file.html">3.8. Feature File - <code class="docutils literal notranslate"><span class="pre">fsl_sss_ftr.h</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/platf-scp-from-fs.html">3.9. Using Platform SCP Keys from File System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/auth/auth-objects.html">3.10. Auth Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/auth/auth-objects-userid.html">3.11. Auth Objects : UserID</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/auth/auth-objects-aeskey.html">3.12. Auth Objects : AESKey</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/auth/auth-objects-eckey.html">3.13. Auth Objects : ECKey</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/key-id-range.html">3.14. Key Id Range and Purpose</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/key-id-range.html#authentication-keys">3.15. Authentication Keys</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../stack/key-id-range.html#trust-provisioned-keyids">3.16. Trust provisioned KeyIDs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sss/ex/doc/puf-scp03.html">3.17. SCP03 with PUF</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sss/doc/sss_heap_management.html">3.18. SSS Heap Management</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../building/index.html">4. Building / Compiling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../building/windows.html">4.1. Windows Build</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../building/frdm-k64f-sdk.html">4.2. Import MCUXPresso projects from SDK</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../building/frdm-k64f-cmake.html">4.3. Freedom K64F Build (CMake - Advanced)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../building/imx6.html">4.4. i.MX Linux Build</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../building/rpi3.html">4.5. Raspberry Pi Build</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../building/cmake.html">4.6. CMake</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../scripts/cmake_options.html">4.7. CMake Options</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../demos/index.html">5. Demo and Examples</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#demo-list">5.1. Demo List</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#sss-api-examples">5.2. SSS API Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#cloud-demos">5.3. Cloud Demos</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#linux-specific-demos">5.4. Linux Specific Demos</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#opc-ua-example">5.5. OPC-UA Example</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#arm-psa-example">5.6. ARM PSA Example</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#se05x-examples">5.7. SE05X Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#openssl-examples">5.8. OpenSSL Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#tests-for-user-crypto">5.9. Tests for User Crypto</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#nxpnfcrdlib-examples">5.10. NXPNFCRDLIB examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#ease-of-use-examples">5.11. Ease-of-Use examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#semslite-examples">5.12. Semslite examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/index.html#puf-examples">5.13. PUF examples</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../edgelock2go-agent.html">6. NXP EdgeLock 2GO Agent</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../nxp_iot_agent/doc/introduction.html">6.1. Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../nxp_iot_agent/doc/introduction.html#building-and-running-the-edgelock-2go-agent">6.2. Building and running the EdgeLock 2GO agent</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../nxp_iot_agent/doc/introduction.html#datastore-keystore">6.3. Datastore / Keystore</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../nxp_iot_agent/doc/introduction.html#connection-to-the-edgelock-2go-cloud-service">6.4. Connection to the EdgeLock 2GO cloud service</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../nxp_iot_agent/doc/introduction.html#claim-codes">6.5. Claim Codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../nxp_iot_agent/doc/edgelock2go_agent_apis.html">6.6. API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../nxp_iot_agent/doc/readme_usage_examples.html">6.7. Usage Examples</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">7. SEMS Lite Agent</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="sems_lite_overview.html">7.1. SEMS Lite Overview (Only for SE051)</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_package.html">7.2. Update Package</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">7.3. SEMS Lite Agent Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_mgmt_api.html">7.4. SEMS Lite management APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_process.html">7.5. SEMS Lite Agent Package Load Process</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_api.html">7.6. APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_known_issue.html">7.7. SEMS Lite Known Issue</a></li>
<li class="toctree-l2"><a class="reference internal" href="demo_update.html">7.8. SEMS Lite DEMOs</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../plugins/index.html">8. Plugins / Add-ins</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../sss/plugin/openssl/scripts/readme.html">8.1. Introduction on OpenSSL engine</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sss/plugin/mbedtls/scripts/readme.html">8.2. Introduction on mbedTLS ALT Implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sss/plugin/psa/Readme.html">8.3. Platform Security Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../plugins/akm.html">8.4. Android Key master</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sss/plugin/open62541/readme.html">8.5. Introduction on Open62541 (OPC UA stack)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../plugins/wifiEAP/wifiEAP.html">8.6. WiFi EAP Demo with Raspberry Pi3</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../plugins/pkcs11.html">8.7. PKCS#11 Standalone Library</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../cli-tool.html">9. CLI Tool</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/doc/introduction.html">9.1. Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/doc/block-diagram.html">9.2. Block Diagram</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/doc/pre-steps.html">9.3. Steps needed before running <code class="docutils literal notranslate"><span class="pre">ssscli</span></code> tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/doc/running.html">9.4. Running the <code class="docutils literal notranslate"><span class="pre">ssscli</span></code> tool - Windows</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/Provisioning/readme.html">9.5. CLI Provisioning</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/doc/readme_usage_examples.html">9.6. Usage Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/doc/cli_commands_list.html">9.7. List of <code class="docutils literal notranslate"><span class="pre">ssscli</span></code> commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/doc/cli_data_format.html">9.8. CLI Data formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../pycli/doc/cli_object_policy.html">9.9. Object Policies Through ssscli</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/upload_se05x_using_pycli.html">9.10. Upload keys and certificates to SE05X using ssscli tool</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../a71ch.html">10. A71CH</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../a71ch/a71ch_sss.html">10.1. A71CH and SSS API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../a71ch/a71ch_miscellaneous.html">10.2. Miscellaneous</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../a71ch/a71ch_legacy_host_api.html">10.3. A71CH Legacy API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../a71ch/a71ch_legacy_hlse_api.html">10.4. A71CH Legacy HLSE (Generic) API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../a71ch/a71ch_configure_tool.html">10.5. A71CH Legacy Configure Tool</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix.html">11. Appendix</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/glossary.html">11.1. Glossary</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/vcom.html">11.2. APDU Commands over VCOM</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/vs2019-setup.html">11.3. Visual Studio 2019 Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/ide_mcux.html">11.4. Setting up MCUXPresso IDE</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../dev-platforms.html">11.5. Development Platforms</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/se_uid.html">11.6. How to get SE Platform Information and UID</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/version_info.html">11.7. Version Information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../demos/Certificate_Chains/Readme.html">11.8. Certificate Chains</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/rjct_server.html">11.9. JRCP_v1 Server</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/platfscp.html">11.10. Using own Platform SCP03 Keys</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../appendix/apdu_write_to_buffer.html">11.11. Write APDU to buffer</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../api/api_list.html">11.12. Plug &amp; Trust MW APIs</a></li>
</ul>
</li>
</ul>
</ul>
</li>
<li class="dropdown">
<a role="button"
id="dLabelLocalToc"
data-toggle="dropdown"
data-target="#"
href="#">Page <b class="caret"></b></a>
<ul class="dropdown-menu localtoc"
role="menu"
aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">7.3. SEMS Lite Agent Usage</a><ul>
<li><a class="reference internal" href="#case-1-basic-usage">7.3.1. Case 1: Basic Usage</a></li>
<li><a class="reference internal" href="#case-2-in-case-there-was-a-tearing">7.3.2. Case 2: In case there was a tearing</a></li>
<li><a class="reference internal" href="#case-3-doing-a-recovery-after-a-failed-update">7.3.3. Case 3: Doing a recovery after a failed update</a></li>
<li><a class="reference internal" href="#case-4-tearing-during-recovery">7.3.4. Case 4: Tearing during recovery</a></li>
<li><a class="reference internal" href="#case-5-load-key-rotate-script-encounter-se-unexpected-power-off">7.3.5. Case 5: Load Key rotate script encounter SE unexpected power off</a></li>
<li><a class="reference internal" href="#api-calls-for-usage-of-sems-lite-agent">7.3.6. API Calls for Usage of SEMS Lite Agent</a></li>
</ul>
</li>
</ul>
</ul>
</li>
<li>
<a href="sems_lite_package.html" title="Previous Chapter: 7.2. Update Package"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; 7.2. Update Package</span>
</a>
</li>
<li>
<a href="sems_lite_mgmt_api.html" title="Next Chapter: 7.4. SEMS Lite management APIs"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">7.4. SEMS Lit... &raquo;</span>
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3">
<div id="sidebar" class="bs-sidenav" role="complementary">
<div class="sidebar-header">
<h3>Plug &amp; Trust MW</h3>
</div>
<div class="row">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../index.html">1. NXP Plug &amp; Trust Middleware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../changes/index.html">2. Changes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../stack/index.html">3. Plug &amp; Trust MW Stack</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../building/index.html">4. Building / Compiling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../demos/index.html">5. Demo and Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../edgelock2go-agent.html">6. NXP EdgeLock 2GO Agent</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">7. SEMS Lite Agent</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="sems_lite_overview.html">7.1. SEMS Lite Overview (Only for SE051)</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_package.html">7.2. Update Package</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">7.3. SEMS Lite Agent Usage</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#case-1-basic-usage">7.3.1. Case 1: Basic Usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#case-2-in-case-there-was-a-tearing">7.3.2. Case 2: In case there was a tearing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#case-3-doing-a-recovery-after-a-failed-update">7.3.3. Case 3: Doing a recovery after a failed update</a></li>
<li class="toctree-l3"><a class="reference internal" href="#case-4-tearing-during-recovery">7.3.4. Case 4: Tearing during recovery</a></li>
<li class="toctree-l3"><a class="reference internal" href="#case-5-load-key-rotate-script-encounter-se-unexpected-power-off">7.3.5. Case 5: Load Key rotate script encounter SE unexpected power off</a></li>
<li class="toctree-l3"><a class="reference internal" href="#api-calls-for-usage-of-sems-lite-agent">7.3.6. API Calls for Usage of SEMS Lite Agent</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_mgmt_api.html">7.4. SEMS Lite management APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_process.html">7.5. SEMS Lite Agent Package Load Process</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_api.html">7.6. APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="sems_lite_known_issue.html">7.7. SEMS Lite Known Issue</a></li>
<li class="toctree-l2"><a class="reference internal" href="demo_update.html">7.8. SEMS Lite DEMOs</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../plugins/index.html">8. Plugins / Add-ins</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cli-tool.html">9. CLI Tool</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../a71ch.html">10. A71CH</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix.html">11. Appendix</a></li>
</ul>
</div>
<div class="row">
<form class="form" action="../../search.html" method="get">
<div class="form-group">
<label for="Search">Search:</label>
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="body col-md-9 content" role="main">
<div class="section" id="sems-lite-agent-usage">
<h1><span class="section-number">7.3. </span>SEMS Lite Agent Usage<a class="headerlink" href="#sems-lite-agent-usage" title="Permalink to this headline"></a></h1>
<div class="section" id="case-1-basic-usage">
<span id="id1"></span><h2><span class="section-number">7.3.1. </span>Case 1: Basic Usage<a class="headerlink" href="#case-1-basic-usage" title="Permalink to this headline"></a></h2>
<p>Basic API usage documentation for using SEMS Lite agent is as under.</p>
<ol class="arabic simple">
<li><p>Call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1gaaccb91a35a7216212dc68ebec3eb9742.html#_CPPv428sems_lite_agent_init_contextP21sems_lite_agent_ctx_tP13sss_session_t" title="sems_lite_agent_init_context"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_init_context()</span></code></a> to do context initialization.</p></li>
<li><p>Call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1gafc25d0739c8db703bfd391e38bfc3387.html#_CPPv428sems_lite_agent_session_openP21sems_lite_agent_ctx_t" title="sems_lite_agent_session_open"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_session_open()</span></code></a> to open channel to SE and select SEMS Lite applet.</p></li>
<li><p>Call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1ga95b2af58604c4d5608e45ec5282118c5.html#_CPPv428sems_lite_agent_load_packageP21sems_lite_agent_ctx_tP19multicast_package_t" title="sems_lite_agent_load_package"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_load_package()</span></code></a> to load upgrade script.</p></li>
<li><p>SEMS Lite agent would internally query the tear status from SE051, if there was a power interrupt during upgradation(tearing event).</p></li>
<li><p>SEMS Lite agent load the script from package to SE051 and get response from SE051.</p></li>
<li><p>SEMS Lite agent checking the response and return “Success” to user.</p></li>
<li><p>User call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1ga0b699a964521f37b0abdfa1380e023a7.html#_CPPv429sems_lite_agent_session_closeP21sems_lite_agent_ctx_t" title="sems_lite_agent_session_close"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_session_close()</span></code></a> to close channel.</p></li>
</ol>
<img alt="../../_images/0022_flow_api_success.png" src="../../_images/0022_flow_api_success.png" />
</div>
<div class="section" id="case-2-in-case-there-was-a-tearing">
<span id="case-2-check-tearing"></span><h2><span class="section-number">7.3.2. </span>Case 2: In case there was a tearing<a class="headerlink" href="#case-2-in-case-there-was-a-tearing" title="Permalink to this headline"></a></h2>
<p>In case of tear which is due to system power off during uploading, user would receive return code “DoRerun” when he try to load new package. Use must load the torn again.</p>
<ol class="arabic simple">
<li><p>Call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1gaaccb91a35a7216212dc68ebec3eb9742.html#_CPPv428sems_lite_agent_init_contextP21sems_lite_agent_ctx_tP13sss_session_t" title="sems_lite_agent_init_context"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_init_context()</span></code></a>, <a class="reference internal" href="../../api/function_group__sems__lite__agent_1gafc25d0739c8db703bfd391e38bfc3387.html#_CPPv428sems_lite_agent_session_openP21sems_lite_agent_ctx_t" title="sems_lite_agent_session_open"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_session_open()</span></code></a> and <a class="reference internal" href="../../api/function_group__sems__lite__agent_1ga95b2af58604c4d5608e45ec5282118c5.html#_CPPv428sems_lite_agent_load_packageP21sems_lite_agent_ctx_tP19multicast_package_t" title="sems_lite_agent_load_package"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_load_package()</span></code></a> as those in <a class="reference internal" href="#case-1-basic-usage"><span class="std std-ref">Case 1: Basic Usage</span></a>.</p></li>
<li><p>SEMS Lite agent would query tear status from SE.</p></li>
<li><p>In case tear happens, SEMS Lite agent would get signature of tear script from SE and compare it to the signature of loaded script.</p></li>
<li><p>If these 2 signatures are same, it means the loaded script is the re-run script. SEMS Lite agent load it to SE.</p></li>
<li><p>If the signatures are different, SEMS Lite agent would inform user to load script again.</p></li>
<li><p>User must find the correct script by signature and load it again.</p></li>
</ol>
<img alt="../../_images/0020_flow_with_signature.png" src="../../_images/0020_flow_with_signature.png" />
</div>
<div class="section" id="case-3-doing-a-recovery-after-a-failed-update">
<h2><span class="section-number">7.3.3. </span>Case 3: Doing a recovery after a failed update<a class="headerlink" href="#case-3-doing-a-recovery-after-a-failed-update" title="Permalink to this headline"></a></h2>
<p>In case the upgrade can not complete, user would receive return code “Do Recovery”. User must load recovery script to resume SE to old Applet.</p>
<ol class="arabic simple">
<li><p>Call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1gaaccb91a35a7216212dc68ebec3eb9742.html#_CPPv428sems_lite_agent_init_contextP21sems_lite_agent_ctx_tP13sss_session_t" title="sems_lite_agent_init_context"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_init_context()</span></code></a>, <a class="reference internal" href="../../api/function_group__sems__lite__agent_1gafc25d0739c8db703bfd391e38bfc3387.html#_CPPv428sems_lite_agent_session_openP21sems_lite_agent_ctx_t" title="sems_lite_agent_session_open"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_session_open()</span></code></a> and <a class="reference internal" href="../../api/function_group__sems__lite__agent_1ga95b2af58604c4d5608e45ec5282118c5.html#_CPPv428sems_lite_agent_load_packageP21sems_lite_agent_ctx_tP19multicast_package_t" title="sems_lite_agent_load_package"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_load_package()</span></code></a> as those in <a class="reference internal" href="#case-1-basic-usage"><span class="std std-ref">Case 1: Basic Usage</span></a>.</p></li>
<li><p>SEMS Lite agent would query tear status from SE as in <a class="reference internal" href="#case-2-check-tearing"><span class="std std-ref">Case 2: In case there was a tearing</span></a>.</p></li>
<li><p>SEMS Lite agent load the script from package to SE. SE can’t complete upgrade and inform SEMS Lite agent to do recovery by response.</p></li>
<li><p>SEMS Lite agent checking the response and return “DoRecovery” to user.</p></li>
<li><p>User must find the recovery script which is used to load the old Applet.</p></li>
<li><p>User load the recovery script and get response from SEMS Lite agent.</p></li>
</ol>
<img alt="../../_images/0025_flow_api_recovery.png" src="../../_images/0025_flow_api_recovery.png" />
<p>Details for SE to report “Do Recovery” can be found in following:</p>
<img alt="../../_images/0030_flow_apis_recovery_detection_scenario1.png" src="../../_images/0030_flow_apis_recovery_detection_scenario1.png" />
<img alt="../../_images/0030_flow_apis_recovery_detection_scenario2.png" src="../../_images/0030_flow_apis_recovery_detection_scenario2.png" />
</div>
<div class="section" id="case-4-tearing-during-recovery">
<h2><span class="section-number">7.3.4. </span>Case 4: Tearing during recovery<a class="headerlink" href="#case-4-tearing-during-recovery" title="Permalink to this headline"></a></h2>
<p>Case 4: In case tear happens when loading recovery package, User should re-run the script in the same way described in <a class="reference internal" href="#case-2-check-tearing"><span class="std std-ref">Case 2: In case there was a tearing</span></a>.</p>
<img alt="../../_images/0041_flow_recovery_tear.png" src="../../_images/0041_flow_recovery_tear.png" />
</div>
<div class="section" id="case-5-load-key-rotate-script-encounter-se-unexpected-power-off">
<h2><span class="section-number">7.3.5. </span>Case 5: Load Key rotate script encounter SE unexpected power off<a class="headerlink" href="#case-5-load-key-rotate-script-encounter-se-unexpected-power-off" title="Permalink to this headline"></a></h2>
<p>In case the SE is powered off unexpectedly during uploading key rotate script, user would receive return code “COM_FAILURE” which means communication failure. User has 2 choices:</p>
<ol class="arabic simple">
<li><p>Load next script. SEMS Lite agent will check tear status and inform user if it’s required to re-run last script. It’s same to <a class="reference internal" href="#case-2-check-tearing"><span class="std std-ref">Case 2: In case there was a tearing</span></a>.</p></li>
<li><p>User software checks tear status and then decides whether to re-load the broken script as following:</p></li>
</ol>
<ol class="lowerroman simple">
<li><p>Call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1gaaccb91a35a7216212dc68ebec3eb9742.html#_CPPv428sems_lite_agent_init_contextP21sems_lite_agent_ctx_tP13sss_session_t" title="sems_lite_agent_init_context"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_init_context()</span></code></a> and <a class="reference internal" href="../../api/function_group__sems__lite__agent_1gafc25d0739c8db703bfd391e38bfc3387.html#_CPPv428sems_lite_agent_session_openP21sems_lite_agent_ctx_t" title="sems_lite_agent_session_open"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_session_open()</span></code></a> as those in <a class="reference internal" href="#case-1-basic-usage"><span class="std std-ref">Case 1: Basic Usage</span></a>.</p></li>
<li><p>Call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1ga792bd76b21552951f0d54bf34c7bf967.html#_CPPv420sems_lite_check_TearP21sems_lite_agent_ctx_tP27sems_lite_tearDown_status_t" title="sems_lite_check_Tear"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_check_Tear()</span></code></a> to decide if tear happens for last upgrade.</p></li>
<li><p>In case tear happens, call <a class="reference internal" href="../../api/function_group__sems__lite__agent_1ga2319aee6139def07df626fead5077366.html#_CPPv435sems_lite_get_SignatureofLastScriptP21sems_lite_agent_ctx_tP7uint8_tP6size_t" title="sems_lite_get_SignatureofLastScript"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_get_SignatureofLastScript()</span></code></a> to get last script signature</p></li>
<li><p>Find the correct script by signature and load the tear script again with <a class="reference internal" href="../../api/function_group__sems__lite__agent_1ga95b2af58604c4d5608e45ec5282118c5.html#_CPPv428sems_lite_agent_load_packageP21sems_lite_agent_ctx_tP19multicast_package_t" title="sems_lite_agent_load_package"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">sems_lite_agent_load_package()</span></code></a>.</p></li>
</ol>
<img alt="../../_images/0050_flow_unexpected_power_off.png" src="../../_images/0050_flow_unexpected_power_off.png" />
</div>
<div class="section" id="api-calls-for-usage-of-sems-lite-agent">
<h2><span class="section-number">7.3.6. </span>API Calls for Usage of SEMS Lite Agent<a class="headerlink" href="#api-calls-for-usage-of-sems-lite-agent" title="Permalink to this headline"></a></h2>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">&quot;sems_lite_api.h&quot;</span><span class="cp"></span>
</pre></div>
</div>
<p>Declare a SEMS Lite input buffer:
SEMS Lite input buffer is hex file converted from protobuf file</p>
<p>Declare SEMS Lite context:
SEMS Lite context holds flags and variables used through the whole loading process</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">sems_lite_agent_ctx_t</span> <span class="n">s_sems_lite_agent_ctx</span> <span class="o">=</span> <span class="p">{</span><span class="mi">0</span><span class="p">};</span>
</pre></div>
</div>
<p>Initilize the context:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">rv</span> <span class="o">=</span> <span class="n">sems_lite_agent_init_context</span><span class="p">(</span><span class="o">&amp;</span><span class="n">s_sems_lite_agent_ctx</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">pCtx</span><span class="o">-&gt;</span><span class="n">session</span><span class="p">);</span>
</pre></div>
</div>
<p>Open session:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">rv</span> <span class="o">=</span> <span class="n">sems_lite_agent_session_open</span><span class="p">(</span><span class="o">&amp;</span><span class="n">s_sems_lite_agent_ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>Load Package:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">status</span> <span class="o">=</span> <span class="n">sems_lite_agent_load_package</span><span class="p">(</span>
<span class="o">&amp;</span><span class="n">s_sems_lite_agent_ctx</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">multicast_package</span><span class="p">);</span>
</pre></div>
</div>
<p>Close the session:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">rv</span> <span class="o">=</span> <span class="n">sems_lite_agent_session_close</span><span class="p">(</span><span class="o">&amp;</span><span class="n">s_sems_lite_agent_ctx</span><span class="p">);</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
&copy; Copyright 2018-2020, NXP.<br/>
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.1.<br/>
</p>
</div>
</footer>
</body>
</html>