Blame - docs/html/general.html - mirror/mbed-crypto

blob: 0a76f6dc8f32cb2e628e8b7c8f4ed2dd02e8eed0 [file] [log] [blame]

Gilles Peskine	06995ff	2019-05-21 19:50:19 +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="X-UA-Compatible" content="IE=Edge" />
				8	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
				9	<title>Introduction — psa_crypto_api 1.0 beta3 documentation</title>
				10	<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
				11	<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
				12	<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
				13	<script type="text/javascript" src="_static/jquery.js"></script>
				14	<script type="text/javascript" src="_static/underscore.js"></script>
				15	<script type="text/javascript" src="_static/doctools.js"></script>
				16	<script type="text/javascript" src="_static/language_data.js"></script>
				17	<link rel="index" title="Index" href="genindex.html" />
				18	<link rel="search" title="Search" href="search.html" />
				19	<link rel="next" title="Implementation-specific definitions" href="from_doxygen.html" />
				20	<link rel="prev" title="PSA Cryptography API Specification" href="index.html" />
				21
				22	<link rel="stylesheet" href="_static/custom.css" type="text/css" />
				23
				24
				25	<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
				26
				27	</head><body>
				28
				29
				30	<div class="document">
				31	<div class="documentwrapper">
				32	<div class="bodywrapper">
				33
				34
				35	<div class="body" role="main">
				36
				37	<div class="section" id="introduction">
				38	<h1>Introduction</h1>
				39	<p>Arm’s Platform Security Architecture (PSA) is a holistic set of threat
				40	models, security analyses, hardware and firmware architecture
				41	specifications, and an open source firmware reference implementation.
				42	PSA provides a recipe, based on industry best practice, that allows
				43	security to be consistently designed in, at both a hardware and firmware
				44	level.</p>
				45	<p>The PSA Cryptographic API (Crypto API) described in this document is an
				46	important PSA component that provides an interface to modern
				47	cryptographic primitives on resource-constrained devices. The interface
				48	is user-friendly, while still providing access to the primitives used in
				49	modern cryptography. It does not require that the user have access to
				50	the key material. Instead, it uses opaque key handles.</p>
				51	<p>This document is part of the PSA family of specifications. It defines an
				52	interface for cryptographic services, including cryptography primitives
				53	and a key storage functionality.</p>
				54	<p>This document includes:</p>
				55	<ul class="simple">
				56	<li>A <a class="reference external" href="#design-goals">rationale</a> for the design.</li>
				57	<li>A <a class="reference external" href="#functionality-overview">high-level overview of the
				58	functionality</a> provided by the interface.</li>
				59	<li>A <a class="reference external" href="#sample-architectures">description of typical architectures</a> of
				60	implementations for this specification.</li>
				61	<li>General considerations <a class="reference external" href="#implementation-considerations">for
				62	implementers</a> of this
				63	specification and <a class="reference external" href="#usage-considerations">for applications</a> that
				64	use the interface defined in this specification.</li>
				65	<li>A detailed definition of the API.</li>
				66	</ul>
				67	<p>Companion documents will define <em>profiles</em> for this specification. A
				68	profile is a minimum mandatory subset of the interface that a compliant
				69	implementation must provide.</p>
				70	</div>
				71	<div class="section" id="design-goals">
				72	<h1>Design goals</h1>
				73	<div class="section" id="suitable-for-constrained-devices">
				74	<h2>Suitable for constrained devices</h2>
				75	<p>The interface is suitable for a vast range of devices: from
				76	special-purpose cryptographic processors that process data with a
				77	built-in key, to constrained devices running custom application code,
				78	such as microcontrollers, and multi-application devices, such as
				79	servers. Consequentially, the interface is scalable and modular.</p>
				80	<ul class="simple">
				81	<li><em>Scalable</em>: you shouldn’t pay for functionality that you don’t need.</li>
				82	<li><em>Modular</em>: larger devices implement larger subsets of the same
				83	interface, rather than different interfaces.</li>
				84	</ul>
				85	<p>Because this specification is suitable for very constrained devices,
				86	including those where memory is very limited, all operations on
				87	unbounded amounts of data allow <em>multipart</em> processing, as long as the
				88	calculations on the data are performed in a streaming manner. This means
				89	that the application does not need to store the whole message in memory
				90	at one time.</p>
				91	<p>Memory outside the keystore boundary is managed by the application. An
				92	implementation of the interface is not required to retain any state
				93	between function calls, apart from the content of the keystore and other
				94	data that must be kept inside the keystore security boundary.</p>
				95	<p>The interface does not expose the representation of keys and
				96	intermediate data, except when required for interchange. This allows
				97	each implementation to choose optimal data representations.
				98	Implementations with multiple components are also free to choose which
				99	memory area to use for internal data.</p>
				100	</div>
				101	<div class="section" id="a-keystore-interface">
				102	<h2>A keystore interface</h2>
				103	<p>The specification allows cryptographic operations to be performed on a
				104	key to which the application does not have direct access. Except where
				105	required for interchange, applications access all keys indirectly, by a
				106	handle. The key material corresponding to that handle can reside inside
				107	a security boundary that prevents it from being extracted, except as
				108	permitted by a policy that is defined when the key is created.</p>
				109	</div>
				110	<div class="section" id="optional-isolation">
				111	<h2>Optional isolation</h2>
				112	<p>Implementations can isolate the cryptoprocessor from the calling
				113	application, and can further isolate multiple calling applications. The
				114	interface allows the implementation to be separated between a frontend
				115	and a backend. In an isolated implementation, the frontend is the part
				116	of the implementation that is located in the same isolation boundary as
				117	the application, which the application accesses by function calls. The
				118	backend is the part of the implementation that is located in a different
				119	environment, which is protected from the frontend. Various technologies
				120	can provide protection, for example:</p>
				121	<ul class="simple">
				122	<li>Process isolation in an operating system.</li>
				123	<li>Partition isolation, either with a virtual machine or a partition
				124	manager.</li>
				125	<li>Physical separation between devices.</li>
				126	</ul>
				127	<p>Communication between the frontend and backend is beyond the scope of
				128	this specification.</p>
				129	<p>In an isolated implementation, the backend can serve more than one
				130	implementation instance. In this case, a single backend communicates
				131	with multiple instances of the frontend. The backend must enforce
				132	<strong>caller isolation</strong>: it must ensure that assets of one frontend are not
				133	visible to any other frontend. How callers are identified is beyond the
				134	scope of this specification. An implementation that provides caller
				135	isolation must document how callers are identified. An implementation
				136	that provides isolation must document any implementation-specific
				137	extension of the API that enables frontend instances to share data in
				138	any form.</p>
				139	<p>In summary, there are three types of implementations:</p>
				140	<ul class="simple">
				141	<li>No isolation: there is no security boundary between the application
				142	and the cryptoprocessor. For example, a statically or dynamically
				143	linked library is an implementation with no isolation.</li>
				144	<li>Cryptoprocessor isolation: there is a security boundary between the
				145	application and the cryptoprocessor, but the cryptoprocessor does not
				146	communicate with other applications. For example, a cryptoprocessor
				147	chip that is a companion to an application processor is an
				148	implementation with cryptoprocessor isolation.</li>
				149	<li>Caller isolation: there are multiple application instances, with a
				150	security boundary between the application instances among themselves,
				151	as well as between the cryptoprocessor and the application instances.
				152	For example, a cryptography service in a multiprocess environment is
				153	an implementation with caller and cryptoprocessor isolation.</li>
				154	</ul>
				155	</div>
				156	<div class="section" id="choice-of-algorithms">
				157	<h2>Choice of algorithms</h2>
				158	<p>The specification defines a low-level cryptographic interface, where the
				159	caller explicitly chooses which algorithm and which security parameters
				160	they use. This is necessary to implement protocols that are inescapable
				161	in various use cases. The design of the interface enables applications
				162	to implement widely-used protocols and data exchange formats, as well as
				163	custom ones.</p>
				164	<p>As a consequence, all cryptographic functionality operates according to
				165	the precise algorithm specified by the caller. However, this does not
				166	apply to device-internal functionality, which does not involve any form
				167	of interoperability, such as random number generation. The specification
				168	does not include generic higher-level interfaces, where the
				169	implementation chooses the best algorithm for a purpose. However,
				170	higher-level libraries can be built on top of the PSA Crypto API.</p>
				171	<p>Another consequence is that the specification permits the use of
				172	algorithms, key sizes and other parameters that, while known to be
				173	insecure, may be necessary to support legacy protocols or legacy data.
				174	Where major weaknesses are known, the algorithm description give
				175	applicable warnings. However, the lack of a warning does not and cannot
				176	indicate that an algorithm is secure in all circumstances. Application
				177	developers should research the security of the algorithms that they plan
				178	to use to determine if the algorithms meet their requirements.</p>
				179	<p>The interface facilitates algorithm agility. As a consequence,
				180	cryptographic primitives are presented through generic functions with a
				181	parameter indicating the specific choice of algorithm. For example,
				182	there is a single function to calculate a message digest, which takes a
				183	parameter that identifies the specific hash algorithm.</p>
				184	</div>
				185	<div class="section" id="ease-of-use">
				186	<h2>Ease of use</h2>
				187	<p>The interface is designed to be as user-friendly as possible, given the
				188	aforementioned constraints on suitability for various types of devices
				189	and on the freedom to choose algorithms.</p>
				190	<p>In particular, the code flows are designed to reduce the chance of
				191	dangerous misuse. The interface makes it harder to misuse than to use
				192	correctly, and typical mistakes result in test failures, rather than
				193	subtle security issues. Implementations avoid leaking data when a
				194	function is called with invalid parameters, to the extent allowed by the
				195	C language and by implementation size constraints.</p>
				196	</div>
				197	<div class="section" id="example-use-cases">
				198	<h2>Example use cases</h2>
				199	<p>This section lists some of the use cases that were considered while
				200	designing this API. This list is not exhaustive, nor are all
				201	implementations required to support all use cases.</p>
				202	<div class="section" id="network-security-tls">
				203	<h3>Network Security (TLS)</h3>
				204	<p>The API provides everything needed to establish TLS connections on the
				205	device side: asymmetric key management inside a key store, symmetric
				206	ciphers, MAC, HMAC, message digests, and AEAD.</p>
				207	</div>
				208	<div class="section" id="secure-storage">
				209	<h3>Secure Storage</h3>
				210	<p>The API provides all primitives related to storage encryption, block or
				211	file-based, with master encryption keys stored inside a key store.</p>
				212	</div>
				213	<div class="section" id="network-credentials">
				214	<h3>Network Credentials</h3>
				215	<p>The API provides network credential management inside a key store, for
				216	example, for X.509-based authentication or pre-shared keys on enterprise
				217	networks.</p>
				218	</div>
				219	<div class="section" id="device-pairing">
				220	<h3>Device Pairing</h3>
				221	<p>The API provides support for key agreement protocols that are often used
				222	for secure pairing of devices over wireless channels. For example, the
				223	pairing of an NFC token or a Bluetooth device could make use of key
				224	agreement protocols upon first use.</p>
				225	</div>
				226	<div class="section" id="secure-boot">
				227	<h3>Secure Boot</h3>
				228	<p>The API provides primitives for use during firmware integrity and
				229	authenticity validation, during a secure or trusted boot process.</p>
				230	</div>
				231	<div class="section" id="attestation">
				232	<h3>Attestation</h3>
				233	<p>The API provides primitives used in attestation activities. Attestation
				234	is the ability for a device to sign an array of bytes with a device
				235	private key and return the result to the caller. There are several use
				236	cases: from attestation of the device state to the ability to generate a
				237	key pair and prove that it has been generated inside a secure key store.
				238	The API provides access to the algorithms commonly used for attestation.</p>
				239	</div>
				240	<div class="section" id="factory-provisioning">
				241	<h3>Factory Provisioning</h3>
				242	<p>Most IoT devices receive a unique identity during the factory
				243	provisioning process, or once deployed to the field. This API provides
				244	the APIs necessary for populating a device with keys that represent that
				245	identity.</p>
				246	</div>
				247	</div>
				248	</div>
				249	<div class="section" id="functionality-overview">
				250	<h1>Functionality overview</h1>
				251	<p>This section provides a high-level overview of the functionality
				252	provided by the interface defined in this specification. Refer to the
				253	API definition for a detailed description.</p>
				254	<p>Due to the modularity of the interface, almost every part of the library
				255	is optional. The only mandatory function is <code class="docutils literal notranslate"><span class="pre">psa_crypto_init</span></code>.</p>
				256	<div class="section" id="library-management">
				257	<h2>Library management</h2>
				258	<p>Before any use, applications must call <code class="docutils literal notranslate"><span class="pre">psa_crypto_init</span></code> to initialize
				259	the library.</p>
				260	</div>
				261	<div class="section" id="key-management">
				262	<h2>Key management</h2>
				263	<p>Applications always access keys via a handle. This allows keys to be
				264	non-extractable, that is, an application can perform operations using a
				265	key without having access to the key material. Non-extractable keys are
				266	bound to the device, can be rate-limited and can have their usage
				267	restricted by policies.</p>
				268	<p>Each key has a set of attributes that describe the key and the policy
				269	for using the key. A <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> object contains all of the
				270	attributes, which is used when creating a key and when querying key
				271	attibutes.</p>
				272	<p>Each key has a <em>lifetime</em> that determines when the key material is
				273	destroyed. There are two types of lifetimes:
				274	<a class="reference external" href="#volatile-keys">volatile</a> and <a class="reference external" href="#persistent-keys">persistent</a>.</p>
				275	<div class="section" id="volatile-keys">
				276	<h3>Volatile keys</h3>
				277	<p>A <em>volatile</em> key is destroyed as soon as the application closes the
				278	handle to the key. When the application terminates, it conceptually
				279	closes all of its key handles. Conceptually, a volatile key is stored in
				280	RAM. Volatile keys have the lifetime <code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code>.</p>
				281	<p>To create a volatile key:</p>
				282	<ol class="arabic simple">
				283	<li>Populate a <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> object with the key’s type, size,
				284	policy and other attributes.</li>
				285	<li>Create the key with <code class="docutils literal notranslate"><span class="pre">psa_import_key</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_generate_key</span></code>,
				286	<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_copy_key</span></code>.</li>
				287	</ol>
				288	<p>To destroy a volatile key, call <code class="docutils literal notranslate"><span class="pre">psa_close_key</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code>
				289	(these functions are equivalent when called on a volatile key).</p>
				290	</div>
				291	<div class="section" id="persistent-keys">
				292	<h3>Persistent keys</h3>
				293	<p>A <em>persistent</em> key exists until it explicitly destroyed with
				294	<code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code> or until it is wiped by the reset or destruction of
				295	the device.</p>
				296	<p>Each persistent key has a key identifier, which acts as a name for the
				297	key. Within an application, the key identifier corresponds to a single
				298	key. The application specifies the key identifier when the key is
				299	created, and uses the key identifier to obtain a handle to a persistent
				300	key that has already been created. If the implementation provides
				301	<a class="reference external" href="#optional-isolation">caller isolation</a>, then key identifiers are
				302	local to each application: the same key identifier in two applications
				303	corresponds to different keys.</p>
				304	<p>Persistent keys may be stored in different storage areas; this is
				305	indicated through different lifetime values. This specification defines
				306	a single lifetime value <code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code> which
				307	corresponds to a default storage area. Implementations may define
				308	alternative lifetime values corresponding to different storage areas
				309	with different retention policies, or to secure elements with different
				310	security characteristics.</p>
				311	<p>To create a persistent key:</p>
				312	<ol class="arabic simple">
				313	<li>Populate a <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> object with the key’s type, size,
				314	policy and other attributes.</li>
				315	<li>In the attributes object, set the desired lifetime and persistent
				316	identifier for the key.</li>
				317	<li>Create the key with <code class="docutils literal notranslate"><span class="pre">psa_import_key</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_generate_key</span></code>,
				318	<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_copy_key</span></code>.</li>
				319	</ol>
				320	<p>To release memory resources associated with a key but keep the key in
				321	storage, call <code class="docutils literal notranslate"><span class="pre">psa_close_key</span></code>. To access an existing persistent key,
				322	call <code class="docutils literal notranslate"><span class="pre">psa_open_key</span></code> with the same key identifier used when creating
				323	the key.</p>
				324	<p>To destroy a persistent key, open it (if it isn’t already open) and call
				325	<code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code>.</p>
				326	<p>The key lifetime and identifier are set when the key is created and
				327	cannot be changed without destroying the key first. If the original key
				328	permits copying, then the application can specify a different lifetime
				329	for the copy of the key.</p>
				330	</div>
				331	<div class="section" id="recommendations-of-minimum-standards-for-key-management">
				332	<h3>Recommendations of minimum standards for key management</h3>
				333	<p>Most implementations provide the function <code class="docutils literal notranslate"><span class="pre">psa_import_key</span></code>. The only
				334	exceptions are implementations that only give access to a key or keys
				335	that are provisioned by proprietary means, and do not allow the main
				336	application to use its own cryptographic material.</p>
				337	<p>Most implementations provide <code class="docutils literal notranslate"><span class="pre">psa_get_key_attributes</span></code> and the
				338	<code class="docutils literal notranslate"><span class="pre">psa_get_key_xxx</span></code> accessor functions, as they are easy to implement,
				339	and it is difficult to write applications and to diagnose issues without
				340	being able to check the metadata.</p>
				341	<p>Most implementations also provide <code class="docutils literal notranslate"><span class="pre">psa_export_public_key</span></code> if they
				342	support any asymmetric algorithm, since public-key cryptography often
				343	requires the delivery of a public key that is associated with a
				344	protected private key.</p>
				345	<p>Most implementations provide <code class="docutils literal notranslate"><span class="pre">psa_export_key</span></code>. However, highly
				346	constrained implementations that are designed to work only with
				347	short-term keys (no non-volatile storage), or only with long-term
				348	non-extractable keys, may omit this function.</p>
				349	</div>
				350	</div>
				351	<div class="section" id="usage-policies">
				352	<h2>Usage policies</h2>
				353	<p>All keys have an associated policy that regulates which operations are
				354	permitted on the key. Each key policy is a set of usage flags and a
				355	specific algorithm that is permitted with the key. The policy is part of
				356	the key attributes that are managed by a <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code>
				357	object.</p>
				358	<p>The usage flags are encoded in a bitmask, which has the type
				359	<code class="docutils literal notranslate"><span class="pre">psa_key_usage_t</span></code>. Three kinds of usage flag can be specified: * The
				360	extractable flag <code class="docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code> determines whether the key
				361	material can be extracted. * The copyable flag <code class="docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_COPY</span></code>
				362	determines whether the key material can be copied into a new key, which
				363	can have a different lifetime or a more restrictive policy. * The usage
				364	flags <code class="docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code>, <code class="docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_SIGN</span></code>, and so on
				365	determine whether the corresponding operation is permitted on the key.</p>
				366	<p>In addition to the usage bitmask, a policy specifies which algorithm is
				367	permitted with the key. This specification only defines policies that
				368	restrict keys to a single algorithm, which is in keeping with common
				369	practice and with security good practice.</p>
				370	<p>A highly constrained implementation may not be able to support all the
				371	policies that can be expressed through this interface. If an
				372	implementation cannot create a key with the required policy, it must
				373	return an appropriate error code when the key is created.</p>
				374	</div>
				375	<div class="section" id="symmetric-cryptography">
				376	<h2>Symmetric cryptography</h2>
				377	<p>This specification defines interfaces for message digests (hash
				378	functions), MAC (message authentication codes), symmetric ciphers and
				379	authenticated encryption with associated data (AEAD). For each type of
				380	primitive, the API includes two standalone functions (compute and
				381	verify, or encrypt and decrypt) as well as a series of functions that
				382	permit <a class="reference external" href="#multipart-operations">multipart operations</a>.</p>
				383	<p>The standalone functions are:</p>
				384	<ul class="simple">
				385	<li><code class="docutils literal notranslate"><span class="pre">psa_hash_compute</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_hash_compare</span></code> to calculate the hash
				386	of a message or compare the hash of a message with a reference value.</li>
				387	<li><code class="docutils literal notranslate"><span class="pre">psa_mac_compute</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_mac_verify</span></code> to calculate the MAC of a
				388	message of compare the MAC with a reference value.</li>
				389	<li><code class="docutils literal notranslate"><span class="pre">psa_cipher_encrypt</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_cipher_decrypt</span></code> to encrypt or
				390	decrypt a message using an unauthenticated symmetric cipher. The
				391	encryption function generates a random IV; to use a deterministic IV
				392	(which is not secure in general, but can be secure in some conditions
				393	that depend on the algorithm), use the multipart API.</li>
				394	<li><code class="docutils literal notranslate"><span class="pre">psa_aead_encrypt</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_aead_decrypt</span></code> to encrypt/decrypt and
				395	authenticate a message using an AEAD algorithm. These functions
				396	follow the interface recommended by RFC 5116.</li>
				397	</ul>
				398	<div class="section" id="multipart-operations">
				399	<h3>Multipart operations</h3>
				400	<p>The API provides a multipart interface to hash, MAC, symmetric cipher
				401	and AEAD primitives. These interfaces process messages one chunk at a
				402	time, with the size of chunks determined by the caller. This allows the
				403	processing of messages that cannot be assembled in memory. To perform a
				404	multipart operation:</p>
				405	<ol class="arabic simple">
				406	<li>Allocate an operation object of the appropriate type. You can use any
				407	allocation strategy: stack, heap, static, etc.</li>
				408	<li>Initialize the operation object by one of the following methods:<ul>
				409	<li>Set it to all-bits-zero.</li>
				410	<li>Initialize it to logical zero.</li>
				411	<li>Assign the value of the associated macro <code class="docutils literal notranslate"><span class="pre">PSA_xxx_INIT</span></code>.</li>
				412	<li>Assign the result of calling the associated function
				413	<code class="docutils literal notranslate"><span class="pre">psa_xxx_init</span></code>.</li>
				414	</ul>
				415	</li>
				416	<li>Specify a key for the operation using the associated setup function:
				417	<code class="docutils literal notranslate"><span class="pre">psa_hash_setup</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_mac_sign_setup</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_mac_verify_setup</span></code>,
				418	<code class="docutils literal notranslate"><span class="pre">psa_cipher_encrypt_setup</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_cipher_decrypt_setup</span></code>,
				419	<code class="docutils literal notranslate"><span class="pre">psa_aead_encrypt_setup</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_aead_decrypt_setup</span></code>.</li>
				420	<li>Provide additional parameters:<ul>
				421	<li>When encrypting data, generate or set an initialization vector
				422	(IV), nonce, or similar initial value such as an initial counter
				423	value.</li>
				424	<li>When decrypting, set the IV or nonce.</li>
				425	<li>For a symmetric cipher, to generate a random IV, which is
				426	recommended in most protocols, call <code class="docutils literal notranslate"><span class="pre">psa_cipher_generate_iv</span></code>. To
				427	set the IV, call <code class="docutils literal notranslate"><span class="pre">psa_cipher_set_iv</span></code>.</li>
				428	<li>For AEAD, call <code class="docutils literal notranslate"><span class="pre">psa_aead_generate_nonce</span></code> or
				429	<code class="docutils literal notranslate"><span class="pre">psa_aead_set_nonce</span></code>.</li>
				430	</ul>
				431	</li>
				432	<li>Call the associated update function on successive chunks of the
				433	message: <code class="docutils literal notranslate"><span class="pre">psa_hash_update</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_mac_update</span></code>,
				434	<code class="docutils literal notranslate"><span class="pre">psa_cipher_update</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_aead_update_ad</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_aead_update</span></code>.</li>
				435	<li>At the end of the message, call the applicable finishing function.
				436	There are three kinds of finishing function, depending on what to do
				437	with the verification tag.<ul>
				438	<li>Unauthenticated encryption and decryption does not involve a
				439	verification tag. Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_finish</span></code>.</li>
				440	<li>To calculate the digest or MAC or authentication tag of a message,
				441	call the associated function to calculate and output the
				442	verification tag: <code class="docutils literal notranslate"><span class="pre">psa_hash_finish</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_mac_sign_finish</span></code> or
				443	<code class="docutils literal notranslate"><span class="pre">psa_aead_finish</span></code>.</li>
				444	<li>To verify the digest or MAC of a message against a reference value
				445	or to verify the authentication tag at the end of AEAD decryption,
				446	call the associated function to compare the verification tag with
				447	the reference value: <code class="docutils literal notranslate"><span class="pre">psa_hash_verify</span></code>,
				448	<code class="docutils literal notranslate"><span class="pre">psa_mac_verify_finish</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_aead_verify</span></code>.</li>
				449	</ul>
				450	</li>
				451	</ol>
				452	<p>Calling the setup function allocates resources inside the
				453	implementation. These resources are freed when calling the associated
				454	finishing function. In addition, each family of functions defines a
				455	function <code class="docutils literal notranslate"><span class="pre">psa_xxx_abort</span></code>, which can be called at any time to free the
				456	resources associated with an operation.</p>
				457	</div>
				458	<div class="section" id="authenticated-encryption">
				459	<h3>Authenticated encryption</h3>
				460	<p>Having a multipart interface to authenticated encryption raises specific
				461	issues.</p>
				462	<p>Multipart authenticated decryption produces partial results that are not
				463	authenticated. Applications must not use or expose partial results of
				464	authenticated decryption until <code class="docutils literal notranslate"><span class="pre">psa_aead_verify</span></code> has returned a
				465	success status, and must destroy all partial results without revealing
				466	them if <code class="docutils literal notranslate"><span class="pre">psa_aead_verify</span></code> returns a failure status. Revealing partial
				467	results (directly, or indirectly through the application’s behavior) can
				468	compromise the confidentiality of all inputs that are encrypted with the
				469	same key.</p>
				470	<p>For encryption, some common algorithms cannot be processed in a
				471	streaming fashion. For SIV mode, the whole plaintext must be known
				472	before the encryption can start; the multipart AEAD API is not meant to
				473	be usable with SIV mode. For CCM mode, the length of the plaintext must
				474	be known before the encryption can start; the application can call the
				475	function <code class="docutils literal notranslate"><span class="pre">psa_aead_set_lengths</span></code> to provide these lengths before
				476	providing input.</p>
				477	</div>
				478	</div>
				479	<div class="section" id="key-derivation">
				480	<h2>Key derivation</h2>
				481	<p>The specification defines a mechanism for key derivation that allows the
				482	output of the derivation to be split into multiple keys, as well as
				483	non-key outputs.</p>
				484	<p>In an implementation with <a class="reference external" href="#optional-isolation">isolation</a>, the
				485	intermediate state of the key derivation is not visible to the caller,
				486	and if an output of the derivation is a non-exportable key, then this
				487	output cannot be recovered outside the isolation boundary.</p>
				488	<div class="section" id="key-derivation-operations">
				489	<h3>Key derivation operations</h3>
				490	<p>A key derivation operation encodes a deterministic method to generate a
				491	finite stream of bytes. This data stream is computed by the
				492	cryptoprocessor and extracted in chunks. If two key derivation
				493	operations are constructed with the same parameters, then they should
				494	produce the same outputs.</p>
				495	<p>Some example uses of key derivation operations are:</p>
				496	<ul class="simple">
				497	<li>A key derivation function: initialized with a secret, a salt and
				498	other parameters.</li>
				499	<li>A key agreement function: initialized with a public key (peer key), a
				500	key pair (own key) and other parameters.</li>
				501	</ul>
				502	<p>Applications use the <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_operation_t</span></code> type to create
				503	key derivation operations.</p>
				504	<p>The lifecycle of a key derivation operation is as follows:</p>
				505	<ol class="arabic simple">
				506	<li>Setup: construct a <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_operation_t</span></code> object, and set
				507	its parameters and inputs. The setup phase determines the key
				508	derivation operation’s capacity, which is the maximum number of bytes
				509	that can be output from this key derivation operation.</li>
				510	<li>Output: read bytes from the stream defined by the key derivation
				511	operation. This can be done any number of times, until the stream is
				512	exhausted when its capacity has been reached. Each output step can
				513	either be used to populate a key object
				514	(<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code>), or to read some bytes and
				515	extract them as cleartext (<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_bytes</span></code>).</li>
				516	<li>Terminate: clear the key derivation operation and release associated
				517	resources (<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_abort</span></code>).</li>
				518	</ol>
				519	<p>A key derivation operation cannot be rewound. Once a part of the stream
				520	has been output, it cannot be output again. This ensures that the same
				521	part of the output will not be used for different purposes.</p>
				522	</div>
				523	<div class="section" id="key-derivation-function">
				524	<h3>Key derivation function</h3>
				525	<p>This specification defines functions to set up a key derivation. A key
				526	derivation consists of two parts:</p>
				527	<ol class="arabic simple">
				528	<li>Input collection. This is sometimes known as <em>extraction</em>: the
				529	operation “extracts” information from the inputs to generate a
				530	pseudorandom intermediate secret value.</li>
				531	<li>Output generation. This is sometimes known as <em>expansion</em>: the
				532	operation “expands” the intermediate secret value to the desired
				533	output length.</li>
				534	</ol>
				535	<p>To perform a key derivation:</p>
				536	<ol class="arabic simple">
				537	<li>Initialize a <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_operation_t</span></code> object to zero or to
				538	<code class="docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_OPERAITON_INIT</span></code>.</li>
				539	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_setup</span></code> to select a key derivation
				540	algorithm.</li>
				541	<li>Call the functions <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_input_bytes</span></code> and
				542	<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_input_key</span></code>, or
				543	<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_key_agreement</span></code> to provide the inputs to the key
				544	derivation algorithm. Many key derivation algorithms take multiple
				545	inputs; the “step” parameter to these functions indicates which input
				546	is being passed. The documentation for each key derivation algorithm
				547	describes the expected inputs for that algorithm.</li>
				548	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code> to create a derived key, or
				549	<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_bytes</span></code> to export the derived data. These
				550	functions may be called multiple times to read successive output from
				551	the key derivation.</li>
				552	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_abort</span></code> to release the key derivation
				553	operation memory.</li>
				554	</ol>
				555	<p>Here is an example of a use case where a master key is used to generate
				556	both a message encryption key and an IV for the encryption, and the
				557	derived key and IV are then used to encrypt a message.</p>
				558	<ol class="arabic simple">
				559	<li>Derive the message encryption material from the master key.<ol class="arabic">
				560	<li>Initialize a <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_operation_t</span></code> object to zero or
				561	to <code class="docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code>.</li>
				562	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_setup</span></code> with <code class="docutils literal notranslate"><span class="pre">PSA_ALG_HKDF</span></code> as the
				563	algorithm.</li>
				564	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_input_key</span></code> with the step
				565	<code class="docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> and the master key.</li>
				566	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_input_bytes</span></code> with the step
				567	<code class="docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code> and a public value that uniquely
				568	identifies the message.</li>
				569	<li>Populate a <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> object with the derived
				570	message encryption key’s attributes.</li>
				571	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code> to create the derived
				572	message key.</li>
				573	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_bytes</span></code> to generate the derived
				574	IV.</li>
				575	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_abort</span></code> to release the key derivation
				576	operation memory.</li>
				577	</ol>
				578	</li>
				579	<li>Encrypt the message with the derived material.<ol class="arabic">
				580	<li>Initialize a <code class="docutils literal notranslate"><span class="pre">psa_cipher_operation_t</span></code> object to zero or to
				581	<code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code>.</li>
				582	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_encrypt_setup</span></code> with the derived message
				583	encryption key.</li>
				584	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_set_iv</span></code> using the derived IV retrieved above.</li>
				585	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_update</span></code> one or more times to encrypt the
				586	message.</li>
				587	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_finish</span></code> at the end of the message.</li>
				588	</ol>
				589	</li>
				590	<li>Call <code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code> to clear the generated key.</li>
				591	</ol>
				592	</div>
				593	</div>
				594	<div class="section" id="asymmetric-cryptography">
				595	<h2>Asymmetric cryptography</h2>
				596	<p>The asymmetric cryptography part of this interface defines functions for
				597	asymmetric encryption, asymmetric signature and two-way key agreement.</p>
				598	<div class="section" id="asymmetric-encryption">
				599	<h3>Asymmetric encryption</h3>
				600	<p>Asymmetric encryption is provided through the functions
				601	<code class="docutils literal notranslate"><span class="pre">psa_asymmetric_encrypt</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_decrypt</span></code>.</p>
				602	</div>
				603	<div class="section" id="hash-and-sign">
				604	<h3>Hash-and-sign</h3>
				605	<p>The signature and verification functions <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_sign</span></code> and
				606	<code class="docutils literal notranslate"><span class="pre">psa_asymmetric_verify</span></code> take a hash as one of their inputs. This hash
				607	should be calculated with <code class="docutils literal notranslate"><span class="pre">psa_hash_setup</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_hash_update</span></code> and
				608	<code class="docutils literal notranslate"><span class="pre">psa_hash_finish</span></code> before calling <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_sign</span></code> or
				609	<code class="docutils literal notranslate"><span class="pre">psa_asymmetric_verify</span></code>. To determine which hash algorithm to use,
				610	call the macro <code class="docutils literal notranslate"><span class="pre">PSA_ALG_SIGN_GET_HASH</span></code> on the corresponding signature
				611	algorithm.</p>
				612	</div>
				613	<div class="section" id="key-agreement">
				614	<h3>Key agreement</h3>
				615	<p>This specification defines two functions for a Diffie-Hellman-style key
				616	agreement where each party combines its own private key with the peer’s
				617	public key.</p>
				618	<p>The recommended approach is to use a <a class="reference external" href="#key-derivation">key derivation
				619	operation</a> with the
				620	<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_key_agreement</span></code> input function, which calculates a
				621	shared secret for the key derivation function.</p>
				622	<p>In case an application needs direct access to the shared secret, it can
				623	call <code class="docutils literal notranslate"><span class="pre">psa_raw_key_agreement</span></code> instead. Note that in general the shared
				624	secret is not directly suitable for use as a key because it is biased.</p>
				625	</div>
				626	</div>
				627	<div class="section" id="randomness-and-key-generation">
				628	<h2>Randomness and key generation</h2>
				629	<p>We strongly recommended that implementations include a random generator,
				630	consisting of a cryptographically secure pseudo-random generator
				631	(CSPRNG), which is adequately seeded with a cryptographic-quality
				632	hardware entropy source, commonly referred to as a true random number
				633	generator (TRNG). Constrained implementations may omit the random
				634	generation functionality if they do not implement any algorithm that
				635	requires randomness internally, and they do not provide a key generation
				636	functionality. For example, a special-purpose component for signature
				637	verification can omit this.</p>
				638	<p>Applications should use <code class="docutils literal notranslate"><span class="pre">psa_generate_key</span></code>,
				639	<code class="docutils literal notranslate"><span class="pre">psa_encrypt_generate_iv</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_aead_generate_iv</span></code> to generate
				640	suitably-formatted random data, as applicable. In addition, the API
				641	includes a function <code class="docutils literal notranslate"><span class="pre">psa_generate_random</span></code> to generate and extract
				642	arbitrary random data.</p>
				643	</div>
				644	<div class="section" id="future-additions">
				645	<h2>Future additions</h2>
				646	<p>We plan to cover the following features in future drafts and editions of
				647	this specification:</p>
				648	<ul class="simple">
				649	<li>Single-shot functions for symmetric operations.</li>
				650	<li>Multi-part operations for hybrid cryptography. For example, this
				651	includes hash-and-sign for EdDSA, and hybrid encryption for ECIES.</li>
				652	<li>Key exchange and a more general interface to key derivation. This
				653	would enable an application to derive a non-extractable session key
				654	from non-extractable secrets, without leaking the intermediate
				655	material.</li>
				656	<li>Key wrapping mechanisms to extract and import keys in a protected
				657	form (encrypted and authenticated).</li>
				658	<li>Key discovery mechanisms. This would enable an application to locate
				659	a key by its name or attributes.</li>
				660	<li>Implementation capability description. This would enable an
				661	application to determine the algorithms, key types and storage
				662	lifetimes that the implementation provides.</li>
				663	<li>An ownership and access control mechanism allowing a multi-client
				664	implementation to have privileged clients that are able to manage
				665	keys of other clients.</li>
				666	</ul>
				667	</div>
				668	</div>
				669	<div class="section" id="sample-architectures">
				670	<h1>Sample architectures</h1>
				671	<p>This section describes some example architectures that can be used for
				672	implementations of the interface described in this specification. This
				673	list is not exhaustive and the section is entirely non-normative.</p>
				674	<div class="section" id="single-partition-architecture">
				675	<h2>Single-partition architecture</h2>
				676	<p>In this architecture, there is no security boundary inside the system.
				677	The application code may access all the system memory, including the
				678	memory used by the cryptographic services described in this
				679	specification. Thus, the architecture provides <a class="reference external" href="#optional-isolation">no
				680	isolation</a>.</p>
				681	<p>This architecture does not conform to the Arm <em>Platform Security
				682	Architecture Security Model</em>. However, it may be useful for providing
				683	cryptographic services that use the same interface, even on devices that
				684	cannot support any security boundary. So, while this architecture is not
				685	the primary design goal of the API defined in the present specification,
				686	it is supported.</p>
				687	<p>The functions in this specification simply execute the underlying
				688	algorithmic code. Security checks can be kept to a minimum, since the
				689	cryptoprocessor cannot defend against a malicious application. Key
				690	import and export copy data inside the same memory space.</p>
				691	<p>This architecture also describes a subset of some larger systems, where
				692	the cryptographic services are implemented inside a high-security
				693	partition, separate from the code of the main application, though it
				694	shares this high-security partition with other platform security
				695	services.</p>
				696	</div>
				697	<div class="section" id="cryptographic-token-and-single-application-processor">
				698	<h2>Cryptographic token and single-application processor</h2>
				699	<p>This system is composed of two partitions: one is a cryptoprocessor and
				700	the other partition runs an application. There is a security boundary
				701	between the two partitions, so that the application cannot access the
				702	cryptoprocessor, except through its public interface. Thus, the
				703	architecture provides <a class="reference external" href="#optional-isolation">cryptoprocessor
				704	isolation</a>. The cryptoprocessor has some
				705	nonvolatile storage, a TRNG, and possibly, some cryptographic
				706	accelerators.</p>
				707	<p>There are a number of potential physical realizations: the
				708	cryptoprocessor may be a separate chip, a separate processor on the same
				709	chip, or a logical partition using a combination of hardware and
				710	software to provide the isolation. These realizations are functionally
				711	equivalent in terms of the offered software interface, but they would
				712	typically offer different levels of security guarantees.</p>
				713	<p>The PSA crypto API in the application processor consists of a thin layer
				714	of code that translates function calls to remote procedure calls in the
				715	cryptoprocessor. All cryptographic computations are, therefore,
				716	performed inside the cryptoprocessor. Non-volatile keys are stored
				717	inside the cryptoprocessor.</p>
				718	</div>
				719	<div class="section" id="cryptoprocessor-with-no-key-storage">
				720	<h2>Cryptoprocessor with no key storage</h2>
				721	<p>As in the <a class="reference external" href="#cryptographic-token-and-single-application-processor">previous
				722	example</a>, this
				723	system is also composed of two partitions separated by a security
				724	boundary. Thus, this architecture also provides <a class="reference external" href="#optional-isolation">cryptoprocessor
				725	isolation</a>. However, unlike the previous
				726	architecture, in this system, the cryptoprocessor does not have any
				727	secure, persistent storage that could be used to store application keys.</p>
				728	<p>If the cryptoprocessor is not capable of storing cryptographic material,
				729	then there is little use for a separate cryptoprocessor, since all data
				730	would have to be imported by the application.</p>
				731	<p>The cryptoprocessor can provide useful services if it is able to store
				732	at least one key. This may be a hardware unique key that is burnt to
				733	one-time programmable memory during the manufacturing of the device.
				734	This key can be used for one or more purposes:</p>
				735	<ul class="simple">
				736	<li>Encrypt and authenticate data stored in the application processor.</li>
				737	<li>Communicate with a paired device.</li>
				738	<li>Allow the application to perform operations with keys that are
				739	derived from the hardware unique key.</li>
				740	</ul>
				741	</div>
				742	<div class="section" id="multi-client-cryptoprocessor">
				743	<h2>Multi-client cryptoprocessor</h2>
				744	<p>This is an expanded variant of the <a class="reference external" href="#cryptographic-token-and-single-application-processor">cryptographic token plus application
				745	architecture</a>.
				746	In this variant, the cryptoprocessor serves multiple applications that
				747	are mutually untrustworthy. This architecture provides <a class="reference external" href="#optional-isolation">caller
				748	isolation</a>.</p>
				749	<p>In this architecture, API calls are translated to remote procedure
				750	calls, which encode the identity of the client application. The
				751	cryptoprocessor carefully segments its internal storage to ensure that a
				752	client’s data is never leaked to another client.</p>
				753	</div>
				754	<div class="section" id="multi-cryptoprocessor-architecture">
				755	<h2>Multi-cryptoprocessor architecture</h2>
				756	<p>This system includes multiple cryptoprocessors. There are several
				757	reasons to have multiple cryptoprocessors:</p>
				758	<ul class="simple">
				759	<li>Different compromises between security and performance for different
				760	keys. Typically, this means a cryptoprocessor that runs on the same
				761	hardware as the main application and processes short-term secrets, a
				762	secure element or a similar separate chip that retains long-term
				763	secrets.</li>
				764	<li>Independent provisioning of certain secrets.</li>
				765	<li>A combination of a non-removable cryptoprocessor and removable ones,
				766	for example, a smartcard or HSM.</li>
				767	<li>Cryptoprocessors managed by different stakeholders who do not trust
				768	each other.</li>
				769	</ul>
				770	<p>The keystore implementation needs to dispatch each request to the
				771	correct processor. For example: * All requests involving a
				772	non-extractable key must be processed in the cryptoprocessor that holds
				773	that key. * Requests involving a persistent key must be processed in
				774	the cryptoprocessor that corresponds to the key’s lifetime value. *
				775	Requests involving a volatile key may target a cryptoprocessor based on
				776	parameters supplied by the application, or based on considerations such
				777	as performance inside the implementation.</p>
				778	</div>
				779	</div>
				780	<div class="section" id="library-conventions">
				781	<h1>Library conventions</h1>
				782	<div class="section" id="error-handling">
				783	<h2>Error handling</h2>
				784	<div class="section" id="return-status">
				785	<h3>Return status</h3>
				786	<p>Almost all functions return a status indication of type
				787	<code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code>. This is an enumeration of integer values, with 0
				788	(<code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code>) indicating successful operation and other values
				789	indicating errors. The exception is data structure accessor functions,
				790	which cannot fail. Such functions may return <code class="docutils literal notranslate"><span class="pre">void</span></code> or a data value.</p>
				791	<p>Unless specified otherwise, if multiple error conditions apply, an
				792	implementation is free to return any of the applicable error codes. The
				793	choice of error code is considered an implementation quality issue.
				794	Different implementations may make different choices, for example to
				795	favor code size over ease of debugging or vice versa.</p>
				796	<p>Note that if the behavior is undefined (for example, if a function
				797	receives an invalid pointer as a parameter), this specification makes no
				798	guarantee that the function will return an error. Implementations are
				799	encouraged to return an error or halt the application in a manner that
				800	is appropriate for the platform if the undefined behavior condition can
				801	be detected. However, application programmers should be aware that
				802	undefined behavior conditions cannot be detected in general.</p>
				803	</div>
				804	<div class="section" id="behavior-on-error">
				805	<h3>Behavior on error</h3>
				806	<p>All function calls must be implemented atomically:</p>
				807	<ul class="simple">
				808	<li>When a function returns a type other than <code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code>, the
				809	requested action has been carried out.</li>
				810	<li>When a function returns the status <code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code>, the requested
				811	action has been carried out.</li>
				812	<li>When a function returns another status of type <code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code>, no
				813	action has been carried out. The content of the output parameters is
				814	undefined, but otherwise the state of the system has not changed,
				815	except as described below.</li>
				816	</ul>
				817	<p>In general, functions that modify the system state, for example,
				818	creating or destroying a key, must leave the system state unchanged if
				819	they return an error code. There are specific conditions that can result
				820	in different behavior:</p>
				821	<ul class="simple">
				822	<li>The status <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code> indicates that a parameter was not
				823	in a valid state for the requested action. This parameter may have
				824	been modified by the call and is now in an undefined state. The only
				825	valid action on an object in an undefined state is to abort it with
				826	the appropriate <code class="docutils literal notranslate"><span class="pre">psa_abort_xxx</span></code> function.</li>
				827	<li>The status <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_CAPACITY</span></code> indicates that a key
				828	derivation object has reached its maximum capacity. The key
				829	derivation operation may have been modified by the call. Any further
				830	attempt to obtain output from the key derivation operation will
				831	return <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_CAPACITY</span></code>.</li>
				832	<li>The status <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code> indicates that the
				833	communication between the application and the cryptoprocessor has
				834	broken down. In this case, the cryptoprocessor must either finish the
				835	requested action successfully, or interrupt the action and roll back
				836	the system to its original state. Because it is often impossible to
				837	report the outcome to the application after a communication failure,
				838	this specification does not provide a way for the application to
				839	determine whether the action was successful.</li>
				840	<li>The statuses <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code>,
				841	<code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code> and <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_TAMPERING_DETECTED</span></code>
				842	may indicate data corruption in the system state. When a function
				843	returns one of these statuses, the system state may have changed from
				844	its previous state before the function call, even though the function
				845	call failed.</li>
				846	<li>Some system states cannot be rolled back, for example, the internal
				847	state of the random number generator or the content of access logs.</li>
				848	</ul>
				849	<p>Unless otherwise documented, the content of output parameters is not
				850	defined when a function returns a status other than <code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code>.
				851	Implementations should set output parameters to safe defaults to avoid
				852	leaking confidential data and limit risk, in case an application does
				853	not properly handle all errors.</p>
				854	</div>
				855	</div>
				856	<div class="section" id="parameter-conventions">
				857	<h2>Parameter conventions</h2>
				858	<div class="section" id="pointer-conventions">
				859	<h3>Pointer conventions</h3>
				860	<p>Unless explicitly stated in the documentation of a function, all
				861	pointers must be valid pointers to an object of the specified type.</p>
				862	<p>A parameter is considered a <strong>buffer</strong> if it points to an array of
				863	bytes. A buffer parameter always has the type <code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*</span></code> or
				864	<code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*</span></code>, and always has an associated parameter indicating
				865	the size of the array. Note that a parameter of type <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> is never
				866	considered a buffer.</p>
				867	<p>All parameters of pointer type must be valid non-null pointers, unless
				868	the pointer is to a buffer of length 0 or the function’s documentation
				869	explicitly describes the behavior when the pointer is null.
				870	Implementations where a null pointer dereference usually aborts the
				871	application, passing <code class="docutils literal notranslate"><span class="pre">NULL</span></code> as a function parameter where a null
				872	pointer is not allowed, should abort the caller in the habitual manner.</p>
				873	<p>Pointers to input parameters may be in read-only memory. Output
				874	parameters must be in writable memory. Output parameters that are not
				875	buffers must also be readable, and the implementation must be able to
				876	write to a non-buffer output parameter and read back the same value, as
				877	explained in the <a class="reference external" href="#stability-of-parameters">“Stability of
				878	parameters”</a> section.</p>
				879	</div>
				880	<div class="section" id="input-buffer-sizes">
				881	<h3>Input buffer sizes</h3>
				882	<p>For input buffers, the parameter convention is:</p>
				883	<ul class="simple">
				884	<li><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*foo</span></code>: pointer to the first byte of the data. The
				885	pointer may be invalid if the buffer size is 0.</li>
				886	<li><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_length</span></code>: size of the buffer in bytes.</li>
				887	</ul>
				888	<p>The interface never uses input-output buffers.</p>
				889	</div>
				890	<div class="section" id="output-buffer-sizes">
				891	<h3>Output buffer sizes</h3>
				892	<p>For output buffers, the parameter convention is:</p>
				893	<ul class="simple">
				894	<li><code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code>: pointer to the first byte of the data. The pointer
				895	may be invalid if the buffer size is 0.</li>
				896	<li><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_size</span></code>: the size of the buffer in bytes.</li>
				897	<li><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">*foo_length</span></code>: on successful return, contains the length of
				898	the output in bytes.</li>
				899	</ul>
				900	<p>The content of the data buffer and of <code class="docutils literal notranslate"><span class="pre">*foo_length</span></code> on errors is
				901	unspecified, unless explicitly mentioned in the function description.
				902	They may be unmodified or set to a safe default. On successful
				903	completion, the content of the buffer between the offsets
				904	<code class="docutils literal notranslate"><span class="pre">*foo_length</span></code> and <code class="docutils literal notranslate"><span class="pre">foo_size</span></code> is also unspecified.</p>
				905	<p>Functions return <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code> if the buffer size is
				906	insufficient to carry out the requested operation. The interface defines
				907	macros to calculate a sufficient buffer size for each operation that has
				908	an output buffer. These macros return compile-time constants if their
				909	arguments are compile-time constants, so they are suitable for static or
				910	stack allocation. Refer to an individual function’s documentation for
				911	the associated output size macro.</p>
				912	<p>Some functions always return exactly as much data as the size of the
				913	output buffer. In this case, the parameter convention changes to:</p>
				914	<ul class="simple">
				915	<li><code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code>: pointer to the first byte of the output. The
				916	pointer may be invalid if the buffer size is 0.</li>
				917	<li><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_length</span></code>: the number of bytes to return in <code class="docutils literal notranslate"><span class="pre">foo</span></code> if
				918	successful.</li>
				919	</ul>
				920	</div>
				921	<div class="section" id="overlap-between-parameters">
				922	<h3>Overlap between parameters</h3>
				923	<p>Output parameters that are not buffers must not overlap with any input
				924	buffer or with any other output parameter. Otherwise, the behavior is
				925	undefined.</p>
				926	<p>Output buffers may overlap with input buffers. If this happens, the
				927	implementation must return the same result, as if the buffers did not
				928	overlap. In other words, the implementation must behave as if it had
				929	copied all the inputs into temporary memory, as far as the result is
				930	concerned. However, application developers should note that overlap
				931	between parameters may affect the performance of a function call.
				932	Overlap may also affect memory management security if the buffer is
				933	located in memory that the caller shares with another security context,
				934	as described in the <a class="reference external" href="#stability-of-parameters">“Stability of
				935	parameters”</a> section.</p>
				936	</div>
				937	<div class="section" id="stability-of-parameters">
				938	<h3>Stability of parameters</h3>
				939	<p>In some environments, it is possible for the content of a parameter to
				940	change while a function is executing. It may also be possible for the
				941	content of an output parameter to be read before the function
				942	terminates. This can happen if the application is multithreaded. In some
				943	implementations, memory can be shared between security contexts, for
				944	example, between tasks in a multitasking operating system, between a
				945	user land task and the kernel, or between the non-secure world and the
				946	secure world of a trusted execution environment. This section describes
				947	what implementations need or need not guarantee in such cases.</p>
				948	<p>Parameters that are not buffers are assumed to be under the caller’s
				949	full control. In a shared memory environment, this means that the
				950	parameter must be in memory that is exclusively accessible by the
				951	application. In a multithreaded environment, this means that the
				952	parameter may not be modified during the execution, and the value of an
				953	output parameter is undetermined until the function returns. The
				954	implementation may read an input parameter that is not a buffer multiple
				955	times and expect to read the same data. The implementation may write to
				956	an output parameter that is not a buffer and expect to read back the
				957	value that it last wrote. The implementation has the same permissions on
				958	buffers that overlap with a buffer in the opposite direction.</p>
				959	<p>In an environment with multiple threads or with shared memory, the
				960	implementation carefully accesses non-overlapping buffer parameters in
				961	order to prevent any security risk resulting from the content of the
				962	buffer being modified or observed during the execution of the function.
				963	In an input buffer that does not overlap with an output buffer, the
				964	implementation reads each byte of the input once, at most. The
				965	implementation does not read from an output buffer that does not overlap
				966	with an input buffer. Additionally, the implementation does not write
				967	data to a non-overlapping output buffer if this data is potentially
				968	confidential and the implementation has not yet verified that outputting
				969	this data is authorized.</p>
				970	</div>
				971	</div>
				972	<div class="section" id="key-types-and-algorithms">
				973	<h2>Key types and algorithms</h2>
				974	<p>Types of cryptographic keys and cryptographic algorithms are encoded
				975	separately. Each is encoded by using an integral type:
				976	<code class="docutils literal notranslate"><span class="pre">psa_key_type_t</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_algorithm_t</span></code>, respectively.</p>
				977	<p>There is some overlap in the information conveyed by key types and
				978	algorithms. Both types contain enough information, so that the meaning
				979	of an algorithm type value does not depend on what type of key it is
				980	used with, and vice versa. However, the particular instance of an
				981	algorithm may depend on the key type. For example, the algorithm
				982	<code class="docutils literal notranslate"><span class="pre">PSA_ALG_GCM</span></code> can be instantiated as any AEAD algorithm using the GCM
				983	mode over a block cipher. The underlying block cipher is determined by
				984	the key type.</p>
				985	<p>Key types do not encode the key size. For example, AES-128, AES-192 and
				986	AES-256 share a key type <code class="docutils literal notranslate"><span class="pre">PSA_KEY_TYPE_AES</span></code>.</p>
				987	<div class="section" id="structure-of-key-and-algorithm-types">
				988	<h3>Structure of key and algorithm types</h3>
				989	<p>Both types use a partial bitmask structure, which allows the analysis
				990	and building of values from parts. However, the interface defines
				991	constants, so that applications do not need to depend on the encoding,
				992	and an implementation may only care about the encoding for code size
				993	optimization.</p>
				994	<p>The encodings follows a few conventions:</p>
				995	<ul class="simple">
				996	<li>The highest bit is a vendor flag. Current and future versions of this
				997	specification will only define values where this bit is clear.
				998	Implementations that wish to define additional
				999	implementation-specific values must use values where this bit is set,
				1000	to avoid conflicts with future versions of this specification.</li>
				1001	<li>The next few highest bits indicate the corresponding algorithm
				1002	category: hash, MAC, symmetric cipher, asymmetric encryption, and so
				1003	on.</li>
				1004	<li>The following bits identify a family of algorithms in a
				1005	category-dependent manner.</li>
				1006	<li>In some categories and algorithm families, the lowest-order bits
				1007	indicate a variant in a systematic way. For example, algorithm
				1008	families that are parametrized around a hash function encode the hash
				1009	in the 8 lowest bits.</li>
				1010	</ul>
				1011	</div>
				1012	</div>
				1013	<div class="section" id="concurrent-calls">
				1014	<h2>Concurrent calls</h2>
				1015	<p>In some environments, an application can make calls to the PSA crypto
				1016	API in separate threads. In such an environment, concurrent calls are
				1017	performed correctly, as if the calls were executed in sequence, provided
				1018	that they obey the following constraints:</p>
				1019	<ul class="simple">
				1020	<li>There is no overlap between an output parameter of one call and an
				1021	input or output parameter of another call. Overlap between input
				1022	parameters is permitted.</li>
				1023	<li>If a call modifies a key, then no other call must modify or use that
				1024	key. <em>Using</em>, in this context, includes all functions of multipart
				1025	operations using the key. Concurrent calls that merely use the same
				1026	key are permitted.</li>
				1027	<li>Concurrent calls must not use the same operation object.</li>
				1028	</ul>
				1029	<p>If any of these constraints are violated, the behavior is undefined.</p>
				1030	<p>Individual implementations may provide additional guarantees.</p>
				1031	</div>
				1032	</div>
				1033	<div class="section" id="implementation-considerations">
				1034	<h1>Implementation considerations</h1>
				1035	<div class="section" id="implementation-specific-aspects-of-the-interface">
				1036	<h2>Implementation-specific aspects of the interface</h2>
				1037	<div class="section" id="implementation-profile">
				1038	<h3>Implementation profile</h3>
				1039	<p>Implementations may implement a subset of the API and a subset of the
				1040	available algorithms. The implemented subset is known as the
				1041	implementation’s profile. The documentation for each implementation must
				1042	describe the profile that it implements. This specification’s companion
				1043	documents also define a number of standard profiles.</p>
				1044	</div>
				1045	<div class="section" id="implementation-specific-types">
				1046	<h3>Implementation-specific types</h3>
				1047	<p>This specification defines a number of platform-specific types, which
				1048	represent data structures whose content depends on the implementation.
				1049	These are C <code class="docutils literal notranslate"><span class="pre">struct</span></code> types. In the associated header files,
				1050	<code class="docutils literal notranslate"><span class="pre">crypto.h</span></code> declares the <code class="docutils literal notranslate"><span class="pre">struct</span></code> tags and <code class="docutils literal notranslate"><span class="pre">crypto_struct.h</span></code>
				1051	provides a definition for the structures.</p>
				1052	</div>
				1053	<div class="section" id="implementation-specific-macros">
				1054	<h3>Implementation-specific macros</h3>
				1055	<p>Some macros compute a result based on an algorithm or key type. This
				1056	specification provides a sample implementation of these macros, which
				1057	works for all standard types. If an implementation defines
				1058	vendor-specific algorithms or key types, then it must provide an
				1059	implementation for such macros that takes all relevant algorithms and
				1060	types into account. Conversely, an implementation that does not support
				1061	a certain algorithm or key type can define such macros in a simpler way
				1062	that does not take unsupported argument values into account.</p>
				1063	<p>Some macros define the minimum sufficient output buffer size for certain
				1064	functions. In some cases, an implementation is allowed to require a
				1065	buffer size that is larger than the theoretical minimum. An
				1066	implementation must define minimum-size macros in such a way that it
				1067	guarantees that the buffer of the resulting size is sufficient for the
				1068	output of the corresponding function. Refer to each macro’s
				1069	documentation for the applicable requirements.</p>
				1070	</div>
				1071	</div>
				1072	<div class="section" id="porting-to-a-platform">
				1073	<h2>Porting to a platform</h2>
				1074	<div class="section" id="platform-assumptions">
				1075	<h3>Platform assumptions</h3>
				1076	<p>This specification is designed for a C89 platform. The interface is
				1077	defined in terms of C macros, functions and objects.</p>
				1078	<p>The specification assumes 8-bit bytes, and “byte” and “octet” are used
				1079	synonymously.</p>
				1080	</div>
				1081	<div class="section" id="platform-specific-types">
				1082	<h3>Platform-specific types</h3>
				1083	<p>The specification makes use of some platform-specific types, which
				1084	should be defined in <code class="docutils literal notranslate"><span class="pre">crypto_platform.h</span></code> or by a header included in
				1085	this file. <code class="docutils literal notranslate"><span class="pre">crypto_platform.h</span></code> must define the following types:</p>
				1086	<ul class="simple">
				1087	<li><code class="docutils literal notranslate"><span class="pre">uint8_t</span></code>, <code class="docutils literal notranslate"><span class="pre">uint16_t</span></code>, <code class="docutils literal notranslate"><span class="pre">uint32_t</span></code>: unsigned integer types with
				1088	8, 16 and 32 value bits respectively. These may be the types defined
				1089	by the C99 header <code class="docutils literal notranslate"><span class="pre">stdint.h</span></code>.</li>
				1090	<li><code class="docutils literal notranslate"><span class="pre">psa_key_handle_t</span></code>: an unsigned integer type of the
				1091	implementation’s choice.</li>
				1092	</ul>
				1093	</div>
				1094	<div class="section" id="cryptographic-hardware-support">
				1095	<h3>Cryptographic hardware support</h3>
				1096	<p>Implementations are encouraged to make use of hardware accelerators
				1097	where available. A future version of this specification will define a
				1098	function interface that calls drivers for hardware accelerators and
				1099	external cryptographic hardware.</p>
				1100	</div>
				1101	</div>
				1102	<div class="section" id="security-requirements-and-recommendations">
				1103	<h2>Security requirements and recommendations</h2>
				1104	<div class="section" id="error-detection">
				1105	<h3>Error detection</h3>
				1106	<p>Implementations that provide isolation between the caller and the
				1107	cryptography processing environment must validate parameters to ensure
				1108	that the cryptography processing environment is protected from attacks
				1109	caused by passing invalid parameters.</p>
				1110	<p>Even implementations that do not provide isolation should strive to
				1111	detect bad parameters and fail-safe as much as possible.</p>
				1112	</div>
				1113	<div class="section" id="memory-cleanup">
				1114	<h3>Memory cleanup</h3>
				1115	<p>Implementations must wipe all sensitive data from memory when it is no
				1116	longer used. They should wipe this sensitive data as soon as possible.
				1117	In any case, all temporary data used during the execution of a function,
				1118	such as stack buffers, must be wiped before the function returns. All
				1119	data associated with an object, such as a multipart operation, must be
				1120	wiped, at the latest, when the object becomes inactive, for example,
				1121	when a multipart operation is aborted.</p>
				1122	<p>The rationale for this non-functional requirement is to minimize impact
				1123	if the system is compromised. If sensitive data is wiped immediately
				1124	after use, only data that is currently in use can be leaked. It does not
				1125	compromise past data.</p>
				1126	</div>
				1127	<div class="section" id="safe-outputs-on-error">
				1128	<h3>Safe outputs on error</h3>
				1129	<p>Implementations must ensure that confidential data is not written to
				1130	output parameters before validating that the disclosure of this
				1131	confidential data is authorized. This requirement is especially
				1132	important for implementations where the caller may share memory with
				1133	another security context, as described in the <a class="reference external" href="#stability-of-parameters">“Stability of
				1134	parameters”</a> section.</p>
				1135	<p>In most cases, the specification does not define the content of output
				1136	parameters when an error occurs. Implementations should try to ensure
				1137	that the content of output parameters is as safe as possible, in case an
				1138	application flaw or a data leak causes it to be used. In particular, Arm
				1139	recommends that implementations avoid placing partial output in output
				1140	buffers when an action is interrupted. The meaning of “safe as possible”
				1141	depends on the implementation, as different environments require
				1142	different compromises between implementation complexity, overall
				1143	robustness and performance. Some common strategies are to leave output
				1144	parameters unchanged, in case of errors, or zeroing them out.</p>
				1145	</div>
				1146	<div class="section" id="attack-resistance">
				1147	<h3>Attack resistance</h3>
				1148	<p>Cryptographic code tends to manipulate high-value secrets, from which
				1149	other secrets can be unlocked. As such, it is a high-value target for
				1150	attacks. There is a vast body of literature on attack types, such as
				1151	side channel attacks and glitch attacks. Typical side channels include
				1152	timing, cache access patterns, branch-prediction access patterns, power
				1153	consumption, radio emissions and more.</p>
				1154	<p>This specification does not specify particular requirements for attack
				1155	resistance. Therefore, implementers should consider the attack
				1156	resistance desired in each use case and design their implementation
				1157	accordingly. Security standards for attack resistance for particular
				1158	targets may be applicable in certain use cases.</p>
				1159	</div>
				1160	</div>
				1161	<div class="section" id="other-implementation-considerations">
				1162	<h2>Other implementation considerations</h2>
				1163	<div class="section" id="philosophy-of-resource-management">
				1164	<h3>Philosophy of resource management</h3>
				1165	<p>The specification allows most functions to return
				1166	<code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code>. This gives implementations the
				1167	freedom to manage memory as they please.</p>
				1168	<p>Alternatively, the interface is also designed for conservative
				1169	strategies of memory management. An implementation may avoid dynamic
				1170	memory allocation altogether by obeying certain restrictions:</p>
				1171	<ul class="simple">
				1172	<li>Pre-allocate memory for a predefined number of keys, each with
				1173	sufficient memory for all key types that can be stored.</li>
				1174	<li>For multipart operations, in an implementation without isolation,
				1175	place all the data that needs to be carried over from one step to the
				1176	next in the operation object. The application is then fully in
				1177	control of how memory is allocated for the operation.</li>
				1178	<li>In an implementation with isolation, pre-allocate memory for a
				1179	predefined number of operations inside the cryptoprocessor.</li>
				1180	</ul>
				1181	<!--
				1182	#### Inclusion of algorithms
				1183
				1184	Inline algorithm-generic functions into specialized functions at compile/link time
				1185	--></div>
				1186	</div>
				1187	</div>
				1188	<div class="section" id="usage-considerations">
				1189	<h1>Usage considerations</h1>
				1190	<div class="section" id="security-recommendations">
				1191	<h2>Security recommendations</h2>
				1192	<div class="section" id="always-check-for-errors">
				1193	<h3>Always check for errors</h3>
				1194	<p>Most functions in this API can return errors. All functions that can
				1195	fail have the return type <code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code>. A few functions cannot fail,
				1196	and thus, return <code class="docutils literal notranslate"><span class="pre">void</span></code> or some other type.</p>
				1197	<p>If an error occurs, unless otherwise specified, the content of the
				1198	output parameters is undefined and must not be used.</p>
				1199	<p>Some common causes of errors include:</p>
				1200	<ul class="simple">
				1201	<li>In implementations where the keys are stored and processed in a
				1202	separate environment from the application, all functions that need to
				1203	access the cryptography processing environment may fail due to an
				1204	error in the communication between the two environments.</li>
				1205	<li>If an algorithm is implemented with a hardware accelerator, which is
				1206	logically separate from the application processor, the accelerator
				1207	may fail, even when the application processor keeps running normally.</li>
				1208	<li>All functions may fail due to a lack of resources. However, some
				1209	implementations guarantee that certain functions always have
				1210	sufficient memory.</li>
				1211	<li>All functions that access persistent keys may fail due to a storage
				1212	failure.</li>
				1213	<li>All functions that require randomness may fail due to a lack of
				1214	entropy. Implementations are encouraged to seed the random generator
				1215	with sufficient entropy during the execution of <code class="docutils literal notranslate"><span class="pre">psa_crypto_init</span></code>.
				1216	However, some security standards require periodic reseeding from a
				1217	hardware random generator, which can fail.</li>
				1218	</ul>
				1219	</div>
				1220	<div class="section" id="shared-memory-and-concurrency">
				1221	<h3>Shared memory and concurrency</h3>
				1222	<p>Some environments allow applications to be multithreaded, while others
				1223	do not. In some environments, applications may share memory with a
				1224	different security context. In environments with multithreaded
				1225	applications or shared memory, applications must be written carefully to
				1226	avoid data corruption or leakage. This specification requires the
				1227	application to obey certain constraints.</p>
				1228	<p>In general, this API allows either one writer or any number of
				1229	simultaneous readers, on any given object. In other words, if two or
				1230	more calls access the same object concurrently, then the behavior is
				1231	only well-defined if all the calls are only reading from the object and
				1232	do not modify it. Read accesses include reading memory by input
				1233	parameters and reading keystore content by using a key. For more
				1234	details, refer to the <a class="reference external" href="#concurrent-calls">“Concurrent calls”</a>
				1235	section.</p>
				1236	<p>If an application shares memory with another security context, it may
				1237	pass shared memory blocks as input buffers or output buffers, but not as
				1238	non-buffer parameters. For more details, refer to the <a class="reference external" href="#stability-of-parameters">“Stability of
				1239	parameters”</a> section.</p>
				1240	</div>
				1241	<div class="section" id="cleaning-up-after-use">
				1242	<h3>Cleaning up after use</h3>
				1243	<p>To minimize impact if the system is compromised, applications should
				1244	wipe all sensitive data from memory when it is no longer used. That way,
				1245	only data that is currently in use may be leaked, and past data is not
				1246	compromised.</p>
				1247	<p>Wiping sensitive data includes:</p>
				1248	<ul class="simple">
				1249	<li>Clearing temporary buffers in the stack or on the heap.</li>
				1250	<li>Aborting operations if they will not be finished.</li>
				1251	<li>Destroying keys that are no longer used.</li>
				1252	</ul>
				1253	</div>
				1254	</div>
				1255	</div>
				1256
				1257
				1258	</div>
				1259
				1260	</div>
				1261	</div>
				1262	<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
				1263	<div class="sphinxsidebarwrapper">
				1264	<h1 class="logo"><a href="index.html">psa_crypto_api</a></h1>
				1265
				1266
				1267
				1268
				1269
				1270
				1271
				1272
				1273	<h3>Navigation</h3>
				1274	<ul class="current">
				1275	<li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction</a></li>
				1276	<li class="toctree-l1"><a class="reference internal" href="#design-goals">Design goals</a><ul>
				1277	<li class="toctree-l2"><a class="reference internal" href="#suitable-for-constrained-devices">Suitable for constrained devices</a></li>
				1278	<li class="toctree-l2"><a class="reference internal" href="#a-keystore-interface">A keystore interface</a></li>
				1279	<li class="toctree-l2"><a class="reference internal" href="#optional-isolation">Optional isolation</a></li>
				1280	<li class="toctree-l2"><a class="reference internal" href="#choice-of-algorithms">Choice of algorithms</a></li>
				1281	<li class="toctree-l2"><a class="reference internal" href="#ease-of-use">Ease of use</a></li>
				1282	<li class="toctree-l2"><a class="reference internal" href="#example-use-cases">Example use cases</a><ul>
				1283	<li class="toctree-l3"><a class="reference internal" href="#network-security-tls">Network Security (TLS)</a></li>
				1284	<li class="toctree-l3"><a class="reference internal" href="#secure-storage">Secure Storage</a></li>
				1285	<li class="toctree-l3"><a class="reference internal" href="#network-credentials">Network Credentials</a></li>
				1286	<li class="toctree-l3"><a class="reference internal" href="#device-pairing">Device Pairing</a></li>
				1287	<li class="toctree-l3"><a class="reference internal" href="#secure-boot">Secure Boot</a></li>
				1288	<li class="toctree-l3"><a class="reference internal" href="#attestation">Attestation</a></li>
				1289	<li class="toctree-l3"><a class="reference internal" href="#factory-provisioning">Factory Provisioning</a></li>
				1290	</ul>
				1291	</li>
				1292	</ul>
				1293	</li>
				1294	<li class="toctree-l1"><a class="reference internal" href="#functionality-overview">Functionality overview</a><ul>
				1295	<li class="toctree-l2"><a class="reference internal" href="#library-management">Library management</a></li>
				1296	<li class="toctree-l2"><a class="reference internal" href="#key-management">Key management</a><ul>
				1297	<li class="toctree-l3"><a class="reference internal" href="#volatile-keys">Volatile keys</a></li>
				1298	<li class="toctree-l3"><a class="reference internal" href="#persistent-keys">Persistent keys</a></li>
				1299	<li class="toctree-l3"><a class="reference internal" href="#recommendations-of-minimum-standards-for-key-management">Recommendations of minimum standards for key management</a></li>
				1300	</ul>
				1301	</li>
				1302	<li class="toctree-l2"><a class="reference internal" href="#usage-policies">Usage policies</a></li>
				1303	<li class="toctree-l2"><a class="reference internal" href="#symmetric-cryptography">Symmetric cryptography</a><ul>
				1304	<li class="toctree-l3"><a class="reference internal" href="#multipart-operations">Multipart operations</a></li>
				1305	<li class="toctree-l3"><a class="reference internal" href="#authenticated-encryption">Authenticated encryption</a></li>
				1306	</ul>
				1307	</li>
				1308	<li class="toctree-l2"><a class="reference internal" href="#key-derivation">Key derivation</a><ul>
				1309	<li class="toctree-l3"><a class="reference internal" href="#key-derivation-operations">Key derivation operations</a></li>
				1310	<li class="toctree-l3"><a class="reference internal" href="#key-derivation-function">Key derivation function</a></li>
				1311	</ul>
				1312	</li>
				1313	<li class="toctree-l2"><a class="reference internal" href="#asymmetric-cryptography">Asymmetric cryptography</a><ul>
				1314	<li class="toctree-l3"><a class="reference internal" href="#asymmetric-encryption">Asymmetric encryption</a></li>
				1315	<li class="toctree-l3"><a class="reference internal" href="#hash-and-sign">Hash-and-sign</a></li>
				1316	<li class="toctree-l3"><a class="reference internal" href="#key-agreement">Key agreement</a></li>
				1317	</ul>
				1318	</li>
				1319	<li class="toctree-l2"><a class="reference internal" href="#randomness-and-key-generation">Randomness and key generation</a></li>
				1320	<li class="toctree-l2"><a class="reference internal" href="#future-additions">Future additions</a></li>
				1321	</ul>
				1322	</li>
				1323	<li class="toctree-l1"><a class="reference internal" href="#sample-architectures">Sample architectures</a><ul>
				1324	<li class="toctree-l2"><a class="reference internal" href="#single-partition-architecture">Single-partition architecture</a></li>
				1325	<li class="toctree-l2"><a class="reference internal" href="#cryptographic-token-and-single-application-processor">Cryptographic token and single-application processor</a></li>
				1326	<li class="toctree-l2"><a class="reference internal" href="#cryptoprocessor-with-no-key-storage">Cryptoprocessor with no key storage</a></li>
				1327	<li class="toctree-l2"><a class="reference internal" href="#multi-client-cryptoprocessor">Multi-client cryptoprocessor</a></li>
				1328	<li class="toctree-l2"><a class="reference internal" href="#multi-cryptoprocessor-architecture">Multi-cryptoprocessor architecture</a></li>
				1329	</ul>
				1330	</li>
				1331	<li class="toctree-l1"><a class="reference internal" href="#library-conventions">Library conventions</a><ul>
				1332	<li class="toctree-l2"><a class="reference internal" href="#error-handling">Error handling</a><ul>
				1333	<li class="toctree-l3"><a class="reference internal" href="#return-status">Return status</a></li>
				1334	<li class="toctree-l3"><a class="reference internal" href="#behavior-on-error">Behavior on error</a></li>
				1335	</ul>
				1336	</li>
				1337	<li class="toctree-l2"><a class="reference internal" href="#parameter-conventions">Parameter conventions</a><ul>
				1338	<li class="toctree-l3"><a class="reference internal" href="#pointer-conventions">Pointer conventions</a></li>
				1339	<li class="toctree-l3"><a class="reference internal" href="#input-buffer-sizes">Input buffer sizes</a></li>
				1340	<li class="toctree-l3"><a class="reference internal" href="#output-buffer-sizes">Output buffer sizes</a></li>
				1341	<li class="toctree-l3"><a class="reference internal" href="#overlap-between-parameters">Overlap between parameters</a></li>
				1342	<li class="toctree-l3"><a class="reference internal" href="#stability-of-parameters">Stability of parameters</a></li>
				1343	</ul>
				1344	</li>
				1345	<li class="toctree-l2"><a class="reference internal" href="#key-types-and-algorithms">Key types and algorithms</a><ul>
				1346	<li class="toctree-l3"><a class="reference internal" href="#structure-of-key-and-algorithm-types">Structure of key and algorithm types</a></li>
				1347	</ul>
				1348	</li>
				1349	<li class="toctree-l2"><a class="reference internal" href="#concurrent-calls">Concurrent calls</a></li>
				1350	</ul>
				1351	</li>
				1352	<li class="toctree-l1"><a class="reference internal" href="#implementation-considerations">Implementation considerations</a><ul>
				1353	<li class="toctree-l2"><a class="reference internal" href="#implementation-specific-aspects-of-the-interface">Implementation-specific aspects of the interface</a><ul>
				1354	<li class="toctree-l3"><a class="reference internal" href="#implementation-profile">Implementation profile</a></li>
				1355	<li class="toctree-l3"><a class="reference internal" href="#implementation-specific-types">Implementation-specific types</a></li>
				1356	<li class="toctree-l3"><a class="reference internal" href="#implementation-specific-macros">Implementation-specific macros</a></li>
				1357	</ul>
				1358	</li>
				1359	<li class="toctree-l2"><a class="reference internal" href="#porting-to-a-platform">Porting to a platform</a><ul>
				1360	<li class="toctree-l3"><a class="reference internal" href="#platform-assumptions">Platform assumptions</a></li>
				1361	<li class="toctree-l3"><a class="reference internal" href="#platform-specific-types">Platform-specific types</a></li>
				1362	<li class="toctree-l3"><a class="reference internal" href="#cryptographic-hardware-support">Cryptographic hardware support</a></li>
				1363	</ul>
				1364	</li>
				1365	<li class="toctree-l2"><a class="reference internal" href="#security-requirements-and-recommendations">Security requirements and recommendations</a><ul>
				1366	<li class="toctree-l3"><a class="reference internal" href="#error-detection">Error detection</a></li>
				1367	<li class="toctree-l3"><a class="reference internal" href="#memory-cleanup">Memory cleanup</a></li>
				1368	<li class="toctree-l3"><a class="reference internal" href="#safe-outputs-on-error">Safe outputs on error</a></li>
				1369	<li class="toctree-l3"><a class="reference internal" href="#attack-resistance">Attack resistance</a></li>
				1370	</ul>
				1371	</li>
				1372	<li class="toctree-l2"><a class="reference internal" href="#other-implementation-considerations">Other implementation considerations</a><ul>
				1373	<li class="toctree-l3"><a class="reference internal" href="#philosophy-of-resource-management">Philosophy of resource management</a></li>
				1374	</ul>
				1375	</li>
				1376	</ul>
				1377	</li>
				1378	<li class="toctree-l1"><a class="reference internal" href="#usage-considerations">Usage considerations</a><ul>
				1379	<li class="toctree-l2"><a class="reference internal" href="#security-recommendations">Security recommendations</a><ul>
				1380	<li class="toctree-l3"><a class="reference internal" href="#always-check-for-errors">Always check for errors</a></li>
				1381	<li class="toctree-l3"><a class="reference internal" href="#shared-memory-and-concurrency">Shared memory and concurrency</a></li>
				1382	<li class="toctree-l3"><a class="reference internal" href="#cleaning-up-after-use">Cleaning up after use</a></li>
				1383	</ul>
				1384	</li>
				1385	</ul>
				1386	</li>
				1387	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html">Implementation-specific definitions</a></li>
				1388	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#library-initialization">Library initialization</a></li>
				1389	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-attributes">Key attributes</a></li>
				1390	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-management">Key management</a></li>
				1391	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-import-and-export">Key import and export</a></li>
				1392	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#message-digests">Message digests</a></li>
				1393	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#message-authentication-codes">Message authentication codes</a></li>
				1394	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#symmetric-ciphers">Symmetric ciphers</a></li>
				1395	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#authenticated-encryption-with-associated-data-aead">Authenticated encryption with associated data (AEAD)</a></li>
				1396	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#asymmetric-cryptography">Asymmetric cryptography</a></li>
				1397	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-derivation-and-pseudorandom-generation">Key derivation and pseudorandom generation</a></li>
				1398	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#random-generation">Random generation</a></li>
				1399	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#error-codes">Error codes</a></li>
				1400	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-and-algorithm-types">Key and algorithm types</a></li>
				1401	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-lifetimes">Key lifetimes</a></li>
				1402	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-policies">Key policies</a></li>
				1403	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-derivation">Key derivation</a></li>
				1404	<li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#other-definitions">Other definitions</a></li>
				1405	</ul>
				1406
				1407	<div class="relations">
				1408	<h3>Related Topics</h3>
				1409	<ul>
				1410	<li><a href="index.html">Documentation overview</a><ul>
				1411	<li>Previous: <a href="index.html" title="previous chapter">PSA Cryptography API Specification</a></li>
				1412	<li>Next: <a href="from_doxygen.html" title="next chapter">Implementation-specific definitions</a></li>
				1413	</ul></li>
				1414	</ul>
				1415	</div>
				1416	<div id="searchbox" style="display: none" role="search">
				1417	<h3>Quick search</h3>
				1418	<div class="searchformwrapper">
				1419	<form class="search" action="search.html" method="get">
				1420	<input type="text" name="q" />
				1421	<input type="submit" value="Go" />
				1422	<input type="hidden" name="check_keywords" value="yes" />
				1423	<input type="hidden" name="area" value="default" />
				1424	</form>
				1425	</div>
				1426	</div>
				1427	<script type="text/javascript">$('#searchbox').show(0);</script>
				1428
				1429
				1430
				1431
				1432
				1433
				1434
				1435
				1436	</div>
				1437	</div>
				1438	<div class="clearer"></div>
				1439	</div>
				1440	<div class="footer">
				1441	©2019, Arm.
				1442
				1443	\|
				1444	Powered by <a href="http://sphinx-doc.org/">Sphinx 1.8.5</a>
				1445	& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
				1446
				1447	\|
				1448	<a href="_sources/general.rst.txt"
				1449	rel="nofollow">Page source</a>
				1450	</div>
				1451
				1452
				1453
				1454
				1455	</body>
				1456	</html>