crypto

Data Structures
struct	crypto_key_plain
	Internal representation of a key in byte string format. More...
struct	crypto_key
	Private/public key handle. More...

Macros
#define	crypto_alg_null   0
	Null operation for all algorithms. More...
#define	CRYPTO_SHA1_LEN   20
	Destination buffer lengths for hash algorithms. More...
#define	CRYPTO_SHA224_LEN   28
#define	CRYPTO_SHA256_LEN   32
#define	CRYPTO_SHA384_LEN   48
#define	CRYPTO_SHA512_LEN   64
#define	CRYPTO_AES_BLOCK_SIZE_BYTES   16
	Size of AES cipher and plain text blocks in bytes. More...
#define	CRYPTO_KEY_INITIALIZER   { NULL, crypto_key_type_none, false }
	static initializer

Enumerations
enum	crypto_sym_alg { crypto_sym_alg_invalid = 0, crypto_sym_alg_aes_cbc = 1 }
	Enumeration of symmetric encryption algorithms. More...
enum	crypto_asym_alg { crypto_asym_alg_invalid = 0, crypto_asym_alg_rsa = 1, crypto_asym_alg_rsa_sha256 = 2 }
	Enumeration of asymmetric encryption algorithms. More...
enum	crypto_sign_alg {   crypto_sign_alg_invalid = 0, crypto_sign_alg_hmac_sha1 = 1, crypto_sign_alg_hmac_sha224 = 2, crypto_sign_alg_hmac_sha256 = 3,   crypto_sign_alg_hmac_sha384 = 4, crypto_sign_alg_hmac_sha512 = 5, crypto_sign_alg_rsa_sha1 = 6, crypto_sign_alg_rsa_sha256 = 7,   crypto_sign_alg_rsa_sha256_pss = 8 }
	Enumeration of message signing algorithms (algorithm, hash and scheme combined). More...
enum	crypto_hash_alg {   crypto_hash_alg_invalid = 0, crypto_hash_alg_sha1 = 1, crypto_hash_alg_sha224 = 2, crypto_hash_alg_sha256 = 3,   crypto_hash_alg_sha384 = 4, crypto_hash_alg_sha512 = 5 }
	Enumeration of hash algorithms. More...
enum	crypto_pad_alg { crypto_pad_invalid = 0, crypto_pad_pkcs1_v15 = 1, crypto_pad_pkcs1_oaep = 2 }
	Enumeration of padding algorithms. More...
enum	crypto_key_format { crypto_key_format_none = 0, crypto_key_format_pem = 1, crypto_key_format_der = 2 }
	Describes several key encoding formats. More...
enum	crypto_key_type {   crypto_key_type_none = 0, crypto_key_type_rsa_public = 1, crypto_key_type_rsa_private = 2, crypto_key_type_aes_encrypt = 3,   crypto_key_type_aes_decrypt = 4, crypto_key_type_hmac_sign = 5 }
	Describes the type of the contained key. More...

Functions
int	crypt_sym_encrypt (enum crypto_sym_alg alg_id, struct crypto_key *key, unsigned char *iv, size_t len, const unsigned char *in, unsigned char *out)
	En-/decrypt buffer content using the requested algorithm. More...
int	crypt_sym_decrypt (enum crypto_sym_alg alg_id, struct crypto_key *key, unsigned char *iv, size_t len, const unsigned char *in, unsigned char *out)
	En-/decrypt buffer content using the requested algorithm. More...
int	crypt_sym_sign (enum crypto_sign_alg alg_id, struct crypto_key *signkey, const unsigned char *data, size_t datalen, unsigned char *mac, size_t maclen)
	Sign the given data using HMAC and the given algorithm. More...
int	crypt_sym_verify (enum crypto_sign_alg alg_id, struct crypto_key *signkey, const unsigned char *data, size_t datalen, unsigned char *mac, size_t maclen)
	Verify the correctness of the given signature. More...
int	crypt_encrypt (enum crypto_asym_alg alg_id, enum crypto_pad_alg pad_id, struct crypto_key *pubkey, const unsigned char *ptext, size_t plen, unsigned char *ctext, size_t *clen)
	Encrypt buffer content using the requested algorithm. More...
int	crypt_decrypt (enum crypto_asym_alg alg_id, enum crypto_pad_alg pad_id, struct crypto_key *privkey, const unsigned char *ctext, size_t clen, unsigned char *ptext, size_t *plen)
	Decrypt buffer content using the requested algorithm. More...
int	crypt_sign (enum crypto_sign_alg alg_id, struct crypto_key *privkey, const unsigned char *data, size_t datalen, unsigned char *sig, size_t siglen)
	Create cryptographic signature (e.g. More...
int	crypt_verify (enum crypto_sign_alg alg_id, struct crypto_key *verkey, const unsigned char *data, size_t len, const unsigned char *sig, size_t siglen)
	Verify cryptographic signature (e.g. More...
int	crypt_hash (enum crypto_hash_alg alg_id, const unsigned char *data, size_t len, unsigned char *md)
	Generate a hash value (e.g. More...
int	crypt_psha (enum crypto_hash_alg alg_id, const unsigned char *secret, size_t secretlen, const unsigned char *seed, size_t seedlen, unsigned char *out, size_t outlen)
	Generate P-SHA hash value. More...
int	crypt_random (unsigned char *data, size_t len)
	Fill the given buffer with random bytes. More...
int	crypt_random_seed (const unsigned char *seed, size_t seedlen)
	Initializes the RNG with the provided seed data. More...
int	crypt_init (const unsigned char *seed, size_t seedlen)
	Initialize the crypto library. More...
void	crypt_clear (void)
	Clean up resources of the crypto library.
int	crypto_key_from_pem (const unsigned char *pem, size_t pemlen, const unsigned char *pwd, size_t pwdlen, enum crypto_key_type type, struct crypto_key *key)
	Decode RSA key from PEM format. More...
int	crypto_key_to_pem (struct crypto_key *key, unsigned char *pem, size_t *pemlen)
	Encode private key into PEM format. More...
int	crypto_key_create_rsa_key (struct crypto_key *key, size_t bits)
	Create a random RSA keypair. More...
int	crypto_key_get_rsa_public_key (struct crypto_key *key, struct crypto_key *pubkey)
	Get the public key from a keypair/private key. More...
int	crypto_key_check_rsa_pair (struct crypto_key *key, struct crypto_key *pubkey)
	Check if the public key and the private key match. More...
int	crypto_key_init (enum crypto_key_type type, const unsigned char *keydata, size_t keydatalen, struct crypto_key *key)
	Prepare key structure for use in symmetric encryption. More...
size_t	crypto_key_length (struct crypto_key *key)
	Get the key length. More...
void	crypto_key_clear (struct crypto_key *key)
	Release handle to key. More...

Detailed Description

Macro Definition Documentation

CRYPTO_AES_BLOCK_SIZE_BYTES

#define CRYPTO_AES_BLOCK_SIZE_BYTES   16

Size of AES cipher and plain text blocks in bytes.

crypto_alg_null

#define crypto_alg_null   0

Null operation for all algorithms.

CRYPTO_SHA1_LEN

#define CRYPTO_SHA1_LEN   20

Destination buffer lengths for hash algorithms.

Enumeration Type Documentation

crypto_asym_alg

enum crypto_asym_alg

Enumeration of asymmetric encryption algorithms.

Enumerator
crypto_asym_alg_invalid	invalid enumeration value
crypto_asym_alg_rsa	RSA encryption with SHA1.
crypto_asym_alg_rsa_sha256	RSA encryption with SHA256.

crypto_hash_alg

enum crypto_hash_alg

Enumeration of hash algorithms.

Enumerator
crypto_hash_alg_invalid	invalid enumeration value
crypto_hash_alg_sha1	160 bit secure hash algorithm (SHA1)
crypto_hash_alg_sha224	224 bit secure hash algorithm (SHA2)
crypto_hash_alg_sha256	256 bit secure hash algorithm (SHA2)
crypto_hash_alg_sha384	384 bit secure hash algorithm (SHA2)
crypto_hash_alg_sha512	512 bit secure hash algorithm (SHA2)

crypto_key_format

enum crypto_key_format

Describes several key encoding formats.

Enumerator
crypto_key_format_none	Empty format placeholder.
crypto_key_format_pem	PEM encoding.
crypto_key_format_der	DER.

crypto_key_type

enum crypto_key_type

Describes the type of the contained key.

Enumerator
crypto_key_type_none	Empty key structure.
crypto_key_type_rsa_public	Public key used for RSA crypto operations.
crypto_key_type_rsa_private	Private key used for RSA crypto operations.
crypto_key_type_aes_encrypt	Symmetric key used for AES encrypt operations.
crypto_key_type_aes_decrypt	Symmetric key used for AES decrypt operations.
crypto_key_type_hmac_sign	Key used for HMAC operations.

crypto_pad_alg

enum crypto_pad_alg

Enumeration of padding algorithms.

Enumerator
crypto_pad_invalid	invalid enumeration value
crypto_pad_pkcs1_v15	PKCS1 padding v1.5.
crypto_pad_pkcs1_oaep	PKCS1 OAEP.

crypto_sign_alg

enum crypto_sign_alg

Enumeration of message signing algorithms (algorithm, hash and scheme combined).

Enumerator
crypto_sign_alg_invalid	invalid enumeration value
crypto_sign_alg_hmac_sha1	hash-base message authentication using 160 bit SHA1
crypto_sign_alg_hmac_sha224	hash-base message authentication using 224 bit SHA2
crypto_sign_alg_hmac_sha256	hash-base message authentication using 256 bit SHA2
crypto_sign_alg_hmac_sha384	hash-base message authentication using 384 bit SHA2
crypto_sign_alg_hmac_sha512	hash-base message authentication using 512 bit SHA2
crypto_sign_alg_rsa_sha1	RSA based signature using 160 bit SHA1.
crypto_sign_alg_rsa_sha256	RSA based signature using 256 bit SHA2.
crypto_sign_alg_rsa_sha256_pss	RSA based signature using 256 bit SHA2 and PSS padding.

crypto_sym_alg

enum crypto_sym_alg

Enumeration of symmetric encryption algorithms.

Enumerator
crypto_sym_alg_invalid	invalid value
crypto_sym_alg_aes_cbc	AES encryption with cipher block chaining.

Function Documentation

crypt_decrypt()

int crypt_decrypt	(	enum crypto_asym_alg	alg_id,
		enum crypto_pad_alg	pad_id,
		struct crypto_key *	privkey,
		const unsigned char *	ctext,
		size_t	clen,
		unsigned char *	ptext,
		size_t *	plen
	)

Decrypt buffer content using the requested algorithm.

Parameters

alg_id	Identifier of the requested algorithm.
pad_id	Identifier of the padding algorithm.
privkey	The private key.
ctext	The cipher text. Can contain more than one encrypted block.
clen	Length of the cipher text. Must be a multiple of the key length.
ptext	The plain text.
plen	Length of the plain text buffer. Used length on return.

Returns

Error Code

crypt_encrypt()

int crypt_encrypt	(	enum crypto_asym_alg	alg_id,
		enum crypto_pad_alg	pad_id,
		struct crypto_key *	pubkey,
		const unsigned char *	ptext,
		size_t	plen,
		unsigned char *	ctext,
		size_t *	clen
	)

Encrypt buffer content using the requested algorithm.

The plain text can be of any size, independently of alg_id and pad_id. ctext can contain more than one block.

Parameters

alg_id	Identifier of the encryption algorithm.
pad_id	Identifier of the padding algorithm.
pubkey	The public key.
ctext	The plain text.
plen	Length of the plain text.
ptext	The cipher text.
clen	Length of the cipher text buffer. Used space on return.

Returns

Error Code

crypt_hash()

int crypt_hash	(	enum crypto_hash_alg	alg_id,
		const unsigned char *	data,
		size_t	len,
		unsigned char *	md
	)

Generate a hash value (e.g.

SHA1).

Parameters

alg_id	Identifier of the requested algorithm.
data	Data to hash.
len	Length in bytes of the data to hash.
md	The resulting message digest.

Returns

Error Code

crypt_init()

int crypt_init	(	const unsigned char *	seed,
		size_t	seedlen
	)

Initialize the crypto library.

Must be called before any other call to this API.

Parameters

seed	Data for seeding the entropy generator.
seedlen	Length of seed.

Returns

Error Code

crypt_psha()

int crypt_psha	(	enum crypto_hash_alg	alg_id,
		const unsigned char *	secret,
		size_t	secretlen,
		const unsigned char *	seed,
		size_t	seedlen,
		unsigned char *	out,
		size_t	outlen
	)

Generate P-SHA hash value.

Parameters

alg_id	Identifier of the requested algorithm (only sha1 and sha256 mandatory).
secret	Shared secret data.
secretlen	Length in bytes of the shared secret.
seed	Label and seed data.
seedlen	Length in bytes of the label and seed. The max. supported size is 32 bytes.
out	Buffer of size outlen for storing the created hashes.
outlen	Length in bytes of the hash value to create. Must be a multiple of the digest length.

Returns

Error Code

crypt_random()

int crypt_random	(	unsigned char *	data,
		size_t	len
	)

Fill the given buffer with random bytes.

Parameters

data	Buffer to fill with random bytes.
len	Size of the buffer in bytes.

Returns

Error Code

crypt_random_seed()

int crypt_random_seed	(	const unsigned char *	seed,
		size_t	seedlen
	)

Initializes the RNG with the provided seed data.

Parameters

seed	Data for seeding the random number generator.
seedlen	Length of seed in bytes.

Returns

Error Code

crypt_sign()

int crypt_sign	(	enum crypto_sign_alg	alg_id,
		struct crypto_key *	privkey,
		const unsigned char *	data,
		size_t	datalen,
		unsigned char *	sig,
		size_t	siglen
	)

Create cryptographic signature (e.g.

RSA SHA1).

Parameters

alg_id	Identifier of the requested algorithm.
privkey	The private signing key.
data	Data to sign.
datalen	Length in bytes of the data to sign.
sig	The resulting signature.
siglen	Length of the buffer to store the signature.

Returns

Error Code

crypt_sym_decrypt()

int crypt_sym_decrypt	(	enum crypto_sym_alg	alg_id,
		struct crypto_key *	key,
		unsigned char *	iv,
		size_t	len,
		const unsigned char *	in,
		unsigned char *	out
	)

En-/decrypt buffer content using the requested algorithm.

Parameters

alg_id	Identifier of the crypto algorithm.
key	Encrytpion key.
iv	Initialization vector of size 16 bytes. (updated after use)
len	Length in bytes of the text to encrypt/decrypt (multiple of 16).
out	Cipher text of "len" bytes". @param in Plain text of "len" bytes".

Returns

Error Code

crypt_sym_encrypt()

int crypt_sym_encrypt	(	enum crypto_sym_alg	alg_id,
		struct crypto_key *	key,
		unsigned char *	iv,
		size_t	len,
		const unsigned char *	in,
		unsigned char *	out
	)

En-/decrypt buffer content using the requested algorithm.

Parameters

alg_id	Identifier of the crypto algorithm.
key	Encrytpion key.
iv	Initialization vector of size 16 bytes. (updated after use)
len	Length in bytes of the text to encrypt/decrypt (multiple of 16).
in	Plain text of "len" bytes". @param out Cipher text of "len" bytes".

Returns

Error Code

crypt_sym_sign()

int crypt_sym_sign	(	enum crypto_sign_alg	alg_id,
		struct crypto_key *	signkey,
		const unsigned char *	data,
		size_t	datalen,
		unsigned char *	mac,
		size_t	maclen
	)

Sign the given data using HMAC and the given algorithm.

Parameters

alg_id	HMAC algorithm to use.
signkey	Key for hashing.
data	Data to sign.
datalen	Length of the data to sign.
mac	Destination buffer of size maclen.
maclen	Size of the destination buffer.

Returns

Error Code

crypt_sym_verify()

int crypt_sym_verify	(	enum crypto_sign_alg	alg_id,
		struct crypto_key *	signkey,
		const unsigned char *	data,
		size_t	datalen,
		unsigned char *	mac,
		size_t	maclen
	)

Verify the correctness of the given signature.

Parameters

alg_id	HMAC algorithm to use.
signkey	Key for hashing.
data	Data to sign.
datalen	Length of the data to sign.
mac	Buffer containing the signature to verify.
maclen	Length of the signature data to be verified.

Returns

Error Code; UA_EBADSIGNATURE if signature cannot be verified.

crypt_verify()

int crypt_verify	(	enum crypto_sign_alg	alg_id,
		struct crypto_key *	verkey,
		const unsigned char *	data,
		size_t	len,
		const unsigned char *	sig,
		size_t	siglen
	)

Verify cryptographic signature (e.g.

RSA SHA1).

Parameters

alg_id	Identifier of the requested algorithm.
verkey	Key containing the public key component.
data	Signed data.
len	Length in bytes of the signed data.
sig	The message digest.
siglen	Length of the buffer with the message digest.

Returns

Error Code; UA_EBADSIGNATURE if signature cannot be verified.

crypto_key_check_rsa_pair()

int crypto_key_check_rsa_pair	(	struct crypto_key *	key,
		struct crypto_key *	pubkey
	)

Check if the public key and the private key match.

Useful to check if a certificate and a private key match. This function is optional and may return UA_EBADNOTSUPPORTED.

Parameters

key	Pointer to the private key.
pubkey	Pointer to the public key.

Returns

Error Code

crypto_key_clear()

void crypto_key_clear

(

struct crypto_key *

key

)

Release handle to key.

Parameters

key	Key handle to release.

crypto_key_create_rsa_key()

int crypto_key_create_rsa_key	(	struct crypto_key *	key,
		size_t	bits
	)

Create a random RSA keypair.

Parameters

key	Pointer to the key structure to be set.
bits	Required length of the key in bits.

Returns

Error Code

crypto_key_from_pem()

int crypto_key_from_pem	(	const unsigned char *	pem,
		size_t	pemlen,
		const unsigned char *	pwd,
		size_t	pwdlen,
		enum crypto_key_type	type,
		struct crypto_key *	key
	)

Decode RSA key from PEM format.

Parameters

pem	Buffer containing a PEM encoded key.
pemlen	Length of the data in the buffer.
pwd	Buffer containing a optional password.
pwdlen	Length of the password.
type	Type of the decoded key.
key	Handle to the decoded key.

Returns

Error Code

crypto_key_get_rsa_public_key()

int crypto_key_get_rsa_public_key	(	struct crypto_key *	key,
		struct crypto_key *	pubkey
	)

Get the public key from a keypair/private key.

This function is optional and may return UA_EBADNOTSUPPORTED.

Parameters

key	Pointer to the key structure containing the keypair/private key.
pubkey	Pointer to the key structure to be initialized with the public key.

Returns

Error Code

crypto_key_init()

int crypto_key_init	(	enum crypto_key_type	type,
		const unsigned char *	keydata,
		size_t	keydatalen,
		struct crypto_key *	key
	)

Prepare key structure for use in symmetric encryption.

Parameters

type	The type of key.
keydata	Buffer containing the key data.
keydatalen	Length of the data in the key buffer.
key	Pointer to the key structure to be initialized.

Returns

Error Code

crypto_key_length()

size_t crypto_key_length

(

struct crypto_key *

key

)

Get the key length.

Parameters

key	Handle of the key.

Returns

Length of the key in bytes.

crypto_key_to_pem()

int crypto_key_to_pem	(	struct crypto_key *	key,
		unsigned char *	pem,
		size_t *	pemlen
	)

Encode private key into PEM format.

The result is a zero terminated string.

Parameters

key	Handle to the key to be encoded.
pem	Buffer to store the encoded key.
pemlen	Length of the destination buffer and used buffer on return.

Returns

Error Code