TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 882f7c72267ee598fd4f7c0d34b2c70760c76d8c / . / docs / 1.1.0 / html / overview / usage.html
blob: f2d8d5b383e35a6c79688d0d34a3963471d499dc [file] [log] [blame]
Gilles Peskine882f7c72022-04-07 13:44:55 +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>7. Usage considerations &#8212; PSA Crypto API 1.1.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.1.0',
15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
17 HAS_SOURCE: false,
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="author" title="About these documents" href="../about.html" />
25 <link rel="index" title="Index" href="../genindex.html" />
26 <link rel="search" title="Search" href="../search.html" />
27 <link rel="next" title="8. Library management reference" href="../api/library/index.html" />
28 <link rel="prev" title="6. Implementation considerations" href="implementation.html" />
29
30 <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
31
32 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
33
34 </head>
35 <body>
36
37
38 <div class="document">
39 <div class="documentwrapper">
40 <div class="bodywrapper">
41 <div class="body" role="main">
42
43 <div class="section" id="usage-considerations">
44<span id="id1"></span><h1>7. Usage considerations</h1>
45<div class="section" id="security-recommendations">
46<h2>7.1. Security recommendations</h2>
47<div class="section" id="always-check-for-errors">
48<h3>7.1.1. Always check for errors</h3>
49<p>Most functions in this API can return errors. All functions that can fail have
50the 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
51<code class="docutils literal"><span class="pre">void</span></code> or some other type.</p>
52<p>If an error occurs, unless otherwise specified, the content of the output
53parameters is undefined and must not be used.</p>
54<p>Some common causes of errors include:</p>
55<ul class="simple">
56<li>In implementations where the keys are stored and processed in a separate
57environment from the application, all functions that need to access the
58cryptography processing environment might fail due to an error in the
59communication between the two environments.</li>
60<li>If an algorithm is implemented with a hardware accelerator, which is
61logically separate from the application processor, the accelerator might fail,
62even when the application processor keeps running normally.</li>
63<li>Most functions might fail due to a lack of resources. However, some
64implementations guarantee that certain functions always have sufficient
65memory.</li>
66<li>All functions that access persistent keys might fail due to a storage failure.</li>
67<li>All functions that require randomness might fail due to a lack of entropy.
68Implementations are encouraged to seed the random generator with sufficient
69entropy 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
70standards require periodic reseeding from a hardware random generator, which
71can fail.</li>
72</ul>
73</div>
74<div class="section" id="shared-memory-and-concurrency">
75<h3>7.1.2. Shared memory and concurrency</h3>
76<p>Some environments allow applications to be multithreaded, while others do not.
77In some environments, applications can share memory with a different security
78context. In environments with multithreaded applications or shared memory,
79applications must be written carefully to avoid data corruption or leakage. This
80specification requires the application to obey certain constraints.</p>
81<p>In general, this API allows either one writer or any number of simultaneous
82readers, on any given object. In other words, if two or more calls access the
83same object concurrently, then the behavior is only well-defined if all the
84calls are only reading from the object and do not modify it. Read accesses
85include reading memory by input parameters and reading keystore content by using
86a key. For more details, refer to <a class="reference internal" href="conventions.html#concurrency"><span class="secref">Concurrent calls</span></a>.</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 <a class="reference internal" href="conventions.html#stability-of-parameters"><span class="secref">Stability of parameters</span></a>.</p>
90</div>
91<div class="section" id="cleaning-up-after-use">
92<h3>7.1.3. 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"><h3><a href="../index.html"><b>PSA Crypto API</b></a></h3>
113IHI 0086<br/>
114Non-confidential<br/>
115Version 1.1.0
116<span style="color: red; font-weight: bold;"></span>
117<ul>
118<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
119</ul>
120<ul class="current">
121<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
122<li class="toctree-l1"><a class="reference internal" href="goals.html">2. Design goals</a></li>
123<li class="toctree-l1"><a class="reference internal" href="functionality.html">3. Functionality overview</a></li>
124<li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li>
125<li class="toctree-l1"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
126<li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
127<li class="toctree-l1 current"><a class="current reference internal" href="#">7. Usage considerations</a><ul>
128<li class="toctree-l2"><a class="reference internal" href="#security-recommendations">7.1. Security recommendations</a><ul>
129<li class="toctree-l3"><a class="reference internal" href="#always-check-for-errors">7.1.1. Always check for errors</a></li>
130<li class="toctree-l3"><a class="reference internal" href="#shared-memory-and-concurrency">7.1.2. Shared memory and concurrency</a></li>
131<li class="toctree-l3"><a class="reference internal" href="#cleaning-up-after-use">7.1.3. Cleaning up after use</a></li>
132</ul>
133</li>
134</ul>
135</li>
136<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
137<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
138<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
139</ul>
140<ul>
141<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
142<li class="toctree-l1"><a class="reference internal" href="../appendix/encodings.html">Algorithm and key type encoding</a></li>
143<li class="toctree-l1"><a class="reference internal" href="../appendix/specdef_values.html">Example macro implementations</a></li>
144<li class="toctree-l1"><a class="reference internal" href="../appendix/sra.html">Security Risk Assessment</a></li>
145<li class="toctree-l1"><a class="reference internal" href="../appendix/history.html">Changes to the API</a></li>
146</ul>
147<ul>
148<li class="toctree-l1"><a class="reference internal" href="../psa_c-identifiers.html">Index of API elements</a></li>
149</ul>
150<div id="searchbox" style="display: none" role="search">
151 <h3>Quick search</h3>
152 <form class="search" action="../search.html" method="get">
153 <div><input type="text" name="q" /></div>
154 <div><input type="submit" value="Go" /></div>
155 <input type="hidden" name="check_keywords" value="yes" />
156 <input type="hidden" name="area" value="default" />
157 </form>
158</div>
159<script type="text/javascript">$('#searchbox').show(0);</script>
160 </div>
161 </div>
162 <div class="clearer"></div>
163 </div>
164 <div class="footer">
165 &copy; 2018-2022, Arm Limited or its affiliates. All rights reserved.
166
167 |
168 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
169 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
170
171 </div>
172
173
174
175
176 </body>
177</html>