.. _pqspp_sign_digest:


===================
PQSPP_sign_digest
===================

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

`PQSPP_sign_digest` signs a message digest using the secret key generated from `PQSPP_keygen`.


Syntax
-------

.. code-block:: c

    int PQSPP_sign_digest(
        uint8_t*        sk, 
        unsigned char*  pbHash,
        size_t          cbHash, 
        uint8_t**       ec_sig, 
        int*            ec_sig_len, 
        uint8_t**       pip, 
        int*            pip_len
    );


Parameters
-----------
- `sk`
The pointer to the secret key. This secret key will be used to sign `pbHash`.

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

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

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

- `ec_sig`
The address of a uint8_t* pointer. `PQSPP_sign_digest` will populate this address with the address of the signature.

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

- `ec_sig_len`
The address of an integer variable. `PQSPP_sign_digest` will populate this address with the size of the signature. This size is in terms of number of bytes.

- `pip`
The address of a uint8_t* pointer. `PQSPP_sign_digest` will populate this address with the address of the proof.

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

- `pip_len`
The address of an integer variable. `PQSPP_sign_digest` will populate this address with the size of the proof. This size is in terms of 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);
        */

        // 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);

        // PQSPP_sign_digest
        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);
    }