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