TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 132d88c4436af3a8ad535238788b3c8beb21e29d / . / docs / html / overview / usage.html
blob: ab13482574a28400c9dddf968321ecece2dab364 [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" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]8 <title>7. Usage considerations &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]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: '../',
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]14 VERSION: '1.0.1',
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]17 HAS_SOURCE: false,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]24 <link rel="author" title="About these documents" href="../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]25 <link rel="index" title="Index" href="../genindex.html" />
26 <link rel="search" title="Search" href="../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]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" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]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">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]44<span id="id1"></span><h1>7. Usage considerations</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]45<div class="section" id="security-recommendations">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]46<h2>7.1. Security recommendations</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]47<div class="section" id="always-check-for-errors">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]48<h3>7.1.1. Always check for errors</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]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">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]75<h3>7.1.2. Shared memory and concurrency</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]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 the <a class="reference internal" href="conventions.html#concurrency"><span class="std std-ref">Concurrent calls</span></a>
87section.</p>
88<p>If an application shares memory with another security context, it can pass
89shared memory blocks as input buffers or output buffers, but not as non-buffer
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]90parameters. 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]91</div>
92<div class="section" id="cleaning-up-after-use">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]93<h3>7.1.3. Cleaning up after use</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]94<p>To minimize impact if the system is compromised, it is recommended that
95applications wipe all sensitive data from memory when it is no longer used. That
96way, only data that is currently in use can be leaked, and past data is not
97compromised.</p>
98<p>Wiping sensitive data includes:</p>
99<ul class="simple">
100<li>Clearing temporary buffers in the stack or on the heap.</li>
101<li>Aborting operations if they will not be finished.</li>
102<li>Destroying keys that are no longer used.</li>
103</ul>
104</div>
105</div>
106</div>
107
108
109 </div>
110 </div>
111 </div>
112 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]113 <div class="sphinxsidebarwrapper"><h3><a href="../index.html"><b>PSA Crypto API</b></a></h3>
114IHI 0086<br/>
115Non-confidential<br/>
116Version 1.0.1
117<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]118<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]119<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]120</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]121<ul class="current">
122<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
123<li class="toctree-l1"><a class="reference internal" href="goals.html">2. Design goals</a></li>
124<li class="toctree-l1"><a class="reference internal" href="functionality.html">3. Functionality overview</a></li>
125<li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li>
126<li class="toctree-l1"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
127<li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
128<li class="toctree-l1 current"><a class="current reference internal" href="#">7. Usage considerations</a><ul>
129<li class="toctree-l2"><a class="reference internal" href="#security-recommendations">7.1. Security recommendations</a><ul>
130<li class="toctree-l3"><a class="reference internal" href="#always-check-for-errors">7.1.1. Always check for errors</a></li>
131<li class="toctree-l3"><a class="reference internal" href="#shared-memory-and-concurrency">7.1.2. Shared memory and concurrency</a></li>
132<li class="toctree-l3"><a class="reference internal" href="#cleaning-up-after-use">7.1.3. Cleaning up after use</a></li>
133</ul>
134</li>
135</ul>
136</li>
137<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
138<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
139<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
140</ul>
141<ul>
142<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</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/history.html">Changes to the API</a></li>
145</ul>
146<ul>
147<li class="toctree-l1"><a class="reference internal" href="../psa_c-identifiers.html">Index of API elements</a></li>
148</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]149<div id="searchbox" style="display: none" role="search">
150 <h3>Quick search</h3>
151 <form class="search" action="../search.html" method="get">
152 <div><input type="text" name="q" /></div>
153 <div><input type="submit" value="Go" /></div>
154 <input type="hidden" name="check_keywords" value="yes" />
155 <input type="hidden" name="area" value="default" />
156 </form>
157</div>
158<script type="text/javascript">$('#searchbox').show(0);</script>
159 </div>
160 </div>
161 <div class="clearer"></div>
162 </div>
163 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]164 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]165
166 |
167 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
168 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
169
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]170 </div>
171
172
173
174
175 </body>
176</html>