TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / e26ccadad2903200a70e2bda85902c009246a59a / . / docs / html / overview / usage.html
blob: a1f98ce5c4f4c94ab69cd1bb471836831d9d2460 [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]2<!DOCTYPE html>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]3
4<html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]6 <meta charset="utf-8" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]7 <title>7. Usage considerations &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]8 <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
9 <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]10 <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]11 <script type="text/javascript" src="../_static/jquery.js"></script>
12 <script type="text/javascript" src="../_static/underscore.js"></script>
13 <script type="text/javascript" src="../_static/doctools.js"></script>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]14 <script type="text/javascript" src="../_static/language_data.js"></script>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]15 <link rel="author" title="About these documents" href="../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]16 <link rel="index" title="Index" href="../genindex.html" />
17 <link rel="search" title="Search" href="../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]18 <link rel="next" title="8. Library management reference" href="../api/library/index.html" />
19 <link rel="prev" title="6. Implementation considerations" href="implementation.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]20
21 <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
22
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]23
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]24 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
25
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]26 </head><body>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]27
28
29 <div class="document">
30 <div class="documentwrapper">
31 <div class="bodywrapper">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]32
33
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]34 <div class="body" role="main">
35
36 <div class="section" id="usage-considerations">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]37<span id="id1"></span><h1>7. Usage considerations</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]38<div class="section" id="security-recommendations">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]39<h2>7.1. Security recommendations</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]40<div class="section" id="always-check-for-errors">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]41<h3>7.1.1. Always check for errors</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]42<p>Most functions in this API can return errors. All functions that can fail have
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]43the return type <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_status_t</span></code></a>. A few functions cannot fail, and thus, return
44<code class="docutils literal notranslate"><span class="pre">void</span></code> or some other type.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]45<p>If an error occurs, unless otherwise specified, the content of the output
46parameters is undefined and must not be used.</p>
47<p>Some common causes of errors include:</p>
48<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]49<li><p>In implementations where the keys are stored and processed in a separate
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]50environment from the application, all functions that need to access the
51cryptography processing environment might fail due to an error in the
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]52communication between the two environments.</p></li>
53<li><p>If an algorithm is implemented with a hardware accelerator, which is
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]54logically separate from the application processor, the accelerator might fail,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]55even when the application processor keeps running normally.</p></li>
56<li><p>Most functions might fail due to a lack of resources. However, some
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]57implementations guarantee that certain functions always have sufficient
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]58memory.</p></li>
59<li><p>All functions that access persistent keys might fail due to a storage failure.</p></li>
60<li><p>All functions that require randomness might fail due to a lack of entropy.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]61Implementations are encouraged to seed the random generator with sufficient
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]62entropy during the execution of <a class="reference internal" href="../api/library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. However, some security
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]63standards require periodic reseeding from a hardware random generator, which
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]64can fail.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]65</ul>
66</div>
67<div class="section" id="shared-memory-and-concurrency">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]68<h3>7.1.2. Shared memory and concurrency</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]69<p>Some environments allow applications to be multithreaded, while others do not.
70In some environments, applications can share memory with a different security
71context. In environments with multithreaded applications or shared memory,
72applications must be written carefully to avoid data corruption or leakage. This
73specification requires the application to obey certain constraints.</p>
74<p>In general, this API allows either one writer or any number of simultaneous
75readers, on any given object. In other words, if two or more calls access the
76same object concurrently, then the behavior is only well-defined if all the
77calls are only reading from the object and do not modify it. Read accesses
78include reading memory by input parameters and reading keystore content by using
79a key. For more details, refer to the <a class="reference internal" href="conventions.html#concurrency"><span class="std std-ref">Concurrent calls</span></a>
80section.</p>
81<p>If an application shares memory with another security context, it can pass
82shared memory blocks as input buffers or output buffers, but not as non-buffer
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]83parameters. For more details, refer to the <a class="reference internal" href="conventions.html#stability-of-parameters"><span class="secref">Stability of parameters</span></a> section.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]84</div>
85<div class="section" id="cleaning-up-after-use">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]86<h3>7.1.3. Cleaning up after use</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]87<p>To minimize impact if the system is compromised, it is recommended that
88applications wipe all sensitive data from memory when it is no longer used. That
89way, only data that is currently in use can be leaked, and past data is not
90compromised.</p>
91<p>Wiping sensitive data includes:</p>
92<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]93<li><p>Clearing temporary buffers in the stack or on the heap.</p></li>
94<li><p>Aborting operations if they will not be finished.</p></li>
95<li><p>Destroying keys that are no longer used.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]96</ul>
97</div>
98</div>
99</div>
100
101
102 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]103
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]104 </div>
105 </div>
106 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]107 <div class="sphinxsidebarwrapper"><h3><a href="../index.html"><b>PSA Crypto API</b></a></h3>
108IHI 0086<br/>
109Non-confidential<br/>
110Version 1.0.1
111<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]112<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]113<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]114</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]115<ul class="current">
116<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
117<li class="toctree-l1"><a class="reference internal" href="goals.html">2. Design goals</a></li>
118<li class="toctree-l1"><a class="reference internal" href="functionality.html">3. Functionality overview</a></li>
119<li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li>
120<li class="toctree-l1"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
121<li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
122<li class="toctree-l1 current"><a class="current reference internal" href="#">7. Usage considerations</a><ul>
123<li class="toctree-l2"><a class="reference internal" href="#security-recommendations">7.1. Security recommendations</a><ul>
124<li class="toctree-l3"><a class="reference internal" href="#always-check-for-errors">7.1.1. Always check for errors</a></li>
125<li class="toctree-l3"><a class="reference internal" href="#shared-memory-and-concurrency">7.1.2. Shared memory and concurrency</a></li>
126<li class="toctree-l3"><a class="reference internal" href="#cleaning-up-after-use">7.1.3. Cleaning up after use</a></li>
127</ul>
128</li>
129</ul>
130</li>
131<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
132<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
133<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
134</ul>
135<ul>
136<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
137<li class="toctree-l1"><a class="reference internal" href="../appendix/specdef_values.html">Example macro implementations</a></li>
138<li class="toctree-l1"><a class="reference internal" href="../appendix/history.html">Changes to the API</a></li>
139</ul>
140<ul>
141<li class="toctree-l1"><a class="reference internal" href="../psa_c-identifiers.html">Index of API elements</a></li>
142</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]143<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]144 <h3 id="searchlabel">Quick search</h3>
145 <div class="searchformwrapper">
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]146 <form class="search" action="../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]147 <input type="text" name="q" aria-labelledby="searchlabel" />
148 <input type="submit" value="Go" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]149 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]150 </div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]151</div>
152<script type="text/javascript">$('#searchbox').show(0);</script>
153 </div>
154 </div>
155 <div class="clearer"></div>
156 </div>
157 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]158 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]159
160 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]161 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
162 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]163
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]164 </div>
165
166
167
168
169 </body>
170</html>