YACA Encryption

---

Provides APIs for encryption and decryption operations.

Required Header

#include <yaca/yaca_crypto.h>
#include <yaca/yaca_encrypt.h>
#include <yaca/yaca_seal.h>
#include <yaca/yaca_types.h>
#include <yaca/yaca_error.h>

Overview

It provides advanced APIs for encryption/decryption operations with symmetric keys and sealing/opening operations with asymmetric keys.

Examples

Encrypt API example

#include <stdio.h>

#include <yaca_crypto.h>
#include <yaca_encrypt.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 key = YACA_KEY_NULL;
    yaca_key_h iv = YACA_KEY_NULL;

    char *encrypted = NULL;
    char *decrypted = NULL;
    size_t encrypted_len;
    size_t decrypted_len;

    size_t block_len;
    size_t output_len;
    size_t written_len;

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

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

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

    /* IV generation */
    ret = yaca_key_generate(YACA_KEY_TYPE_IV, YACA_KEY_LENGTH_IV_128BIT, &iv);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Encryption */
    {
        /* Initialize encryption context */
        ret = yaca_encrypt_initialize(&ctx, YACA_ENCRYPT_AES, YACA_BCM_CBC, key, iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the update */
        ret = yaca_context_get_output_length(ctx, INPUT_DATA_SIZE, &output_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the finalize */
        ret = yaca_context_get_output_length(ctx, 0, &block_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate max output length and allocate memory */
        encrypted_len = output_len + block_len;
        ret = yaca_zalloc(encrypted_len, (void**)&encrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Encrypt data */
        ret = yaca_encrypt_update(ctx, INPUT_DATA, INPUT_DATA_SIZE, encrypted, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        encrypted_len = written_len;

        ret = yaca_encrypt_finalize(ctx, encrypted + encrypted_len, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        encrypted_len += written_len;

        /* Resize output buffer */
        ret = yaca_realloc(encrypted_len, (void**)&encrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display encrypted data in hexadecimal format */
        dump_hex(encrypted, 16, "Encrypted data (16 of %zu bytes): ", encrypted_len);

        yaca_context_destroy(ctx);
        ctx = YACA_CONTEXT_NULL;
    }

    /* Decryption */
    {
        /* Initialize decryption context */
        ret = yaca_decrypt_initialize(&ctx, YACA_ENCRYPT_AES, YACA_BCM_CBC, key, iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the update */
        ret = yaca_context_get_output_length(ctx, encrypted_len, &output_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the finalize */
        ret = yaca_context_get_output_length(ctx, 0, &block_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate max output length and allocate memory */
        decrypted_len = output_len + block_len;
        ret = yaca_zalloc(decrypted_len, (void**)&decrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Decrypt data */
        ret = yaca_decrypt_update(ctx, encrypted, encrypted_len, decrypted, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        decrypted_len = written_len;

        ret = yaca_decrypt_finalize(ctx, decrypted + decrypted_len, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        decrypted_len += written_len;

        /* Resize output buffer */
        ret = yaca_realloc(decrypted_len, (void**)&decrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        printf("Decrypted data (16 of %zu bytes): %.16s\n\n", decrypted_len, decrypted);
    }

exit:
    yaca_free(decrypted);
    yaca_free(encrypted);
    yaca_context_destroy(ctx);
    yaca_key_destroy(iv);
    yaca_key_destroy(key);

    yaca_cleanup();
    return ret;
}

AES GCM encrypt API example

#include <stdio.h>

#include <yaca_crypto.h>
#include <yaca_encrypt.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 key = YACA_KEY_NULL;
    yaca_key_h iv = YACA_KEY_NULL;

    char *encrypted = NULL;
    char *decrypted = NULL;
    size_t encrypted_len;
    size_t decrypted_len;

    char *aad = NULL;
    char *tag = NULL;
    size_t aad_len = 16;
    size_t tag_len = 16;

    size_t block_len;
    size_t output_len;
    size_t written_len;

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

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

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

    /* IV generation */
    ret = yaca_key_generate(YACA_KEY_TYPE_IV, YACA_KEY_LENGTH_IV_128BIT, &iv);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Additional Authentication Data generation */
    ret = yaca_zalloc(aad_len, (void**)&aad);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_randomize_bytes(aad, aad_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Allocate memory for tag */
    ret = yaca_zalloc(tag_len, (void**)&tag);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Encryption */
    {
        /* Initialize encryption context */
        ret = yaca_encrypt_initialize(&ctx, YACA_ENCRYPT_AES, YACA_BCM_GCM, key, iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the update */
        ret = yaca_context_get_output_length(ctx, INPUT_DATA_SIZE, &output_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the finalize */
        ret = yaca_context_get_output_length(ctx, 0, &block_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate max output length and allocate memory */
        encrypted_len = output_len + block_len;
        ret = yaca_zalloc(encrypted_len, (void**)&encrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Provide Additional Authentication Data */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_GCM_AAD, aad, aad_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Encrypt data */
        ret = yaca_encrypt_update(ctx, INPUT_DATA, INPUT_DATA_SIZE, encrypted, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        encrypted_len = written_len;

        ret = yaca_encrypt_finalize(ctx, encrypted + encrypted_len, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        encrypted_len += written_len;

        /* Resize output buffer */
        ret = yaca_realloc(encrypted_len, (void**)&encrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Set the tag length and get the tag */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_GCM_TAG_LEN, &tag_len, sizeof(tag_len));
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_context_get_property(ctx, YACA_PROPERTY_GCM_TAG, (void**)tag, &tag_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display encrypted data in hexadecimal format */
        dump_hex(encrypted, 16, "Encrypted data (16 of %zu bytes): ", encrypted_len);

        yaca_context_destroy(ctx);
        ctx = YACA_CONTEXT_NULL;
    }

    /* Decryption */
    {
        /* Initialize decryption context */
        ret = yaca_decrypt_initialize(&ctx, YACA_ENCRYPT_AES, YACA_BCM_GCM, key, iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the update */
        ret = yaca_context_get_output_length(ctx, encrypted_len, &output_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the finalize */
        ret = yaca_context_get_output_length(ctx, 0, &block_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate max output length and allocate memory */
        decrypted_len = output_len + block_len;
        ret = yaca_zalloc(decrypted_len, (void**)&decrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Provide Additional Authentication Data */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_GCM_AAD, aad, aad_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Decrypt data */
        ret = yaca_decrypt_update(ctx, encrypted, encrypted_len, decrypted, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        decrypted_len = written_len;

        /* Set expected tag value before final decryption */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_GCM_TAG, tag, tag_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_decrypt_finalize(ctx, decrypted + decrypted_len, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        decrypted_len += written_len;

        /* Resize output buffer */
        ret = yaca_realloc(decrypted_len, (void**)&decrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        printf("Decrypted data (16 of %zu bytes): %.16s\n\n", decrypted_len, decrypted);
    }

exit:
    yaca_free(decrypted);
    yaca_free(encrypted);
    yaca_free(tag);
    yaca_free(aad);
    yaca_context_destroy(ctx);
    yaca_key_destroy(iv);
    yaca_key_destroy(key);

    yaca_cleanup();
    return ret;
}

AES CCM encrypt API example

#include <stdio.h>

#include <yaca_crypto.h>
#include <yaca_encrypt.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 key = YACA_KEY_NULL;
    yaca_key_h iv = YACA_KEY_NULL;

    char *encrypted = NULL;
    char *decrypted = NULL;
    size_t encrypted_len;
    size_t decrypted_len;

    char *aad = NULL;
    char *tag = NULL;
    size_t aad_len = 16;
    size_t tag_len = 12;

    size_t block_len;
    size_t output_len;
    size_t written_len;

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

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

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

    /* IV generation */
    ret = yaca_key_generate(YACA_KEY_TYPE_IV, YACA_KEY_LENGTH_IV_64BIT, &iv);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Additional Authentication Data generation */
    ret = yaca_zalloc(aad_len, (void**)&aad);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_randomize_bytes(aad, aad_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Allocate memory for tag */
    ret = yaca_zalloc(tag_len, (void**)&tag);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Encryption */
    {
        /* Initialize encryption context */
        ret = yaca_encrypt_initialize(&ctx, YACA_ENCRYPT_AES, YACA_BCM_CCM, key, iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the update */
        ret = yaca_context_get_output_length(ctx, INPUT_DATA_SIZE, &output_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the finalize */
        ret = yaca_context_get_output_length(ctx, 0, &block_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate max output length and allocate memory */
        encrypted_len = output_len + block_len;
        ret = yaca_zalloc(encrypted_len, (void**)&encrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Set tag length */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_CCM_TAG_LEN, &tag_len, sizeof(tag_len));
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* The total plain text length must be passed (only needed if AAD is passed) */
        ret = yaca_encrypt_update(ctx, NULL, INPUT_DATA_SIZE , NULL, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Provide Additional Authentication Data */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_CCM_AAD, aad, aad_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Encrypt data */
        ret = yaca_encrypt_update(ctx, INPUT_DATA, INPUT_DATA_SIZE, encrypted, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        encrypted_len = written_len;

        ret = yaca_encrypt_finalize(ctx, encrypted + encrypted_len, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        encrypted_len += written_len;

        /* Resize output buffer */
        ret = yaca_realloc(encrypted_len, (void**)&encrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get the tag after final encryption */
        ret = yaca_context_get_property(ctx, YACA_PROPERTY_CCM_TAG, (void**)tag, &tag_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display encrypted data in hexadecimal format */
        dump_hex(encrypted, 16, "Encrypted data (16 of %zu bytes): ", encrypted_len);

        yaca_context_destroy(ctx);
        ctx = YACA_CONTEXT_NULL;
    }

    /* Decryption */
    {
        /* Initialize decryption context */
        ret = yaca_decrypt_initialize(&ctx, YACA_ENCRYPT_AES, YACA_BCM_CCM, key, iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the update */
        ret = yaca_context_get_output_length(ctx, encrypted_len, &output_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the finalize */
        ret = yaca_context_get_output_length(ctx, 0, &block_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate max output length and allocate memory */
        decrypted_len = output_len + block_len;
        ret = yaca_zalloc(decrypted_len, (void**)&decrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Set expected tag value */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_CCM_TAG, tag, tag_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* The total encrypted text length must be passed (only needed if AAD is passed) */
        ret = yaca_decrypt_update(ctx, NULL, encrypted_len , NULL, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Provide Additional Authentication Data */
        ret = yaca_context_set_property(ctx, YACA_PROPERTY_CCM_AAD, aad, aad_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Decrypt data */
        ret = yaca_decrypt_update(ctx, encrypted, encrypted_len, decrypted, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        decrypted_len = written_len;

        ret = yaca_decrypt_finalize(ctx, decrypted + decrypted_len, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        decrypted_len += written_len;

        /* Resize output buffer */
        ret = yaca_realloc(decrypted_len, (void**)&decrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        printf("Decrypted data (16 of %zu bytes): %.16s\n\n", decrypted_len, decrypted);
    }

exit:
    yaca_free(decrypted);
    yaca_free(encrypted);
    yaca_free(tag);
    yaca_free(aad);
    yaca_context_destroy(ctx);
    yaca_key_destroy(iv);
    yaca_key_destroy(key);

    yaca_cleanup();
    return ret;
}

Asymmetric Encryption API example

#include <stdio.h>

#include <yaca_crypto.h>
#include <yaca_seal.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 rsa_pub = YACA_KEY_NULL;
    yaca_key_h rsa_priv = YACA_KEY_NULL;
    yaca_key_h sym_key = YACA_KEY_NULL;
    yaca_key_h iv = YACA_KEY_NULL;

    char *encrypted = NULL;
    char *decrypted = NULL;
    size_t encrypted_len;
    size_t decrypted_len;

    size_t block_len;
    size_t output_len;
    size_t written_len;

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

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

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

    ret = yaca_key_extract_public(rsa_priv, &rsa_pub);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Encryption */
    {
        /* Initialize encryption context */
        ret = yaca_seal_initialize(&ctx, rsa_pub, YACA_ENCRYPT_AES, YACA_BCM_CBC,
                                   YACA_KEY_LENGTH_256BIT, &sym_key, &iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the update */
        ret = yaca_context_get_output_length(ctx, INPUT_DATA_SIZE, &output_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the finalize */
        ret = yaca_context_get_output_length(ctx, 0, &block_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate max output length and allocate memory */
        encrypted_len = output_len + block_len;
        ret = yaca_zalloc(encrypted_len, (void**)&encrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Encrypt data */
        ret = yaca_seal_update(ctx, INPUT_DATA, INPUT_DATA_SIZE, encrypted, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        encrypted_len = written_len;

        ret = yaca_seal_finalize(ctx, encrypted + encrypted_len, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        encrypted_len += written_len;

        /* Resize output buffer */
        ret = yaca_realloc(encrypted_len, (void**)&encrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display encrypted data in hexadecimal format */
        dump_hex(encrypted, 16, "Encrypted data (16 of %zu bytes): ", encrypted_len);

        yaca_context_destroy(ctx);
        ctx = YACA_CONTEXT_NULL;
    }

    /* Decryption */
    {
        /* Initialize decryption context */
        ret = yaca_open_initialize(&ctx, rsa_priv, YACA_ENCRYPT_AES, YACA_BCM_CBC,
                                   YACA_KEY_LENGTH_256BIT, sym_key, iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the update */
        ret = yaca_context_get_output_length(ctx, encrypted_len, &output_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Get output length for the finalize */
        ret = yaca_context_get_output_length(ctx, 0, &block_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Calculate max output length and allocate memory */
        decrypted_len = output_len + block_len;
        ret = yaca_zalloc(decrypted_len, (void**)&decrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* Decrypt data */
        ret = yaca_open_update(ctx, encrypted, encrypted_len, decrypted, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        decrypted_len = written_len;

        ret = yaca_open_finalize(ctx, decrypted + decrypted_len, &written_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        decrypted_len += written_len;

        /* Resize output buffer */
        ret = yaca_realloc(decrypted_len, (void**)&decrypted);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        printf("Decrypted data (16 of %zu bytes): %.16s\n\n", decrypted_len, decrypted);
    }

exit:
    yaca_free(decrypted);
    yaca_free(encrypted);
    yaca_context_destroy(ctx);
    yaca_key_destroy(sym_key);
    yaca_key_destroy(iv);
    yaca_key_destroy(rsa_pub);
    yaca_key_destroy(rsa_priv);

    yaca_cleanup();
    return ret;
}

Functions
int	yaca_initialize (void)
	Initializes the library. Must be called before any other crypto function. Should be called once in each thread that uses yaca.
void	yaca_cleanup (void)
	Cleans up the library. Must be called before exiting the thread that called yaca_initialize().
int	yaca_malloc (size_t size, void **memory)
	Allocates the memory.
int	yaca_zalloc (size_t size, void **memory)
	Allocates the zeroed memory.
int	yaca_realloc (size_t size, void **memory)
	Re-allocates the memory.
void	yaca_free (void *memory)
	Frees the memory allocated by yaca_malloc(), yaca_zalloc(), yaca_realloc() or one of the cryptographic operations.
int	yaca_memcmp (const void *first, const void *second, size_t len)
	Safely compares first len bytes of two buffers.
int	yaca_randomize_bytes (char *data, size_t data_len)
	Generates random data.
int	yaca_context_set_property (yaca_context_h ctx, yaca_property_e property, const void *value, size_t value_len)
	Sets the non-standard context properties. Can only be called on an initialized context.
int	yaca_context_get_property (const yaca_context_h ctx, yaca_property_e property, void **value, size_t *value_len)
	Returns the non-standard context properties. Can only be called on an initialized context.
int	yaca_context_get_output_length (const yaca_context_h ctx, size_t input_len, size_t *output_len)
	Returns the minimum required size of the output buffer for a single crypto function call.
void	yaca_context_destroy (yaca_context_h ctx)
	Destroys the crypto context. Must be called on all contexts that are no longer used. Passing YACA_CONTEXT_NULL is allowed.
int	yaca_encrypt_get_iv_bit_length (yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, size_t key_bit_len, size_t *iv_bit_len)
	Returns the recommended/default length of the Initialization Vector for a given encryption configuration.
int	yaca_encrypt_initialize (yaca_context_h *ctx, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv)
	Initializes an encryption context.
int	yaca_encrypt_update (yaca_context_h ctx, const char *plaintext, size_t plaintext_len, char *ciphertext, size_t *ciphertext_len)
	Encrypts chunk of the data.
int	yaca_encrypt_finalize (yaca_context_h ctx, char *ciphertext, size_t *ciphertext_len)
	Encrypts the final chunk of the data.
int	yaca_decrypt_initialize (yaca_context_h *ctx, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv)
	Initializes an decryption context.
int	yaca_decrypt_update (yaca_context_h ctx, const char *ciphertext, size_t ciphertext_len, char *plaintext, size_t *plaintext_len)
	Decrypts chunk of the data.
int	yaca_decrypt_finalize (yaca_context_h ctx, char *plaintext, size_t *plaintext_len)
	Decrypts the final chunk of the data.
int	yaca_seal_initialize (yaca_context_h *ctx, const yaca_key_h pub_key, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, size_t sym_key_bit_len, yaca_key_h *sym_key, yaca_key_h *iv)
	Initializes an asymmetric encryption context and generates symmetric key and Initialization Vector.
int	yaca_seal_update (yaca_context_h ctx, const char *plaintext, size_t plaintext_len, char *ciphertext, size_t *ciphertext_len)
	Encrypts piece of the data.
int	yaca_seal_finalize (yaca_context_h ctx, char *ciphertext, size_t *ciphertext_len)
	Encrypts the final piece of the data.
int	yaca_open_initialize (yaca_context_h *ctx, const yaca_key_h prv_key, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, size_t sym_key_bit_len, const yaca_key_h sym_key, const yaca_key_h iv)
	Initializes an asymmetric decryption context.
int	yaca_open_update (yaca_context_h ctx, const char *ciphertext, size_t ciphertext_len, char *plaintext, size_t *plaintext_len)
	Decrypts piece of the data.
int	yaca_open_finalize (yaca_context_h ctx, char *plaintext, size_t *plaintext_len)
	Decrypts last chunk of sealed message.
Typedefs
typedef struct yaca_context_s *	yaca_context_h
	The context handle.
typedef struct yaca_key_s *	yaca_key_h
	The handle of a key, an Initialization Vector or a key generation parameters.
Defines
#define	YACA_CONTEXT_NULL   ((yaca_context_h) NULL)
	NULL value for the crypto context.
#define	YACA_KEY_LENGTH_DH_GENERATOR_2   (YACA_KEYLEN_COMPONENT_TYPE_DH | YACA_KEYLEN_COMPONENT_DH_GEN_2)
	A value indicating generator equal 2 for DH parameters. To be or'ed with safe prime length in bits. Prime length is recommended to be 2048 bits or higher.
#define	YACA_KEY_LENGTH_DH_GENERATOR_5   (YACA_KEYLEN_COMPONENT_TYPE_DH | YACA_KEYLEN_COMPONENT_DH_GEN_5)
	A value indicating generator equal 5 for DH parameters. To be or'ed with safe prime length in bits. Prime length is recommended to be 2048 bits or higher.

---

Define Documentation

#define YACA_CONTEXT_NULL   ((yaca_context_h) NULL)

NULL value for the crypto context.

Since :

3.0

---

Typedef Documentation

typedef struct yaca_context_s* yaca_context_h

The context handle.

Since :

3.0

typedef struct yaca_key_s* yaca_key_h

The handle of a key, an Initialization Vector or a key generation parameters.

Since :

3.0

---

Enumeration Type Documentation

enum yaca_block_cipher_mode_e

Enumeration of YACA chaining modes for block ciphers.

Since :

3.0

Enumerator:

YACA_BCM_NONE	Used when algorithm doesn't support block ciphers modes. Initialization Vector is not used.
YACA_BCM_ECB	ECB block cipher mode. Initialization Vector is not used. By default the input data is padded using standard block padding (YACA_PADDING_PKCS7). Padding can be disabled using yaca_context_set_property() and YACA_PROPERTY_PADDING,YACA_PADDING_NONE, then the total length of data passed until *_finalize() MUST be a multiple of block size. YACA_PROPERTY_PADDING can be set at the latest before the *_finalize() call.
YACA_BCM_CTR	CTR block cipher mode. 128-bit Initialization Vector for AES, 64-bit for other algorithms is mandatory.
YACA_BCM_CBC	CBC block cipher mode. 128-bit Initialization Vector for AES, 64-bit for other algorithms is mandatory. By default the input data is padded using standard block padding (YACA_PADDING_PKCS7). Padding can be disabled using yaca_context_set_property() and YACA_PROPERTY_PADDING, YACA_PADDING_NONE, then the total length of data passed until *_finalize() MUST be a multiple of block size. YACA_PROPERTY_PADDING can be set at the latest before the *_finalize() call.
YACA_BCM_GCM	GCM block cipher mode. This is a variable Initialization Vector length mode (recommended 96-bits). Supported properties: YACA_PROPERTY_GCM_TAG_LEN = GCM tag length (optional) Supported tag lengths: 4, 8, 12, 13, 14, 15, 16 (16 bytes tag by default). Set after yaca_encrypt_finalize() / yaca_seal_finalize() and before yaca_context_get_property(YACA_PROPERTY_GCM_TAG) in encryption / seal operation. The value should be a size_t variable. In decryption / open operation tag length is not set. YACA_PROPERTY_GCM_TAG = GCM tag Get after yaca_encrypt_finalize() / yaca_seal_finalize() in encryption / seal operation. Set after yaca_decrypt_update() / yaca_open_update() and before yaca_decrypt_finalize() / yaca_open_finalize() in decryption / open operation. YACA_PROPERTY_GCM_AAD = additional authentication data (optional) Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation. Set after yaca_decrypt_initialize() / yaca_open_initialize() and before yaca_decrypt_update() / yaca_open_update() in decryption / open operation. See also: yaca_context_set_property() yaca_context_get_property()
YACA_BCM_CFB	Default CFB block cipher mode. 128-bit Initialization Vector for AES, 64-bit for other algorithms is mandatory.
YACA_BCM_CFB1	1 bit CFB block cipher mode. 128-bit Initialization Vector for AES, 64-bit for other algorithms is mandatory.
YACA_BCM_CFB8	8 bits CFB block cipher mode. 128-bit Initialization Vector for AES, 64-bit for other algorithms is mandatory.
YACA_BCM_OFB	OFB block cipher mode. 128-bit Initialization Vector for AES, 64-bit for other algorithms is mandatory.
YACA_BCM_CCM	CBC-MAC Mode (AES). This is a variable Initialization Vector length mode. Supported Initialization Vector lengths: 56-104 bits in steps of 8 bits (recommended 56-bits). Supported properties: YACA_PROPERTY_CCM_TAG_LEN = CCM tag length (optional) Supported tag lengths: 4-16 bytes in steps of 2 bytes (12 bytes tag by default). Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation. The value should be a size_t variable. In decryption / open operation tag length is not set. YACA_PROPERTY_CCM_TAG = CCM tag Get after yaca_encrypt_finalize() / yaca_seal_finalize() in encryption / seal operation. Set after yaca_decrypt_initialize() / yaca_open_initialize() and before yaca_decrypt_update() / yaca_open_update() in decryption / open operation. YACA_PROPERTY_CCM_AAD = additional authentication data (optional) The total plaintext length must be passed to yaca_encrypt_update() / yaca_seal_update() if AAD is used. Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation. You can only call yaca_encrypt_update() / yaca_seal_update() once for AAD and once for the plaintext. The total encrypted text length must be passed to yaca_decrypt_update() / yaca_open_update() if AAD is used. Set after yaca_decrypt_initialize() / yaca_open_initialize() and before yaca_decrypt_update() / yaca_open_update() in decryption / open operation. You can only call yaca_decrypt_update() / yaca_open_update() once for AAD and once for the encrypted text. See also: yaca_context_set_property() yaca_context_get_property()
YACA_BCM_WRAP	Used with YACA_ENCRYPT_AES or YACA_ENCRYPT_3DES_3TDEA to perform a key wrapping (key material symmetric encryption). Only a single yaca_encrypt_update() / yaca_decrypt_update() is allowed. Usage in yaca_seal_initialize() / yaca_open_finalize() is forbidden. Key used to do the wrapping with YACA_ENCRYPT_AES can be a 128-bit key, a 192-bit key, or a 256-bit key. 64-bit Initialization Vector is used. Wrapped key can be a 128-bit key, a 192-bit key, or a 256-bit key. YACA_ENCRYPT_AES allows wrapping multiple keys together. Key used to do the wrapping with YACA_ENCRYPT_3DES_3TDEA can be a 192-bit DES key only. Initialization Vector is not used. Wrapped key can be a 128-bit DES key (two-key), or a 192-bit DES key (three-key). YACA_ENCRYPT_3DES_3TDEA allows wrapping only one key.

enum yaca_digest_algorithm_e

Enumeration of YACA message digest algorithms.

Since :

3.0

Enumerator:

YACA_DIGEST_MD5	Message digest algorithm MD5
YACA_DIGEST_SHA1	Message digest algorithm SHA1
YACA_DIGEST_SHA224	Message digest algorithm SHA2, 224bit
YACA_DIGEST_SHA256	Message digest algorithm SHA2, 256bit
YACA_DIGEST_SHA384	Message digest algorithm SHA2, 384bit
YACA_DIGEST_SHA512	Message digest algorithm SHA2, 512bit

enum yaca_encrypt_algorithm_e

Enumeration of YACA symmetric encryption algorithms.

Since :

3.0

Enumerator:

YACA_ENCRYPT_AES	AES encryption. Supported key lengths: 128, 192 and 256 bits. Supported block cipher modes: YACA_BCM_CBC, YACA_BCM_OFB, YACA_BCM_CFB, YACA_BCM_CFB1, YACA_BCM_CFB8, YACA_BCM_ECB, YACA_BCM_GCM, YACA_BCM_CCM, YACA_BCM_CTR, YACA_BCM_WRAP see yaca_block_cipher_mode_e for details on additional properties (mandatory).
YACA_ENCRYPT_UNSAFE_DES	DES encryption. Supported key lengths: 64 bits. Supported block cipher modes: YACA_BCM_CBC, YACA_BCM_OFB, YACA_BCM_CFB, YACA_BCM_CFB1, YACA_BCM_CFB8, YACA_BCM_ECB see yaca_block_cipher_mode_e for details on additional properties (mandatory).
YACA_ENCRYPT_UNSAFE_3DES_2TDEA	3DES 2-key encryption. Supported key lengths: 128 bits. Supported block cipher modes: YACA_BCM_CBC, YACA_BCM_OFB, YACA_BCM_CFB, YACA_BCM_ECB see yaca_block_cipher_mode_e for details on additional properties (mandatory). Use double DES keys to perform corresponding 2-key 3DES encryption.
YACA_ENCRYPT_3DES_3TDEA	3DES 3-key encryption. Supported key lengths: 192 bits. Supported block cipher modes: YACA_BCM_CBC, YACA_BCM_OFB, YACA_BCM_CFB, YACA_BCM_CFB1, YACA_BCM_CFB8, YACA_BCM_ECB, YACA_BCM_WRAP see yaca_block_cipher_mode_e for details on additional properties (mandatory). Use triple DES keys to perform corresponding 3-key 3DES encryption.
YACA_ENCRYPT_UNSAFE_RC2	RC2 encryption. This is a variable key length cipher. Supported key lengths: 8-1024 bits in steps of 8 bits. Effective key bits property by default equals to 128 bits. Effective key bits can be set using yaca_context_set_property() and YACA_PROPERTY_RC2_EFFECTIVE_KEY_BITS. It can be set after yaca_encrypt_initialize() / yaca_decrypt_initialize(), and before yaca_encrypt_update() / yaca_decrypt_update() in encryption / decryption operation. Supported block cipher modes: YACA_BCM_CBC, YACA_BCM_OFB, YACA_BCM_CFB, YACA_BCM_ECB see yaca_block_cipher_mode_e for details on additional properties (mandatory).
YACA_ENCRYPT_UNSAFE_RC4	RC4 encryption. This is a variable key length cipher. Supported key lengths: 40–2048 bits in steps of 8 bits. Initialization Vector is not used. This cipher doesn't support block cipher modes, use YACA_BCM_NONE instead.
YACA_ENCRYPT_CAST5	CAST5 encryption. This is a variable key length cipher. Supported key lengths: 40-128 bits in steps of 8 bits. Supported block cipher modes: YACA_BCM_CBC, YACA_BCM_OFB, YACA_BCM_CFB, YACA_BCM_ECB see yaca_block_cipher_mode_e for details on additional properties (mandatory).

enum yaca_error_e

Enumeration of YACA error values.

Since :

3.0

Enumerator:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Invalid function parameter
YACA_ERROR_OUT_OF_MEMORY	Out of memory
YACA_ERROR_INTERNAL	Internal error
YACA_ERROR_DATA_MISMATCH	Data mismatch
YACA_ERROR_INVALID_PASSWORD	Invalid password

enum yaca_kdf_e

Enumeration of YACA key derivation functions.

Since :

3.0

Enumerator:

YACA_KDF_X942	ANSI X9.42 key derivation function, (shared secret derived using Diffie-Helmann key exchange protocol).
YACA_KDF_X962	ANSI X9.62 key derivation function, (shared secret derived using EC Diffie-Helmann key exchange protocol).

enum yaca_key_bit_length_dh_rfc_e

Enumeration of YACA DH parameters taken from RFC 5114. It's meant to be passed or returned as a key_bit_len param in appropriate functions when dealing with DH and wanting to use RFC 5114 values.

Since :

3.0

Enumerator:

YACA_KEY_LENGTH_DH_RFC_1024_160	RFC 5114 DH parameters 1024_160
YACA_KEY_LENGTH_DH_RFC_2048_224	RFC 5114 DH parameters 2048_224
YACA_KEY_LENGTH_DH_RFC_2048_256	RFC 5114 DH parameters 2048_256

enum yaca_key_bit_length_e

Enumeration of YACA key lengths. It is possible to use arbitrary integer instead, this enum values are placed here to avoid magic numbers.

Since :

3.0

Enumerator:

YACA_KEY_LENGTH_IV_64BIT	64 bits
YACA_KEY_LENGTH_IV_128BIT	128 bits
YACA_KEY_LENGTH_UNSAFE_8BIT	8 bits
YACA_KEY_LENGTH_UNSAFE_40BIT	40 bits
YACA_KEY_LENGTH_UNSAFE_64BIT	64 bits
YACA_KEY_LENGTH_UNSAFE_80BIT	80 bits
YACA_KEY_LENGTH_UNSAFE_128BIT	128 bits
YACA_KEY_LENGTH_192BIT	192 bits
YACA_KEY_LENGTH_256BIT	256 bits
YACA_KEY_LENGTH_512BIT	512 bits
YACA_KEY_LENGTH_1024BIT	1024 bits
YACA_KEY_LENGTH_2048BIT	2048 bits
YACA_KEY_LENGTH_3072BIT	3072 bits
YACA_KEY_LENGTH_4096BIT	4096 bits

enum yaca_key_bit_length_ec_e

Enumeration of YACA elliptic curve types with their bit lengths. It's meant to be passed or returned as a key_bit_len param in appropriate functions when dealing with elliptic curves.

Since :

3.0

Enumerator:

YACA_KEY_LENGTH_EC_PRIME192V1	Elliptic curve prime192v1
YACA_KEY_LENGTH_EC_PRIME256V1	Elliptic curve prime256v1
YACA_KEY_LENGTH_EC_SECP256K1	Elliptic curve secp256k1
YACA_KEY_LENGTH_EC_SECP384R1	Elliptic curve secp384r1
YACA_KEY_LENGTH_EC_SECP521R1	Elliptic curve secp521r1

enum yaca_key_file_format_e

Enumeration of YACA key file formats.

Since :

3.0

Enumerator:

YACA_KEY_FILE_FORMAT_RAW	Key file is in raw binary format, used for symmetric keys
YACA_KEY_FILE_FORMAT_BASE64	Key file is encoded in ASCII-base64, used for symmetric keys
YACA_KEY_FILE_FORMAT_PEM	Key file is in PEM file format, used for asymmetric keys
YACA_KEY_FILE_FORMAT_DER	Key file is in DER file format, used for asymmetric keys

enum yaca_key_format_e

Enumeration of YACA key formats.

Since :

3.0

Enumerator:

YACA_KEY_FORMAT_DEFAULT	Key is either PKCS#1 for RSA or SSLeay for DSA, also use this option for symmetric
YACA_KEY_FORMAT_PKCS8	Key is in PKCS#8, can only be used for asymmetric private keys

enum yaca_key_type_e

Enumeration of YACA key types, Initialization Vector is considered as key.

Since :

3.0

Enumerator:

YACA_KEY_TYPE_SYMMETRIC	Generic symmetric cipher KEY
YACA_KEY_TYPE_DES	DES* key - must be handled differently because of parity bits
YACA_KEY_TYPE_IV	Initialization Vector for symmetric algorithms
YACA_KEY_TYPE_RSA_PUB	RSA public key
YACA_KEY_TYPE_RSA_PRIV	RSA private key
YACA_KEY_TYPE_DSA_PUB	Digital Signature Algorithm public key
YACA_KEY_TYPE_DSA_PRIV	Digital Signature Algorithm private key
YACA_KEY_TYPE_DH_PUB	Diffie-Hellman public key
YACA_KEY_TYPE_DH_PRIV	Diffie-Hellman private key
YACA_KEY_TYPE_EC_PUB	Elliptic Curve public key (for DSA and DH)
YACA_KEY_TYPE_EC_PRIV	Elliptic Curve private key (for DSA and DH)
YACA_KEY_TYPE_DSA_PARAMS	Digital Signature Algorithm parameters
YACA_KEY_TYPE_DH_PARAMS	Diffie-Hellman parameters
YACA_KEY_TYPE_EC_PARAMS	Elliptic Curve parameters

enum yaca_padding_e

Enumeration of YACA paddings.

Since :

3.0

Enumerator:

YACA_PADDING_NONE	No padding at all. This method assumes that the input data already has a proper length for a given cryptographic operation (e.g. it has been padded by the client). Suitable for symmetric encrypt/decrypt operations as well as low-level RSA operations.
YACA_PADDING_X931	X9.31 padding. Suitable for RSA sign/verify operation. Not supported in low-level RSA operations.
YACA_PADDING_PKCS1	PKCS #1 v1.5 padding. Suitable for RSA sign/verify and low-level RSA operations. For low-level operations the input must be at least 11 bytes shorter than the key length.
YACA_PADDING_PKCS1_PSS	PKCS #1 PSS padding. Suitable for RSA sign/verify operations. Not supported in low-level RSA operations.
YACA_PADDING_PKCS1_OAEP	EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty encoding parameter. Suitable for low-level RSA public_encrypt/private_decrypt operations. For low-level operations the input must be at least 42 bytes shorter than the key length.
YACA_PADDING_PKCS1_SSLV23	PKCS #1 v1.5 padding with an SSL-specific modification that denotes that the party is SSL3 capable. It is used for rollback attack detection in SSLv3. If during decryption it turns out that both parties are using YACA_PADDING_PKCS1_SSLV23 (both are communicating using SSL2 and both are SSL3 capable) it is treated as a rollback attack and an error is returned. Suitable for low-level RSA public_encrypt/private_decrypt operations. For low-level operations the input must be at least 11 bytes shorter than the key length.
YACA_PADDING_PKCS7	PKCS #7 padding. Suitable for symmetric encrypt/decrypt operation.

enum yaca_property_e

Enumeration of YACA non-standard properties for algorithms.

Since :

3.0

See also:

yaca_padding_e

Enumerator:

YACA_PROPERTY_PADDING	Padding for the encrypt/decrypt or sign/verify operation. Property type is yaca_padding_e. This property can be set at the latest before the *_finalize() call.
YACA_PROPERTY_GCM_AAD	GCM Additional Authentication Data. Property type is a buffer (e.g. char*)
YACA_PROPERTY_GCM_TAG	GCM Tag. Property type is a buffer (e.g. char*)
YACA_PROPERTY_GCM_TAG_LEN	GCM Tag length in bytes. Property type is size_t.
YACA_PROPERTY_CCM_AAD	CCM Additional Authentication Data. Property type is a buffer (e.g. char*)
YACA_PROPERTY_CCM_TAG	CCM Tag. Property type is a buffer (e.g. char*)
YACA_PROPERTY_CCM_TAG_LEN	CCM Tag length in bytes. Property type is size_t.
YACA_PROPERTY_RC2_EFFECTIVE_KEY_BITS	RC2 effective key bits, 1-1024, 1 bit resolution. Property type is size_t.

---

Function Documentation

void yaca_cleanup

(

void

)

Cleans up the library. Must be called before exiting the thread that called yaca_initialize().

Since :

3.0

See also:

yaca_initialize()

void yaca_context_destroy

(

yaca_context_h

ctx

)

Destroys the crypto context. Must be called on all contexts that are no longer used. Passing YACA_CONTEXT_NULL is allowed.

Since :

3.0

Parameters:

[in,out]

ctx

Crypto context

See also:

yaca_context_h

int yaca_context_get_output_length	(	const yaca_context_h	ctx,
		size_t	input_len,
		size_t *	output_len
	)

Returns the minimum required size of the output buffer for a single crypto function call.

Since :

3.0

Remarks:

This function should be used to learn the required size of the output buffer for a single function call (eg. *_update or *_finalize). The actual output length (number of bytes that has been used) will be returned by the function call itself.

In case the function call has no output (e.g. yaca_sign_update(), yaca_digest_update()), there is no need to use this function.

In case the function call has no input (eg. *_finalize), the value of input_len has to be set to 0.

Parameters:

[in]	ctx	Previously initialized crypto context
[in]	input_len	Length of the input data to be processed
[out]	output_len	Required length of the output

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 or too big input_len)
YACA_ERROR_INTERNAL	Internal error

int yaca_context_get_property	(	const yaca_context_h	ctx,
		yaca_property_e	property,
		void **	value,
		size_t *	value_len
	)

Returns the non-standard context properties. Can only be called on an initialized context.

Since :

3.0

Remarks:

The value should be freed using yaca_free().

The value has to be of type appropriate for given property. See yaca_property_e for details on corresponding types.

The value_len can be NULL if returned value is a single object (i.e. not an array/buffer).

Parameters:

[in]	ctx	Previously initialized crypto context
[in]	property	Property to be read
[out]	value	Copy of the property value
[out]	value_len	Length of the property value 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 or property)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_property_e

yaca_context_set_property()

yaca_free()

int yaca_context_set_property	(	yaca_context_h	ctx,
		yaca_property_e	property,
		const void *	value,
		size_t	value_len
	)

Sets the non-standard context properties. Can only be called on an initialized context.

Remarks:

The value has to be of type appropriate for given property. See yaca_property_e for details on corresponding types.

Since :

3.0

Parameters:

[in,out]	ctx	Previously initialized crypto context
[in]	property	Property to be set
[in]	value	Property value
[in]	value_len	Length of the property value

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 or property)
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_property_e

yaca_context_get_property()

int yaca_decrypt_finalize	(	yaca_context_h	ctx,
		char *	plaintext,
		size_t *	plaintext_len
	)

Decrypts the final chunk of the data.

Remarks:

Skipping yaca_decrypt_update() and calling only yaca_decrypt_finalize() will produce a decryption of an empty ciphertext.

Since :

3.0

Parameters:

[in,out]	ctx	A valid decrypt context
[out]	plaintext	Final piece of the decrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]	plaintext_len	Length of the final piece, 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), wrong YACA_PROPERTY_GCM_AAD or wrong YACA_PROPERTY_GCM_TAG was used
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_decrypt_initialize()

yaca_decrypt_update()

yaca_context_get_output_length()

int yaca_decrypt_initialize	(	yaca_context_h *	ctx,
		yaca_encrypt_algorithm_e	algo,
		yaca_block_cipher_mode_e	bcm,
		const yaca_key_h	sym_key,
		const yaca_key_h	iv
	)

Initializes an decryption context.

Since :

3.0

Remarks:

The ctx should be released using yaca_context_destroy().

Parameters:

[out]	ctx	Newly created context
[in]	algo	Encryption algorithm that was used to encrypt the data
[in]	bcm	Chaining mode that was used to encrypt the data
[in]	sym_key	Symmetric key that was used to encrypt the data
[in]	iv	Initialization Vector that was used to encrypt the data

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, bcm, sym_key or iv)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_encrypt_algorithm_e

yaca_block_cipher_mode_e

yaca_decrypt_update()

yaca_decrypt_finalize()

yaca_context_destroy()

int yaca_decrypt_update	(	yaca_context_h	ctx,
		const char *	ciphertext,
		size_t	ciphertext_len,
		char *	plaintext,
		size_t *	plaintext_len
	)

Decrypts chunk of the data.

Since :

3.0

Parameters:

[in,out]	ctx	Context created by yaca_decrypt_initialize()
[in]	ciphertext	Ciphertext to be decrypted
[in]	ciphertext_len	Length of the ciphertext
[out]	plaintext	Buffer for the decrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]	plaintext_len	Length of the decrypted data, 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, 0, invalid ctx), wrong YACA_PROPERTY_CCM_AAD or wrong YACA_PROPERTY_CCM_TAG was used
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_decrypt_initialize()

yaca_decrypt_finalize()

yaca_context_get_output_length()

int yaca_encrypt_finalize	(	yaca_context_h	ctx,
		char *	ciphertext,
		size_t *	ciphertext_len
	)

Encrypts the final chunk of the data.

Remarks:

Skipping yaca_encrypt_update() and calling only yaca_encrypt_finalize() will produce an encryption of an empty message.

Since :

3.0

Parameters:

[in,out]	ctx	A valid encrypt context
[out]	ciphertext	Final piece of the encrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]	ciphertext_len	Length of the final piece, 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_encrypt_initialize()

yaca_encrypt_update()

yaca_context_get_output_length()

int yaca_encrypt_get_iv_bit_length	(	yaca_encrypt_algorithm_e	algo,
		yaca_block_cipher_mode_e	bcm,
		size_t	key_bit_len,
		size_t *	iv_bit_len
	)

Returns the recommended/default length of the Initialization Vector for a given encryption configuration.

Since :

3.0

Remarks:

If returned iv_bit_len equals 0 that means that for this specific algorithm and its parameters Initialization Vector is not used.

Parameters:

[in]	algo	Encryption algorithm
[in]	bcm	Chain mode
[in]	key_bit_len	Key length in bits
[out]	iv_bit_len	Recommended Initialization Vector length in bits

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, bcm or key_bit_len)
YACA_ERROR_INTERNAL	Internal error

int yaca_encrypt_initialize	(	yaca_context_h *	ctx,
		yaca_encrypt_algorithm_e	algo,
		yaca_block_cipher_mode_e	bcm,
		const yaca_key_h	sym_key,
		const yaca_key_h	iv
	)

Initializes an encryption context.

Since :

3.0

Remarks:

The ctx should be released using yaca_context_destroy().

Parameters:

[out]	ctx	Newly created context
[in]	algo	Encryption algorithm that will be used
[in]	bcm	Chaining mode that will be used
[in]	sym_key	Symmetric key that will be used
[in]	iv	Initialization Vector 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, bcm, sym_key or iv)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_encrypt_algorithm_e

yaca_block_cipher_mode_e

yaca_encrypt_update()

yaca_encrypt_finalize()

yaca_context_destroy()

int yaca_encrypt_update	(	yaca_context_h	ctx,
		const char *	plaintext,
		size_t	plaintext_len,
		char *	ciphertext,
		size_t *	ciphertext_len
	)

Encrypts chunk of the data.

Since :

3.0

Parameters:

[in,out]	ctx	Context created by yaca_encrypt_initialize()
[in]	plaintext	Plaintext to be encrypted
[in]	plaintext_len	Length of the plaintext
[out]	ciphertext	Buffer for the encrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]	ciphertext_len	Length of the encrypted data, 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, 0, invalid ctx)
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_encrypt_initialize()

yaca_encrypt_finalize()

yaca_context_get_output_length()

void yaca_free

(

void *

memory

)

Frees the memory allocated by yaca_malloc(), yaca_zalloc(), yaca_realloc() or one of the cryptographic operations.

Since :

3.0

Parameters:

[in]

memory

Pointer to the memory to be freed

See also:

yaca_malloc()

yaca_zalloc()

yaca_realloc()

int yaca_initialize

(

void

)

Initializes the library. Must be called before any other crypto function. Should be called once in each thread that uses yaca.

Since :

3.0

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_cleanup()

int yaca_malloc	(	size_t	size,
		void **	memory
	)

Allocates the memory.

Since :

3.0

Remarks:

The memory should be freed using yaca_free().

Parameters:

[in]	size	Size of the allocation (bytes)
[out]	memory	Allocated memory

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)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error

See also:

yaca_zalloc()

yaca_realloc()

yaca_free()

int yaca_memcmp	(	const void *	first,
		const void *	second,
		size_t	len
	)

Safely compares first len bytes of two buffers.

Since :

3.0

Parameters:

[in]	first	Pointer to the first buffer
[in]	second	Pointer to the second buffer
[in]	len	Length to compare

Returns:

YACA_ERROR_NONE when buffers are equal otherwise YACA_ERROR_DATA_MISMATCH

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Required parameters have incorrect values (NULL, 0)
YACA_ERROR_DATA_MISMATCH	Buffers are different

int yaca_open_finalize	(	yaca_context_h	ctx,
		char *	plaintext,
		size_t *	plaintext_len
	)

Decrypts last chunk of sealed message.

Remarks:

Skipping yaca_open_update() and calling only yaca_open_finalize() will produce a decryption of an empty ciphertext.

Since :

3.0

Parameters:

[in,out]	ctx	A valid open context
[out]	plaintext	Final piece of the decrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]	plaintext_len	Length of the final piece, 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), wrong YACA_PROPERTY_GCM_AAD or wrong YACA_PROPERTY_GCM_TAG was used
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_open_initialize()

yaca_open_update()

yaca_context_get_output_length()

int yaca_open_initialize	(	yaca_context_h *	ctx,
		const yaca_key_h	prv_key,
		yaca_encrypt_algorithm_e	algo,
		yaca_block_cipher_mode_e	bcm,
		size_t	sym_key_bit_len,
		const yaca_key_h	sym_key,
		const yaca_key_h	iv
	)

Initializes an asymmetric decryption context.

Since :

3.0

Remarks:

The ctx should be released using yaca_context_destroy().

The prv_key must be YACA_KEY_TYPE_RSA_PRIV.

Parameters:

[out]	ctx	Newly created context
[in]	prv_key	Private key, part of the pair that was used for the encryption
[in]	algo	Symmetric algorithm that was used for the encryption
[in]	bcm	Block chaining mode for the symmetric algorithm
[in]	sym_key_bit_len	Symmetric key length (in bits) that was used for the encryption
[in]	sym_key	Symmetric key, encrypted with the public key, that was used to encrypt the data
[in]	iv	Initialization Vector that was used for the encryption

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, bcm, sym_key_bit_len, prv_key, sym_key or iv)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_encrypt_algorithm_e

yaca_block_cipher_mode_e

yaca_key_bit_length_e

yaca_open_update()

yaca_open_finalize()

yaca_context_destroy()

int yaca_open_update	(	yaca_context_h	ctx,
		const char *	ciphertext,
		size_t	ciphertext_len,
		char *	plaintext,
		size_t *	plaintext_len
	)

Decrypts piece of the data.

Since :

3.0

Parameters:

[in,out]	ctx	Context created by yaca_open_initialize()
[in]	ciphertext	Ciphertext to be decrypted
[in]	ciphertext_len	Length of the ciphertext
[out]	plaintext	Buffer for the decrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]	plaintext_len	Length of the decrypted data, 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, 0, invalid ctx), wrong YACA_PROPERTY_CCM_AAD or wrong YACA_PROPERTY_CCM_TAG was used
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_open_initialize()

yaca_open_finalize()

yaca_context_get_output_length()

int yaca_randomize_bytes	(	char *	data,
		size_t	data_len
	)

Generates random data.

Since :

3.0

Parameters:

[in,out]	data	Pointer to the memory to be randomized
[in]	data_len	Length of the memory to be randomized

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)
YACA_ERROR_INTERNAL	Internal error

int yaca_realloc	(	size_t	size,
		void **	memory
	)

Re-allocates the memory.

Since :

3.0

Remarks:

In case of failure the function doesn't free the memory pointed by memory.

If memory is NULL then the call is equivalent to yaca_malloc().

If the function fails the contents of memory will be left unchanged.

The memory should be freed using yaca_free().

Parameters:

[in]	size	Size of the new allocation (bytes)
[in,out]	memory	Memory to be reallocated

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)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error

See also:

yaca_malloc()

yaca_zalloc()

yaca_free()

int yaca_seal_finalize	(	yaca_context_h	ctx,
		char *	ciphertext,
		size_t *	ciphertext_len
	)

Encrypts the final piece of the data.

Remarks:

Skipping yaca_seal_update() and calling only yaca_seal_finalize() will produce an encryption of an empty message.

Since :

3.0

Parameters:

[in,out]	ctx	A valid seal context
[out]	ciphertext	Final piece of the encrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]	ciphertext_len	Length of the final piece, 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_seal_initialize()

yaca_seal_update()

yaca_context_get_output_length()

int yaca_seal_initialize	(	yaca_context_h *	ctx,
		const yaca_key_h	pub_key,
		yaca_encrypt_algorithm_e	algo,
		yaca_block_cipher_mode_e	bcm,
		size_t	sym_key_bit_len,
		yaca_key_h *	sym_key,
		yaca_key_h *	iv
	)

Initializes an asymmetric encryption context and generates symmetric key and Initialization Vector.

Remarks:

Generated symmetric key is encrypted with public key, so can be only used with yaca_open_initialize(). It can be exported, but after import it can be only used with yaca_open_initialize() as well.

The ctx should be released using yaca_context_destroy().

The pub_key must be YACA_KEY_TYPE_RSA_PUB.

The sym_key_bit_len must be at least 88 bits shorter than the pub_key bit length.

The sym_key should be released using yaca_key_destroy().

The iv should be released using yaca_key_destroy().

Since :

3.0

Parameters:

[out]	ctx	Newly created context
[in]	pub_key	Public key of the peer that will receive the encrypted data
[in]	algo	Symmetric algorithm that will be used
[in]	bcm	Block chaining mode for the symmetric algorithm
[in]	sym_key_bit_len	Symmetric key length (in bits) that will be generated
[out]	sym_key	Generated symmetric key that will be used, it is encrypted with peer's public key
[out]	iv	Generated Initialization Vector 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, bcm, sym_key_bit_len or pub_key)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_encrypt_algorithm_e

yaca_block_cipher_mode_e

yaca_key_bit_length_e

yaca_seal_update()

yaca_seal_finalize()

yaca_open_initialize()

yaca_key_destroy()

yaca_context_destroy()

int yaca_seal_update	(	yaca_context_h	ctx,
		const char *	plaintext,
		size_t	plaintext_len,
		char *	ciphertext,
		size_t *	ciphertext_len
	)

Encrypts piece of the data.

Since :

3.0

Parameters:

[in,out]	ctx	Context created by yaca_seal_initialize()
[in]	plaintext	Plaintext to be encrypted
[in]	plaintext_len	Length of the plaintext
[out]	ciphertext	Buffer for the encrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]	ciphertext_len	Length of the encrypted data, 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, 0, invalid ctx)
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_seal_initialize()

yaca_seal_finalize()

yaca_context_get_output_length()

int yaca_zalloc	(	size_t	size,
		void **	memory
	)

Allocates the zeroed memory.

Since :

3.0

Remarks:

The memory should be freed using yaca_free().

Parameters:

[in]	size	Size of the allocation (bytes)
[out]	memory	Allocated memory

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)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error

See also:

yaca_malloc()

yaca_realloc()

yaca_free()