TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 132d88c4436af3a8ad535238788b3c8beb21e29d / . / docs / html / api / ops / sign.html
blob: 9a1cb86f898a0ee93ba66d5b282f5263b84ec62f [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]8 <title>10.7. Asymmetric signature &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]9 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
10 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
11 <script type="text/javascript">
12 var DOCUMENTATION_OPTIONS = {
13 URL_ROOT: '../../',
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]14 VERSION: '1.0.1',
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]17 HAS_SOURCE: false,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]18 SOURCELINK_SUFFIX: '.txt'
19 };
20 </script>
21 <script type="text/javascript" src="../../_static/jquery.js"></script>
22 <script type="text/javascript" src="../../_static/underscore.js"></script>
23 <script type="text/javascript" src="../../_static/doctools.js"></script>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]24 <link rel="author" title="About these documents" href="../../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]25 <link rel="index" title="Index" href="../../genindex.html" />
26 <link rel="search" title="Search" href="../../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]27 <link rel="next" title="10.8. Asymmetric encryption" href="pke.html" />
28 <link rel="prev" title="10.6. Key derivation" href="kdf.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]29
30 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
31
32 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
33
34 </head>
35 <body>
36
37
38 <div class="document">
39 <div class="documentwrapper">
40 <div class="bodywrapper">
41 <div class="body" role="main">
42
43 <div class="section" id="asymmetric-signature">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]44<span id="sign"></span><h1>10.7. Asymmetric signature</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]45<div class="section" id="asymmetric-signature-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]46<span id="sign-algorithms"></span><h2>10.7.1. Asymmetric signature algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]47<div class="section" id="PSA_ALG_RSA_PKCS1V15_SIGN">
48<span id="c.PSA_ALG_RSA_PKCS1V15_SIGN"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]49<p>The RSA PKCS#1 v1.5 message signature scheme, with hashing.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]50<pre class="literal-block">
51#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN" title="PSA_ALG_RSA_PKCS1V15_SIGN">PSA_ALG_RSA_PKCS1V15_SIGN</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
52</pre>
53<p class="rubric">Parameters</p>
54<dl class="docutils">
55<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]56<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]57</dl>
58<p class="rubric">Returns</p>
59<p>The corresponding RSA PKCS#1 v1.5 signature algorithm.</p>
60<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
61<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]62<p>This algorithm can be used with both the message and hash signature functions.</p>
63<p>This signature scheme is defined by <span><em>PKCS #1: RSA Cryptography Specifications Version 2.2</em> <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.2">§8.2</a> under the name RSASSA-PKCS1-v1_5.</p>
64<p>When used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>, the provided <code class="docutils literal"><span class="pre">hash</span></code> parameter is used as <em>H</em> from step 2 onwards in the message encoding algorithm <code class="docutils literal"><span class="pre">EMSA-PKCS1-V1_5-ENCODE()</span></code> in <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-9.2">§9.2</a>. <em>H</em> is usually the message digest, using the <code class="docutils literal"><span class="pre">hash_alg</span></code> hash algorithm.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]65</div>
66<div class="section" id="PSA_ALG_RSA_PKCS1V15_SIGN_RAW">
67<span id="c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]68<p>The raw RSA PKCS#1 v1.5 signature algorithm, without hashing.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]69<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]70#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000200)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]71</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]72<p>This algorithm can be only used with the <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> functions.</p>
73<p>This signature scheme is defined by <span><em>PKCS #1: RSA Cryptography Specifications Version 2.2</em> <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.2">§8.2</a> under the name RSASSA-PKCS1-v1_5.</p>
74<p>The <code class="docutils literal"><span class="pre">hash</span></code> parameter to <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> is used as <em>T</em> from step 3 onwards in the message encoding algorithm <code class="docutils literal"><span class="pre">EMSA-PKCS1-V1_5-ENCODE()</span></code> in <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-9.2">§9.2</a>. <em>T</em> is the DER encoding of the <em>DigestInfo</em> structure normally produced by step 2 in the message encoding algorithm.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]75</div>
76<div class="section" id="PSA_ALG_RSA_PSS">
77<span id="c.PSA_ALG_RSA_PSS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PSS</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]78<p>The RSA PSS message signature scheme, with hashing.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]79<pre class="literal-block">
80#define <a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS">PSA_ALG_RSA_PSS</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
81</pre>
82<p class="rubric">Parameters</p>
83<dl class="docutils">
84<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]85<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]86</dl>
87<p class="rubric">Returns</p>
88<p>The corresponding RSA PSS signature algorithm.</p>
89<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
90<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]91<p>This algorithm can be used with both the message and hash signature functions.</p>
92<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
93<p>This is the signature scheme defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.1">§8.1</a> under the name RSASSA-PSS, with the following options:</p>
94<ul class="simple">
95<li>The mask generation function is <em>MGF1</em> defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#appendix-B">Appendix B</a>.</li>
96<li>The salt length is equal to the length of the hash.</li>
97<li>The specified hash algorithm is used to hash the input message, to create the salted hash, and for the mask generation.</li>
98</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]99</div>
100<div class="section" id="PSA_ALG_ECDSA">
101<span id="c.PSA_ALG_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]102<p>The randomized ECDSA signature scheme, with hashing.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]103<pre class="literal-block">
104#define <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA">PSA_ALG_ECDSA</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
105</pre>
106<p class="rubric">Parameters</p>
107<dl class="docutils">
108<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]109<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]110</dl>
111<p class="rubric">Returns</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]112<p>The corresponding randomized ECDSA signature algorithm.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]113<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
114<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]115<p>This algorithm can be used with both the message and hash signature functions.</p>
116<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
117<div class="admonition note">
118<p class="first admonition-title">Note</p>
119<p>When based on the same hash algorithm, the verification operations for <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> are identical. A signature created using <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>. Similarly, a signature created using <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>.</p>
120<p class="last">In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.</p>
121</div>
122<p>This signature scheme is defined by <span><em>SEC 1: Elliptic Curve Cryptography</em> <a class="reference internal" href="../../about.html#citation-sec1"><span class="cite">[SEC1]</span></a></span>, and also by <span><em>Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA)</em> <a class="reference internal" href="../../about.html#citation-x9-62"><span class="cite">[X9-62]</span></a></span>, with a random per-message secret number <em>k</em>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]123<p>The representation of the signature as a byte string consists of the concatenation of the signature values <em>r</em> and <em>s</em>. Each of <em>r</em> and <em>s</em> is encoded as an <em>N</em>-octet string, where <em>N</em> is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first.</p>
124</div>
125<div class="section" id="PSA_ALG_ECDSA_ANY">
126<span id="c.PSA_ALG_ECDSA_ANY"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA_ANY</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]127<p>The randomized ECDSA signature scheme, without hashing.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]128<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]129#define <a class="reference internal" href="#c.PSA_ALG_ECDSA_ANY" title="PSA_ALG_ECDSA_ANY">PSA_ALG_ECDSA_ANY</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000600)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]130</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]131<p>This algorithm can be only used with the <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> functions.</p>
132<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
133<p>This is the same signature scheme as <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA()</span></code></a>, but without specifying a hash algorithm, and skipping the message hashing operation.</p>
134<p>This algorithm is only recommended to sign or verify a sequence of bytes that are an already-calculated hash. Note that the input is padded with zeros on the left or truncated on the right as required to fit the curve size.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]135</div>
136<div class="section" id="PSA_ALG_DETERMINISTIC_ECDSA">
137<span id="c.PSA_ALG_DETERMINISTIC_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]138<p>Deterministic ECDSA signature scheme, with hashing.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]139<pre class="literal-block">
140#define <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA">PSA_ALG_DETERMINISTIC_ECDSA</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
141</pre>
142<p class="rubric">Parameters</p>
143<dl class="docutils">
144<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]145<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]146</dl>
147<p class="rubric">Returns</p>
148<p>The corresponding deterministic ECDSA signature algorithm.</p>
149<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
150<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]151<p>This algorithm can be used with both the message and hash signature functions.</p>
152<div class="admonition note">
153<p class="first admonition-title">Note</p>
154<p>When based on the same hash algorithm, the verification operations for <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> are identical. A signature created using <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>. Similarly, a signature created using <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>.</p>
155<p class="last">In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.</p>
156</div>
157<p>This is the deterministic ECDSA signature scheme defined by <span><em>Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)</em> <a class="reference internal" href="../../about.html#citation-rfc6979"><span class="cite">[RFC6979]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]158<p>The representation of a signature is the same as with <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]159</div>
160</div>
161<div class="section" id="asymmetric-signature-functions">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]162<h2>10.7.2. Asymmetric signature functions</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]163<div class="section" id="psa_sign_message">
164<span id="c.psa_sign_message"></span><h3><code class="docutils literal"><span class="pre">psa_sign_message</span></code> (function)</h3>
165<p>Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.</p>
166<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]167<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
168 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]169 const uint8_t * input,
170 size_t input_length,
171 uint8_t * signature,
172 size_t signature_size,
173 size_t * signature_length);
174</pre>
175<p class="rubric">Parameters</p>
176<dl class="docutils">
177<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]178<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]179<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
180<dd>An asymmetric signature algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_MESSAGE" title="PSA_ALG_IS_SIGN_MESSAGE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
181<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
182<dd>The input message to sign.</dd>
183<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
184<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
185<dt> <code class="docutils literal"><span class="pre">signature</span></code></dt>
186<dd>Buffer where the signature is to be written.</dd>
187<dt> <code class="docutils literal"><span class="pre">signature_size</span></code></dt>
188<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer in bytes.
189This must be appropriate for the selected algorithm and key:</p>
190<ul class="last simple">
191<li>The required signature size is <a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">key_bits</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> and <code class="docutils literal"><span class="pre">key_bits</span></code> are the type and bit-size respectively of <code class="docutils literal"><span class="pre">key</span></code>.</li>
192<li><a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> evaluates to the maximum signature size of any supported signature algorithm.</li>
193</ul>
194</dd>
195<dt> <code class="docutils literal"><span class="pre">signature_length</span></code></dt>
196<dd>On success, the number of bytes that make up the returned signature value.</dd>
197</dl>
198<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
199<dl class="docutils">
200<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
201<dd></dd>
202<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
203<dd></dd>
204<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]205<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]206<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
207<dd>The size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer is too small.
208<a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
209<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
210<dd></dd>
211<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
212<dd></dd>
213<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
214<dd></dd>
215<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
216<dd></dd>
217<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
218<dd></dd>
219<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
220<dd></dd>
221<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
222<dd></dd>
223<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
224<dd></dd>
225<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
226<dd></dd>
227<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_ENTROPY" title="PSA_ERROR_INSUFFICIENT_ENTROPY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_ENTROPY</span></code></a></dt>
228<dd></dd>
229<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
230<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
231</dl>
232<p class="rubric">Description</p>
233<div class="admonition note">
234<p class="first admonition-title">Note</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]235<p class="last">To perform a multi-part hash-and-sign signature algorithm, first use a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> and then pass the resulting hash to <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a>. <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> can be used to determine the hash algorithm to use.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]236</div>
237</div>
238<div class="section" id="psa_verify_message">
239<span id="c.psa_verify_message"></span><h3><code class="docutils literal"><span class="pre">psa_verify_message</span></code> (function)</h3>
240<p>Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.</p>
241<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]242<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message">psa_verify_message</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
243 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]244 const uint8_t * input,
245 size_t input_length,
246 const uint8_t * signature,
247 size_t signature_length);
248</pre>
249<p class="rubric">Parameters</p>
250<dl class="docutils">
251<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]252<dd>Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]253<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
254<dd>An asymmetric signature algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_MESSAGE" title="PSA_ALG_IS_SIGN_MESSAGE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
255<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
256<dd>The message whose signature is to be verified.</dd>
257<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
258<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
259<dt> <code class="docutils literal"><span class="pre">signature</span></code></dt>
260<dd>Buffer containing the signature to verify.</dd>
261<dt> <code class="docutils literal"><span class="pre">signature_length</span></code></dt>
262<dd>Size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer in bytes.</dd>
263</dl>
264<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
265<dl class="docutils">
266<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
267<dd>The signature is valid.</dd>
268<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
269<dd></dd>
270<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]271<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]272<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
273<dd>The calculation was performed successfully, but the passed signature is not a valid signature.</dd>
274<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
275<dd></dd>
276<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
277<dd></dd>
278<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
279<dd></dd>
280<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
281<dd></dd>
282<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
283<dd></dd>
284<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
285<dd></dd>
286<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
287<dd></dd>
288<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
289<dd></dd>
290<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
291<dd></dd>
292<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
293<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
294</dl>
295<p class="rubric">Description</p>
296<div class="admonition note">
297<p class="first admonition-title">Note</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]298<p class="last">To perform a multi-part hash-and-sign signature verification algorithm, first use a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> to hash the message and then pass the resulting hash to <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>. <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> can be used to determine the hash algorithm to use.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]299</div>
300</div>
301<div class="section" id="psa_sign_hash">
302<span id="c.psa_sign_hash"></span><h3><code class="docutils literal"><span class="pre">psa_sign_hash</span></code> (function)</h3>
303<p>Sign an already-calculated hash with a private key.</p>
304<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]305<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash">psa_sign_hash</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
306 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]307 const uint8_t * hash,
308 size_t hash_length,
309 uint8_t * signature,
310 size_t signature_size,
311 size_t * signature_length);
312</pre>
313<p class="rubric">Parameters</p>
314<dl class="docutils">
315<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]316<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]317<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
318<dd>An asymmetric signature algorithm that separates the hash and sign operations (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
319<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
320<dd>The input to sign. This is usually the hash of a message. See the detailed description of this function and the description of individual signature algorithms for a detailed description of acceptable inputs.</dd>
321<dt> <code class="docutils literal"><span class="pre">hash_length</span></code></dt>
322<dd>Size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer in bytes.</dd>
323<dt> <code class="docutils literal"><span class="pre">signature</span></code></dt>
324<dd>Buffer where the signature is to be written.</dd>
325<dt> <code class="docutils literal"><span class="pre">signature_size</span></code></dt>
326<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer in bytes.
327This must be appropriate for the selected algorithm and key:</p>
328<ul class="last simple">
329<li>The required signature size is <a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">key_bits</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> and <code class="docutils literal"><span class="pre">key_bits</span></code> are the type and bit-size respectively of <code class="docutils literal"><span class="pre">key</span></code>.</li>
330<li><a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> evaluates to the maximum signature size of any supported signature algorithm.</li>
331</ul>
332</dd>
333<dt> <code class="docutils literal"><span class="pre">signature_length</span></code></dt>
334<dd>On success, the number of bytes that make up the returned signature value.</dd>
335</dl>
336<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
337<dl class="docutils">
338<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
339<dd></dd>
340<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
341<dd></dd>
342<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]343<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a> flag, or it does not permit the requested algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]344<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
345<dd>The size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer is too small.
346<a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
347<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
348<dd></dd>
349<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
350<dd></dd>
351<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
352<dd></dd>
353<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
354<dd></dd>
355<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
356<dd></dd>
357<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
358<dd></dd>
359<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
360<dd></dd>
361<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
362<dd></dd>
363<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
364<dd></dd>
365<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_ENTROPY" title="PSA_ERROR_INSUFFICIENT_ENTROPY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_ENTROPY</span></code></a></dt>
366<dd></dd>
367<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
368<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
369</dl>
370<p class="rubric">Description</p>
371<p>With most signature mechanisms that follow the hash-and-sign paradigm, the hash input to this function is the hash of the message to sign. The hash algorithm is encoded in the signature algorithm.</p>
372<p>Some hash-and-sign mechanisms apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. The current version of this specification defines one such signature algorithm: <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code></a>.</p>
373<div class="admonition note">
374<p class="first admonition-title">Note</p>
375<p class="last">To perform a hash-and-sign algorithm, the hash must be calculated before passing it to this function. This can be done by calling <a class="reference internal" href="hashes.html#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a> or with a multi-part hash operation. Alternatively, to hash and sign a message in a single call, use <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a>.</p>
376</div>
377</div>
378<div class="section" id="psa_verify_hash">
379<span id="c.psa_verify_hash"></span><h3><code class="docutils literal"><span class="pre">psa_verify_hash</span></code> (function)</h3>
380<p>Verify the signature of a hash or short message using a public key.</p>
381<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]382<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash">psa_verify_hash</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
383 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]384 const uint8_t * hash,
385 size_t hash_length,
386 const uint8_t * signature,
387 size_t signature_length);
388</pre>
389<p class="rubric">Parameters</p>
390<dl class="docutils">
391<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]392<dd>Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]393<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
394<dd>An asymmetric signature algorithm that separates the hash and sign operations (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
395<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
396<dd>The input whose signature is to be verified. This is usually the hash of a message. See the detailed description of this function and the description of individual signature algorithms for a detailed description of acceptable inputs.</dd>
397<dt> <code class="docutils literal"><span class="pre">hash_length</span></code></dt>
398<dd>Size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer in bytes.</dd>
399<dt> <code class="docutils literal"><span class="pre">signature</span></code></dt>
400<dd>Buffer containing the signature to verify.</dd>
401<dt> <code class="docutils literal"><span class="pre">signature_length</span></code></dt>
402<dd>Size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer in bytes.</dd>
403</dl>
404<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
405<dl class="docutils">
406<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
407<dd>The signature is valid.</dd>
408<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
409<dd></dd>
410<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]411<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a> flag, or it does not permit the requested algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]412<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
413<dd>The calculation was performed successfully, but the passed signature is not a valid signature.</dd>
414<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
415<dd></dd>
416<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
417<dd></dd>
418<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
419<dd></dd>
420<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
421<dd></dd>
422<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
423<dd></dd>
424<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
425<dd></dd>
426<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
427<dd></dd>
428<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
429<dd></dd>
430<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
431<dd></dd>
432<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
433<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
434</dl>
435<p class="rubric">Description</p>
436<p>With most signature mechanisms that follow the hash-and-sign paradigm, the hash input to this function is the hash of the message to sign. The hash algorithm is encoded in the signature algorithm.</p>
437<p>Some hash-and-sign mechanisms apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. The current version of this specification defines one such signature algorithm: <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code></a>.</p>
438<div class="admonition note">
439<p class="first admonition-title">Note</p>
440<p class="last">To perform a hash-and-sign verification algorithm, the hash must be calculated before passing it to this function. This can be done by calling <a class="reference internal" href="hashes.html#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a> or with a multi-part hash operation. Alternatively, to hash and verify a message signature in a single call, use <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a>.</p>
441</div>
442</div>
443</div>
444<div class="section" id="support-macros">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]445<h2>10.7.3. Support macros</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]446<div class="section" id="PSA_ALG_IS_SIGN_MESSAGE">
447<span id="c.PSA_ALG_IS_SIGN_MESSAGE"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code> (macro)</h3>
448<p>Whether the specified algorithm is a signature algorithm that can be used with <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a>.</p>
449<pre class="literal-block">
450#define <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_MESSAGE" title="PSA_ALG_IS_SIGN_MESSAGE">PSA_ALG_IS_SIGN_MESSAGE</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
451</pre>
452<p class="rubric">Parameters</p>
453<dl class="docutils">
454<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]455<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]456</dl>
457<p class="rubric">Returns</p>
458<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can be used to sign a message. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can only be used to sign an already-calculated hash. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a signature algorithm. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
459</div>
460<div class="section" id="PSA_ALG_IS_SIGN_HASH">
461<span id="c.PSA_ALG_IS_SIGN_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code> (macro)</h3>
462<p>Whether the specified algorithm is a signature algorithm that can be used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>.</p>
463<pre class="literal-block">
464#define <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH">PSA_ALG_IS_SIGN_HASH</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
465</pre>
466<p class="rubric">Parameters</p>
467<dl class="docutils">
468<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]469<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]470</dl>
471<p class="rubric">Returns</p>
472<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can be used to sign a hash. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can only be used to sign a message. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a signature algorithm. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
473</div>
474<div class="section" id="PSA_ALG_IS_RSA_PKCS1V15_SIGN">
475<span id="c.PSA_ALG_IS_RSA_PKCS1V15_SIGN"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PKCS1V15_SIGN</span></code> (macro)</h3>
476<p>Whether the specified algorithm is an RSA PKCS#1 v1.5 signature algorithm.</p>
477<pre class="literal-block">
478#define <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PKCS1V15_SIGN" title="PSA_ALG_IS_RSA_PKCS1V15_SIGN">PSA_ALG_IS_RSA_PKCS1V15_SIGN</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
479</pre>
480<p class="rubric">Parameters</p>
481<dl class="docutils">
482<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]483<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]484</dl>
485<p class="rubric">Returns</p>
486<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA PKCS#1 v1.5 signature algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
487<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
488</div>
489<div class="section" id="PSA_ALG_IS_RSA_PSS">
490<span id="c.PSA_ALG_IS_RSA_PSS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS</span></code> (macro)</h3>
491<p>Whether the specified algorithm is an RSA PSS signature algorithm.</p>
492<pre class="literal-block">
493#define <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PSS" title="PSA_ALG_IS_RSA_PSS">PSA_ALG_IS_RSA_PSS</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
494</pre>
495<p class="rubric">Parameters</p>
496<dl class="docutils">
497<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]498<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]499</dl>
500<p class="rubric">Returns</p>
501<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA PSS signature algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
502<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
503</div>
504<div class="section" id="PSA_ALG_IS_ECDSA">
505<span id="c.PSA_ALG_IS_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_ECDSA</span></code> (macro)</h3>
506<p>Whether the specified algorithm is ECDSA.</p>
507<pre class="literal-block">
508#define <a class="reference internal" href="#c.PSA_ALG_IS_ECDSA" title="PSA_ALG_IS_ECDSA">PSA_ALG_IS_ECDSA</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
509</pre>
510<p class="rubric">Parameters</p>
511<dl class="docutils">
512<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]513<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]514</dl>
515<p class="rubric">Returns</p>
516<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
517<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
518</div>
519<div class="section" id="PSA_ALG_IS_DETERMINISTIC_ECDSA">
520<span id="c.PSA_ALG_IS_DETERMINISTIC_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_DETERMINISTIC_ECDSA</span></code> (macro)</h3>
521<p>Whether the specified algorithm is deterministic ECDSA.</p>
522<pre class="literal-block">
523#define <a class="reference internal" href="#c.PSA_ALG_IS_DETERMINISTIC_ECDSA" title="PSA_ALG_IS_DETERMINISTIC_ECDSA">PSA_ALG_IS_DETERMINISTIC_ECDSA</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
524</pre>
525<p class="rubric">Parameters</p>
526<dl class="docutils">
527<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]528<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]529</dl>
530<p class="rubric">Returns</p>
531<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a deterministic ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
532<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
533<p class="rubric">Description</p>
534<p>See also <a class="reference internal" href="#c.PSA_ALG_IS_ECDSA" title="PSA_ALG_IS_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_ECDSA()</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_IS_RANDOMIZED_ECDSA" title="PSA_ALG_IS_RANDOMIZED_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_RANDOMIZED_ECDSA()</span></code></a>.</p>
535</div>
536<div class="section" id="PSA_ALG_IS_RANDOMIZED_ECDSA">
537<span id="c.PSA_ALG_IS_RANDOMIZED_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RANDOMIZED_ECDSA</span></code> (macro)</h3>
538<p>Whether the specified algorithm is randomized ECDSA.</p>
539<pre class="literal-block">
540#define <a class="reference internal" href="#c.PSA_ALG_IS_RANDOMIZED_ECDSA" title="PSA_ALG_IS_RANDOMIZED_ECDSA">PSA_ALG_IS_RANDOMIZED_ECDSA</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
541</pre>
542<p class="rubric">Parameters</p>
543<dl class="docutils">
544<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]545<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]546</dl>
547<p class="rubric">Returns</p>
548<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a randomized ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
549<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
550<p class="rubric">Description</p>
551<p>See also <a class="reference internal" href="#c.PSA_ALG_IS_ECDSA" title="PSA_ALG_IS_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_ECDSA()</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_IS_DETERMINISTIC_ECDSA" title="PSA_ALG_IS_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_DETERMINISTIC_ECDSA()</span></code></a>.</p>
552</div>
553<div class="section" id="PSA_ALG_IS_HASH_AND_SIGN">
554<span id="c.PSA_ALG_IS_HASH_AND_SIGN"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN</span></code> (macro)</h3>
555<p>Whether the specified algorithm is a hash-and-sign algorithm that signs exactly the hash value.</p>
556<pre class="literal-block">
557#define <a class="reference internal" href="#c.PSA_ALG_IS_HASH_AND_SIGN" title="PSA_ALG_IS_HASH_AND_SIGN">PSA_ALG_IS_HASH_AND_SIGN</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
558</pre>
559<p class="rubric">Parameters</p>
560<dl class="docutils">
561<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]562<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]563</dl>
564<p class="rubric">Returns</p>
565<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a hash-and-sign algorithm that signs exactly the hash value, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
566<p class="rubric">Description</p>
567<p>This macro identifies algorithms that can be used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> that use the exact message hash value as an input the signature operation. This excludes hash-and-sign algorithms that require a encoded or modified hash for the signature step in the algorithm, such as <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code></a>.</p>
568</div>
569<div class="section" id="PSA_ALG_ANY_HASH">
570<span id="c.PSA_ALG_ANY_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]571<p>When setting a hash-and-sign algorithm in a key policy, permit any hash algorithm.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]572<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]573#define <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH">PSA_ALG_ANY_HASH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x020000ff)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]574</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]575<p>This value can be used to form the permitted algorithm attribute of a key policy for a signature algorithm that is parametrized by a hash. A key with this policy can then be used to perform operations using the same signature algorithm parametrized with any supported hash.
576A signature algorithm created using this macro is a wildcard algorithm, and <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_WILDCARD" title="PSA_ALG_IS_WILDCARD"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_WILDCARD()</span></code></a> will return true.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]577<p>This value must not be used to build other algorithms that are parametrized over a hash. For any valid use of this macro to build an algorithm <code class="docutils literal"><span class="pre">alg</span></code>, <a class="reference internal" href="#c.PSA_ALG_IS_HASH_AND_SIGN" title="PSA_ALG_IS_HASH_AND_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]578<p>This value must not be used to build an algorithm specification to perform an operation. It is only valid for setting the permitted algorithm in a key policy.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]579<p class="rubric">Usage</p>
580<p>For example, suppose that <code class="docutils literal"><span class="pre">PSA_xxx_SIGNATURE</span></code> is one of the following macros:</p>
581<ul class="simple">
582<li><a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN" title="PSA_ALG_RSA_PKCS1V15_SIGN"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code></a></li>
583<li><a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS</span></code></a></li>
584<li><a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a></li>
585<li><a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a></li>
586</ul>
587<p>The following sequence of operations shows how <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> can be used in a key policy:</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]588<ol class="arabic">
589<li><p class="first">Set the key usage flags using <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a>, for example:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]590<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]591<a class="reference internal" href="../keys/policy.html#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags">psa_set_key_usage_flags</a>(&amp;attributes, <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE">PSA_KEY_USAGE_SIGN_MESSAGE</a>); // or VERIFY_MESSAGE
592<a class="reference internal" href="../keys/policy.html#c.psa_set_key_algorithm" title="psa_set_key_algorithm">psa_set_key_algorithm</a>(&amp;attributes, PSA_xxx_SIGNATURE(<a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH">PSA_ALG_ANY_HASH</a>));
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]593</pre>
594</li>
595<li><p class="first">Import or generate key material.</p>
596</li>
597<li><p class="first">Call <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> or <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a>, passing an algorithm built from <code class="docutils literal"><span class="pre">PSA_xxx_SIGNATURE</span></code> and a specific hash. Each call to sign or verify a message can use a different hash algorithm.</p>
598<pre class="literal-block">
599<a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(key, PSA_xxx_SIGNATURE(<a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256">PSA_ALG_SHA_256</a>), ...);
600<a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(key, PSA_xxx_SIGNATURE(<a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_512" title="PSA_ALG_SHA_512">PSA_ALG_SHA_512</a>), ...);
601<a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(key, PSA_xxx_SIGNATURE(<a class="reference internal" href="hashes.html#c.PSA_ALG_SHA3_256" title="PSA_ALG_SHA3_256">PSA_ALG_SHA3_256</a>), ...);
602</pre>
603</li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]604</ol>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]605</div>
606<div class="section" id="PSA_SIGN_OUTPUT_SIZE">
607<span id="c.PSA_SIGN_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE</span></code> (macro)</h3>
608<p>Sufficient signature buffer size for <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a>.</p>
609<pre class="literal-block">
610#define <a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE">PSA_SIGN_OUTPUT_SIZE</a>(key_type, key_bits, alg) \
611 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
612</pre>
613<p class="rubric">Parameters</p>
614<dl class="docutils">
615<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
616<dd>An asymmetric key type. This can be a key pair type or a public key type.</dd>
617<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
618<dd>The size of the key in bits.</dd>
619<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
620<dd>The signature algorithm.</dd>
621</dl>
622<p class="rubric">Returns</p>
623<p>If the parameters are valid and supported, return a buffer size in bytes that guarantees that <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> will not fail with <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a>. If the parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or <code class="docutils literal"><span class="pre">0</span></code>. If the parameters are not valid, the return value is unspecified.</p>
624<p class="rubric">Description</p>
625<p>This macro returns a sufficient buffer size for a signature using a key of the specified type and size, with the specified algorithm. Note that the actual size of the signature might be smaller, as some algorithms produce a variable-size signature.</p>
626<div class="admonition warning">
627<p class="first admonition-title">Warning</p>
628<p class="last">This function might evaluate its arguments multiple times or zero times. Providing arguments that have side effects will result in implementation-specific behavior, and is non-portable.</p>
629</div>
630<p>See also <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a>.</p>
631</div>
632<div class="section" id="PSA_SIGNATURE_MAX_SIZE">
633<span id="c.PSA_SIGNATURE_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code> (macro)</h3>
634<p>Maximum size of an asymmetric signature.</p>
635<pre class="literal-block">
636#define <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE">PSA_SIGNATURE_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
637</pre>
638<p>This macro must expand to a compile-time constant integer.
639It is recommended that this value is the maximum size of an asymmetric signature supported by the implementation, in bytes. The value must not be smaller than this maximum.</p>
640<p>See also <a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE()</span></code></a>.</p>
641</div>
642</div>
643</div>
644
645
646 </div>
647 </div>
648 </div>
649 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]650 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
651IHI 0086<br/>
652Non-confidential<br/>
653Version 1.0.1
654<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]655<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]656<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]657</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]658<ul class="current">
659<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
660<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
661<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
662<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
663<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
664<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
665<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
666<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
667<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
668<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
669<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
670<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
671<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
672<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
673<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
674<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
675<li class="toctree-l2 current"><a class="current reference internal" href="#">10.7. Asymmetric signature</a><ul>
676<li class="toctree-l3"><a class="reference internal" href="#asymmetric-signature-algorithms">10.7.1. Asymmetric signature algorithms</a></li>
677<li class="toctree-l3"><a class="reference internal" href="#asymmetric-signature-functions">10.7.2. Asymmetric signature functions</a></li>
678<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.7.3. Support macros</a></li>
679</ul>
680</li>
681<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
682<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
683<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
684</ul>
685</li>
686</ul>
687<ul>
688<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
689<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
690<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
691</ul>
692<ul>
693<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
694</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]695<div id="searchbox" style="display: none" role="search">
696 <h3>Quick search</h3>
697 <form class="search" action="../../search.html" method="get">
698 <div><input type="text" name="q" /></div>
699 <div><input type="submit" value="Go" /></div>
700 <input type="hidden" name="check_keywords" value="yes" />
701 <input type="hidden" name="area" value="default" />
702 </form>
703</div>
704<script type="text/javascript">$('#searchbox').show(0);</script>
705 </div>
706 </div>
707 <div class="clearer"></div>
708 </div>
709 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]710 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]711
712 |
713 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
714 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
715
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]716 </div>
717
718
719
720
721 </body>
722</html>