.. _pqspp_verify_digest:


====================
PQSPP_verify_digest
====================

Description
------------

`PQSPP_verify_digest` verifies the message digest against its signature.


Syntax
--------

.. code-block:: c

    int PQSPP_verify_digest(
        uint8_t*        pk, 
        int             pk_len,
        unsigned char*  pbHash,
        size_t          cbHash, 
        uint8_t*        ec_sig, 
        int             ec_sig_len, 
        uint8_t*        pip, 
        int             pip_len
    );


Parameters
----------
- `pk`
The pointer to a public key. This public key will be used to verify `ec_sig` against `pbHash`.

Note to free this memory address by calling `PQSPP_free_memory` on `pk` when the memory is no longer needed.

- `pk_len`
The size of the public key. This size is in terms of the number of bytes.

- `pbHash`
A pointer to a buffer that contains the hash value to verify against. The `cbHash` parameter contains the size of this buffer.

- `cbHash`
The number of bytes in the `pbHash` buffer.

- `ec_sig`
A pointer to a buffer that contains the signature. The `ec_sig_len` parameter contains the size of this buffer.

Note to free this memory address by calling `PQSPP_free_memory` on `ec_sig`.

- `ec_sig_len`
The size of the signature. This size is in terms of the number of bytes.

- `pip`
A pointer to a buffer that contains the proof. The `pip_len` parameter contains the size of this buffer.

Note to free this memory address by calling `PQSPP_free_memory` on `pip`.

- `pip_len`
The size of the proof. This size is in terms of the number of bytes.

Return value
--------------

+-------------+----------------------------+
| Return code | Description                |   
+=============+============================+
| PQSPP_OK    | The function was successful|
+-------------+----------------------------+

Anything other than OK is an error.


Code example
------------------

.. code-block:: c

    #include "pqspp.h"
    #include "sha256.h"

    #include <stdio.h>
    #include <stdlib.h>

    int main() 
    {

        // PQSPP_keygen
        /*
        uint8_t *sk = NULL;
        uint8_t *pk = NULL;
        int pk_len = -1;

        int ret = PQSPP_keygen(&sk, &pk, &pk_len);
        if (ret != PQSPP_OK) {
            printf("Error in keygen: %d\n", ret);
            return -1;
        }
        printf(
            "Generated a secret key and a public key (DER encoded of length %d)!\n",
            pk_len);
        */

        // PQSPP_sign_digest
        /*
        // message digest
        uint8_t message[4] = {0x01, 0x02, 0x03, 0x04};
        unsigned char hash[32];
        SHA256_CTX ctx;

        // hash the message 
        sha256_init(&ctx);
        sha256_update(&ctx,message,sizeof(message));
        sha256_final(&ctx,hash);

        uint8_t *ec_sig = NULL;
        int ec_sig_len = -1;
        uint8_t *pip = NULL;
        int pip_len = -1;
        
        ret =
            PQSPP_sign_digest(sk, hash,sizeof(hash), &ec_sig, &ec_sig_len, &pip, &pip_len);
        if (ret != PQSPP_OK) {
            printf("Error in sign: %d\n", ret);
            PQSPP_free_memory(sk);
            PQSPP_free_memory(pk);
            return -2;
        }
        printf("Signed a message; got a pq_proof of size %d bytes\n", pip_len);
        */

        // PQSPP_verify_digest
        ret = PQSPP_verify_digest(pk, pk_len, hash, sizeof(hash), ec_sig, ec_sig_len, pip,
        pip_len);
        if (ret != PQSPP_OK) {
            printf("Error in verify: %d\n", ret);
            PQSPP_free_memory(sk);
            PQSPP_free_memory(pk);
            PQSPP_free_memory(ec_sig);
            PQSPP_free_memory(pip);
            return -3;
        }

        printf("Successfully verified the signature and the preimage proof!\n");
    }