Typeset all mathematical equations and symbols as :math:

Author: athoelke

doc/crypto/api/keys/management.rst

@@ -155,7 +155,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
 
     The following type-specific considerations apply:
 
-    *   For RSA keys (`PSA_KEY_TYPE_RSA_KEY_PAIR`), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.
+    *   For RSA keys (`PSA_KEY_TYPE_RSA_KEY_PAIR`), the public exponent is 65537. The modulus is a product of two probabilistic primes between :math:`2^{n-1}` and :math:`2^n` where :math:`n` is the bit size specified in the attributes.
 
 .. function:: psa_copy_key
 
@@ -626,29 +626,29 @@ This section defines the format of the key data that an implementation is requir
 
             The key data is the content of the ``privateKey`` field of the ``ECPrivateKey`` format defined by :RFC-title:`5915`.
 
-            This is a ``ceiling(m/8)``-byte string in big-endian order where ``m`` is the key size in bits.
+            This is a :math:`\lceil{m/8}\rceil`-byte string in big-endian order, where :math:`m` is the key size in bits.
 
     *   -   Weierstrass Elliptic curve public key
         -   :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(ecc_family)`, where ``ecc_family`` designates a Weierstrass curve family.
 
             The key data is the uncompressed representation of an elliptic curve point as an octet string defined in :cite-title:`SEC1` §2.3.3.
-            If ``m`` is the bit size associated with the curve, i.e. the bit size of ``q`` for a curve over ``F_q``, then the representation consists of:
+            If :math:`m` is the bit size associated with the curve, i.e. the bit size of :math:`q` for a curve over :math:`\mathbb{F}_q`, then the representation of point :math:`P` consists of:
 
             *   The byte ``0x04``;
-            *   ``x_P`` as a ``ceiling(m/8)``-byte string, big-endian;
-            *   ``y_P`` as a ``ceiling(m/8)``-byte string, big-endian.
+            *   :math:`x_P` as a :math:`\lceil{m/8}\rceil`-byte string, big-endian;
+            *   :math:`y_P` as a :math:`\lceil{m/8}\rceil`-byte string, big-endian.
 
     *   -   Montgomery Elliptic curve key pair
         -   :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_MONTGOMERY)`
 
             The key data is the scalar value of the 'private key' in little-endian order as defined by :RFC-title:`7748#6`. The value must have the forced bits set to zero or one as specified by ``decodeScalar25519()`` and ``decodeScalar448()`` in :RFC:`7748#5`.
 
-            This is a ``ceiling(m/8)``-byte string where ``m`` is the key size in bits. This is 32 bytes for Curve25519, and 56 bytes for Curve448.
+            This is a :math:`\lceil{m/8}\rceil`-byte string where :math:`m` is the key size in bits. This is 32 bytes for Curve25519, and 56 bytes for Curve448.
 
     *   -   Montgomery Elliptic curve public key
         -   :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_MONTGOMERY)`
 
-            The key data is the scalar value of the 'public key' in little-endian order as defined by :RFC-title:`7748#6`. This is a ``ceiling(m/8)``-byte string where ``m`` is the key size in bits.
+            The key data is the scalar value of the 'public key' in little-endian order as defined by :RFC-title:`7748#6`. This is a :math:`\lceil{m/8}\rceil`-byte string where :math:`m` is the key size in bits.
 
             *   This is 32 bytes for Curve25519, computed as ``X25519(private_key, 9)``.
             *   This is 56 bytes for Curve448, computed as ``X448(private_key, 5)``.
@@ -670,9 +670,9 @@ This section defines the format of the key data that an implementation is requir
     *   -   Finite-field Diffie-Hellman key pair
         -   :code:`PSA_KEY_TYPE_DH_KEY_PAIR(dh_family)` where ``dh_family`` designates any Diffie-Hellman family.
 
-            The key data is the representation of the private key ``x`` as a big-endian byte string. The length of the byte string is the private key size in bytes, and leading zeroes are not stripped.
+            The key data is the representation of the private key :math:`x` as a big-endian byte string. The length of the byte string is the private key size in bytes, and leading zeroes are not stripped.
 
     *   -   Finite-field Diffie-Hellman public key
         -   :code:`PSA_KEY_TYPE_DH_PUBLIC_KEY(dh_family)` where ``dh_family`` designates any Diffie-Hellman family.
 
-            The key data is the representation of the public key ``y = g^x mod p`` as a big-endian byte string. The length of the byte string is the length of the base prime ``p`` in bytes.
+            The key data is the representation of the public key :math:`y = g^x\!\mod p` as a big-endian byte string. The length of the byte string is the length of the base prime :math:`p` in bytes.

doc/crypto/api/keys/types.rst

@@ -495,7 +495,7 @@ Elliptic Curve keys
     .. summary::
         Elliptic curve key pair: both the private and public key.
 
-    The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of *q* for a curve over a field *F*\ :sub:`q`. See the documentation of each Elliptic curve family for details.
+    The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:`q`` for a curve over a field :math:`\mathbb{F}_q`. See the documentation of each Elliptic curve family for details.
 
     .. param:: curve
         A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used.

doc/crypto/api/ops/aead.rst

@@ -58,13 +58,13 @@ AEAD algorithms
 
     To use `PSA_ALG_CCM` with a multi-part AEAD operation, the application must call `psa_aead_set_lengths()` before providing the nonce, the additional data and plaintext to the operation.
 
-    CCM requires a nonce of between 7 and 13 bytes in length. The length of the nonce affects the maximum length of the plaintext than can be encrypted or decrypted. If the nonce has length *N*, then the plaintext length *pLen* is encoded in *L* = 15 - *N* octets, this requires that *pLen* < 2\ :sup:`8L`.
+    CCM requires a nonce of between 7 and 13 bytes in length. The length of the nonce affects the maximum length of the plaintext than can be encrypted or decrypted. If the nonce has length :math:`N`, then the plaintext length :math:`pLen` is encoded in :math:`L = 15 - N` octets, this requires that :math:`pLen < 2^{8L}`.
 
-    The value for *L* that is used with `PSA_ALG_CCM` depends on the function used to provide the nonce:
+    The value for :math:`L` that is used with `PSA_ALG_CCM` depends on the function used to provide the nonce:
 
-    *   A call to `psa_aead_encrypt()`, `psa_aead_decrypt()`, or `psa_aead_set_nonce()` will set *L* to 15 - ``nonce_length``. If the plaintext length cannot be encoded in *L* octets, then a :code:`PSA_ERROR_INVALID_ARGUMENT` error is returned.
+    *   A call to `psa_aead_encrypt()`, `psa_aead_decrypt()`, or `psa_aead_set_nonce()` will set :math:`L = 15 - \mathtt{nonce\_length}`. If the plaintext length cannot be encoded in :math:`L` octets, then a :code:`PSA_ERROR_INVALID_ARGUMENT` error is returned.
 
-    *   A call to `psa_aead_generate_nonce()` on a multi-part cipher operation will select *L* as the smallest integer >= 2 where *pLen* < 2\ :sup:`8L`, with *pLen* being the ``plaintext_length`` provided to `psa_aead_set_lengths()`. The call to `psa_aead_generate_nonce()` will generate and return a random nonce of length 15 - *L* bytes.
+    *   A call to `psa_aead_generate_nonce()` on a multi-part cipher operation will select the smallest integer :math:`L \geq 2`, where :math:`pLen < 2^{8L}`, with :math:`pLen` being the ``plaintext_length`` provided to `psa_aead_set_lengths()`. The call to `psa_aead_generate_nonce()` will generate and return a random nonce of length :math:`15 - L` bytes.
 
     CCM supports authentication tag sizes of 4, 6, 8, 10, 12, 14, and 16 bytes. The default tag length is 16. Shortened tag lengths can be requested using :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)`, where ``tag_length`` is a valid CCM tag length.
 

doc/crypto/api/ops/ciphers.rst

@@ -119,7 +119,7 @@ Cipher algorithms
 
     A counter block value must only be used once across all messages encrypted using the same key value. This is typically achieved by splitting the counter block into a nonce, which is unique among all message encrypted with the key, and a counter which is incremented for each block of a message.
 
-    For example, when using AES-CTR encryption, which uses a 16-byte block, the application can provide a 12-byte nonce when setting the IV. This leaves 4 bytes for the counter, allowing up to 2^32 blocks (64GB) of message data to be encrypted in each message.
+    For example, when using AES-CTR encryption, which uses a 16-byte block, the application can provide a 12-byte nonce when setting the IV. This leaves 4 bytes for the counter, allowing up to :math:`2^{32}` blocks (64GB) of message data to be encrypted in each message.
 
     The first counter block is constructed from the initialization vector (IV). The initial counter block is is constructed in the following ways:
 
@@ -129,7 +129,7 @@ Cipher algorithms
 
     *   A call to `psa_cipher_generate_iv()` on a multi-part cipher operation will generate and return a random counter block value.
 
-    *   A call to `psa_cipher_set_iv()` on a multi-part cipher operation requires an IV that is between ``1`` and *n* bytes in length, where *n* is the cipher block length. The counter block is initialized using the IV, and padded with zero bytes up to the block length.
+    *   A call to `psa_cipher_set_iv()` on a multi-part cipher operation requires an IV that is between ``1`` and :math:`n` bytes in length, where :math:`n` is the cipher block length. The counter block is initialized using the IV, and padded with zero bytes up to the block length.
 
     During the counter block update operation, the counter block is treated as a single big-endian encoded integer and the update operation increments this integer by ``1``.
 
@@ -170,15 +170,15 @@ Cipher algorithms
 
         The Zigbee message encryption algorithm is based on CCM*. This is detailed in :cite-title:`ZIGBEE` §B.1.1 and §A.
 
-        *   For unauthenticated messages — when *M* = 0 --- the `PSA_ALG_CCM_STAR_NO_TAG` algorithm is used with an AES-128 key in a multi-part cipher operation. The 13-byte IV must be constructed as specified in `[ZIGBEE]`, and provided to the operation using `psa_cipher_set_iv()`.
+        *   For unauthenticated messages --- when tag length :math:`M = 0` --- the `PSA_ALG_CCM_STAR_NO_TAG` algorithm is used with an AES-128 key in a multi-part cipher operation. The 13-byte IV must be constructed as specified in `[ZIGBEE]`, and provided to the operation using `psa_cipher_set_iv()`.
 
             .. note::
 
                 An implementation of Zigbee cannot use the single-part `psa_cipher_encrypt()` function, as this generates a random IV, which is not valid for the Zigbee protocol.
 
-        *   For authenticated messages — when *M* ∈ {4, 8, 16} --- the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` algorithm is used with an AES-128 key, where ``tag_length`` is the required value of *M*. The 13-byte nonce must be constructed as specified in `[ZIGBEE]`.
+        *   For authenticated messages --- when tag length :math:`M \in \{4, 8, 16\}` --- the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` algorithm is used with an AES-128 key, where ``tag_length`` is the required value of :math:`M`. The 13-byte nonce must be constructed as specified in `[ZIGBEE]`.
 
-            As the default tag length for CCM is 16, then `PSA_ALG_CCM` algorithm can be used when *M* = 16.
+            As the default tag length for CCM is 16, then `PSA_ALG_CCM` algorithm can be used when :math:`M = 16`.
 
         *   To enable a single AES-128 key to be used for both the `PSA_ALG_CCM_STAR_NO_TAG` cipher and `PSA_ALG_CCM` AEAD algorithm, the key can be defined with the wildcard `PSA_ALG_CCM_STAR_ANY_TAG` permitted algorithm.
 
@@ -206,7 +206,7 @@ Cipher algorithms
     .. note::
         The cipher block length can be determined using `PSA_BLOCK_CIPHER_BLOCK_LENGTH()`.
 
-    The CFB block cipher mode is defined in :cite-title:`SP800-38A`, using a segment size *s* equal to the block size *b*. The definition in `[SP800-38A]` is extended to allow an incomplete final block of input, in which case the algorithm discards the final bytes of the key stream when encrypting or decrypting the final partial block.
+    The CFB block cipher mode is defined in :cite-title:`SP800-38A`, using a segment size :math:`s` equal to the block size :math:`b`. The definition in `[SP800-38A]` is extended to allow an incomplete final block of input, in which case the algorithm discards the final bytes of the key stream when encrypting or decrypting the final partial block.
 
     .. subsection:: Compatible key types
 

doc/crypto/api/ops/hashes.rst

@@ -81,7 +81,7 @@ Hash algorithms
 
     This is the cryptographic hash function based on the Merkle-Damgård construction over a Matyas-Meyer-Oseas one-way compression function and the AES-128 block cipher, with the parametrization defined in :cite-title:`ZIGBEE` §B.6.
 
-    This hash function can operate on input strings of up to 2\ :sup:`32` - 1 bits.
+    This hash function can operate on input strings of up to :math:`2^{32} - 1` bits.
 
     .. note::
 
@@ -780,35 +780,37 @@ Hash suspend state format
 
 The hash suspend state has the following format:
 
-*hash-suspend-state* = *algorithm* || *input-length* || *hash-state* || *unprocessed-input*
+.. math::
+
+    hash\_suspend\_state = algorithm\ ||\ input\_length\ ||\ hash\_state\ ||\ unprocessed\_input
 
 The fields in the hash suspend state are defined as follows:
 
-*algorithm*
+:math:`algorithm`
     A big-endian 32-bit unsigned integer.
 
     The |API| algorithm identifier value.
 
-    The byte length of the *algorithm* field can be evaluated using `PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH`.
+    The byte length of the :math:`algorithm` field can be evaluated using `PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH`.
 
-*input-length*
+:math:`input\_length`
     A big-endian unsigned integer
 
     The content of this field is algorithm-specific:
 
-    *   For MD2, this is the number of bytes in the *unprocessed-input*.
-    *   For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the *unprocessed-input* bytes.
+    *   For MD2, this is the number of bytes in :math:`unprocessed\_input`.
+    *   For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the :math:`unprocessed\_input` bytes.
 
     The size of this field is algorithm-specific:
 
-    *   For MD2: *input-length* is an 8-bit unsigned integer.
-    *   For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: *input-length* is a 64-bit unsigned integer.
-    *   For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: *input-length* is a 128-bit unsigned integer.
+    *   For MD2: :math:`input\_length` is an 8-bit unsigned integer.
+    *   For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: :math:`input\_length` is a 64-bit unsigned integer.
+    *   For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: :math:`input\_length` is a 128-bit unsigned integer.
 
-    The length, in bytes, of the *input-length* field can be calculated using :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm.
+    The length, in bytes, of the :math:`input\_length` field can be calculated using :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm.
     See :secref:`hash-suspend-state-constants`.
 
-*hash-state*
+:math:`hash\_state`
     An array of bytes
 
     Algorithm-specific intermediate hash state:
@@ -821,17 +823,19 @@ The fields in the hash suspend state are defined as follows:
     *   For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: 8x 64-bit integers, in big-endian encoding.
 
     The length of this field is specific to the algorithm.
-    The length, in bytes, of the *hash-state* field can be calculated using :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm.
+    The length, in bytes, of the :math:`hash\_state` field can be calculated using :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` where ``alg`` is a hash algorithm.
     See :secref:`hash-suspend-state-constants`.
 
-*unprocessed-input*
-    0 to (*hash-block-size*-1) bytes
+:math:`unprocessed\_input`
+    :math:`0\ \text{to}\ (hash\_block\_size - 1)` bytes
+
+    A partial block of unprocessed input data. This is between zero and :math:`hash\_block\_size - 1` bytes of data, the length can be calculated by:
 
-    A partial block of unprocessed input data. This is between zero and *hash-block-size*-1 bytes of data, the length can be calculated by:
+    .. math::
 
-    ``length(``\ *unprocessed-input*\ ``)`` ``=`` *input-length* ``%`` *hash-block-size*.
+        \text{length}(unprocessed\_input) = input\_length \mod hash\_block\_size.
 
-    The *hash-block-size* is specific to the algorithm.
+    The value of :math:`hash\_block\_size` is specific to the hash algorithm.
     The size of a hash block can be calculated using :code:`PSA_HASH_BLOCK_LENGTH(alg)` where ``alg`` is a hash algorithm.
     See :secref:`hash-suspend-state-constants`.
 
@@ -842,18 +846,18 @@ Hash suspend state field sizes
 
 The following table defines the algorithm-specific field lengths for the hash suspend state returned by `psa_hash_suspend()`. All of the field lengths are in bytes. To compute the field lengths for algorithm ``alg``, use the following expressions:
 
-*   :code:`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` returns the length of the *algorithm* field.
-*   :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` returns the length of the *input-length* field.
-*   :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` returns the length of the *hash-state* field.
-*   :code:`PSA_HASH_BLOCK_LENGTH(alg)-1` is the maximum length of the *unprocessed-bytes* field.
+*   :code:`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` returns the length of the :math:`algorithm` field.
+*   :code:`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg)` returns the length of the :math:`input\_length` field.
+*   :code:`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg)` returns the length of the :math:`hash\_state` field.
+*   :code:`PSA_HASH_BLOCK_LENGTH(alg) - 1` is the maximum length of the :math:`unprocessed\_bytes` field.
 *   :code:`PSA_HASH_SUSPEND_OUTPUT_SIZE(alg)` returns the maximum size of the hash suspend state.
 
 .. csv-table::
     :header-rows: 1
     :widths: auto
     :align: left
 
-    Hash algorithm, *input-length* size (bytes), *hash-state* length (bytes), *unprocessed-bytes* length (bytes)
+    Hash algorithm, :math:`input\_length` size (bytes), :math:`hash\_state` length (bytes), :math:`unprocessed\_bytes` length (bytes)
     `PSA_ALG_MD2`, 1, 64, 0 -- 15
     `PSA_ALG_MD4`, 8, 16, 0 -- 63
     `PSA_ALG_MD5`, 8, 16, 0 -- 63