.. _key-types:

Key types
=========

Key categories
--------------

.. macro:: PSA_KEY_TYPE_NONE
    :definition: ((psa_key_type_t)0x0000)

    .. summary::
        An invalid key type value.

    Zero is not the encoding of any key type.

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

    .. summary::
        Whether a key type is an unstructured array of bytes.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

    This encompasses both symmetric keys and non-key data.

    See :title:`symmetric-keys` for a list of symmetric key types.

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

    .. summary::
        Whether a key type is asymmetric: either a key pair or a public key.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

    See :title:`asymmetric-keys` for a list of asymmetric key types.

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

    .. summary::
        Whether a key type is the public part of a key pair.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

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

    .. summary::
        Whether a key type is a key pair containing a private part and a public part.

    .. param:: type
        A key type (value of type `psa_key_type_t`).


.. _symmetric-keys:

Symmetric keys
--------------

.. macro:: PSA_KEY_TYPE_RAW_DATA
    :definition: ((psa_key_type_t)0x1001)

    .. summary::
        Raw data.

    A "key" of this type cannot be used for any cryptographic operation. Applications can use this type to store arbitrary data in the keystore.

.. macro:: PSA_KEY_TYPE_HMAC
    :definition: ((psa_key_type_t)0x1100)

    .. summary::
        HMAC key.

    The key policy determines which underlying hash algorithm the key can be used for.

    HMAC keys typically have the same size as the underlying hash. This size can be calculated with :code:`PSA_HASH_LENGTH(alg)` where ``alg`` is the HMAC algorithm or the underlying hash algorithm.

.. macro:: PSA_KEY_TYPE_DERIVE
    :definition: ((psa_key_type_t)0x1200)

    .. summary::
        A secret for key derivation.

    The key policy determines which key derivation algorithm the key can be used for.

.. macro:: PSA_KEY_TYPE_AES
    :definition: ((psa_key_type_t)0x2400)

    .. summary::
        Key for a cipher, AEAD or MAC algorithm based on the AES block cipher.

    The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or 32 bytes (AES-256).

.. macro:: PSA_KEY_TYPE_DES
    :definition: ((psa_key_type_t)0x2301)

    .. summary::
        Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).

    The size of the key can be 8 bytes (single DES), 16 bytes (2-key 3DES) or 24 bytes (3-key 3DES).

    .. warning::
        Single DES and 2-key 3DES are weak and strongly deprecated and are only recommended for decrypting legacy data.

        3-key 3DES is weak and deprecated and is only recommended for use in legacy protocols.

.. macro:: PSA_KEY_TYPE_CAMELLIA
    :definition: ((psa_key_type_t)0x2403)

    .. summary::
        Key for a cipher, AEAD or MAC algorithm based on the Camellia block cipher.

.. macro:: PSA_KEY_TYPE_ARC4
    :definition: ((psa_key_type_t)0x2002)

    .. summary::
        Key for the RC4 stream cipher.

    Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the ARC4 cipher.

    .. warning::
        The RC4 cipher is weak and deprecated and is only recommended for use in legacy protocols.

    The ARC4 cipher does not use an initialization vector (IV). When using a multi-part cipher operation with the `PSA_ALG_STREAM_CIPHER` algorithm and an ARC4 key, `psa_cipher_generate_iv()` and `psa_cipher_set_iv()` must not be called.

.. macro:: PSA_KEY_TYPE_CHACHA20
    :definition: ((psa_key_type_t)0x2004)

    .. summary::
        Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm.

    ChaCha20 and the ChaCha20_Poly1305 construction are defined in :RFC:`7539`.

    Variants of these algorithms are defined by the length of the nonce:

    - Implementations must support a 12-byte nonce, as defined in :RFC:`7539`.
    - Implementations can optionally support an 8-byte nonce, the original variant.
    - It is recommended that implementations do not support other sizes of nonce.

    Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the ChaCha20 cipher for unauthenticated encryption.


.. _asymmetric-keys:

RSA keys
--------

.. macro:: PSA_KEY_TYPE_RSA_PUBLIC_KEY
    :definition: ((psa_key_type_t)0x4001)

    .. summary::
        RSA public key.

.. macro:: PSA_KEY_TYPE_RSA_KEY_PAIR
    :definition: ((psa_key_type_t)0x7001)

    .. summary::
        RSA key pair: both the private and public key.

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

    .. summary::
        Whether a key type is an RSA key. This includes both key pairs and public keys.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

Elliptic Curve keys
-------------------

.. typedef:: uint8_t psa_ecc_family_t

    .. summary::
        The type of PSA elliptic curve family identifiers.

    The curve identifier is required to create an ECC key using the `PSA_KEY_TYPE_ECC_KEY_PAIR()` or `PSA_KEY_TYPE_ECC_PUBLIC_KEY()` macros.

    The specific ECC curve within a family is identified by the ``key_bits`` attribute of the key.

    The range of Elliptic curve family identifier values is divided as follows:

    :code:`0x00 - 0x7f`
        ECC family identifiers defined by this standard.
        Unallocated values in this range are reserved for future use.
    :code:`0x80 - 0xff`
        Implementations that define additional families must use an encoding in this range.

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

    .. summary::
        Elliptic curve key pair: both the private and public key.

    .. param:: curve
        A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used.

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

    .. summary::
        Elliptic curve public key.

    .. param:: curve
        A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used.


.. macro:: PSA_ECC_FAMILY_SECP_K1
    :definition: ((psa_ecc_family_t) 0x17)

    .. summary::
        SEC Koblitz curves over prime fields.

    This family comprises the following curves:

    - secp192k1 : ``key_bits = 192``
    - secp224k1 : ``key_bits = 225``
    - secp256k1 : ``key_bits = 256``

    They are defined in *Standards for Efficient Cryptography*, |SEC2|_.

    .. |SEC2| replace:: *SEC 2: Recommended Elliptic Curve Domain Parameters*
    .. _SEC2: https://www.secg.org/sec2-v2.pdf

.. macro:: PSA_ECC_FAMILY_SECP_R1
    :definition: ((psa_ecc_family_t) 0x12)

    .. summary::
        SEC random curves over prime fields.

    This family comprises the following curves:

    - secp192r1 : ``key_bits = 192``
    - secp224r1 : ``key_bits = 224``
    - secp256r1 : ``key_bits = 256``
    - secp384r1 : ``key_bits = 384``
    - secp521r1 : ``key_bits = 512``

    They are defined in *Standards for Efficient Cryptography*, |SEC2|_

.. macro:: PSA_ECC_FAMILY_SECP_R2
    :definition: ((psa_ecc_family_t) 0x1b)

    .. summary::
        .. warning::
            This family of curves is weak and deprecated.

    This family comprises the following curves:

    - secp160r2 : ``key_bits = 160`` *(Deprecated)*

    It is defined in the superseded |SEC2v1|_.

    .. |SEC2v1| replace:: *SEC 2: Recommended Elliptic Curve Domain Parameters, Version 1.0*
    .. _SEC2v1: https://www.secg.org/SEC2-Ver-1.0.pdf

.. macro:: PSA_ECC_FAMILY_SECT_K1
    :definition: ((psa_ecc_family_t) 0x27)

    .. summary::
        SEC Koblitz curves over binary fields.

    This family comprises the following curves:

    - sect163k1 : ``key_bits = 163`` *(Deprecated)*
    - sect233k1 : ``key_bits = 233``
    - sect239k1 : ``key_bits = 239``
    - sect283k1 : ``key_bits = 283``
    - sect409k1 : ``key_bits = 409``
    - sect571k1 : ``key_bits = 571``

    They are defined in *Standards for Efficient Cryptography*, |SEC2|_

    .. warning::
        The 163-bit curve sect163k1 is weak and deprecated and is only recommended for use in legacy protocols.

.. macro:: PSA_ECC_FAMILY_SECT_R1
    :definition: ((psa_ecc_family_t) 0x22)

    .. summary::
        SEC random curves over binary fields.

    This family comprises the following curves:

    - sect163r1 : ``key_bits = 163`` *(Deprecated)*
    - sect233r1 : ``key_bits = 233``
    - sect283r1 : ``key_bits = 283``
    - sect409r1 : ``key_bits = 409``
    - sect571r1 : ``key_bits = 571``

    They are defined in *Standards for Efficient Cryptography*, |SEC2|_

    .. warning::
        The 163-bit curve sect163r1 is weak and deprecated and is only recommended for use in legacy protocols.

.. macro:: PSA_ECC_FAMILY_SECT_R2
    :definition: ((psa_ecc_family_t) 0x2b)

    .. summary::
        SEC additional random curves over binary fields.

    This family comprises the following curves:

    - sect163r2 : ``key_bits = 163`` *(Deprecated)*

    It is defined in *Standards for Efficient Cryptography*, |SEC2|_

    .. warning::
        The 163-bit curve sect163r2 is weak and deprecated and is only recommended for use in legacy protocols.

.. macro:: PSA_ECC_FAMILY_BRAINPOOL_P_R1
    :definition: ((psa_ecc_family_t) 0x30)

    .. summary::
        Brainpool P random curves.

    This family comprises the following curves:

    - brainpoolP160r1 : ``key_bits = 160`` *(Deprecated)*
    - brainpoolP192r1 : ``key_bits = 192``
    - brainpoolP224r1 : ``key_bits = 224``
    - brainpoolP256r1 : ``key_bits = 256``
    - brainpoolP320r1 : ``key_bits = 320``
    - brainpoolP384r1 : ``key_bits = 384``
    - brainpoolP512r1 : ``key_bits = 512``

    They are defined in :rfc:`5639`.

    .. warning::
        The 160-bit curve brainpoolP160r1 is weak and deprecated and is only recommended for use in legacy protocols.

.. macro:: PSA_ECC_FAMILY_FRP
    :definition: ((psa_ecc_family_t) 0x33)

    .. summary::
        Curve used primarily in France and elsewhere in Europe.

    This family comprises one 256-bit curve:

    - FRP256v1 : ``key_bits = 256``

    This is defined by *Agence nationale de la sécurité des systèmes d'information* in |FRP|_, 21 November 2011.

    .. |FRP| replace:: *Publication d'un paramétrage de courbe elliptique visant des applications de passeport électronique et de l'administration électronique française*
    .. _FRP: https://www.ssi.gouv.fr/agence/publication/publication-dun-parametrage-de-courbe-elliptique-visant-des-applications-de-passeport-electronique-et-de-ladministration-electronique-francaise/

.. macro:: PSA_ECC_FAMILY_MONTGOMERY
    :definition: ((psa_ecc_family_t) 0x41)

    .. summary::
        Montgomery curves.

    This family comprises the following Montgomery curves:

    - Curve25519 : ``key_bits = 255``

      This curve is defined in Bernstein et al., |Curve25519|_, LNCS 3958, 2006.

      .. |Curve25519| replace:: *Curve25519: new Diffie-Hellman speed records*
      .. _Curve25519: https://www.iacr.org/archive/pkc2006/39580209/39580209.pdf

      The algorithm `PSA_ALG_ECDH` performs X25519 when used with this curve.

    - Curve448 : ``key_bits = 448``

      This curve is defined in Hamburg, |Ed448|_, NIST ECC Workshop, 2015.

      .. |Ed448| replace:: *Ed448-Goldilocks, a new elliptic curve*
      .. _Ed448: https://eprint.iacr.org/2015/625.pdf

      The algorithm `PSA_ALG_ECDH` performs X448 when used with this curve.

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

    .. summary::
        Whether a key type is an elliptic curve key, either a key pair or a public key.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

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

    .. summary::
        Whether a key type is an elliptic curve key pair.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

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

    .. summary::
        Whether a key type is an elliptic curve public key.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

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

    .. summary::
        Extract the curve family from an elliptic curve key type.

    .. param:: type
        An elliptic curve key type (value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_ECC(type)` is true).

    .. return:: psa_ecc_family_t
        The elliptic curve family id, if ``type`` is a supported elliptic curve key. Unspecified if ``type`` is not a supported elliptic curve key.

Diffie Hellman keys
-------------------

.. typedef:: uint8_t psa_dh_family_t

    .. summary::
        The type of PSA Diffie-Hellman group family identifiers.

    The group family identifier is required to create an Diffie-Hellman key using the `PSA_KEY_TYPE_DH_KEY_PAIR()` or `PSA_KEY_TYPE_DH_PUBLIC_KEY()` macros.

    The specific Diffie-Hellman group within a family is identified by the ``key_bits`` attribute of the key.

    The range of Diffie-Hellman group family identifier values is divided as follows:

    :code:`0x00 - 0x7f`
        DH group family identifiers defined by this standard.
        Unallocated values in this range are reserved for future use.
    :code:`0x80 - 0xff`
        Implementations that define additional families must use an encoding in this range.

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

    .. summary::
        Diffie-Hellman key pair: both the private key and public key.

    .. param:: group
        A value of type `psa_dh_family_t` that identifies the Diffie-Hellman group family to be used.

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

    .. summary::
        Diffie-Hellman public key.

    .. param:: group
        A value of type `psa_dh_family_t` that identifies the Diffie-Hellman group family to be used.

.. macro:: PSA_DH_FAMILY_RFC7919
    :definition: ((psa_dh_family_t) 0x03)

    .. summary::
        Diffie-Hellman groups defined in :rfc:`7919#A`.

    This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, 6144, 8192.
    An implementation can support all of these sizes or only a subset.

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

    .. summary::
        The key pair type corresponding to a public key type.

    .. param:: type
        A public key type or key pair type.

    .. return::
        The corresponding key pair type. If ``type`` is not a public key or a key pair, the return value is undefined.

    If ``type`` is a key pair type, it will be left unchanged.

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

    .. summary::
        The public key type corresponding to a key pair type.

    .. param:: type
        A public key type or key pair type.

    .. return::
        The corresponding public key type. If ``type`` is not a public key or a key pair, the return value is undefined.

    If ``type`` is a public key type, it will be left unchanged.

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

    .. summary::
        Whether a key type is a Diffie-Hellman key, either a key pair or a public key.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

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

    .. summary::
        Whether a key type is a Diffie-Hellman key pair.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

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

    .. summary::
        Whether a key type is a Diffie-Hellman public key.

    .. param:: type
        A key type (value of type `psa_key_type_t`).

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

    .. summary::
        Extract the group family from a Diffie-Hellman key type.

    .. param:: type
        A Diffie-Hellman key type (value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_DH(type)` is true).

    .. return:: psa_dh_family_t
        The Diffie-Hellman group family id, if ``type`` is a supported Diffie-Hellman key. Unspecified if ``type`` is not a supported Diffie-Hellman key.

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

.. function:: psa_set_key_type

    .. summary::
        Declare the type of a key.

    .. param:: psa_key_attributes_t * attributes
        The attribute object to write to.
    .. param:: psa_key_type_t type
        The key type to write. If this is `PSA_KEY_TYPE_NONE`, the key type in ``attributes`` becomes unspecified.

    .. return:: void

    This function overwrites any key type 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_type

    .. summary::
        Retrieve the key type from key attributes.

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

    .. return:: psa_key_type_t
        The key type 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.

.. function:: psa_get_key_bits

    .. summary::
        Retrieve the key size from key attributes.

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

    .. return:: size_t
        The key size stored in the attribute object, in bits.

    .. 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_set_key_bits

    .. summary::
        Declare the size of a key.

    .. param:: psa_key_attributes_t * attributes
        The attribute object to write to.
    .. param:: size_t bits
        The key size in bits. If this is ``0``, the key size in ``attributes`` becomes unspecified. Keys of size ``0`` are not supported.

    .. return:: void

    This function overwrites any key size 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.
