rsassa_pss.h

/*
* Copyright (c) 2025 Emil Lenngren
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this
*    list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
*    this list of conditions and the following disclaimer in the documentation
*    and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

#pragma once

#include <stdint.h>
#include <stddef.h>

#ifndef P_Q_MAX
#define P_Q_MAX(p, q) ((p) > (q) ? (p) : (q))
#endif

#define RSASSA_PSS_VERIFY_TEMP_AREA_NUM_UINT32(public_key_n_length_bytes) \
    (7 * ((((public_key_n_length_bytes) + 31) & ~31) / sizeof(uint32_t)))

#define RSASSA_PSS_SIGN_TEMP_AREA_NUM_UINT32(private_key_p_length_bytes, private_key_q_length_bytes) \
    (25 * (((P_Q_MAX((private_key_p_length_bytes), (private_key_q_length_bytes)) + 31) & ~31) / sizeof(uint32_t)))

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Type definition for a hash function callback.
 *
 * This function computes a cryptographic hash over a given input buffer.
 *
 * @param[in] user_data
 *     Opaque pointer to user-defined data passed through to the callback.
 *
 * @param[out] output
 *     Buffer to store the resulting hash.
 *
 * @param[in] input
 *     Pointer to the input data to be hashed.
 *
 * @param[in] input_length_bytes
 *     Length of the input data in bytes.
 *
 * @return Zero on success, non-zero on failure.
 */
typedef int (*hash_fn)(void *user_data, uint8_t *output, const uint8_t *input, size_t input_length_bytes);

/**
 * @brief Verifies an RSASSA-PSS signature against a given message hash.
 *
 * This function verifies a PSS-padded RSA signature using a given hash
 * function according to RFC 8017 Section 8.1.2.
 *
 * The MGF used is MGF1 with the same hash function as is used on the message.
 * 
 * The salt length used is the same as the message hash length.
 *
 * @param[in] public_key_e
 *     Pointer to the RSA public exponent \c e in big-endian byte order.
 *
 * @param[in] public_key_e_length_bytes
 *     Length of \p public_key_e in bytes.
 *
 * @param[in] public_key_n
 *     Pointer to the RSA modulus \c n in big-endian byte order.
 *     The first byte (most significant) must be non-zero, or an error will be returned.
 *
 * @param[in] public_key_n_length_bytes
 *     Length of \p public_key_n in bytes.
 *
 * @param[in] message_hash
 *     Pointer to the precomputed message hash to be verified.
 *
 * @param[in] signature
 *     Pointer to the signature to be verified.
 *
 * @param[in] signature_length_bytes
 *     Length of \p signature in bytes.
 *
 * @param[in] hash_function
 *     Pointer to a hash function callback of type ::hash_fn.
 *     This function must implement the same hash function used to produce \p message_hash.
 *
 * @param[in] hash_function_user_data
 *     Pointer to user-defined data passed to \p hash_function.
 *     Can be \c nullptr if unused by the hash function.
 *
 * @param[in] hash_length_bytes
 *     Length in bytes of the hash function output (e.g., 32 for SHA-256).
 *
 * @param[in,out] temp_area
 *     Pointer to an array of \c uint32_t (temporary workspace).
 *     Use the ::RSASSA_PSS_VERIFY_TEMP_AREA_NUM_UINT32 macro to calculate the required size.
 *
 * @retval  0   The signature is valid.
 * @retval -1   The signature is invalid or basic verification checks on the public key failed.
 * @retval -2   The hash function failed. The user_data parameter could be used for communicating the specific failure.
 */
int rsassa_pss_verify_hash(
    const uint8_t *public_key_e, size_t public_key_e_length_bytes,
    const uint8_t *public_key_n, size_t public_key_n_length_bytes,
    const uint8_t *message_hash,
    const uint8_t *signature, size_t signature_length_bytes,
    hash_fn hash_function,
    void *hash_function_user_data,
    size_t hash_length_bytes,
    uint32_t *temp_area);

/**
 * @brief Creates an RSASSA-PSS signature for a given message hash.
 *
 * This function generates a PSS-padded RSA signature using CRT optimization
 * and a specified hash function according to RFC 8017 Section 8.1.1.
 *
 * The MGF used is MGF1 with the same hash function as is used on the message.
 * 
 * The salt length used is the same as the message hash length.
 *
 * The behaviour of this function is undefined if the private key is invalid,
 * or if the requirements for the parameters are not satisfied.
 *
 * @param[out] signature
 *     Buffer where the resulting signature will be written.
 *     Must be the same length as \p private_key_n.
 *
 * @param[in] private_key_n
 *     Pointer to the RSA modulus \c n in big-endian byte order.
 *     The first byte (most significant) must be non-zero.
 *
 * @param[in] private_key_n_length_bytes
 *     Length of \p private_key_n in bytes.
 *
 * @param[in] private_key_p
 *     Pointer to the first prime factor \c p, in big-endian byte order.
 *
 * @param[in] private_key_p_length_bytes
 *     Length of \p private_key_p in bytes.
 *
 * @param[in] private_key_q
 *     Pointer to the second prime factor \c q, in big-endian byte order.
 *
 * @param[in] private_key_q_length_bytes
 *     Length of \p private_key_q in bytes.
 *
 * @param[in] private_key_q_inv
 *     Pointer to the modular inverse of \c q mod \c p, in big-endian byte order.
 *
 * @param[in] private_key_q_inv_length_bytes
 *     Length of \p private_key_q_inv in bytes.
 *
 * @param[in] private_key_dp
 *     Pointer to the CRT exponent \c dP = d mod (p-1), in big-endian byte order.
 *
 * @param[in] private_key_dp_length_bytes
 *     Length of \p private_key_dp in bytes.
 *
 * @param[in] private_key_dq
 *     Pointer to the CRT exponent \c dQ = d mod (q-1), in big-endian byte order.
 *
 * @param[in] private_key_dq_length_bytes
 *     Length of \p private_key_dq in bytes.
 *
 * @param[in] message_hash
 *     Pointer to the precomputed hash of the message to be signed.
 *
 * @param[in] randomly_generated_salt
 *     Pointer to a cryptographically securely generated random salt of size \p hash_length_bytes.
 *
 * @param[in] hash_function
 *     Pointer to a hash function callback of type ::hash_fn.
 *     This function must implement the same hash function used to produce \p message_hash.
 *
 * @param[in] hash_function_user_data
 *     Pointer to user-defined data passed to \p hash_function.
 *     Can be \c nullptr if unused by the hash function.
 *
 * @param[in] hash_length_bytes
 *     Length in bytes of the hash function output (e.g., 32 for SHA-256).
 *
 * @param[in,out] temp_area
 *     Pointer to an array of \c uint32_t (temporary workspace).
 *     Use the ::RSASSA_PSS_SIGN_TEMP_AREA_NUM_UINT32 macro to calculate the required size.
 *
 * @retval  0   Signature was generated successfully.
 * @retval -1   The modulus is too small for the given hash function output length.
 * @retval -2   The hash function failed. The user_data parameter could be used for communicating the specific failure.
 */
int rsassa_pss_sign_hash(
    uint8_t *signature,
    const uint8_t *private_key_n, size_t private_key_n_length_bytes,
    const uint8_t *private_key_p, size_t private_key_p_length_bytes,
    const uint8_t *private_key_q, size_t private_key_q_length_bytes,
    const uint8_t *private_key_q_inv, size_t private_key_q_inv_length_bytes,
    const uint8_t *private_key_dp, size_t private_key_dp_length_bytes,
    const uint8_t *private_key_dq, size_t private_key_dq_length_bytes,
    const uint8_t *message_hash,
    const uint8_t *randomly_generated_salt,
    hash_fn hash_function,
    void *hash_function_user_data,
    size_t hash_length_bytes,
    uint32_t *temp_area
);

#ifdef __cplusplus
}
#endif