TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 6c723a2f46051a3543bb7856b41761e84f5a8a15 / . / docs / html / overview / usage.html
blob: 306bcee87e8d2f77d3fd7ae796e26890eb053ffa [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame^]1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8 <title>Usage considerations &#8212; PSA Crypto API 1.0.0 documentation</title>
9 <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
10 <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
11 <script type="text/javascript">
12 var DOCUMENTATION_OPTIONS = {
13 URL_ROOT: '../',
14 VERSION: '1.0.0',
15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
17 HAS_SOURCE: true,
18 SOURCELINK_SUFFIX: '.txt'
19 };
20 </script>
21 <script type="text/javascript" src="../_static/jquery.js"></script>
22 <script type="text/javascript" src="../_static/underscore.js"></script>
23 <script type="text/javascript" src="../_static/doctools.js"></script>
24 <link rel="index" title="Index" href="../genindex.html" />
25 <link rel="search" title="Search" href="../search.html" />
26 <link rel="next" title="Library management reference" href="../api/library/index.html" />
27 <link rel="prev" title="Implementation considerations" href="implementation.html" />
28
29 <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
30
31 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
32
33 </head>
34 <body>
35
36
37 <div class="document">
38 <div class="documentwrapper">
39 <div class="bodywrapper">
40 <div class="body" role="main">
41
42 <div class="section" id="usage-considerations">
43<span id="id1"></span><h1>Usage considerations</h1>
44<div class="section" id="security-recommendations">
45<h2>Security recommendations</h2>
46<div class="section" id="always-check-for-errors">
47<h3>Always check for errors</h3>
48<p>Most functions in this API can return errors. All functions that can fail have
49the 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"><span class="pre">psa_status_t</span></code></a>. A few functions cannot fail, and thus, return
50<code class="docutils literal"><span class="pre">void</span></code> or some other type.</p>
51<p>If an error occurs, unless otherwise specified, the content of the output
52parameters is undefined and must not be used.</p>
53<p>Some common causes of errors include:</p>
54<ul class="simple">
55<li>In implementations where the keys are stored and processed in a separate
56environment from the application, all functions that need to access the
57cryptography processing environment might fail due to an error in the
58communication between the two environments.</li>
59<li>If an algorithm is implemented with a hardware accelerator, which is
60logically separate from the application processor, the accelerator might fail,
61even when the application processor keeps running normally.</li>
62<li>Most functions might fail due to a lack of resources. However, some
63implementations guarantee that certain functions always have sufficient
64memory.</li>
65<li>All functions that access persistent keys might fail due to a storage failure.</li>
66<li>All functions that require randomness might fail due to a lack of entropy.
67Implementations are encouraged to seed the random generator with sufficient
68entropy 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"><span class="pre">psa_crypto_init()</span></code></a>. However, some security
69standards require periodic reseeding from a hardware random generator, which
70can fail.</li>
71</ul>
72</div>
73<div class="section" id="shared-memory-and-concurrency">
74<h3>Shared memory and concurrency</h3>
75<p>Some environments allow applications to be multithreaded, while others do not.
76In some environments, applications can share memory with a different security
77context. In environments with multithreaded applications or shared memory,
78applications must be written carefully to avoid data corruption or leakage. This
79specification requires the application to obey certain constraints.</p>
80<p>In general, this API allows either one writer or any number of simultaneous
81readers, on any given object. In other words, if two or more calls access the
82same object concurrently, then the behavior is only well-defined if all the
83calls are only reading from the object and do not modify it. Read accesses
84include reading memory by input parameters and reading keystore content by using
85a key. For more details, refer to the <a class="reference internal" href="conventions.html#concurrency"><span class="std std-ref">Concurrent calls</span></a>
86section.</p>
87<p>If an application shares memory with another security context, it can pass
88shared memory blocks as input buffers or output buffers, but not as non-buffer
89parameters. For more details, refer to the <em><a class="reference internal" href="conventions.html#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
90</div>
91<div class="section" id="cleaning-up-after-use">
92<h3>Cleaning up after use</h3>
93<p>To minimize impact if the system is compromised, it is recommended that
94applications wipe all sensitive data from memory when it is no longer used. That
95way, only data that is currently in use can be leaked, and past data is not
96compromised.</p>
97<p>Wiping sensitive data includes:</p>
98<ul class="simple">
99<li>Clearing temporary buffers in the stack or on the heap.</li>
100<li>Aborting operations if they will not be finished.</li>
101<li>Destroying keys that are no longer used.</li>
102</ul>
103</div>
104</div>
105</div>
106
107
108 </div>
109 </div>
110 </div>
111 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
112 <div class="sphinxsidebarwrapper">
113 <h3><a href="../index.html">Table Of Contents</a></h3>
114 <ul>
115<li><a class="reference internal" href="#">Usage considerations</a><ul>
116<li><a class="reference internal" href="#security-recommendations">Security recommendations</a><ul>
117<li><a class="reference internal" href="#always-check-for-errors">Always check for errors</a></li>
118<li><a class="reference internal" href="#shared-memory-and-concurrency">Shared memory and concurrency</a></li>
119<li><a class="reference internal" href="#cleaning-up-after-use">Cleaning up after use</a></li>
120</ul>
121</li>
122</ul>
123</li>
124</ul>
125<div class="relations">
126<h3>Related Topics</h3>
127<ul>
128 <li><a href="../index.html">Documentation overview</a><ul>
129 <li>Previous: <a href="implementation.html" title="previous chapter">Implementation considerations</a></li>
130 <li>Next: <a href="../api/library/index.html" title="next chapter">Library management reference</a></li>
131 </ul></li>
132</ul>
133</div>
134 <div role="note" aria-label="source link">
135 <h3>This Page</h3>
136 <ul class="this-page-menu">
137 <li><a href="../_sources/overview/usage.rst.txt"
138 rel="nofollow">Show Source</a></li>
139 </ul>
140 </div>
141<div id="searchbox" style="display: none" role="search">
142 <h3>Quick search</h3>
143 <form class="search" action="../search.html" method="get">
144 <div><input type="text" name="q" /></div>
145 <div><input type="submit" value="Go" /></div>
146 <input type="hidden" name="check_keywords" value="yes" />
147 <input type="hidden" name="area" value="default" />
148 </form>
149</div>
150<script type="text/javascript">$('#searchbox').show(0);</script>
151 </div>
152 </div>
153 <div class="clearer"></div>
154 </div>
155 <div class="footer">
156 &copy; 2019-2020, Arm Limited or its affiliates. All rights reserved.
157
158 |
159 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
160 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
161
162 |
163 <a href="../_sources/overview/usage.rst.txt"
164 rel="nofollow">Page source</a>
165 </div>
166
167
168
169
170 </body>
171</html>