YACA Key Management

---

Provides APIs for key handling operations such as generating and importing a key.

Required Header

#include <yaca/yaca_key.h>

Overview

It provides APIs for generating key using random number or password, importing a key trying to match it to the key_type specified and exporting a key to arbitrary format.

Examples

Key generation API example

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

int main()
{
    int ret;
    yaca_key_h key = YACA_KEY_NULL;
    yaca_key_h key_params = YACA_KEY_NULL;

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

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

    ret = yaca_key_generate(YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_LENGTH_2048BIT, &key);
    if (ret != YACA_ERROR_NONE)
        goto exit;
    yaca_key_destroy(key);

    ret = yaca_key_generate(YACA_KEY_TYPE_DH_PRIV, YACA_KEY_LENGTH_DH_RFC_2048_224, &key);
    if (ret != YACA_ERROR_NONE)
        goto exit;
    yaca_key_destroy(key);

    ret = yaca_key_generate(YACA_KEY_TYPE_EC_PRIV, YACA_KEY_LENGTH_EC_SECP384R1, &key);
    if (ret != YACA_ERROR_NONE)
        goto exit;
    yaca_key_destroy(key);

    /* Params + key generation */
    ret = yaca_key_generate(YACA_KEY_TYPE_DH_PARAMS, YACA_KEY_LENGTH_DH_RFC_2048_256, &key_params);
    if (ret != YACA_ERROR_NONE)
        goto exit;
    ret = yaca_key_generate_from_parameters(key_params, &key);
    if (ret != YACA_ERROR_NONE)
        goto exit;
    yaca_key_destroy(key);
    yaca_key_destroy(key_params);

    ret = yaca_key_generate(YACA_KEY_TYPE_EC_PARAMS, YACA_KEY_LENGTH_EC_PRIME256V1, &key_params);
    if (ret != YACA_ERROR_NONE)
        goto exit;
    ret = yaca_key_generate_from_parameters(key_params, &key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

exit:
    yaca_key_destroy(key);
    yaca_key_destroy(key_params);

    yaca_cleanup();
    return ret;
}

Symmetric key import/export API example

#include <stdio.h>

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

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

int main()
{
    int ret;
    yaca_key_h sym_key = YACA_KEY_NULL;
    yaca_key_h raw_imported = YACA_KEY_NULL;
    yaca_key_h b64_imported = YACA_KEY_NULL;

    char *raw = NULL;
    size_t raw_len;
    char *b64 = NULL;
    size_t b64_len;

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

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

    /* BASE64 */
    ret = yaca_key_export(sym_key, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_BASE64, NULL,
                          &b64, &b64_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_key_import(YACA_KEY_TYPE_SYMMETRIC, NULL, b64, b64_len, &b64_imported);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    printf("\t***** BASE64 exported key: *****\n%.*s\n", (int)b64_len, b64);
    yaca_free(b64);
    b64 = NULL;

    ret = yaca_key_export(b64_imported, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_BASE64, NULL,
                          &b64, &b64_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    printf("\t***** BASE64 imported key: *****\n%.*s\n", (int)b64_len, b64);

    /* RAW */
    ret = yaca_key_export(sym_key, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_RAW, NULL,
                          &raw, &raw_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_key_import(YACA_KEY_TYPE_SYMMETRIC, NULL, raw, raw_len, &raw_imported);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* display key in hexadecimal format */
    dump_hex(raw, raw_len, "\n\t***** RAW exported key: *****");
    yaca_free(raw);
    raw = NULL;

    ret = yaca_key_export(raw_imported, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_RAW, NULL,
                          &raw, &raw_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* display key in hexadecimal format */
    dump_hex(raw, raw_len, "\t***** RAW imported key: *****");

exit:
    yaca_key_destroy(sym_key);
    yaca_key_destroy(raw_imported);
    yaca_key_destroy(b64_imported);
    yaca_free(raw);
    yaca_free(b64);

    yaca_cleanup();
    return ret;
}

Asymmetric key import/export API example

#include <stdio.h>

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

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

int main()
{
    int ret;
    yaca_key_h rsa_priv = YACA_KEY_NULL;
    yaca_key_h rsa_pub = YACA_KEY_NULL;
    yaca_key_h pem_priv_imported = YACA_KEY_NULL;
    yaca_key_h der_pub_imported = YACA_KEY_NULL;

    char *pem_priv = NULL;
    size_t pem_priv_len;
    char *der_pub = NULL;
    size_t der_pub_len;

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

    ret = yaca_key_generate(YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_LENGTH_2048BIT, &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;

    /* PEM private */
    ret = yaca_key_export(rsa_priv, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_PEM, NULL,
                          &pem_priv, &pem_priv_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_key_import(YACA_KEY_TYPE_RSA_PRIV, NULL, pem_priv, pem_priv_len, &pem_priv_imported);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    printf("\t***** PEM exported private key: *****\n%.*s", (int)pem_priv_len, pem_priv);
    yaca_free(pem_priv);
    pem_priv = NULL;

    ret = yaca_key_export(pem_priv_imported, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_PEM,
                          NULL, &pem_priv, &pem_priv_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    printf("\t***** PEM imported private key: *****\n%.*s", (int)pem_priv_len, pem_priv);

    /* DER public */
    ret = yaca_key_export(rsa_pub, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_DER, NULL,
                          &der_pub, &der_pub_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_key_import(YACA_KEY_TYPE_RSA_PUB, NULL, der_pub, der_pub_len, &der_pub_imported);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* display key in hexadecimal format */
    dump_hex(der_pub, der_pub_len, "\n\t***** DER exported public key: *****");
    yaca_free(der_pub);
    der_pub = NULL;

    ret = yaca_key_export(der_pub_imported, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_DER,
                          NULL, &der_pub, &der_pub_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* display key in hexadecimal format */
    dump_hex(der_pub, der_pub_len, "\t***** DER imported public key: *****");

exit:
    yaca_key_destroy(rsa_pub);
    yaca_key_destroy(rsa_priv);
    yaca_key_destroy(pem_priv_imported);
    yaca_key_destroy(der_pub_imported);
    yaca_free(pem_priv);
    yaca_free(der_pub);

    yaca_cleanup();
    return ret;
}

Key import/export with password API example

#include <stdio.h>

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

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

int main()
{
    int ret;
    yaca_key_h key = YACA_KEY_NULL;
    char *password = NULL;
    char *key_data = NULL;
    size_t key_data_len;

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

    ret = yaca_key_generate(YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_LENGTH_2048BIT, &key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Export key */
    {
        ret = read_stdin_line("encryption pass: ", &password);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_key_export(key, YACA_KEY_FORMAT_PKCS8, YACA_KEY_FILE_FORMAT_PEM, password,
                              &key_data, &key_data_len);
        if (ret == YACA_ERROR_INVALID_PARAMETER)
            printf("invalid parameter, probably a missing password for PKCS8\n");
        if (ret != YACA_ERROR_NONE)
            goto exit;

        yaca_key_destroy(key);
        key = YACA_KEY_NULL;
        yaca_free(password);
        password = NULL;
    }

    /* Import key */
    {
        ret = read_stdin_line("decryption pass: ", &password);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_key_import(YACA_KEY_TYPE_RSA_PRIV, password, key_data, key_data_len, &key);
        if (ret == YACA_ERROR_INVALID_PASSWORD)
            printf("invalid password\n");
        if (ret != YACA_ERROR_NONE)
            goto exit;

        yaca_free(key_data);
        key_data = NULL;

        ret = yaca_key_export(key, YACA_KEY_FORMAT_PKCS8, YACA_KEY_FILE_FORMAT_PEM, password,
                              &key_data, &key_data_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        printf("%.*s", (int)key_data_len, key_data);
    }

exit:
    yaca_free(key_data);
    yaca_free(password);
    yaca_key_destroy(key);

    yaca_cleanup();
    return ret;
}

Diffie-Helmann key exchange API example

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

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

static yaca_key_h exchange_public_keys(const yaca_key_h peer_key)
{
    int ret;
    yaca_key_h params = YACA_KEY_NULL;
    yaca_key_h priv_key = YACA_KEY_NULL;
    yaca_key_h pub_key = YACA_KEY_NULL;

    ret = yaca_key_extract_parameters(peer_key, &params);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_key_generate_from_parameters(params, &priv_key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

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

exit:
    yaca_key_destroy(priv_key);
    yaca_key_destroy(params);

    return pub_key;
}

int main()
{
    int ret;
    yaca_key_h priv_key = YACA_KEY_NULL;
    yaca_key_h pub_key = YACA_KEY_NULL;
    yaca_key_h peer_key = YACA_KEY_NULL;
    yaca_key_h aes_key = YACA_KEY_NULL;
    yaca_key_h iv = YACA_KEY_NULL;

    char *secret = NULL;
    size_t secret_len;
    char *key_material = NULL;
    size_t key_material_len;
    char *iv_material = NULL;
    size_t iv_material_len;
    char *temp_material = NULL;
    size_t temp_material_len;

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

    /* Key generation */
    ret = yaca_key_generate(YACA_KEY_TYPE_DH_PRIV, YACA_KEY_LENGTH_DH_RFC_2048_256, &priv_key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

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

    /* Send own public key and get peer public key */
    peer_key = exchange_public_keys(pub_key);
    if (peer_key == YACA_KEY_NULL)
        goto exit;

    /* Derive shared secret */
    ret = yaca_key_derive_dh(priv_key, peer_key, &secret, &secret_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* Derive AES key and IV */
    key_material_len = YACA_KEY_LENGTH_256BIT / 8;
    iv_material_len = YACA_KEY_LENGTH_IV_128BIT / 8;
    temp_material_len = key_material_len + iv_material_len;
    ret = yaca_key_derive_kdf(YACA_KDF_X942, YACA_DIGEST_SHA512, secret, secret_len,
                              NULL, 0, temp_material_len, &temp_material);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    key_material = temp_material;
    iv_material = temp_material + key_material_len;

    ret = yaca_key_import(YACA_KEY_TYPE_SYMMETRIC, NULL, key_material, key_material_len, &aes_key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    ret = yaca_key_import(YACA_KEY_TYPE_IV, NULL, iv_material, iv_material_len, &iv);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* display key and IV in hexadecimal format */
    dump_hex(key_material, key_material_len, "***** Derived AES key: *****");
    dump_hex(iv_material, iv_material_len, "\n***** Derived IV: *****");

exit:
    yaca_key_destroy(priv_key);
    yaca_key_destroy(pub_key);
    yaca_key_destroy(peer_key);
    yaca_key_destroy(aes_key);
    yaca_key_destroy(iv);
    yaca_free(secret);
    yaca_free(temp_material);

    yaca_cleanup();
    return ret;
}

Key wrapping API example

#include <yaca_crypto.h>
#include <yaca_simple.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_key_h aes_key = YACA_KEY_NULL;
    yaca_key_h key = YACA_KEY_NULL;
    yaca_key_h iv = YACA_KEY_NULL;
    size_t iv_bit_len;

    char *aes_key_data = NULL;
    size_t aes_key_data_len;
    char *wrapped_key_data = NULL;
    size_t wrapped_key_data_len;

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

    /* Generate key to wrap */
    ret = yaca_key_generate(YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_LENGTH_256BIT, &aes_key);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    /* 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_encrypt_get_iv_bit_length(YACA_ENCRYPT_AES, YACA_BCM_WRAP, YACA_KEY_LENGTH_256BIT,
                                         &iv_bit_len);
    if (ret != YACA_ERROR_NONE)
        goto exit;

    if (iv_bit_len > 0) {
        ret = yaca_key_generate(YACA_KEY_TYPE_IV, iv_bit_len, &iv);
        if (ret != YACA_ERROR_NONE)
            goto exit;
    }

    /* Key wrapping */
    {
        ret = yaca_key_export(aes_key, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_RAW, NULL,
                              &aes_key_data, &aes_key_data_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_simple_encrypt(YACA_ENCRYPT_AES, YACA_BCM_WRAP, key, iv,
                                  aes_key_data, aes_key_data_len,
                                  &wrapped_key_data, &wrapped_key_data_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display key in hexadecimal format */
        dump_hex(aes_key_data, aes_key_data_len, "***** Unwrapped key:*****");
        dump_hex(wrapped_key_data, wrapped_key_data_len, "***** Wrapped key:*****");
    }

    yaca_free(aes_key_data);
    aes_key_data = NULL;
    yaca_key_destroy(aes_key);
    aes_key = YACA_KEY_NULL;

    /* Key unwrapping */
    {
        ret = yaca_simple_decrypt(YACA_ENCRYPT_AES, YACA_BCM_WRAP, key, iv,
                                  wrapped_key_data, wrapped_key_data_len,
                                  &aes_key_data, &aes_key_data_len);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        ret = yaca_key_import(YACA_KEY_TYPE_SYMMETRIC, NULL, aes_key_data, aes_key_data_len,
                              &aes_key);
        if (ret != YACA_ERROR_NONE)
            goto exit;

        /* display key in hexadecimal format */
        dump_hex(aes_key_data, aes_key_data_len, "***** Unwrapped key:*****");
    }

exit:
    yaca_key_destroy(aes_key);
    yaca_key_destroy(key);
    yaca_key_destroy(iv);
    yaca_free(aes_key_data);
    yaca_free(wrapped_key_data);

    yaca_cleanup();
    return ret;
}

Functions
int	yaca_key_get_type (const yaca_key_h key, yaca_key_type_e *key_type)
	Gets key's type.
int	yaca_key_get_bit_length (const yaca_key_h key, size_t *key_bit_len)
	Gets key's length (in bits).
int	yaca_key_import (yaca_key_type_e key_type, const char *password, const char *data, size_t data_len, yaca_key_h *key)
	Imports a key or key generation parameters.
int	yaca_key_export (const yaca_key_h key, yaca_key_format_e key_fmt, yaca_key_file_format_e key_file_fmt, const char *password, char **data, size_t *data_len)
	Exports a key or key generation parameters to arbitrary format.
int	yaca_key_generate (yaca_key_type_e key_type, size_t key_bit_len, yaca_key_h *key)
	Generates a secure key or key generation parameters (or an Initialization Vector).
int	yaca_key_generate_from_parameters (const yaca_key_h params, yaca_key_h *prv_key)
	Generates a secure private asymmetric key from parameters.
int	yaca_key_extract_public (const yaca_key_h prv_key, yaca_key_h *pub_key)
	Extracts public key from a private one.
int	yaca_key_extract_parameters (const yaca_key_h key, yaca_key_h *params)
	Extracts parameters from a private or a public key.
int	yaca_key_derive_dh (const yaca_key_h prv_key, const yaca_key_h pub_key, char **secret, size_t *secret_len)
	Derives a shared secret using Diffie-Helmann or EC Diffie-Helmann key exchange protocol.
int	yaca_key_derive_kdf (yaca_kdf_e kdf, yaca_digest_algorithm_e algo, const char *secret, size_t secret_len, const char *info, size_t info_len, size_t key_material_len, char **key_material)
	Derives a key material from shared secret.
int	yaca_key_derive_pbkdf2 (const char *password, const char *salt, size_t salt_len, size_t iterations, yaca_digest_algorithm_e algo, size_t key_bit_len, yaca_key_h *key)
	Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).
void	yaca_key_destroy (yaca_key_h key)
	Release the key created by the library. Passing YACA_KEY_NULL is allowed.
Defines
#define	YACA_KEY_NULL   ((yaca_key_h) NULL)
	NULL value for yaca_key_h type.

---

Define Documentation

#define YACA_KEY_NULL   ((yaca_key_h) NULL)

NULL value for yaca_key_h type.

Since :

3.0

---

Function Documentation

int yaca_key_derive_dh	(	const yaca_key_h	prv_key,
		const yaca_key_h	pub_key,
		char **	secret,
		size_t *	secret_len
	)

Derives a shared secret using Diffie-Helmann or EC Diffie-Helmann key exchange protocol.

Since :

3.0

Remarks:

The secret should not be used as a symmetric key, to produce a symmetric key pass the secret to a key derivation function (KDF) or a message digest function.

The secret should be freed with yaca_free().

Parameters:

[in]	prv_key	Our private key
[in]	pub_key	Peer public key
[out]	secret	Generated shared secret
[out]	secret_len	Size of the shared secret

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

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

See also:

yaca_key_derive_kdf()

yaca_simple_calculate_digest()

yaca_free()

int yaca_key_derive_kdf	(	yaca_kdf_e	kdf,
		yaca_digest_algorithm_e	algo,
		const char *	secret,
		size_t	secret_len,
		const char *	info,
		size_t	info_len,
		size_t	key_material_len,
		char **	key_material
	)

Derives a key material from shared secret.

Since :

3.0

Remarks:

The info parameter is ANSI X9.42 OtherInfo or ANSI X9.62 SharedInfo structure, more information can be found in ANSI X9.42/62 standard specification.

The key_material or separate parts of it can be used to import a symmetric key with yaca_key_import().

The key_material should be freed using yaca_free().

Parameters:

[in]	kdf	Key derivation function
[in]	algo	Digest algorithm that should be used in key derivation
[in]	secret	Shared secret
[in]	secret_len	Size of the shared secret
[in]	info	Optional additional info, use NULL if not appending extra info
[in]	info_len	Length of additional info, use 0 if not using additional info
[in]	key_material_len	Length of a key material to be generated
[out]	key_material	Newly generated key material

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 algo or kdf)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_kdf_e

yaca_digest_algorithm_e

yaca_key_derive_dh()

yaca_key_import()

yaca_free()

int yaca_key_derive_pbkdf2	(	const char *	password,
		const char *	salt,
		size_t	salt_len,
		size_t	iterations,
		yaca_digest_algorithm_e	algo,
		size_t	key_bit_len,
		yaca_key_h *	key
	)

Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).

Since :

3.0

Remarks:

The key should be released using yaca_key_destroy().

Parameters:

[in]	password	User password as a null-terminated string
[in]	salt	Salt, should be a non-empty string
[in]	salt_len	Length of the salt
[in]	iterations	Number of iterations
[in]	algo	Digest algorithm that should be used in key generation
[in]	key_bit_len	Length of a key (in bits) to be generated
[out]	key	Newly generated key

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 algo or key_bit_len not dividable by 8)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_digest_algorithm_e

yaca_key_destroy()

void yaca_key_destroy

(

yaca_key_h

key

)

Release the key created by the library. Passing YACA_KEY_NULL is allowed.

Since :

3.0

Parameters:

[in,out]

key

Key to be released

See also:

yaca_key_import()

yaca_key_export()

yaca_key_generate()

int yaca_key_export	(	const yaca_key_h	key,
		yaca_key_format_e	key_fmt,
		yaca_key_file_format_e	key_file_fmt,
		const char *	password,
		char **	data,
		size_t *	data_len
	)

Exports a key or key generation parameters to arbitrary format.

Since :

3.0

Remarks:

Everywhere where either a key (of any type) or an asymmetric key is referred in the documentation of this function key generator parameters are also included.

This function exports the key to an arbitrary key format and key file format.

For key formats two values are allowed:

• YACA_KEY_FORMAT_DEFAULT: this is the only option possible in case of symmetric keys (or Initialization Vector), for asymmetric keys it will export to their default ASN1 structure format (e.g. PKCS#1, SSLeay, PKCS#3).
• YACA_KEY_FORMAT_PKCS8: this will only work for private asymmetric keys.

The following file formats are supported:

• YACA_KEY_FILE_FORMAT_RAW: used only for symmetric, raw binary format
• YACA_KEY_FILE_FORMAT_BASE64: used only for symmetric, BASE64 encoded binary form
• YACA_KEY_FILE_FORMAT_PEM: used only for asymmetric, PEM file format
• YACA_KEY_FILE_FORMAT_DER: used only for asymmetric, DER file format

Encryption is supported and optional for RSA/DSA private keys in the YACA_KEY_FORMAT_DEFAULT with YACA_KEY_FILE_FORMAT_PEM format. If no password is provided the exported key will be unencrypted. The encryption algorithm used in this case is AES-256-CBC.

Encryption is obligatory for YACA_KEY_FORMAT_PKCS8 format (for both, PEM and DER file formats). If no password is provided the YACA_ERROR_INVALID_PARAMETER will be returned. The encryption algorithm used in this case is AES-256-CBC. The key is generated from password using PBKDF2 with HMAC-SHA1 function and 2048 iterations.

Encryption is not supported for the symmetric, public keys and key generation parameters in all their supported formats. If a password is provided in such case the YACA_ERROR_INVALID_PARAMETER will be returned.

Parameters:

[in]	key	Key to be exported
[in]	key_fmt	Format of the key
[in]	key_file_fmt	Format of the key file
[in]	password	Password used for the encryption (can be NULL)
[out]	data	Data, allocated by the library, containing exported key (must be freed with yaca_free())
[out]	data_len	Size of the output 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, 0, invalid key_fmt, key_file_fmt or data_len too big)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_format_e

yaca_key_file_format_e

yaca_key_import()

yaca_key_destroy()

int yaca_key_extract_parameters	(	const yaca_key_h	key,
		yaca_key_h *	params
	)

Extracts parameters from a private or a public key.

Since :

3.0

Remarks:

The params should be released using yaca_key_destroy().

Parameters:

[in]	key	A key to extract the parameters from
[out]	params	Extracted parameters

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	key is of invalid type or params is NULL
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_generate()

yaca_key_generate_from_parameters()

yaca_key_import()

yaca_key_destroy()

int yaca_key_extract_public	(	const yaca_key_h	prv_key,
		yaca_key_h *	pub_key
	)

Extracts public key from a private one.

Since :

3.0

Remarks:

The pub_key should be released using yaca_key_destroy().

Parameters:

[in]	prv_key	Private key to extract the public one from
[out]	pub_key	Extracted public key

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	prv_key is of invalid type or pub_key is NULL
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_generate()

yaca_key_import()

yaca_key_destroy()

int yaca_key_generate	(	yaca_key_type_e	key_type,
		size_t	key_bit_len,
		yaca_key_h *	key
	)

Generates a secure key or key generation parameters (or an Initialization Vector).

Since :

3.0

Remarks:

This function is used to generate symmetric keys, private asymmetric keys or key generation parameters for key types that support them (DSA, DH and EC).

Supported key lengths:

• RSA: length >= 512bits
• DSA: length >= 512bits, multiple of 64
• DH: a value taken from yaca_key_bit_length_dh_rfc_e or (YACA_KEY_LENGTH_DH_GENERATOR_* | prime_length_in_bits), where prime_length_in_bits can be any positive number
• EC: a value taken from yaca_key_bit_length_ec_e

The key should be released using yaca_key_destroy().

Parameters:

[in]	key_type	Type of the key to be generated
[in]	key_bit_len	Length of the key (in bits) to be generated
[out]	key	Newly generated key

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	key is NULL, incorrect key_type or key_bit_len is not dividable by 8
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_type_e

yaca_key_bit_length_e

yaca_key_bit_length_dh_rfc_e

YACA_KEY_LENGTH_DH_GENERATOR_2

YACA_KEY_LENGTH_DH_GENERATOR_5

yaca_key_bit_length_ec_e

yaca_key_destroy()

int yaca_key_generate_from_parameters	(	const yaca_key_h	params,
		yaca_key_h *	prv_key
	)

Generates a secure private asymmetric key from parameters.

Since :

3.0

Remarks:

This function is used to generate private asymmetric keys based on pre-generated parameters.

The key should be released using yaca_key_destroy().

Parameters:

[in]	params	Pre-generated parameters
[out]	prv_key	Newly generated private key

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	prv_key is NULL or incorrect params
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_destroy()

yaca_key_generate()

yaca_key_extract_parameters()

int yaca_key_get_bit_length	(	const yaca_key_h	key,
		size_t *	key_bit_len
	)

Gets key's length (in bits).

Since :

3.0

Remarks:

The key can be any symmetric (including an Initialization Vector) or asymmetric key (including key generation parameters).

For Diffie-Helmann key_bit_len returns prime length in bits. Values used to generate the key/parameters in yaca_key_generate() are not restored. Neither generator number nor values from yaca_key_bit_length_dh_rfc_e.

For Elliptic Curves key_bit_len returns values from yaca_key_bit_length_ec_e.

Parameters:

[in]	key	Key which length we return
[out]	key_bit_len	Key length in bits

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Either of the params is NULL
YACA_ERROR_INTERNAL	Internal error

See also:

yaca_key_bit_length_e

yaca_key_bit_length_dh_rfc_e

yaca_key_bit_length_ec_e

int yaca_key_get_type	(	const yaca_key_h	key,
		yaca_key_type_e *	key_type
	)

Gets key's type.

Since :

3.0

Parameters:

[in]	key	Key which type we return
[out]	key_type	Key type

Returns:

YACA_ERROR_NONE on success, negative on error

Return values:

YACA_ERROR_NONE	Successful
YACA_ERROR_INVALID_PARAMETER	Either of the params is NULL

See also:

yaca_key_type_e

int yaca_key_import	(	yaca_key_type_e	key_type,
		const char *	password,
		const char *	data,
		size_t	data_len,
		yaca_key_h *	key
	)

Imports a key or key generation parameters.

Since :

3.0

Remarks:

Everywhere where either a key (of any type) or an asymmetric key is referred in the documentation of this function key generator parameters are also included.

This function imports a key trying to match it to the key_type specified. It should autodetect both the key format and the file format.

For symmetric, Initialization Vector and DES keys RAW binary format and BASE64 encoded binary format are supported. For asymmetric keys PEM and DER file formats are supported.

Asymmetric keys can be in their default ASN1 structure formats (like PKCS#1, SSleay or PKCS#3). Private asymmetric keys can also be in PKCS#8 format. Additionally it is possible to import public RSA/DSA/EC keys from X509 certificate.

If the key is encrypted the algorithm will be autodetected and password used. If it's not known if the key is encrypted one should pass NULL as password and check for the YACA_ERROR_INVALID_PASSWORD return code.

If the imported key will be detected as a format that does not support encryption and password was passed YACA_ERROR_INVALID_PARAMETER will be returned. For a list of keys and formats that do support encryption see yaca_key_export() documentation.

The key should be released using yaca_key_destroy().

Parameters:

[in]	key_type	Type of the key
[in]	password	Null-terminated password for the key (can be NULL)
[in]	data	Blob containing the key
[in]	data_len	Size of the blob
[out]	key	Returned key

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 key_type or data_len too big)
YACA_ERROR_OUT_OF_MEMORY	Out of memory error
YACA_ERROR_INTERNAL	Internal error
YACA_ERROR_INVALID_PASSWORD	Invalid password given or password was required and none was given

See also:

yaca_key_type_e

yaca_key_export()

yaca_key_destroy()