| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <title>9.5. Key policies — PSA Crypto API 1.1.0 documentation</title> |
| <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" /> |
| <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" /> |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT: '../../', |
| VERSION: '1.1.0', |
| COLLAPSE_INDEX: false, |
| FILE_SUFFIX: '.html', |
| HAS_SOURCE: false, |
| SOURCELINK_SUFFIX: '.txt' |
| }; |
| </script> |
| <script type="text/javascript" src="../../_static/jquery.js"></script> |
| <script type="text/javascript" src="../../_static/underscore.js"></script> |
| <script type="text/javascript" src="../../_static/doctools.js"></script> |
| <link rel="author" title="About these documents" href="../../about.html" /> |
| <link rel="index" title="Index" href="../../genindex.html" /> |
| <link rel="search" title="Search" href="../../search.html" /> |
| <link rel="next" title="9.6. Key management functions" href="management.html" /> |
| <link rel="prev" title="9.4. Key identifiers" href="ids.html" /> |
| |
| <link rel="stylesheet" href="../../_static/custom.css" type="text/css" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> |
| |
| </head> |
| <body> |
| |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| <div class="body" role="main"> |
| |
| <div class="section" id="key-policies"> |
| <span id="key-policy"></span><h1>9.5. Key policies</h1> |
| <p>All keys have an associated policy that regulates which operations are permitted on the key. A key policy is composed of two elements:</p> |
| <ul class="simple"> |
| <li>A set of usage flags. See <a class="reference internal" href="#key-usage-flags"><span class="secref">Key usage flags</span></a>.</li> |
| <li>A specific algorithm that is permitted with the key. See <a class="reference internal" href="#permitted-algorithms"><span class="secref">Permitted algorithms</span></a>.</li> |
| </ul> |
| <p>The policy is part of the key attributes that are managed by a <a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object.</p> |
| <p>A highly constrained implementation might not be able to support all the policies that can be expressed through this interface. If an implementation cannot create a key with the required policy, it must return an appropriate error code when the key is created.</p> |
| <div class="section" id="permitted-algorithms"> |
| <span id="id1"></span><h2>9.5.1. Permitted algorithms</h2> |
| <p>The permitted algorithm is encoded using a algorithm identifier, as described in <a class="reference internal" href="../ops/algorithms.html#algorithms"><span class="secref">Algorithms</span></a>.</p> |
| <p>This specification only defines policies that restrict keys to a single algorithm, which is consistent with both common practice and security good practice.</p> |
| <p>The following algorithm policies are supported:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../ops/algorithms.html#c.PSA_ALG_NONE" title="PSA_ALG_NONE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_NONE</span></code></a> does not permit any cryptographic operation with the key. The key can still be used for non-cryptographic actions such as exporting, if permitted by the usage flags.</li> |
| <li>A specific algorithm value permits exactly that particular algorithm.</li> |
| <li>A signature algorithm constructed with <a class="reference internal" href="../ops/sign.html#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> permits the specified signature scheme with any hash algorithm. In addition, <a class="reference internal" href="../ops/sign.html#c.PSA_ALG_RSA_PKCS1V15_SIGN" title="PSA_ALG_RSA_PKCS1V15_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../ops/sign.html#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a><code class="docutils literal"><span class="pre">)</span></code> also permits the <a class="reference internal" href="../ops/sign.html#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> signature algorithm.</li> |
| <li>A raw key agreement algorithm also permits the specified key agreement scheme to be combined with any key derivation algorithm.</li> |
| <li>An algorithm built from <a class="reference internal" href="../ops/macs.html#c.PSA_ALG_AT_LEAST_THIS_LENGTH_MAC" title="PSA_ALG_AT_LEAST_THIS_LENGTH_MAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()</span></code></a> allows any MAC algorithm from the same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm.</li> |
| <li>An algorithm built from <a class="reference internal" href="../ops/aead.html#c.PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG" title="PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()</span></code></a> allows any AEAD algorithm from the same base class (for example, CCM) which computes or verifies a tag length greater than or equal to the length encoded in the wildcard algorithm.</li> |
| </ul> |
| <p>When a key is used in a cryptographic operation, the application must supply the algorithm to use for the operation. This algorithm is checked against the key’s permitted algorithm policy.</p> |
| <div class="section" id="psa_set_key_algorithm"> |
| <span id="c.psa_set_key_algorithm"></span><h3><code class="docutils literal"><span class="pre">psa_set_key_algorithm</span></code> (function)</h3> |
| <p>Declare the permitted algorithm policy for a key.</p> |
| <pre class="literal-block"> |
| void <a class="reference internal" href="#c.psa_set_key_algorithm" title="psa_set_key_algorithm">psa_set_key_algorithm</a>(<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes, |
| <a class="reference internal" href="../ops/algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt> |
| <dd>The attribute object to write to.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The permitted algorithm to write.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p> |
| <p class="rubric">Description</p> |
| <p>The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key.</p> |
| <p>This function overwrites any permitted algorithm policy previously set in <code class="docutils literal"><span class="pre">attributes</span></code>.</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like-macro.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_get_key_algorithm"> |
| <span id="c.psa_get_key_algorithm"></span><h3><code class="docutils literal"><span class="pre">psa_get_key_algorithm</span></code> (function)</h3> |
| <p>Retrieve the permitted algorithm policy from key attributes.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../ops/algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> <a class="reference internal" href="#c.psa_get_key_algorithm" title="psa_get_key_algorithm">psa_get_key_algorithm</a>(const <a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt> |
| <dd>The key attribute object to query.</dd> |
| </dl> |
| <p class="rubric">Returns: <a class="reference internal" href="../ops/algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="docutils literal"><span class="pre">psa_algorithm_t</span></code></a></p> |
| <p>The algorithm stored in the attribute object.</p> |
| <p class="rubric">Description</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like-macro.</p> |
| </div> |
| </div> |
| </div> |
| <div class="section" id="key-usage-flags"> |
| <span id="id2"></span><h2>9.5.2. Key usage flags</h2> |
| <p>The usage flags are encoded in a bitmask, which has the type <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_usage_t</span></code></a>. Four kinds of usage flag can be specified:</p> |
| <ul class="simple"> |
| <li>The extractable flag <a class="reference internal" href="#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code></a> determines whether the key material can be extracted.</li> |
| <li>The copyable flag <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> determines whether the key material can be copied into a new key, which can have a different lifetime or a more restrictive policy.</li> |
| <li>The cacheable flag <a class="reference internal" href="#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a> determines whether the implementation is permitted to retain non-essential copies of the key material in RAM. This policy only applies to persistent keys. See also <a class="reference internal" href="../../overview/implementation.html#key-material"><span class="secref">Managing key material</span></a>.</li> |
| <li>The other usage flags, for example, <a class="reference internal" href="#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> and <a class="reference internal" href="#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>, determine whether the corresponding operation is permitted on the key.</li> |
| </ul> |
| <div class="section" id="psa_key_usage_t"> |
| <span id="c.psa_key_usage_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_usage_t</span></code> (type)</h3> |
| <p>Encoding of permitted usage on a key.</p> |
| <pre class="literal-block"> |
| typedef uint32_t <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>; |
| </pre> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_EXPORT"> |
| <span id="c.PSA_KEY_USAGE_EXPORT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code> (macro)</h3> |
| <p>Permission to export the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT">PSA_KEY_USAGE_EXPORT</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000001) |
| </pre> |
| <p>This flag allows the use of <a class="reference internal" href="management.html#c.psa_export_key" title="psa_export_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_key()</span></code></a> to export a key from the cryptoprocessor. A public key or the public part of a key pair can always be exported regardless of the value of this permission flag.</p> |
| <p>This flag can also be required to copy a key using <a class="reference internal" href="management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a> outside of a secure element. See also <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a>.</p> |
| <p>If a key does not have export permission, implementations must not allow the key to be exported in plain form from the cryptoprocessor, whether through <a class="reference internal" href="management.html#c.psa_export_key" title="psa_export_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_key()</span></code></a> or through a proprietary interface. The key might still be exportable in a wrapped form, i.e. in a form where it is encrypted by another key.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_COPY"> |
| <span id="c.PSA_KEY_USAGE_COPY"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code> (macro)</h3> |
| <p>Permission to copy the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY">PSA_KEY_USAGE_COPY</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000002) |
| </pre> |
| <p>This flag allows the use of <a class="reference internal" href="management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a> to make a copy of the key with the same policy or a more restrictive policy.</p> |
| <p>For lifetimes for which the key is located in a secure element which enforce the non-exportability of keys, copying a key outside the secure element also requires the usage flag <a class="reference internal" href="#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code></a>. Copying the key inside the secure element is permitted with just <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> if the secure element supports it. For keys with the lifetime <a class="reference internal" href="lifetimes.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a> or <a class="reference internal" href="lifetimes.html#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a>, the usage flag <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> is sufficient to permit the copy.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_CACHE"> |
| <span id="c.PSA_KEY_USAGE_CACHE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code> (macro)</h3> |
| <p>Permission for the implementation to cache the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE">PSA_KEY_USAGE_CACHE</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000004) |
| </pre> |
| <p>This flag allows the implementation to make additional copies of the key material that are not in storage and not for the purpose of an ongoing operation. Applications can use it as a hint to keep the key around for repeated access.</p> |
| <p>An application can request that cached key material is removed from memory by calling <a class="reference internal" href="management.html#c.psa_purge_key" title="psa_purge_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_purge_key()</span></code></a>.</p> |
| <p>The presence of this usage flag when creating a key is a hint:</p> |
| <ul class="simple"> |
| <li>An implementation is not required to cache keys that have this usage flag.</li> |
| <li>An implementation must not report an error if it does not cache keys.</li> |
| </ul> |
| <p>If this usage flag is not present, the implementation must ensure key material is removed from memory as soon as it is not required for an operation or for maintenance of a volatile key.</p> |
| <p>This flag must be preserved when reading back the attributes for all keys, regardless of key type or implementation behavior.</p> |
| <p>See also <a class="reference internal" href="../../overview/implementation.html#key-material"><span class="secref">Managing key material</span></a>.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_ENCRYPT"> |
| <span id="c.PSA_KEY_USAGE_ENCRYPT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code> (macro)</h3> |
| <p>Permission to encrypt a message with the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT">PSA_KEY_USAGE_ENCRYPT</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000100) |
| </pre> |
| <p>This flag allows the key to be used for a symmetric encryption operation, for an AEAD encryption-and-authentication operation, or for an asymmetric encryption operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../ops/ciphers.html#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/ciphers.html#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/aead.html#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/aead.html#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/pke.html#c.psa_asymmetric_encrypt" title="psa_asymmetric_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_encrypt()</span></code></a></li> |
| </ul> |
| <p>For a key pair, this concerns the public key.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_DECRYPT"> |
| <span id="c.PSA_KEY_USAGE_DECRYPT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code> (macro)</h3> |
| <p>Permission to decrypt a message with the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT">PSA_KEY_USAGE_DECRYPT</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000200) |
| </pre> |
| <p>This flag allows the key to be used for a symmetric decryption operation, for an AEAD decryption-and-verification operation, or for an asymmetric decryption operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../ops/ciphers.html#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/ciphers.html#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/aead.html#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/aead.html#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/pke.html#c.psa_asymmetric_decrypt" title="psa_asymmetric_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_decrypt()</span></code></a></li> |
| </ul> |
| <p>For a key pair, this concerns the private key.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_SIGN_MESSAGE"> |
| <span id="c.PSA_KEY_USAGE_SIGN_MESSAGE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code> (macro)</h3> |
| <p>Permission to sign a message with the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE">PSA_KEY_USAGE_SIGN_MESSAGE</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000400) |
| </pre> |
| <p>This flag allows the key to be used for a MAC calculation operation or for an asymmetric message signature operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../ops/macs.html#c.psa_mac_compute" title="psa_mac_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_compute()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/macs.html#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/sign.html#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></li> |
| </ul> |
| <p>For a key pair, this concerns the private key.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_VERIFY_MESSAGE"> |
| <span id="c.PSA_KEY_USAGE_VERIFY_MESSAGE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code> (macro)</h3> |
| <p>Permission to verify a message signature with the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE">PSA_KEY_USAGE_VERIFY_MESSAGE</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000800) |
| </pre> |
| <p>This flag allows the key to be used for a MAC verification operation or for an asymmetric message signature verification operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../ops/macs.html#c.psa_mac_verify" title="psa_mac_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/macs.html#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/sign.html#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></li> |
| </ul> |
| <p>For a key pair, this concerns the public key.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_SIGN_HASH"> |
| <span id="c.PSA_KEY_USAGE_SIGN_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code> (macro)</h3> |
| <p>Permission to sign a message hash with the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH">PSA_KEY_USAGE_SIGN_HASH</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00001000) |
| </pre> |
| <p>This flag allows the key to be used to sign a message hash as part of an asymmetric signature operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used when calling <a class="reference internal" href="../ops/sign.html#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> |
| <p>This flag automatically sets <a class="reference internal" href="#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>: if an application sets the flag <a class="reference internal" href="#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> when creating a key, then the key always has the permissions conveyed by <a class="reference internal" href="#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>, and the flag <a class="reference internal" href="#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> will also be present when the application queries the usage flags of the key.</p> |
| <p>For a key pair, this concerns the private key.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_VERIFY_HASH"> |
| <span id="c.PSA_KEY_USAGE_VERIFY_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code> (macro)</h3> |
| <p>Permission to verify a message hash with the key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH">PSA_KEY_USAGE_VERIFY_HASH</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00002000) |
| </pre> |
| <p>This flag allows the key to be used to verify a message hash as part of an asymmetric signature verification operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used when calling <a class="reference internal" href="../ops/sign.html#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> |
| <p>This flag automatically sets <a class="reference internal" href="#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>: if an application sets the flag <a class="reference internal" href="#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> when creating a key, then the key always has the permissions conveyed by <a class="reference internal" href="#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>, and the flag <a class="reference internal" href="#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> will also be present when the application queries the usage flags of the key.</p> |
| <p>For a key pair, this concerns the public key.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_DERIVE"> |
| <span id="c.PSA_KEY_USAGE_DERIVE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code> (macro)</h3> |
| <p>Permission to derive other keys or produce a password hash from this key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE">PSA_KEY_USAGE_DERIVE</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00004000) |
| </pre> |
| <p>This flag allows the key to be used for a key derivation operation or for a key agreement operation, if otherwise permitted by the key’s type and policy.</p> |
| <p>This flag must be present on keys used with the following APIs:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../ops/ka.html#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a></li> |
| <li><a class="reference internal" href="../ops/ka.html#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_raw_key_agreement()</span></code></a></li> |
| </ul> |
| <p>If this flag is present on all keys used in calls to <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a> for a key derivation operation, then it permits calling <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> or <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> at the end of the operation.</p> |
| </div> |
| <div class="section" id="PSA_KEY_USAGE_VERIFY_DERIVATION"> |
| <span id="c.PSA_KEY_USAGE_VERIFY_DERIVATION"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_DERIVATION</span></code> (macro)</h3> |
| <p>Permission to verify the result of a key derivation, including password hashing.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_DERIVATION" title="PSA_KEY_USAGE_VERIFY_DERIVATION">PSA_KEY_USAGE_VERIFY_DERIVATION</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00008000) |
| </pre> |
| <p>This flag allows the key to be used in a key derivation operation, if otherwise permitted by the key’s type and policy.</p> |
| <p>This flag must be present on keys used with <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_verify_key" title="psa_key_derivation_verify_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_verify_key()</span></code></a>.</p> |
| <p>If this flag is present on all keys used in calls to <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a> for a key derivation operation, then it permits calling <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_verify_bytes" title="psa_key_derivation_verify_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_verify_bytes()</span></code></a> or <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_verify_key" title="psa_key_derivation_verify_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_verify_key()</span></code></a> at the end of the operation.</p> |
| </div> |
| <div class="section" id="psa_set_key_usage_flags"> |
| <span id="c.psa_set_key_usage_flags"></span><h3><code class="docutils literal"><span class="pre">psa_set_key_usage_flags</span></code> (function)</h3> |
| <p>Declare usage flags for a key.</p> |
| <pre class="literal-block"> |
| void <a class="reference internal" href="#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags">psa_set_key_usage_flags</a>(<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes, |
| <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a> usage_flags); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt> |
| <dd>The attribute object to write to.</dd> |
| <dt> <code class="docutils literal"><span class="pre">usage_flags</span></code></dt> |
| <dd>The usage flags to write.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p> |
| <p class="rubric">Description</p> |
| <p>Usage flags are part of a key’s policy. They encode what kind of operations are permitted on the key. For more details, see <a class="reference internal" href="#key-policy"><span class="secref">Key policies</span></a>.</p> |
| <p>This function overwrites any usage flags previously set in <code class="docutils literal"><span class="pre">attributes</span></code>.</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like-macro.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_get_key_usage_flags"> |
| <span id="c.psa_get_key_usage_flags"></span><h3><code class="docutils literal"><span class="pre">psa_get_key_usage_flags</span></code> (function)</h3> |
| <p>Retrieve the usage flags from key attributes.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a> <a class="reference internal" href="#c.psa_get_key_usage_flags" title="psa_get_key_usage_flags">psa_get_key_usage_flags</a>(const <a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt> |
| <dd>The key attribute object to query.</dd> |
| </dl> |
| <p class="rubric">Returns: <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t"><code class="docutils literal"><span class="pre">psa_key_usage_t</span></code></a></p> |
| <p>The usage flags stored in the attribute object.</p> |
| <p class="rubric">Description</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like-macro.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3> |
| IHI 0086<br/> |
| Non-confidential<br/> |
| Version 1.1.0 |
| <span style="color: red; font-weight: bold;"></span> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li> |
| </ul> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li> |
| <li class="toctree-l1 current"><a class="reference internal" href="index.html">9. Key management reference</a><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="attributes.html">9.1. Key attributes</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="types.html">9.2. Key types</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="lifetimes.html">9.3. Key lifetimes</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="ids.html">9.4. Key identifiers</a></li> |
| <li class="toctree-l2 current"><a class="current reference internal" href="#">9.5. Key policies</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#permitted-algorithms">9.5.1. Permitted algorithms</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#key-usage-flags">9.5.2. Key usage flags</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="management.html">9.6. Key management functions</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../ops/index.html">10. Cryptographic operation reference</a></li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/encodings.html">Algorithm and key type encoding</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/sra.html">Security Risk Assessment</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li> |
| </ul> |
| <div id="searchbox" style="display: none" role="search"> |
| <h3>Quick search</h3> |
| <form class="search" action="../../search.html" method="get"> |
| <div><input type="text" name="q" /></div> |
| <div><input type="submit" value="Go" /></div> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| <script type="text/javascript">$('#searchbox').show(0);</script> |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="footer"> |
| © 2018-2022, Arm Limited or its affiliates. All rights reserved. |
| |
| | |
| Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a> |
| & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a> |
| |
| </div> |
| |
| |
| |
| |
| </body> |
| </html> |