Tizen Native API  5.5
Functions | Typedefs | Defines
YACA Encryption
YACA

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;

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

    /* 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
 An Initialization Vector or a key generation parameters by the key handle.

Defines

#define YACA_CONTEXT_NULL   ((yaca_context_h) NULL)
 Definition for NULL value for the crypto context.
#define YACA_KEY_LENGTH_DH_GENERATOR_2   (YACA_KEYLEN_COMPONENT_TYPE_DH | YACA_KEYLEN_COMPONENT_DH_GEN_2)
 Definition for the 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)
 Definition for the 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)

Definition for 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

An Initialization Vector or a key generation parameters by the key handle.

Since :
3.0

Enumeration Type Documentation

enum yaca_block_cipher_mode_e

Enumeration for 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_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_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 for 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 for YACA symmetric encryption algorithms.

Since :
3.0
Enumerator:
YACA_ENCRYPT_AES 

AES encryption.

YACA_ENCRYPT_UNSAFE_DES 

DES encryption.

YACA_ENCRYPT_UNSAFE_3DES_2TDEA 

3DES 2-key encryption.

YACA_ENCRYPT_3DES_3TDEA 

3DES 3-key encryption.

YACA_ENCRYPT_UNSAFE_RC2 

RC2 encryption. This is a variable key length cipher.

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.

enum yaca_error_e

Enumeration for 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 for 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 for 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 for 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 for 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 for formats YACA key file.

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 for formats YACA key.

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 for 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 for 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 for 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]ctxCrypto 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]ctxPreviously initialized crypto context
[in]input_lenLength of the input data to be processed
[out]output_lenRequired length of the output
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid ctx or too big input_len)
YACA_ERROR_INTERNALInternal 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]ctxPreviously initialized crypto context
[in]propertyProperty to be read
[out]valueCopy of the property value
[out]value_lenLength of the property value will be returned here
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid ctx or property)
YACA_ERROR_OUT_OF_MEMORYOut of memory error
YACA_ERROR_INTERNALInternal 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.

Since :
3.0
Remarks:
The value has to be of type appropriate for given property. See yaca_property_e for details on corresponding types.
Parameters:
[in,out]ctxPreviously initialized crypto context
[in]propertyProperty to be set
[in]valueProperty value
[in]value_lenLength of the property value
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0, invalid ctx or property)
YACA_ERROR_INTERNALInternal 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.

Since :
3.0
Remarks:
Skipping yaca_decrypt_update() and calling only yaca_decrypt_finalize() will produce a decryption of an empty ciphertext.
Parameters:
[in,out]ctxA valid decrypt context
[out]plaintextFinal piece of the decrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]plaintext_lenLength 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_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid ctx), wrong YACA_PROPERTY_GCM_AAD or wrong YACA_PROPERTY_GCM_TAG was used
YACA_ERROR_INTERNALInternal 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]ctxNewly created context
[in]algoEncryption algorithm that was used to encrypt the data
[in]bcmChaining mode that was used to encrypt the data
[in]sym_keySymmetric key that was used to encrypt the data
[in]ivInitialization Vector that was used to encrypt the data
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid algo, bcm, sym_key or iv)
YACA_ERROR_OUT_OF_MEMORYOut of memory error
YACA_ERROR_INTERNALInternal 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]ctxContext created by yaca_decrypt_initialize()
[in]ciphertextCiphertext to be decrypted
[in]ciphertext_lenLength of the ciphertext
[out]plaintextBuffer for the decrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]plaintext_lenLength 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_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0, invalid ctx), wrong YACA_PROPERTY_CCM_AAD or wrong YACA_PROPERTY_CCM_TAG was used
YACA_ERROR_INTERNALInternal 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.

Since :
3.0
Remarks:
Skipping yaca_encrypt_update() and calling only yaca_encrypt_finalize() will produce an encryption of an empty message.
Parameters:
[in,out]ctxA valid encrypt context
[out]ciphertextFinal piece of the encrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]ciphertext_lenLength 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_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid ctx)
YACA_ERROR_INTERNALInternal 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]algoEncryption algorithm
[in]bcmChain mode
[in]key_bit_lenKey length in bits
[out]iv_bit_lenRecommended Initialization Vector length in bits
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid algo, bcm or key_bit_len)
YACA_ERROR_INTERNALInternal 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]ctxNewly created context
[in]algoEncryption algorithm that will be used
[in]bcmChaining mode that will be used
[in]sym_keySymmetric key that will be used
[in]ivInitialization Vector that will be used
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid algo, bcm, sym_key or iv)
YACA_ERROR_OUT_OF_MEMORYOut of memory error
YACA_ERROR_INTERNALInternal 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]ctxContext created by yaca_encrypt_initialize()
[in]plaintextPlaintext to be encrypted
[in]plaintext_lenLength of the plaintext
[out]ciphertextBuffer for the encrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]ciphertext_lenLength 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_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0, invalid ctx)
YACA_ERROR_INTERNALInternal 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]memoryPointer 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_NONESuccessful
YACA_ERROR_OUT_OF_MEMORYOut of memory error
YACA_ERROR_INTERNALInternal 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]sizeSize of the allocation (bytes)
[out]memoryAllocated memory
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0)
YACA_ERROR_OUT_OF_MEMORYOut 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]firstPointer to the first buffer
[in]secondPointer to the second buffer
[in]lenLength to compare
Returns:
YACA_ERROR_NONE when buffers are equal, otherwise YACA_ERROR_DATA_MISMATCH
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0)
YACA_ERROR_DATA_MISMATCHBuffers are different
int yaca_open_finalize ( yaca_context_h  ctx,
char *  plaintext,
size_t *  plaintext_len 
)

Decrypts last chunk of sealed message.

Since :
3.0
Remarks:
Skipping yaca_open_update() and calling only yaca_open_finalize() will produce a decryption of an empty ciphertext.
Parameters:
[in,out]ctxA valid open context
[out]plaintextFinal piece of the decrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]plaintext_lenLength 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_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid ctx), wrong YACA_PROPERTY_GCM_AAD or wrong YACA_PROPERTY_GCM_TAG was used
YACA_ERROR_INTERNALInternal 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]ctxNewly created context
[in]prv_keyPrivate key, part of the pair that was used for the encryption
[in]algoSymmetric algorithm that was used for the encryption
[in]bcmBlock chaining mode for the symmetric algorithm
[in]sym_key_bit_lenSymmetric key length (in bits) that was used for the encryption
[in]sym_keySymmetric key, encrypted with the public key, that was used to encrypt the data
[in]ivInitialization Vector that was used for the encryption
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid algo, bcm, sym_key_bit_len, prv_key, sym_key or iv)
YACA_ERROR_OUT_OF_MEMORYOut of memory error
YACA_ERROR_INTERNALInternal 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]ctxContext created by yaca_open_initialize()
[in]ciphertextCiphertext to be decrypted
[in]ciphertext_lenLength of the ciphertext
[out]plaintextBuffer for the decrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]plaintext_lenLength 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_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0, invalid ctx), wrong YACA_PROPERTY_CCM_AAD or wrong YACA_PROPERTY_CCM_TAG was used
YACA_ERROR_INTERNALInternal 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]dataPointer to the memory to be randomized
[in]data_lenLength of the memory to be randomized
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0)
YACA_ERROR_INTERNALInternal 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]sizeSize of the new allocation (bytes)
[in,out]memoryMemory to be reallocated
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0)
YACA_ERROR_OUT_OF_MEMORYOut 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.

Since :
3.0
Remarks:
Skipping yaca_seal_update() and calling only yaca_seal_finalize() will produce an encryption of an empty message.
Parameters:
[in,out]ctxA valid seal context
[out]ciphertextFinal piece of the encrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]ciphertext_lenLength 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_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid ctx)
YACA_ERROR_INTERNALInternal 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.

Since :
3.0
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().
Parameters:
[out]ctxNewly created context
[in]pub_keyPublic key of the peer that will receive the encrypted data
[in]algoSymmetric algorithm that will be used
[in]bcmBlock chaining mode for the symmetric algorithm
[in]sym_key_bit_lenSymmetric key length (in bits) that will be generated
[out]sym_keyGenerated symmetric key that will be used, it is encrypted with peer's public key
[out]ivGenerated Initialization Vector that will be used
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, invalid algo, bcm, sym_key_bit_len or pub_key)
YACA_ERROR_OUT_OF_MEMORYOut of memory error
YACA_ERROR_INTERNALInternal 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]ctxContext created by yaca_seal_initialize()
[in]plaintextPlaintext to be encrypted
[in]plaintext_lenLength of the plaintext
[out]ciphertextBuffer for the encrypted data (must be allocated by client, see yaca_context_get_output_length())
[out]ciphertext_lenLength 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_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0, invalid ctx)
YACA_ERROR_INTERNALInternal 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]sizeSize of the allocation (bytes)
[out]memoryAllocated memory
Returns:
YACA_ERROR_NONE on success, negative on error
Return values:
YACA_ERROR_NONESuccessful
YACA_ERROR_INVALID_PARAMETERRequired parameters have incorrect values (NULL, 0)
YACA_ERROR_OUT_OF_MEMORYOut of memory error
See also:
yaca_malloc()
yaca_realloc()
yaca_free()