TrustedQSL Library API: Signing API

TrustedQSL Library API

Functions
Signing API

## Functions
DLLEXPORT int CALLCONVENTION | tqsl_beginSigning (tQSL_Cert cert, char *password, int(*pwcb)(char *pwbuf, int pwsize, void *userdata), void *user)
DLLEXPORT int CALLCONVENTION | tqsl_checkSigningStatus (tQSL_Cert cert)
DLLEXPORT int CALLCONVENTION | tqsl_getMaxSignatureSize (tQSL_Cert cert, int *sigsize)
DLLEXPORT int CALLCONVENTION | tqsl_signDataBlock (tQSL_Cert cert, const unsigned char *data, int datalen, unsigned char *sig, int *siglen)
DLLEXPORT int CALLCONVENTION | tqsl_verifyDataBlock (tQSL_Cert cert, const unsigned char *data, int datalen, unsigned char *sig, int siglen)
DLLEXPORT int CALLCONVENTION | tqsl_signQSORecord (tQSL_Cert cert, tQSL_Location loc, TQSL_QSO_RECORD *rec, unsigned char *sig, int *siglen)
DLLEXPORT int CALLCONVENTION | tqsl_endSigning (tQSL_Cert cert)

## Detailed Description

The Signing API uses a tQSL_Cert (see Certificate Handling API) to digitally sign a block of data.

## Function Documentation

## ◆ tqsl_beginSigning()

DLLEXPORT int CALLCONVENTION tqsl_beginSigning | ( | tQSL_Cert | cert,
|  | char * | password,
|  | int(* | pwcb )(char *pwbuf, int pwsize, void *userdata),
|  | void * | user )

Initialize the tQSL_Cert object for use in signing.

This produces an unencrypted copy of the private key in memory.

if `password` is not NULL, it must point to the password to use to decrypt the private key. If `password` is NULL and `pwcb` is not NULL, `pwcb` is called to get the password. If the private key is encrypted and both `password` and `pwcb` are NULL, or if the supplied password fails to decrypt the key, a TQSL_PASSWORD_ERROR error is returned.

`pwcb` parameters: `pwbuf` is a pointer to a buffer of `pwsize` chars. The buffer should be NUL-terminated.

## ◆ tqsl_checkSigningStatus()

DLLEXPORT int CALLCONVENTION tqsl_checkSigningStatus | ( | tQSL_Cert | cert | ) |

Test whether the tQSL_Cert object is initialized for signing.

Returns 0 if initialized. Sets tQSL_Error to TQSL_SIGNINIT_ERROR if not.

## ◆ tqsl_endSigning()

DLLEXPORT int CALLCONVENTION tqsl_endSigning | ( | tQSL_Cert | cert | ) |

Terminate signing operations for this tQSL_Cert object.

This zero-fills the unencrypted private key in memory.

## ◆ tqsl_getMaxSignatureSize()

DLLEXPORT int CALLCONVENTION tqsl_getMaxSignatureSize | ( | tQSL_Cert | cert,
|  | int * | sigsize )

Get the maximum size of a signature block that will be produced when the tQSL_Cert is used to sign data. (Note that the size of the signature block is unaffected by the size of the data block being signed.)

## ◆ tqsl_signDataBlock()

DLLEXPORT int CALLCONVENTION tqsl_signDataBlock | ( | tQSL_Cert | cert,
|  | const unsigned char * | data,
|  | int | datalen,
|  | unsigned char * | sig,
|  | int * | siglen )

Sign a data block.

tqsl_beginSigning() must have been called for the tQSL_Cert object before calling this function.

## ◆ tqsl_signQSORecord()

DLLEXPORT int CALLCONVENTION tqsl_signQSORecord | ( | tQSL_Cert | cert,
|  | tQSL_Location | loc,
|  | TQSL_QSO_RECORD * | rec,
|  | unsigned char * | sig,
|  | int * | siglen )

Sign a single QSO record

tqsl_beginSigning() must have been called for the tQSL_Cert object before calling this function.

`loc` must be a valid tQSL_Location object. See Data API.

## ◆ tqsl_verifyDataBlock()

DLLEXPORT int CALLCONVENTION tqsl_verifyDataBlock | ( | tQSL_Cert | cert,
|  | const unsigned char * | data,
|  | int | datalen,
|  | unsigned char * | sig,
|  | int | siglen )

Verify a signed data block.

tqsl_beginSigning() need not have been called.