YACA Integrity

---

Provides APIs for creating/verifying a signature and digesting a message.

Required Header

#include <yaca/yaca_sign.h>
#include <yaca/yaca_digest.h>

Overview

It provides advanced APIs for creating a signature using asymmetric private key, verifying a signature using asymmetric public key, calculating a HMAC/CMAC of given message using symmetric key and calculating message digests of given message without key.

Examples

Message Digest API example

#include <stdio.h>

#include <yaca_crypto.h>
#include <yaca_digest.h>
#include <yaca_error.h>

/* include helpers functions and definitions */
#include "misc.h"

int main()
{
    int ret;
    yaca_context_h ctx = YACA_CONTEXT_NULL;

    ret = yaca_initialize();
    if (ret != YACA_ERROR_NONE)
        goto exit;

    printf("Plain data (16 of %zu bytes): %.16s\n", INPUT_DATA_SIZE, INPUT_DATA);

    /* Initialize digest context */
    ret = yaca_digest_initialize(&ctx, YACA_DIGEST_SHA256);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Feeds the message */
    ret = yaca_digest_update(ctx, INPUT_DATA, INPUT_DATA_SIZE);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Get digest length */
    size_t digest_len;
    ret = yaca_context_get_output_length(ctx, 0, &digest_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Calculate digest */
    {
        char digest[digest_len];
        ret = yaca_digest_finalize(ctx, digest, &digest_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display digest in hexadecimal format */
        dump_hex(digest, digest_len, "Message digest: ");
    }

exit:
    yaca_context_destroy(ctx);

    yaca_cleanup();
    return ret;
}

Signature API example

#include <stdio.h>

#include <yaca_crypto.h>
#include <yaca_sign.h>
#include <yaca_key.h>
#include <yaca_error.h>

/* include helpers functions and definitions */
#include "misc.h"

int main()
{
    int ret;
    yaca_context_h ctx = YACA_CONTEXT_NULL;
    yaca_key_h priv_key = YACA_KEY_NULL;
    yaca_key_h pub_key = YACA_KEY_NULL;
    yaca_padding_e padding = YACA_PADDING_PKCS1_PSS;

    char *signature = NULL;
    size_t signature_len;

    ret = yaca_initialize();
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Generate key pair */
    ret = yaca_key_generate(YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_LENGTH_2048BIT, &priv_key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_key_extract_public(priv_key, &pub_key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Sign */
    {
        /* Initialize sign context */
        ret = yaca_sign_initialize(&ctx, YACA_DIGEST_SHA256, priv_key);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Set padding method */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_PADDING, &padding, sizeof(padding));
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Feeds the message */
        ret = yaca_sign_update(ctx, INPUT_DATA, INPUT_DATA_SIZE);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get signature length and allocate memory */
        ret = yaca_context_get_output_length(ctx, 0, &signature_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_malloc(signature_len, (void**)&signature);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate signature */
        ret = yaca_sign_finalize(ctx, signature, &signature_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display signature in hexadecimal format */
        dump_hex(signature, signature_len, "Signature of INPUT_DATA:");

        yaca_context_destroy(ctx);
        ctx = YACA_CONTEXT_NULL;
    }

    /* Verify */
    {
        /* Initialize verify context */
        ret = yaca_verify_initialize(&ctx, YACA_DIGEST_SHA256, pub_key);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Set padding method */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_PADDING, &padding, sizeof(padding));
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Feeds the message */
        ret = yaca_verify_update(ctx, INPUT_DATA, INPUT_DATA_SIZE);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Verify signature */
        ret = yaca_verify_finalize(ctx, signature, signature_len);
        if (ret != YACA_ERROR_NONE) {
            printf("Verification failed\n");
            goto exit;
        } else {
            printf("Verification successful\n");
        }
    }

exit:
    yaca_free(signature);
    yaca_key_destroy(priv_key);
    yaca_key_destroy(pub_key);
    yaca_context_destroy(ctx);

    yaca_cleanup();
    return ret;
}

HMAC Signature API example

#include <stdio.h>

#include <yaca_crypto.h>
#include <yaca_sign.h>
#include <yaca_key.h>
#include <yaca_error.h>

/* include helpers functions and definitions */
#include "misc.h"

int main()
{
    int ret;
    yaca_context_h ctx = YACA_CONTEXT_NULL;
    yaca_key_h sym_key = YACA_KEY_NULL;

    char *signature1 = NULL;
    char *signature2 = NULL;
    size_t signature_len;

    ret = yaca_initialize();
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Key generation */
    ret = yaca_key_generate(YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_LENGTH_256BIT, &sym_key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Sign */
    {
        /* Initialize sign context */
        ret = yaca_sign_initialize_hmac(&ctx, YACA_DIGEST_SHA512, sym_key);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Feeds the message */
        ret = yaca_sign_update(ctx, INPUT_DATA, INPUT_DATA_SIZE);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get signature length and allocate memory */
        ret = yaca_context_get_output_length(ctx, 0, &signature_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_malloc(signature_len, (void**)&signature1);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate signature */
        ret = yaca_sign_finalize(ctx, signature1, &signature_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display signature in hexadecimal format */
        dump_hex(signature1, signature_len, "HMAC Signature of INPUT_DATA:");

        yaca_context_destroy(ctx);
        ctx = YACA_CONTEXT_NULL;
    }

    /* Verify */
    {
        /* Initialize sign context */
        ret = yaca_sign_initialize_hmac(&ctx, YACA_DIGEST_SHA512, sym_key);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Feeds the message */
        ret = yaca_sign_update(ctx, INPUT_DATA, INPUT_DATA_SIZE);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get signature length and allocate memory */
        ret = yaca_context_get_output_length(ctx, 0, &signature_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_malloc(signature_len, (void**)&signature2);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate signature */
        ret = yaca_sign_finalize(ctx, signature2, &signature_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Verify signature */
        ret = yaca_memcmp(signature1, signature2, signature_len);
        if (ret != YACA_ERROR_NONE) {
            printf("Verification failed\n");
            goto exit;
        } else {
            printf("Verification successful\n");
        }
    }

exit:
    yaca_free(signature1);
    yaca_free(signature2);
    yaca_key_destroy(sym_key);
    yaca_context_destroy(ctx);

    yaca_cleanup();
    return ret;
}

Functions
int	yaca_digest_initialize (yaca_context_h *ctx, yaca_digest_algorithm_e algo)
	Initializes a digest context.
int	yaca_digest_update (yaca_context_h ctx, const char *message, size_t message_len)
	Feeds the message into the message digest algorithm.
int	yaca_digest_finalize (yaca_context_h ctx, char *digest, size_t *digest_len)
	Calculates the final digest.
int	yaca_sign_initialize (yaca_context_h *ctx, yaca_digest_algorithm_e algo, const yaca_key_h prv_key)
	Initializes a signature context for asymmetric signatures.
int	yaca_sign_initialize_hmac (yaca_context_h *ctx, yaca_digest_algorithm_e algo, const yaca_key_h sym_key)
	Initializes a signature context for HMAC.
int	yaca_sign_initialize_cmac (yaca_context_h *ctx, yaca_encrypt_algorithm_e algo, const yaca_key_h sym_key)
	Initializes a signature context for CMAC.
int	yaca_sign_update (yaca_context_h ctx, const char *message, size_t message_len)
	Feeds the message into the digital signature or MAC algorithm.
int	yaca_sign_finalize (yaca_context_h ctx, char *signature, size_t *signature_len)
	Calculates the final signature or MAC.
int	yaca_verify_initialize (yaca_context_h *ctx, yaca_digest_algorithm_e algo, const yaca_key_h pub_key)
	Initializes a signature verification context for asymmetric signatures.
int	yaca_verify_update (yaca_context_h ctx, const char *message, size_t message_len)
	Feeds the message into the digital signature verification algorithm.
int	yaca_verify_finalize (yaca_context_h ctx, const char *signature, size_t signature_len)
	Performs the verification.

---

Function Documentation

int yaca_digest_finalize	(	yaca_context_h	ctx,
		char *	digest,
		size_t *	digest_len
	)

Calculates the final digest.

Since :

3.0

Remarks:

Skipping yaca_digest_update() and calling only yaca_digest_finalize() will produce an empty message digest.

Parameters:

[in,out]	ctx	A valid digest context
[out]	digest	Buffer for the message digest (must be allocated by client, see yaca_context_get_output_length())
[out]	digest_len	Length of the digest, actual number of bytes written will be returned here

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, invalid ctx)
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_digest_initialize()

yaca_digest_update()

yaca_context_get_output_length()

int yaca_digest_initialize	(	yaca_context_h *	ctx,
		yaca_digest_algorithm_e	algo
	)

Initializes a digest context.

Since :

3.0

Remarks:

The ctx should be released using yaca_context_destroy().

Parameters:

[out]	ctx	Newly created context
[in]	algo	Digest algorithm that will be used

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, invalid algo)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_digest_algorithm_e

yaca_digest_update()

yaca_digest_finalize()

yaca_context_destroy()

int yaca_digest_update	(	yaca_context_h	ctx,
		const char *	message,
		size_t	message_len
	)

Feeds the message into the message digest algorithm.

Since :

3.0

Parameters:

[in,out]	ctx	Context created by yaca_digest_initialize()
[in]	message	Message from which the digest is to be calculated
[in]	message_len	Length of the message

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, 0, invalid ctx)
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_digest_initialize()

yaca_digest_finalize()

int yaca_sign_finalize	(	yaca_context_h	ctx,
		char *	signature,
		size_t *	signature_len
	)

Calculates the final signature or MAC.

Since :

3.0

Remarks:

Skipping yaca_sign_update() and calling only yaca_sign_finalize() will produce a signature or MAC of an empty message.

Parameters:

[in,out]	ctx	A valid sign context
[out]	signature	Buffer for the MAC or the message signature (must be allocated by client, see yaca_context_get_output_length())
[out]	signature_len	Length of the MAC or the signature, actual number of bytes written will be returned here

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, invalid ctx)
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_sign_initialize()

yaca_sign_update()

yaca_sign_initialize_hmac()

yaca_sign_initialize_cmac()

yaca_context_get_output_length()

int yaca_sign_initialize	(	yaca_context_h *	ctx,
		yaca_digest_algorithm_e	algo,
		const yaca_key_h	prv_key
	)

Initializes a signature context for asymmetric signatures.

Since :

3.0

Remarks:

For verification use yaca_verify_initialize(), yaca_verify_update() and yaca_verify_finalize() functions with matching public key.

For RSA operations the default padding used is YACA_PADDING_PKCS1. It can be changed using yaca_context_set_property() with YACA_PROPERTY_PADDING.

For YACA_DIGEST_SHA384 and YACA_DIGEST_SHA512 the RSA key size must be bigger than YACA_KEY_LENGTH_512BIT.

Using of YACA_DIGEST_MD5 algorithm for DSA and ECDSA operations is prohibited.

Using of YACA_DIGEST_MD5 or YACA_DIGEST_SHA224 with YACA_PADDING_X931 is prohibited.

The ctx should be released using yaca_context_destroy().

Parameters:

[out]	ctx	Newly created context
[in]	algo	Digest algorithm that will be used
[in]	prv_key	Private key that will be used, algorithm is deduced based on key type, supported key types: YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_TYPE_DSA_PRIV, YACA_KEY_TYPE_EC_PRIV

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, invalid algo or prv_key)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_type_e

yaca_digest_algorithm_e

yaca_padding_e

yaca_context_set_property()

yaca_sign_update()

yaca_sign_finalize()

yaca_verify_initialize()

yaca_verify_update()

yaca_verify_finalize()

yaca_context_destroy()

int yaca_sign_initialize_cmac	(	yaca_context_h *	ctx,
		yaca_encrypt_algorithm_e	algo,
		const yaca_key_h	sym_key
	)

Initializes a signature context for CMAC.

Since :

3.0

Remarks:

For verification, calculate message CMAC and compare with received MAC using yaca_memcmp().

The ctx should be released using yaca_context_destroy().

Parameters:

[out]	ctx	Newly created context
[in]	algo	Encryption algorithm that will be used
[in]	sym_key	Symmetric key that will be used, supported key types: YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_TYPE_DES

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, invalid algo or sym_key)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_type_e

yaca_encrypt_algorithm_e

yaca_sign_update()

yaca_sign_finalize()

yaca_memcmp()

yaca_context_destroy()

int yaca_sign_initialize_hmac	(	yaca_context_h *	ctx,
		yaca_digest_algorithm_e	algo,
		const yaca_key_h	sym_key
	)

Initializes a signature context for HMAC.

Since :

3.0

Remarks:

For verification, calculate message HMAC and compare with received MAC using yaca_memcmp().

The ctx should be released using yaca_context_destroy().

Parameters:

[out]	ctx	Newly created context
[in]	algo	Digest algorithm that will be used
[in]	sym_key	Symmetric key that will be used, supported key types: YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_TYPE_DES

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, invalid algo or sym_key)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_type_e

yaca_digest_algorithm_e

yaca_sign_update()

yaca_sign_finalize()

yaca_memcmp()

yaca_context_destroy()

int yaca_sign_update	(	yaca_context_h	ctx,
		const char *	message,
		size_t	message_len
	)

Feeds the message into the digital signature or MAC algorithm.

Since :

3.0

Parameters:

[in,out]	ctx	Context created by yaca_sign_initialize(), yaca_sign_initialize_hmac() or yaca_sign_initialize_cmac()
[in]	message	Message to be signed
[in]	message_len	Length of the message

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, 0, invalid ctx)
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_sign_initialize()

yaca_sign_finalize()

yaca_sign_initialize_hmac()

yaca_sign_initialize_cmac()

int yaca_verify_finalize	(	yaca_context_h	ctx,
		const char *	signature,
		size_t	signature_len
	)

Performs the verification.

Since :

3.0

Remarks:

Skipping yaca_verify_update() and calling only yaca_verify_finalize() will verify the signature of an empty message.

Parameters:

[in,out]	ctx	A valid verify context
[in]	signature	Message signature to be verified
[in]	signature_len	Length of the signature

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, invalid ctx)
YACA_ERROR_INTERNAL	Internal error
YACA_ERROR_DATA_MISMATCH	The verification failed

See also:

yaca_verify_initialize()

yaca_verify_update()

yaca_sign_finalize()

int yaca_verify_initialize	(	yaca_context_h *	ctx,
		yaca_digest_algorithm_e	algo,
		const yaca_key_h	pub_key
	)

Initializes a signature verification context for asymmetric signatures.

Since :

3.0

Remarks:

For RSA operations the default padding used is YACA_PADDING_PKCS1. It can be changed using yaca_context_set_property() with YACA_PROPERTY_PADDING. For verify to succeed it has to be set to the same value it was signed with.

The ctx should be released using yaca_context_destroy().

Parameters:

[out]	ctx	Newly created context
[in]	algo	Digest algorithm that will be used
[in]	pub_key	Public key that will be used, algorithm is deduced based on key type, supported key types: YACA_KEY_TYPE_RSA_PUB, YACA_KEY_TYPE_DSA_PUB, YACA_KEY_TYPE_EC_PUB

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, invalid algo or pub_key)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_type_e

yaca_digest_algorithm_e

yaca_padding_e

yaca_context_set_property()

yaca_verify_update()

yaca_verify_finalize()

yaca_context_destroy()

int yaca_verify_update	(	yaca_context_h	ctx,
		const char *	message,
		size_t	message_len
	)

Feeds the message into the digital signature verification algorithm.

Since :

3.0

Parameters:

[in,out]	ctx	Context created by yaca_verify_initialize()
[in]	message	Message
[in]	message_len	Length of the message

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, 0, invalid ctx)
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_verify_initialize()

yaca_verify_finalize()