.. _algorithms:

Algorithms
==========

Algorithm categories
--------------------

.. macro:: PSA_ALG_NONE
    :definition: ((psa_algorithm_t)0)

    .. summary::
        An invalid algorithm identifier value.

    Zero is not the encoding of any algorithm.

.. macro:: PSA_ALG_IS_HASH
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm is a hash algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is a hash algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    See :title:`hash-algorithms` for a list of defined hash algorithms.

.. macro:: PSA_ALG_IS_MAC
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm is a MAC algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is a MAC algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    See :title:`mac-algorithms` for a list of defined MAC algorithms.

.. macro:: PSA_ALG_IS_CIPHER
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm is a symmetric cipher algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is a symmetric cipher algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    See :title:`cipher-algorithms` for a list of defined cipher algorithms.

.. macro:: PSA_ALG_IS_AEAD
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm is an authenticated encryption with associated data (AEAD) algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is an AEAD algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    See :title:`aead-algorithms` for a list of defined AEAD algorithms.

.. macro:: PSA_ALG_IS_SIGN
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm is a public-key signature algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is a public-key signature algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    See :title:`sign-algorithms` for a list of defined signature algorithms.

.. macro:: PSA_ALG_IS_ASYMMETRIC_ENCRYPTION
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm is a public-key encryption algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is a public-key encryption algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    See :title:`asymmetric-encryption-algorithms` for a list of defined asymmetric encryption algorithms.

.. macro:: PSA_ALG_IS_KEY_AGREEMENT
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm is a key agreement algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is a key agreement algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    See :title:`key-agreement-algorithms` for a list of defined key agreement algorithms.

.. macro:: PSA_ALG_IS_KEY_DERIVATION
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm is a key derivation algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is a key derivation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    See :title:`key-derivation-algorithms` for a list of defined key derivation algorithms.

.. macro:: PSA_ALG_IS_WILDCARD
    :definition: /* specification-defined value */

    .. summary::
        Whether the specified algorithm encoding is a wildcard.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        ``1`` if ``alg`` is a wildcard algorithm encoding.

        ``0`` if ``alg`` is a non-wildcard algorithm encoding that is suitable for an operation.

        This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.

    Wildcard algorithm values can only be used to set the usage algorithm field in a policy, wildcard values cannot be used to perform an operation.

    See `PSA_ALG_ANY_HASH` for example of how a wildcard algorithm can be used in a key policy.

.. macro:: PSA_ALG_GET_HASH
    :definition: /* specification-defined value */

    .. summary::
        Get the hash used by a composite algorithm.

    .. param:: alg
        An algorithm identifier (value of type `psa_algorithm_t`).

    .. return::
        The underlying hash algorithm if ``alg`` is a composite algorithm that uses a hash algorithm.

        `PSA_ALG_NONE` if ``alg`` is not a composite algorithm that uses a hash.

    The following composite algorithms require a hash algorithm:

    - `PSA_ALG_ECDSA()`
    - `PSA_ALG_HKDF()`
    - `PSA_ALG_HMAC()`
    - `PSA_ALG_RSA_OAEP()`
    - `PSA_ALG_IS_RSA_PKCS1V15_SIGN()`
    - `PSA_ALG_RSA_PSS()`
    - `PSA_ALG_TLS12_PRF()`
    - `PSA_ALG_TLS12_PSK_TO_MS()`

Attribute accessors
-------------------

.. function:: psa_set_key_algorithm

    .. summary::
        Declare the permitted algorithm policy for a key.

    .. param:: psa_key_attributes_t * attributes
        The attribute object to write to.
    .. param:: psa_algorithm_t alg
        The permitted algorithm policy to write.

    .. return:: void

    The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key. The following algorithm policies are supported:

    * `PSA_ALG_NONE` does not allow 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.
    * An algorithm value permits this particular algorithm.
    * An algorithm wildcard built from `PSA_ALG_ANY_HASH` allows the specified signature scheme with any hash algorithm.

    This function overwrites any algorithm policy previously set in ``attributes``.

    .. admonition:: Implementation note

        This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:

        - This function can be declared as ``static`` or ``inline``, instead of using the default external linkage.
        - This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.

.. function:: psa_get_key_algorithm

    .. summary::
        Retrieve the algorithm policy from key attributes.

    .. param:: const psa_key_attributes_t * attributes
        The key attribute object to query.

    .. return:: psa_algorithm_t
        The algorithm stored in the attribute object.

    .. admonition:: Implementation note

        This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:

        - This function can be declared as ``static`` or ``inline``, instead of using the default external linkage.
        - This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.
