blob: 508dea718e728feb26016630244cd6a6e6cd42ed [file] [log] [blame]
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>About this document &#8212; PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="author" title="About these documents" href="#" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="1. Introduction" href="overview/intro.html" />
<link rel="prev" title="PSA Cryptography API 1.0" href="index.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="about-this-document">
<span id="id1"></span><h1>About this document</h1>
<div class="section" id="release-information">
<h2>Release information</h2>
<p>The change history table lists the changes that have been made to this document.</p>
<table class="colwidths-given docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 15%" />
<col style="width: 20%" />
<col style="width: 45%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Date</p></th>
<th class="head"><p>Version</p></th>
<th class="head"><p>Confidentiality</p></th>
<th class="head"><p>Change</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>January 2019</p></td>
<td><p>1.0 Beta 1</p></td>
<td><p>Non-confidential</p></td>
<td><p>First public beta release.</p></td>
</tr>
<tr class="row-odd"><td><p>February 2019</p></td>
<td><p>1.0 Beta 2</p></td>
<td><p>Non-confidential</p></td>
<td><p>Update for release with other PSA Dev API specifications.</p></td>
</tr>
<tr class="row-even"><td><p>May 2019</p></td>
<td><p>1.0 Beta 3</p></td>
<td><p>Non-confidential</p></td>
<td><p>Update for release with other PSA API specifications.</p></td>
</tr>
<tr class="row-odd"><td><p>February 2020</p></td>
<td><p>1.0 Final</p></td>
<td><p>Non-confidential</p></td>
<td><p>1.0 API finalized.</p></td>
</tr>
<tr class="row-even"><td><p>August 2020</p></td>
<td><p>1.0.1 Final</p></td>
<td><p>Non-confidential</p></td>
<td><p>Update to fix errors and provide clarifications.</p></td>
</tr>
</tbody>
</table>
<p>The detailed changes in each release are described in <a class="reference internal" href="appendix/history.html#changes"><span class="secref">Document change history</span></a>.</p>
</div>
<p><span class="sectiontitle">PSA Cryptography API</span></p>
<p>Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved. The copyright statement reflects the fact that some
draft issues of this document have been released, to a limited circulation.</p>
<div class="section" id="arm-non-confidential-document-licence-licence">
<h2>Arm Non-Confidential Document Licence (“Licence”)</h2>
<div class="license docutils container">
<p>This Licence is a legal agreement between you and Arm Limited (“<strong>Arm</strong>”) for the use of Arm’s intellectual property (including, without limitation, any copyright) embodied in the document accompanying this Licence (“<strong>Document</strong>”). Arm licenses its intellectual property in the Document to you on condition that you agree to the terms of this Licence. By using or copying the Document you indicate that you agree to be bound by the terms of this Licence.</p>
<p><strong>Subsidiary</strong>” means any company the majority of whose voting shares is now or hereafter owner or controlled, directly or indirectly, by you. A company shall be a Subsidiary only for the period during which such control exists.</p>
<p>This Document is <strong>NON-CONFIDENTIAL</strong> and any use by you and your Subsidiaries (“Licensee”) is subject to the terms of this Licence between you and Arm.</p>
<p>Subject to the terms and conditions of this Licence, Arm hereby grants to Licensee under the intellectual property in the Document owned or controlled by Arm, a non-exclusive, non-transferable, non-sub-licensable, royalty-free, worldwide licence to:</p>
<ol class="lowerroman simple">
<li><p>use and copy the Document for the purpose of designing and having designed products that comply with the Document;</p></li>
<li><p>manufacture and have manufactured products which have been created under the licence granted in (i) above; and</p></li>
<li><p>sell, supply and distribute products which have been created under the licence granted in (i) above.</p></li>
</ol>
<p><strong>Licensee hereby agrees that the licences granted above shall not extend to any portion or function of a product that is not itself compliant with part of the Document.</strong></p>
<p>Except as expressly licensed above, Licensee acquires no right, title or interest in any Arm technology or any intellectual property embodied therein.</p>
<p>THE DOCUMENT IS PROVIDED “AS IS”. ARM PROVIDES NO REPRESENTATIONS AND NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE DOCUMENT. Arm may make changes to the Document at any time and without notice. For the avoidance of doubt, Arm makes no representation with respect to, and has undertaken no analysis to identify or understand the scope and content of, third party patents, copyrights, trade secrets, or other rights.</p>
<p>NOTWITHSTANDING ANYTHING TO THE CONTRARY CONTAINED IN THIS LICENCE, TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT WILL ARM BE LIABLE FOR ANY DAMAGES, IN CONTRACT, TORT OR OTHERWISE, IN CONNECTION WITH THE SUBJECT MATTER OF THIS LICENCE (INCLUDING WITHOUT LIMITATION) (I) LICENSEE’S USE OF THE DOCUMENT; AND (II) THE IMPLEMENTATION OF THE DOCUMENT IN ANY PRODUCT CREATED BY LICENSEE UNDER THIS LICENCE). THE EXISTENCE OF MORE THAN ONE CLAIM OR SUIT WILL NOT ENLARGE OR EXTEND THE LIMIT. LICENSEE RELEASES ARM FROM ALL OBLIGATIONS, LIABILITY, CLAIMS OR DEMANDS IN EXCESS OF THIS LIMITATION.</p>
<p>This Licence shall remain in force until terminated by Licensee or by Arm. Without prejudice to any of its other rights, if Licensee is in breach of any of the terms and conditions of this Licence then Arm may terminate this Licence immediately upon giving written notice to Licensee. Licensee may terminate this Licence at any time. Upon termination of this Licence by Licensee or by Arm, Licensee shall stop using the Document and destroy all copies of the Document in its possession. Upon termination of this Licence, all terms shall survive except for the licence grants.</p>
<p>Any breach of this Licence by a Subsidiary shall entitle Arm to terminate this Licence as if you were the party in breach. Any termination of this Licence shall be effective in respect of all Subsidiaries. Any rights granted to any Subsidiary hereunder shall automatically terminate upon such Subsidiary ceasing to be a Subsidiary.</p>
<p>The Document consists solely of commercial items. Licensee shall be responsible for ensuring that any use, duplication or disclosure of the Document complies fully with any relevant export laws and regulations to assure that the Document or any portion thereof is not exported, directly or indirectly, in violation of such export laws.</p>
<p>This Licence may be translated into other languages for convenience, and Licensee agrees that if there is any conflict between the English version of this Licence and any translation, the terms of the English version of this Licence shall prevail.</p>
<p>The Arm corporate logo and words marked with ® or ™ are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere. All rights reserved. Other brands and names mentioned in this document may be the trademarks of their respective owners. No licence, express, implied or otherwise, is granted to Licensee under this Licence, to use the Arm trade marks in connection with the Document or any products based thereon. Visit Arm’s website at <a class="reference external" href="https://www.arm.com/company/policies/trademarks">https://www.arm.com/company/policies/trademarks</a> for more information about Arm’s trademarks.</p>
<p>The validity, construction and performance of this Licence shall be governed by English Law.</p>
<p>Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved.</p>
<div class="line-block">
<div class="line">Arm Limited. Company 02557590 registered in England.</div>
<div class="line">110 Fulbourn Road, Cambridge, England CB1 9NJ.</div>
</div>
<p>Arm document reference: LES-PRE-21585 version 4.0</p>
</div>
</div>
<div class="section" id="references">
<h2>References</h2>
<p>This document refers to the following documents.</p>
<table class="longtable colwidths-given docutils align-default" id="id2">
<caption><span class="caption-number">Table 1 </span><span class="caption-text">Arm documents referenced by this document</span></caption>
<colgroup>
<col style="width: 15%" />
<col style="width: 20%" />
<col style="width: 65%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Ref</p></th>
<th class="head"><p>Document Number</p></th>
<th class="head"><p>Title</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><span class="target" id="citation-psa-its"></span>[PSA-ITS]</p></td>
<td><p>ARM IHI 0087</p></td>
<td><p><em>PSA Storage API</em>. <a class="reference external" href="https://developer.arm.com/architectures/security-architectures/platform-security-architecture/documentation">https://developer.arm.com/architectures/security-architectures/platform-security-architecture/documentation</a></p></td>
</tr>
</tbody>
</table>
<table class="longtable colwidths-given docutils align-default" id="id3">
<caption><span class="caption-number">Table 2 </span><span class="caption-text">Other documents referenced by this document</span></caption>
<colgroup>
<col style="width: 15%" />
<col style="width: 85%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Ref</p></th>
<th class="head"><p>Title</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><span class="target" id="citation-chacha20"></span>[CHACHA20]</p></td>
<td><p>Bernstein, D., <em>ChaCha, a variant of Salsa20</em>, January 2008. <a class="reference external" href="http://cr.yp.to/chacha/chacha-20080128.pdf">http://cr.yp.to/chacha/chacha-20080128.pdf</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-curve25519"></span>[Curve25519]</p></td>
<td><p>Bernstein et al., <em>Curve25519: new Diffie-Hellman speed records</em>, LNCS 3958, 2006. <a class="reference external" href="https://www.iacr.org/archive/pkc2006/39580209/39580209.pdf">https://www.iacr.org/archive/pkc2006/39580209/39580209.pdf</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-curve448"></span>[Curve448]</p></td>
<td><p>Hamburg, <em>Ed448-Goldilocks, a new elliptic curve</em>, NIST ECC Workshop, 2015. <a class="reference external" href="https://eprint.iacr.org/2015/625.pdf">https://eprint.iacr.org/2015/625.pdf</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-fips180-4"></span>[FIPS180-4]</p></td>
<td><p>NIST, <em>FIPS Publication 180-4: Secure Hash Standard (SHS)</em>, August 2015. <a class="reference external" href="https://doi.org/10.6028/NIST.FIPS.180-4">https://doi.org/10.6028/NIST.FIPS.180-4</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-fips186-4"></span>[FIPS186-4]</p></td>
<td><p>NIST, <em>FIPS Publication 186-4: Digital Signature Standard (DSS)</em>, July 2013. <a class="reference external" href="https://doi.org/10.6028/NIST.FIPS.186-4">https://doi.org/10.6028/NIST.FIPS.186-4</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-fips197"></span>[FIPS197]</p></td>
<td><p>NIST, <em>FIPS Publication 197: Advanced Encryption Standard (AES)</em>, November 2001. <a class="reference external" href="https://doi.org/10.6028/NIST.FIPS.197">https://doi.org/10.6028/NIST.FIPS.197</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-fips202"></span>[FIPS202]</p></td>
<td><p>NIST, <em>FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions</em>, August 2015. <a class="reference external" href="https://doi.org/10.6028/NIST.FIPS.202">https://doi.org/10.6028/NIST.FIPS.202</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-frp"></span>[FRP]</p></td>
<td><p>Agence nationale de la sécurité des systèmes d’information, <em>Publication d’un paramétrage de courbe elliptique visant des applications de passeport électronique et de l’administration électronique française</em>, 21 November 2011. <a class="reference external" href="https://www.ssi.gouv.fr/agence/rayonnement-scientifique/publications-scientifiques/articles-ouvrages-actes">https://www.ssi.gouv.fr/agence/rayonnement-scientifique/publications-scientifiques/articles-ouvrages-actes</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-ieee-xts"></span>[IEEE-XTS]</p></td>
<td><p>IEEE, <em>1619-2018 - IEEE Standard for Cryptographic Protection of Data on Block-Oriented Storage Devices</em>, January 2019. <a class="reference external" href="https://ieeexplore.ieee.org/servlet/opac?punumber=8637986">https://ieeexplore.ieee.org/servlet/opac?punumber=8637986</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-ietf-sm3"></span>[IETF-SM3]</p></td>
<td><p>IETF, <em>The SM3 Cryptographic Hash Function</em>, November 2017. <a class="reference external" href="https://tools.ietf.org/id/draft-oscca-cfrg-sm3-02.html">https://tools.ietf.org/id/draft-oscca-cfrg-sm3-02.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-ietf-sm4"></span>[IETF-SM4]</p></td>
<td><p>IETF, <em>The SM4 Blockcipher Algorithm And Its Modes Of Operations</em>, April 2018. <a class="reference external" href="https://tools.ietf.org/html/draft-ribose-cfrg-sm4-10">https://tools.ietf.org/html/draft-ribose-cfrg-sm4-10</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-iso10118"></span>[ISO10118]</p></td>
<td><p>ISO/IEC, <em>ISO/IEC 10118-3:2018 IT Security techniques — Hash-functions — Part 3: Dedicated hash-functions</em>, October 2018. <a class="reference external" href="https://www.iso.org/standard/67116.html">https://www.iso.org/standard/67116.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-iso9797"></span>[ISO9797]</p></td>
<td><p>ISO/IEC, <em>ISO/IEC 9797-1:2011 Information technology — Security techniques — Message Authentication Codes (MACs) — Part 1: Mechanisms using a block cipher</em>, March 2011. <a class="reference external" href="https://www.iso.org/standard/50375.html">https://www.iso.org/standard/50375.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-ntt-cam"></span>[NTT-CAM]</p></td>
<td><p>NTT Corporation and Mitsubishi Electric Corporation, <em>Specification of Camellia — a 128-bit Block Cipher</em>, September 2001. <a class="reference external" href="https://info.isl.ntt.co.jp/crypt/eng/camellia/specifications">https://info.isl.ntt.co.jp/crypt/eng/camellia/specifications</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-prc-sm3"></span>[PRC-SM3]</p></td>
<td><p>Standardization Administration of the People’s Republic of China, <em>GB/T 32905-2016: Information security techniques — SM3 cryptographic hash algorithm</em>, August 2016. <a class="reference external" href="http://www.gb688.cn/bzgk/gb/newGbInfo?hcno=45B1A67F20F3BF339211C391E9278F5E">http://www.gb688.cn/bzgk/gb/newGbInfo?hcno=45B1A67F20F3BF339211C391E9278F5E</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-prc-sm4"></span>[PRC-SM4]</p></td>
<td><p>Standardization Administration of the People’s Republic of China, <em>GB/T 32907-2016: Information security technology — SM4 block cipher algorithm</em>, August 2016. <a class="reference external" href="http://www.gb688.cn/bzgk/gb/newGbInfo?hcno=7803DE42D3BC5E80B0C3E5D8E873D56A">http://www.gb688.cn/bzgk/gb/newGbInfo?hcno=7803DE42D3BC5E80B0C3E5D8E873D56A</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc1319"></span>[RFC1319]</p></td>
<td><p>IETF, <em>The MD2 Message-Digest Algorithm</em>, April 1992. <a class="reference external" href="https://tools.ietf.org/html/rfc1319.html">https://tools.ietf.org/html/rfc1319.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc1320"></span>[RFC1320]</p></td>
<td><p>IETF, <em>The MD4 Message-Digest Algorithm</em>, April 1992. <a class="reference external" href="https://tools.ietf.org/html/rfc1320.html">https://tools.ietf.org/html/rfc1320.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc1321"></span>[RFC1321]</p></td>
<td><p>IETF, <em>The MD5 Message-Digest Algorithm</em>, April 1992. <a class="reference external" href="https://tools.ietf.org/html/rfc1321.html">https://tools.ietf.org/html/rfc1321.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc2104"></span>[RFC2104]</p></td>
<td><p>IETF, <em>HMAC: Keyed-Hashing for Message Authentication</em>, February 1997. <a class="reference external" href="https://tools.ietf.org/html/rfc2104.html">https://tools.ietf.org/html/rfc2104.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc2315"></span>[RFC2315]</p></td>
<td><p>IETF, <em>PKCS #7: Cryptographic Message Syntax Version 1.5</em>, March 1998. <a class="reference external" href="https://tools.ietf.org/html/rfc2315.html">https://tools.ietf.org/html/rfc2315.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc3279"></span>[RFC3279]</p></td>
<td><p>IETF, <em>Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile</em>, April 2002. <a class="reference external" href="https://tools.ietf.org/html/rfc3279.html">https://tools.ietf.org/html/rfc3279.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc3610"></span>[RFC3610]</p></td>
<td><p>IETF, <em>Counter with CBC-MAC (CCM)</em>, September 2003. <a class="reference external" href="https://tools.ietf.org/html/rfc3610">https://tools.ietf.org/html/rfc3610</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc3713"></span>[RFC3713]</p></td>
<td><p>IETF, <em>A Description of the Camellia Encryption Algorithm</em>, April 2004. <a class="reference external" href="https://tools.ietf.org/html/rfc3713">https://tools.ietf.org/html/rfc3713</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc4279"></span>[RFC4279]</p></td>
<td><p>IETF, <em>Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)</em>, December 2005. <a class="reference external" href="https://tools.ietf.org/html/rfc4279.html">https://tools.ietf.org/html/rfc4279.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc5116"></span>[RFC5116]</p></td>
<td><p>IETF, <em>An Interface and Algorithms for Authenticated Encryption</em>, January 2008. <a class="reference external" href="https://tools.ietf.org/html/rfc5116.html">https://tools.ietf.org/html/rfc5116.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc5246"></span>[RFC5246]</p></td>
<td><p>IETF, <em>The Transport Layer Security (TLS) Protocol Version 1.2</em>, August 2008. <a class="reference external" href="https://tools.ietf.org/html/rfc5246.html">https://tools.ietf.org/html/rfc5246.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc5639"></span>[RFC5639]</p></td>
<td><p>IETF, <em>Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation</em>, March 2010. <a class="reference external" href="https://tools.ietf.org/html/rfc5639.html">https://tools.ietf.org/html/rfc5639.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc5869"></span>[RFC5869]</p></td>
<td><p>IETF, <em>HMAC-based Extract-and-Expand Key Derivation Function (HKDF)</em>, May 2010. <a class="reference external" href="https://tools.ietf.org/html/rfc5869.html">https://tools.ietf.org/html/rfc5869.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc5915"></span>[RFC5915]</p></td>
<td><p>IETF, <em>Elliptic Curve Private Key Structure</em>, June 2010. <a class="reference external" href="https://tools.ietf.org/html/rfc5915.html">https://tools.ietf.org/html/rfc5915.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc6979"></span>[RFC6979]</p></td>
<td><p>IETF, <em>Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>, August 2013. <a class="reference external" href="https://tools.ietf.org/html/rfc6979.html">https://tools.ietf.org/html/rfc6979.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc7539"></span>[RFC7539]</p></td>
<td><p>IETF, <em>ChaCha20 and Poly1305 for IETF Protocols</em>, May 2015. <a class="reference external" href="https://tools.ietf.org/html/rfc7539.html">https://tools.ietf.org/html/rfc7539.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc7748"></span>[RFC7748]</p></td>
<td><p>IETF, <em>Elliptic Curves for Security</em>, January 2016. <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html">https://tools.ietf.org/html/rfc7748.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-rfc7919"></span>[RFC7919]</p></td>
<td><p>IETF, <em>Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS)</em>, August 2016. <a class="reference external" href="https://tools.ietf.org/html/rfc7919.html">https://tools.ietf.org/html/rfc7919.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-rfc8017"></span>[RFC8017]</p></td>
<td><p>IETF, <em>PKCS #1: RSA Cryptography Specifications Version 2.2</em>, November 2016. <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html">https://tools.ietf.org/html/rfc8017.html</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-ripemd"></span>[RIPEMD]</p></td>
<td><p>Dobbertin, Bosselaers and Preneel, <em>RIPEMD-160: A Strengthened Version of RIPEMD</em>, April 1996. <a class="reference external" href="https://homes.esat.kuleuven.be/~bosselae/ripemd160.html">https://homes.esat.kuleuven.be/~bosselae/ripemd160.html</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-sec1"></span>[SEC1]</p></td>
<td><p>Standards for Efficient Cryptography, <em>SEC 1: Elliptic Curve Cryptography</em>, May 2009. <a class="reference external" href="https://www.secg.org/sec1-v2.pdf">https://www.secg.org/sec1-v2.pdf</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-sec2"></span>[SEC2]</p></td>
<td><p>Standards for Efficient Cryptography, <em>SEC 2: Recommended Elliptic Curve Domain Parameters</em>, January 2010. <a class="reference external" href="https://www.secg.org/sec2-v2.pdf">https://www.secg.org/sec2-v2.pdf</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-sec2v1"></span>[SEC2v1]</p></td>
<td><p>Standards for Efficient Cryptography, <em>SEC 2: Recommended Elliptic Curve Domain Parameters, Version 1.0</em>, September 2000. <a class="reference external" href="https://www.secg.org/SEC2-Ver-1.0.pdf">https://www.secg.org/SEC2-Ver-1.0.pdf</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-sp800-38a"></span>[SP800-38A]</p></td>
<td><p>NIST, <em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em>, December 2001. <a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-38A">https://doi.org/10.6028/NIST.SP.800-38A</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-sp800-38b"></span>[SP800-38B]</p></td>
<td><p>NIST, <em>NIST Special Publication 800-38B: Recommendation for Block Cipher Modes of Operation: the CMAC Mode for Authentication</em>, May 2005. <a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-38B">https://doi.org/10.6028/NIST.SP.800-38B</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-sp800-38d"></span>[SP800-38D]</p></td>
<td><p>NIST, <em>NIST Special Publication 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>, November 2007. <a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-38D">https://doi.org/10.6028/NIST.SP.800-38D</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-sp800-56a"></span>[SP800-56A]</p></td>
<td><p>NIST, <em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em>, April 2018. <a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-56Ar3">https://doi.org/10.6028/NIST.SP.800-56Ar3</a></p></td>
</tr>
<tr class="row-odd"><td><p><span class="target" id="citation-sp800-67"></span>[SP800-67]</p></td>
<td><p>NIST, <em>NIST Special Publication 800-67: Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher</em>, November 2017. <a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-67r2">https://doi.org/10.6028/NIST.SP.800-67r2</a></p></td>
</tr>
<tr class="row-even"><td><p><span class="target" id="citation-x9-62"></span>[X9-62]</p></td>
<td><p>ANSI, <em>Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA)</em>. <a class="reference external" href="https://standards.globalspec.com/std/1955141/ANSI%20X9.62">https://standards.globalspec.com/std/1955141/ANSI%20X9.62</a></p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="terms-and-abbreviations">
<h2>Terms and abbreviations</h2>
<p>This document uses the following terms and abbreviations.</p>
<table class="longtable colwidths-given docutils align-default">
<colgroup>
<col style="width: 25%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Term</p></th>
<th class="head"><p>Meaning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><span><span class="target" id="term-aead"></span><span><span>AEAD</span></span></span></td>
<td><span>See <a class="reference internal" href="#term-authenticated-encryption-with-associated-data"><span class="term">Authenticated Encryption with Associated Data</span></a>.</span></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-algorithm"></span><span>Algorithm</span></span></td>
<td><p>A finite sequence of steps to perform a particular operation.</p>
<p>In this specification, an algorithm is a <a class="reference internal" href="#term-cipher"><span class="term">cipher</span></a> or a related function.
Other texts call this a cryptographic mechanism.</p>
</td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-api"></span><span>API</span></span></td>
<td><p>Application Programming Interface.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-asymmetric"></span><span>Asymmetric</span></span></td>
<td><p>See <a class="reference internal" href="#term-public-key-cryptography"><span class="term">Public-key cryptography</span></a>.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-authenticated-encryption-with-associated-data"></span><span>Authenticated Encryption with Associated Data (AEAD)</span></span></td>
<td><p>A type of encryption that
provides confidentiality and authenticity of data using <a class="reference internal" href="#term-symmetric"><span class="term">symmetric</span></a> keys.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-byte"></span><span>Byte</span></span></td>
<td><p>In this specification, a unit of storage comprising eight bits, also called an octet.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-cipher"></span><span>Cipher</span></span></td>
<td><p>An algorithm used for encryption or decryption with a <a class="reference internal" href="#term-symmetric"><span class="term">symmetric</span></a> key.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-cryptoprocessor"></span><span>Cryptoprocessor</span></span></td>
<td><p>The component that performs cryptographic operations.
A cryptoprocessor might contain a <a class="reference internal" href="#term-keystore"><span class="term">keystore</span></a> and countermeasures against a range of physical and timing attacks.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-hash"></span><span>Hash</span></span></td>
<td><p>A cryptographic hash function, or the value returned by such a function.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-hmac"></span><span>HMAC</span></span></td>
<td><p>A type of <a class="reference internal" href="#term-mac"><span class="term">MAC</span></a> that uses a cryptographic key with a <a class="reference internal" href="#term-hash"><span class="term">hash</span></a> function.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-implementation-defined"></span><span class="sc">Implementation defined</span></span></td>
<td><p>Behavior that is not defined by the architecture, but is defined and documented by individual implementations.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-initialization-vector"></span><span>Initialization vector (IV)</span></span></td>
<td><p>An additional input that is not part of the message. It is used to prevent an attacker from making any
correlation between cipher text and plain text.</p>
<p>This specification uses the term for such initial inputs
in all contexts. For example, the initial counter in CTR mode is called the IV.</p>
</td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-iv"></span><span><span>IV</span></span></span></td>
<td><span>See <a class="reference internal" href="#term-initialization-vector"><span class="term">Initialization vector</span></a>.</span></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-kdf"></span><span><span>KDF</span></span></span></td>
<td><span>See <a class="reference internal" href="#term-key-derivation-function"><span class="term">Key Derivation Function</span></a>.</span></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-key-agreement"></span><span>Key agreement</span></span></td>
<td><p>An algorithm for two or more parties to establish a common secret key.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-key-derivation-function"></span><span>Key Derivation Function (KDF)</span></span></td>
<td><p>Key Derivation Function. An algorithm for deriving keys from secret material.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-key-identifier"></span><span>Key identifier</span></span></td>
<td><p>A reference to a cryptographic key. Key identifiers in the PSA Crypto API are 32-bit integers.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-key-policy"></span><span>Key policy</span></span></td>
<td><p>Key metadata that describes and restricts what a key can be used for.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-key-size"></span><span>Key size</span></span></td>
<td><p>The size of a key as defined by common conventions for each key type.
For keys that are built from several numbers of strings, this is the size of a particular one of these numbers or strings.</p>
<p>This specification expresses key sizes in bits.</p>
</td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-key-type"></span><span>Key type</span></span></td>
<td><p>Key metadata that describes the structure and content of a key.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-keystore"></span><span>Keystore</span></span></td>
<td><p>A hardware or software component that protects, stores, and manages cryptographic keys.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-lifetime"></span><span>Lifetime</span></span></td>
<td><p>Key metadata that describes when a key is destroyed.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-mac"></span><span><span>MAC</span></span></span></td>
<td><span>See <a class="reference internal" href="#term-message-authentication-code"><span class="term">Message Authentication Code</span></a>.</span></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-message-authentication-code"></span><span>Message Authentication Code (MAC)</span></span></td>
<td><p>A short piece of information used to authenticate a message.
It is created and verified using a <a class="reference internal" href="#term-symmetric"><span class="term">symmetric</span></a> key.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-message-digest"></span><span>Message digest</span></span></td>
<td><p>A <a class="reference internal" href="#term-hash"><span class="term">hash</span></a> of a message. Used to determine if a message has been tampered.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-multi-part-operation"></span><span>Multi-part operation</span></span></td>
<td><p>An <a class="reference internal" href="#term-api"><span class="term">API</span></a> which splits a single cryptographic operation into a sequence of separate steps.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-non-extractable-key"></span><span>Non-extractable key</span></span></td>
<td><p>A key with a <a class="reference internal" href="#term-key-policy"><span class="term">key policy</span></a> that prevents it from being read by ordinary means.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-nonce"></span><span>Nonce</span></span></td>
<td><p>Used as an input for certain <a class="reference internal" href="#term-aead"><span class="term">AEAD</span></a> algorithms.
Nonces must not be reused with the same key because this can break a cryptographic protocol.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-persistent-key"></span><span>Persistent key</span></span></td>
<td><p>A key that is stored in protected non-volatile memory.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-psa"></span><span>PSA</span></span></td>
<td><p>Platform Security Architecture</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-public-key-cryptography"></span><span>Public-key cryptography</span></span></td>
<td><p>A type of cryptographic system that uses key pairs. A keypair consists of a (secret) private key
and a public key (not secret). A public key cryptographic algorithm can be used for key distribution
and for digital signatures.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-salt"></span><span>Salt</span></span></td>
<td><p>Used as an input for certain algorithms, such as key derivations.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-signature"></span><span>Signature</span></span></td>
<td><p>The output of a digital signature scheme that uses an <a class="reference internal" href="#term-asymmetric"><span class="term">asymmetric</span></a> keypair. Used to establish who produced a message.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-single-part-function"></span><span>Single-part function</span></span></td>
<td><p>An <a class="reference internal" href="#term-api"><span class="term">API</span></a> that implements the cryptographic operation in a single function call.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-specification-defined"></span><span class="sc">Specification defined</span></span></td>
<td><p>Behavior that is defined by this specification.</p></td>
</tr>
<tr class="row-odd"><td><span><span class="target" id="term-symmetric"></span><span>Symmetric</span></span></td>
<td><p>A type of cryptographic algorithm that uses a single key. A symmetric key can be used with
a block cipher or a stream cipher.</p></td>
</tr>
<tr class="row-even"><td><span><span class="target" id="term-volatile-key"></span><span>Volatile key</span></span></td>
<td><p>A key that has a short lifespan and is guaranteed not to exist after a restart of an application instance.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="potential-for-change">
<h2>Potential for change</h2>
<p>The contents of this specification are stable for version 1.0.</p>
<p>The following may change in updates to the version 1.0 specification:</p>
<ul class="simple">
<li><p>Small optional feature additions.</p></li>
<li><p>Clarifications.</p></li>
</ul>
<p>Significant additions, or any changes that affect the compatibility of the
interfaces defined in this specification will only be included in a new major or
minor version of the specification.</p>
</div>
<div class="section" id="conventions">
<h2>Conventions</h2>
<div class="section" id="typographical-conventions">
<h3>Typographical conventions</h3>
<p>The typographical conventions are:</p>
<dl>
<dt><em>italic</em></dt><dd><p>Introduces special terminology, and denotes citations.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">monospace</span></code></dt><dd><p>Used for assembler syntax descriptions, pseudocode, and source code examples.</p>
<p>Also used in the main text for instruction mnemonics and for references to
other items appearing in assembler syntax descriptions, pseudocode, and
source code examples.</p>
</dd>
<dt><span class="sc">small capitals</span></dt><dd><p>Used for some common terms such as <span class="sc">implementation defined</span>.</p>
<p>Used for a few terms that have specific technical meanings, and are included
in the <em>Terms and abbreviations</em>.</p>
</dd>
<dt><span class="issue">Red text</span></dt><dd><p>Indicates an open issue.</p>
</dd>
<dt><span class="anchor">Blue text</span></dt><dd><p>Indicates a link. This can be</p>
<ul class="simple">
<li><p>A cross-reference to another location within the document</p></li>
<li><p>A URL, for example <a class="reference external" href="http://infocenter.arm.com">http://infocenter.arm.com</a></p></li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="numbers">
<h3>Numbers</h3>
<p>Numbers are normally written in decimal. Binary numbers are preceded by 0b, and
hexadecimal numbers by <code class="docutils literal notranslate"><span class="pre">0x</span></code>.</p>
<p>In both cases, the prefix and the associated value are written in a monospace
font, for example <code class="docutils literal notranslate"><span class="pre">0xFFFF0000</span></code>. To improve readability, long numbers can be
written with an underscore separator between every four characters, for example
<code class="docutils literal notranslate"><span class="pre">0xFFFF_0000_0000_0000</span></code>. Ignore any underscores when interpreting the value of
a number.</p>
</div>
</div>
<div class="section" id="pseudocode-descriptions">
<h2>Pseudocode descriptions</h2>
<p>This book uses a form of pseudocode to provide precise descriptions of the
specified functionality. This pseudocode is written in a monospace font. The
pseudocode language is described in the Arm Architecture Reference Manual.</p>
</div>
<div class="section" id="assembler-syntax-descriptions">
<h2>Assembler syntax descriptions</h2>
<p>This book is not expected to contain assembler code or pseudo code examples.</p>
<p>Any code examples are shown in a <code class="docutils literal notranslate"><span class="pre">monospace</span></code> font.</p>
</div>
<div class="section" id="feedback">
<h2>Feedback</h2>
<p>Arm welcomes feedback on its documentation.</p>
<div class="section" id="feedback-on-this-book">
<h3>Feedback on this book</h3>
<p>If you have comments on the content of this book, send an e-mail to
<a class="reference external" href="mailto:arm&#46;psa-feedback&#37;&#52;&#48;arm&#46;com">arm<span>&#46;</span>psa-feedback<span>&#64;</span>arm<span>&#46;</span>com</a>. Give:</p>
<ul class="simple">
<li><p>The title (PSA Cryptography API).</p></li>
<li><p>The number and issue (IHI 0086 1.0.1).</p></li>
<li><p>The page numbers to which your comments apply.</p></li>
<li><p>The rule identifiers to which your comments apply, if applicable.</p></li>
<li><p>A concise explanation of your comments.</p></li>
</ul>
<p>Arm also welcomes general suggestions for additions and improvements.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"><h3><a href="index.html"><b>PSA Crypto API</b></a></h3>
IHI 0086<br/>
Non-confidential<br/>
Version 1.0.1
<span style="color: red; font-weight: bold;"></span>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">About this document</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#release-information">Release information</a></li>
<li class="toctree-l2"><a class="reference internal" href="#arm-non-confidential-document-licence-licence">Arm Non-Confidential Document Licence (“Licence”)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#references">References</a></li>
<li class="toctree-l2"><a class="reference internal" href="#terms-and-abbreviations">Terms and abbreviations</a></li>
<li class="toctree-l2"><a class="reference internal" href="#potential-for-change">Potential for change</a></li>
<li class="toctree-l2"><a class="reference internal" href="#conventions">Conventions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pseudocode-descriptions">Pseudocode descriptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#assembler-syntax-descriptions">Assembler syntax descriptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#feedback">Feedback</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="overview/intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview/goals.html">2. Design goals</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview/functionality.html">3. Functionality overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview/sample-arch.html">4. Sample architectures</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview/conventions.html">5. Library conventions</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview/implementation.html">6. Implementation considerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview/usage.html">7. Usage considerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/library/index.html">8. Library management reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/keys/index.html">9. Key management reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/ops/index.html">10. Cryptographic operation reference</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="appendix/example_header.html">Example header file</a></li>
<li class="toctree-l1"><a class="reference internal" href="appendix/specdef_values.html">Example macro implementations</a></li>
<li class="toctree-l1"><a class="reference internal" href="appendix/history.html">Changes to the API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="psa_c-identifiers.html">Index of API elements</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
</body>
</html>