rsassa_pkcs1_v1_5.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_PKCS1_V1_5_VERIFY_TEMP_AREA_NUM_UINT32(public_key_n_length_bytes) \
    (7 * ((((public_key_n_length_bytes) + 31) & ~31) / sizeof(uint32_t)))

#define RSASSA_PKCS1_V1_5_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 Describes a hash algorithm used in RSASSA-PKCS1-v1_5 signature encoding.
 *
 * This structure holds metadata about a hash function needed for constructing
 * and validating ASN.1 DigestInfo structures in RSASSA-PKCS1-v1_5 signatures.
 */
struct HashAlgorithm {
    const uint8_t *der_prefix_reversed;
    uint16_t der_prefix_length;
    uint16_t digest_length;
};

/**
 * @brief Hash algorithm definition for MD5.
 */
extern const struct HashAlgorithm rsassa_pkcs1_v1_5_hash_algorithm_md5;

/**
 * @brief Hash algorithm definition for SHA-1.
 */
extern const struct HashAlgorithm rsassa_pkcs1_v1_5_hash_algorithm_sha1;

/**
 * @brief Hash algorithm definition for SHA-224.
 */
extern const struct HashAlgorithm rsassa_pkcs1_v1_5_hash_algorithm_sha224;

/**
 * @brief Hash algorithm definition for SHA-256.
 */
extern const struct HashAlgorithm rsassa_pkcs1_v1_5_hash_algorithm_sha256;

/**
 * @brief Hash algorithm definition for SHA-384.
 */
extern const struct HashAlgorithm rsassa_pkcs1_v1_5_hash_algorithm_sha384;

/**
 * @brief Hash algorithm definition for SHA-512.
 */
extern const struct HashAlgorithm rsassa_pkcs1_v1_5_hash_algorithm_sha512;

/**
 * @brief Hash algorithm definition for SHA-512/224.
 */
extern const struct HashAlgorithm rsassa_pkcs1_v1_5_hash_algorithm_sha512_224;

/**
 * @brief Hash algorithm definition for SHA-512/256.
 */
extern const struct HashAlgorithm rsassa_pkcs1_v1_5_hash_algorithm_sha512_256;

/**
 * @brief Verifies an RSASSA-PKCS1-v1_5 signature against a message hash.
 *
 * This function uses the public key and a provided hash algorithm to verify
 * whether the given signature corresponds to the input message hash using
 * the RSASSA-PKCS1-v1_5 scheme.
 *
 * @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 hash of the message.
 *
 * @param[in] signature
 *     Pointer to the RSASSA-PKCS1-v1_5 encoded signature.
 *
 * @param[in] signature_length_bytes
 *     Length of the signature in bytes.
 *
 * @param[in] hash_algorithm
 *     Pointer to a ::HashAlgorithm structure describing the hash used.
 *     Use a pointer to one of the already defined struct objects.
 *
 * @param[in,out] temp_area
 *     Pointer to an array of \c uint32_t (temporary workspace).
 *     Use the ::RSASSA_PKCS1_V1_5_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.
 */
int rsassa_pkcs1_v1_5_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,
    const struct HashAlgorithm *hash_algorithm,
    uint32_t *temp_area);

/**
 * @brief Signs a message hash using RSASSA-PKCS1-v1_5 and CRT optimization.
 *
 * This function generates an RSASSA-PKCS1-v1_5 signature over a given
 * precomputed message hash, using CRT components of the private key for
 * efficiency.
 *
 * 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_length_bytes
 *     Length of the modulus \c n of the private key in bytes,
 *     such that when written in big-endian byte order,
 *     the first byte (most significant) is non-zero.
 *
 * @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] hash_algorithm
 *     Pointer to a ::HashAlgorithm structure describing the hash used.
 *     Use a pointer to one of the already defined struct objects.
 *
 * @param[in,out] temp_area
 *     Pointer to an array of \c uint32_t (temporary workspace).
 *     Use the ::RSASSA_PKCS1_V1_5_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 algorithm.
 */
int rsassa_pkcs1_v1_5_sign_hash(
    uint8_t *signature,
    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 struct HashAlgorithm *hash_algorithm,
    uint32_t *temp_area);

#ifdef __cplusplus
}
#endif