TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / c6b75f89526b234e1bc6a8a8f0c0e57624372954 / . / docs / 1.0.1 / html / overview / goals.html
blob: 02bd5802598300ebb93e2d9378b9233a624c5efd [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>2. Design goals &#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="3. Functionality overview" href="functionality.html" />
19 <link rel="prev" title="1. Introduction" href="intro.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="design-goals">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]37<span id="id1"></span><h1>2. Design goals</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]38<div class="section" id="suitable-for-constrained-devices">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]39<h2>2.1. Suitable for constrained devices</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]40<p>The interface is suitable for a vast range of devices: from special-purpose
41cryptographic processors that process data with a built-in key, to constrained
42devices running custom application code, such as microcontrollers, and
43multi-application devices, such as servers. Consequentially, the interface is
44scalable and modular.</p>
45<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]46<li><p><em>Scalable</em>: devices only need to implement the functionality that they will
47use.</p></li>
48<li><p><em>Modular</em>: larger devices implement larger subsets of the same interface,
49rather than different interfaces.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]50</ul>
51<p>In this interface, all operations on unbounded amounts of data
52allow <em>multi-part</em> processing, as long as the calculations on the data are
53performed in a streaming manner. This means that the application does not need
54to store the whole message in memory at one time. As a result, this
55specification is suitable for very constrained devices, including those where
56memory is very limited.</p>
57<p>Memory outside the keystore boundary is managed by the application. An
58implementation of the interface is not required to retain any state between
59function calls, apart from the content of the keystore and other data that must
60be kept inside the keystore security boundary.</p>
61<p>The interface does not expose the representation of keys and intermediate data,
62except when required for interchange. This allows each implementation to choose
63optimal data representations. Implementations with multiple components are also
64free to choose which memory area to use for internal data.</p>
65</div>
66<div class="section" id="a-keystore-interface">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]67<h2>2.2. A keystore interface</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]68<p>The specification allows cryptographic operations to be performed on a key to
69which the application does not have direct access. Except where required for
70interchange, applications access all keys indirectly, by an identifier. The key
71material corresponding to that identifier can reside inside a security boundary
72that prevents it from being extracted, except as permitted by a policy that is
73defined when the key is created.</p>
74</div>
75<div class="section" id="optional-isolation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]76<span id="isolation"></span><h2>2.3. Optional isolation</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]77<p>Implementations can isolate the cryptoprocessor from the calling application,
78and can further isolate multiple calling applications. The interface allows the
79implementation to be separated between a frontend and a backend. In an isolated
80implementation, the frontend is the part of the implementation that is located
81in the same isolation boundary as the application, which the application
82accesses by function calls. The backend is the part of the implementation that
83is located in a different environment, which is protected from the frontend.
84Various technologies can provide protection, for example:</p>
85<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]86<li><p>Process isolation in an operating system.</p></li>
87<li><p>Partition isolation, either with a virtual machine or a partition manager.</p></li>
88<li><p>Physical separation between devices.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]89</ul>
90<p>Communication between the frontend and backend is beyond the scope of this
91specification.</p>
92<p>In an isolated implementation, the backend can serve more than one
93implementation instance. In this case, a single backend communicates with
94multiple instances of the frontend. The backend must enforce <strong>caller
95isolation</strong>: it must ensure that assets of one frontend are not visible to any
96other frontend. The mechanism for identifying callers is beyond the scope of this
97specification. An implementation that provides caller isolation must document
98the identification mechanism. An implementation that provides isolation must
99document any implementation-specific extension of the API that enables frontend
100instances to share data in any form.</p>
101<p>In summary, there are three types of implementation:</p>
102<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]103<li><p>No isolation: there is no security boundary between the application and the
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]104cryptoprocessor. For example, a statically or dynamically linked library is
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]105an implementation with no isolation.</p></li>
106<li><p>Cryptoprocessor isolation: there is a security boundary between the
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]107application and the cryptoprocessor, but the cryptoprocessor does not
108communicate with other applications. For example, a cryptoprocessor chip that
109is a companion to an application processor is an implementation with
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]110cryptoprocessor isolation.</p></li>
111<li><p>Caller isolation: there are multiple application instances, with a security
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]112boundary between the application instances among themselves, as well as
113between the cryptoprocessor and the application instances. For example, a
114cryptography service in a multiprocess environment is an implementation with
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]115caller and cryptoprocessor isolation.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]116</ul>
117</div>
118<div class="section" id="choice-of-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]119<h2>2.4. Choice of algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]120<p>The specification defines a low-level cryptographic interface, where the caller
121explicitly chooses which algorithm and which security parameters they use. This
122is necessary to implement protocols that are inescapable in various use cases.
123The design of the interface enables applications to implement widely-used
124protocols and data exchange formats, as well as custom ones.</p>
125<p>As a consequence, all cryptographic functionality operates according to the
126precise algorithm specified by the caller. However, this does not apply to
127device-internal functionality, which does not involve any form of
128interoperability, such as random number generation. The specification does not
129include generic higher-level interfaces, where the implementation chooses the
130best algorithm for a purpose. However, higher-level libraries can be built on
131top of the PSA Crypto API.</p>
132<p>Another consequence is that the specification permits the use of algorithms, key
133sizes and other parameters that, while known to be insecure, might be necessary to
134support legacy protocols or legacy data. Where major weaknesses are known, the
135algorithm descriptions give applicable warnings. However, the lack of a warning
136both does not and cannot indicate that an algorithm is secure in all circumstances.
137Application developers need to research the security of the protocols and
138algorithms that they plan to use to determine if these meet their requirements.</p>
139<p>The interface facilitates algorithm agility. As a consequence, cryptographic
140primitives are presented through generic functions with a parameter indicating
141the specific choice of algorithm. For example, there is a single function to
142calculate a message digest, which takes a parameter that identifies the specific
143hash algorithm.</p>
144</div>
145<div class="section" id="ease-of-use">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]146<h2>2.5. Ease of use</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]147<p>The interface is designed to be as user-friendly as possible, given the
148aforementioned constraints on suitability for various types of devices and on
149the freedom to choose algorithms.</p>
150<p>In particular, the code flows are designed to reduce the risk of dangerous
151misuse. The interface is designed in part to make it harder to misuse. Where
152possible, it is designed so that
153typical mistakes result in test failures, rather than subtle security issues.
154Implementations avoid leaking data when a function is called with invalid
155parameters, to the extent allowed by the C language and by implementation size
156constraints.</p>
157</div>
158<div class="section" id="example-use-cases">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]159<h2>2.6. Example use cases</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]160<p>This section lists some of the use cases that were considered during the design
161of this API. This list is not exhaustive, nor are all implementations required to
162support all use cases.</p>
163<div class="section" id="network-security-tls">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]164<h3>2.6.1. Network Security (TLS)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]165<p>The API provides all of the cryptographic primitives needed to establish TLS
166connections.</p>
167</div>
168<div class="section" id="secure-storage">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]169<h3>2.6.2. Secure Storage</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]170<p>The API provides all primitives related to storage encryption, block or
171file-based, with master encryption keys stored inside a key store.</p>
172</div>
173<div class="section" id="network-credentials">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]174<h3>2.6.3. Network Credentials</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]175<p>The API provides network credential management inside a key store, for example,
176for X.509-based authentication or pre-shared keys on enterprise networks.</p>
177</div>
178<div class="section" id="device-pairing">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]179<h3>2.6.4. Device Pairing</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]180<p>The API provides support for key agreement protocols that are often used for
181secure pairing of devices over wireless channels. For example, the pairing of an
182NFC token or a Bluetooth device might use key agreement protocols upon
183first use.</p>
184</div>
185<div class="section" id="secure-boot">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]186<h3>2.6.5. Secure Boot</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]187<p>The API provides primitives for use during firmware integrity and authenticity
188validation, during a secure or trusted boot process.</p>
189</div>
190<div class="section" id="attestation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]191<h3>2.6.6. Attestation</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]192<p>The API provides primitives used in attestation activities. Attestation is the
193ability for a device to sign an array of bytes with a device private key and
194return the result to the caller. There are several use cases; ranging from attestation
195of the device state, to the ability to generate a key pair and prove that it has
196been generated inside a secure key store. The API provides access to the
197algorithms commonly used for attestation.</p>
198</div>
199<div class="section" id="factory-provisioning">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]200<h3>2.6.7. Factory Provisioning</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]201<p>Most IoT devices receive a unique identity during the factory provisioning
202process, or once they have been deployed to the field. This API provides the APIs necessary for
203populating a device with keys that represent that identity.</p>
204</div>
205</div>
206</div>
207
208
209 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]210
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]211 </div>
212 </div>
213 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]214 <div class="sphinxsidebarwrapper"><h3><a href="../index.html"><b>PSA Crypto API</b></a></h3>
215IHI 0086<br/>
216Non-confidential<br/>
217Version 1.0.1
218<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]219<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]220<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]221</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]222<ul class="current">
223<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
224<li class="toctree-l1 current"><a class="current reference internal" href="#">2. Design goals</a><ul>
225<li class="toctree-l2"><a class="reference internal" href="#suitable-for-constrained-devices">2.1. Suitable for constrained devices</a></li>
226<li class="toctree-l2"><a class="reference internal" href="#a-keystore-interface">2.2. A keystore interface</a></li>
227<li class="toctree-l2"><a class="reference internal" href="#optional-isolation">2.3. Optional isolation</a></li>
228<li class="toctree-l2"><a class="reference internal" href="#choice-of-algorithms">2.4. Choice of algorithms</a></li>
229<li class="toctree-l2"><a class="reference internal" href="#ease-of-use">2.5. Ease of use</a></li>
230<li class="toctree-l2"><a class="reference internal" href="#example-use-cases">2.6. Example use cases</a><ul>
231<li class="toctree-l3"><a class="reference internal" href="#network-security-tls">2.6.1. Network Security (TLS)</a></li>
232<li class="toctree-l3"><a class="reference internal" href="#secure-storage">2.6.2. Secure Storage</a></li>
233<li class="toctree-l3"><a class="reference internal" href="#network-credentials">2.6.3. Network Credentials</a></li>
234<li class="toctree-l3"><a class="reference internal" href="#device-pairing">2.6.4. Device Pairing</a></li>
235<li class="toctree-l3"><a class="reference internal" href="#secure-boot">2.6.5. Secure Boot</a></li>
236<li class="toctree-l3"><a class="reference internal" href="#attestation">2.6.6. Attestation</a></li>
237<li class="toctree-l3"><a class="reference internal" href="#factory-provisioning">2.6.7. Factory Provisioning</a></li>
238</ul>
239</li>
240</ul>
241</li>
242<li class="toctree-l1"><a class="reference internal" href="functionality.html">3. Functionality overview</a></li>
243<li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li>
244<li class="toctree-l1"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
245<li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
246<li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li>
247<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
248<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
249<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
250</ul>
251<ul>
252<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
253<li class="toctree-l1"><a class="reference internal" href="../appendix/specdef_values.html">Example macro implementations</a></li>
254<li class="toctree-l1"><a class="reference internal" href="../appendix/history.html">Changes to the API</a></li>
255</ul>
256<ul>
257<li class="toctree-l1"><a class="reference internal" href="../psa_c-identifiers.html">Index of API elements</a></li>
258</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]259<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]260 <h3 id="searchlabel">Quick search</h3>
261 <div class="searchformwrapper">
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]262 <form class="search" action="../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]263 <input type="text" name="q" aria-labelledby="searchlabel" />
264 <input type="submit" value="Go" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]265 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]266 </div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]267</div>
268<script type="text/javascript">$('#searchbox').show(0);</script>
269 </div>
270 </div>
271 <div class="clearer"></div>
272 </div>
273 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]274 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]275
276 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]277 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
278 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]279
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]280 </div>
281
282
283
284
285 </body>
286</html>