TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / b0dbbb12c1b13fc6b262fa0ad65089a997bcd0d1 / . / docs / 1.1.0 / html / api / library / library.html
blob: 13060b122fcef2fc02445d8a516320d76d31ebdf [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>8.2. PSA Crypto library &#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="9. Key management reference" href="../keys/index.html" />
28 <link rel="prev" title="8.1. PSA status codes" href="status.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="psa-crypto-library">
44<h1>8.2. PSA Crypto library</h1>
45<div class="section" id="api-version">
46<span id="id1"></span><h2>8.2.1. API version</h2>
47<div class="section" id="PSA_CRYPTO_API_VERSION_MAJOR">
48<span id="c.PSA_CRYPTO_API_VERSION_MAJOR"></span><h3><code class="docutils literal"><span class="pre">PSA_CRYPTO_API_VERSION_MAJOR</span></code> (macro)</h3>
49<p>The major version of this implementation of the PSA Crypto API.</p>
50<pre class="literal-block">
51#define <a class="reference internal" href="#c.PSA_CRYPTO_API_VERSION_MAJOR" title="PSA_CRYPTO_API_VERSION_MAJOR">PSA_CRYPTO_API_VERSION_MAJOR</a> 1
52</pre>
53</div>
54<div class="section" id="PSA_CRYPTO_API_VERSION_MINOR">
55<span id="c.PSA_CRYPTO_API_VERSION_MINOR"></span><h3><code class="docutils literal"><span class="pre">PSA_CRYPTO_API_VERSION_MINOR</span></code> (macro)</h3>
56<p>The minor version of this implementation of the PSA Crypto API.</p>
57<pre class="literal-block">
58#define <a class="reference internal" href="#c.PSA_CRYPTO_API_VERSION_MINOR" title="PSA_CRYPTO_API_VERSION_MINOR">PSA_CRYPTO_API_VERSION_MINOR</a> 1
59</pre>
60</div>
61</div>
62<div class="section" id="library-initialization">
63<span id="library-init"></span><h2>8.2.2. Library initialization</h2>
64<div class="section" id="psa_crypto_init">
65<span id="c.psa_crypto_init"></span><h3><code class="docutils literal"><span class="pre">psa_crypto_init</span></code> (function)</h3>
66<p>Library initialization.</p>
67<pre class="literal-block">
68<a class="reference internal" href="status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_crypto_init" title="psa_crypto_init">psa_crypto_init</a>(void);
69</pre>
70<p class="rubric">Returns: <a class="reference internal" href="status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
71<dl class="docutils">
72<dt> <a class="reference internal" href="status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
73<dd>Success.</dd>
74<dt> <a class="reference internal" href="status.html#c.PSA_ERROR_INSUFFICIENT_ENTROPY" title="PSA_ERROR_INSUFFICIENT_ENTROPY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_ENTROPY</span></code></a></dt>
75<dd></dd>
76<dt> <a class="reference internal" href="status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
77<dd></dd>
78<dt> <a class="reference internal" href="status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
79<dd></dd>
80<dt> <a class="reference internal" href="status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
81<dd></dd>
82</dl>
83<p class="rubric">Description</p>
84<p>It is recommended that applications call this function before calling any other function in this module.</p>
85<p>Applications are permitted to call this function more than once. Once a call succeeds, subsequent calls are guaranteed to succeed.</p>
86<p>If the application calls any function that returns a <a class="reference internal" href="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> result code before calling <a class="reference internal" href="#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>, the following will occur:</p>
87<ul class="simple">
88<li>If initialization of the library is essential for secure operation of the function, the implementation must return <a class="reference internal" href="status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> or other appropriate error.</li>
89<li>If failure to initialize the library does not compromise the security of the function, the implementation must either provide the expected result for the function, or return <a class="reference internal" href="status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> or other appropriate error.</li>
90</ul>
91<div class="admonition note">
92<p class="first admonition-title">Note</p>
93<p>The following scenarios are examples where an implementation can require that the library has been initialized by calling <a class="reference internal" href="#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>:</p>
94<ul class="last simple">
95<li>A client-server implementation, in which <a class="reference internal" href="#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> establishes the communication with the server. No key management or cryptographic operation can be performed until this is done.</li>
96<li>An implementation in which <a class="reference internal" href="#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> initializes the random bit generator, and no operations that require the RNG can be performed until this is done. For example, random data, key, IV, or nonce generation; randomized signature or encryption; and algorithms that are implemented with blinding.</li>
97</ul>
98</div>
99<div class="admonition warning">
100<p class="first admonition-title">Warning</p>
101<p class="last">The set of functions that depend on successful initialization of the library is <a class="reference internal" href="../../about.html#term-implementation-defined"><span class="scterm">IMPLEMENTATION DEFINED</span></a>. Applications that rely on calling functions before initializing the library might not be portable to other implementations.</p>
102</div>
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="../../overview/intro.html">1. Introduction</a></li>
122<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
123<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
124<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
125<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
126<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
127<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
128<li class="toctree-l1 current"><a class="reference internal" href="index.html">8. Library management reference</a><ul class="current">
129<li class="toctree-l2"><a class="reference internal" href="status.html">8.1. PSA status codes</a></li>
130<li class="toctree-l2 current"><a class="current reference internal" href="#">8.2. PSA Crypto library</a><ul>
131<li class="toctree-l3"><a class="reference internal" href="#api-version">8.2.1. API version</a></li>
132<li class="toctree-l3"><a class="reference internal" href="#library-initialization">8.2.2. Library initialization</a></li>
133</ul>
134</li>
135</ul>
136</li>
137<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
138<li class="toctree-l1"><a class="reference internal" href="../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>