ordo.h File Reference

Wrapper. More...

#include "ordo/common/version.h"
#include "ordo/common/error.h"
#include "ordo/common/query.h"
#include "ordo/enc/enc_stream.h"
#include "ordo/enc/enc_block.h"
#include "ordo/auth/hmac.h"
#include "ordo/kdf/hkdf.h"
#include "ordo/kdf/pbkdf2.h"
#include "ordo/misc/utils.h"
#include "ordo/misc/os_random.h"
#include "ordo/misc/curve25519.h"

Include dependency graph for ordo.h:

Go to the source code of this file.

Functions
ORDO_PUBLIC int	ordo_enc_block (prim_t cipher, const void *cipher_params, prim_t mode, const void *mode_params, int direction, const void *key, size_t key_len, const void *iv, size_t iv_len, const void *in, size_t in_len, void *out, size_t *out_len)
ORDO_PUBLIC int	ordo_enc_stream (prim_t cipher, const void *params, const void *key, size_t key_len, void *inout, size_t len)
ORDO_PUBLIC int	ordo_digest (prim_t hash, const void *params, const void *in, size_t in_len, void *digest)
ORDO_PUBLIC int	ordo_hmac (prim_t hash, const void *params, const void *key, size_t key_len, const void *in, size_t in_len, void *fingerprint)

Detailed Description

Wrapper.

This is the highest-level API for Ordo, which forgoes the use of cryptographic contexts completely, resulting in more concise code at the cost of reduced flexibility - in other words, if you can afford to use them, you probably want to do so.

Usage snippet (compare to snippet in digest.h):

const char x[] = "Hello, world!";
unsigned char out[32]; // 256 bits
int err = ordo_digest(HASH_SHA256, 0, x, strlen(x), out);
if (err) printf("Error encountered!\n");
// out = 315f5bdb76d0...

Some specialized headers are not included by this header - these are the endianness header & all primitive headers (their parameters are included), if you need their functionality please include them explicitly.

Function Documentation

ORDO_PUBLIC int ordo_enc_block	(	prim_t	cipher,
		const void *	cipher_params,
		prim_t	mode,
		const void *	mode_params,
		int	direction,
		const void *	key,
		size_t	key_len,
		const void *	iv,
		size_t	iv_len,
		const void *	in,
		size_t	in_len,
		void *	out,
		size_t *	out_len
	)

Encrypts or decrypts data using a block cipher with a mode of operation.

Parameters

[in]	cipher	The block cipher to use.
[in]	cipher_params	The block cipher parameters.
[in]	mode	The mode of operation to use.
[in]	mode_params	The mode of operation parameters.
[in]	direction	1 for encryption, 0 for decryption.
[in]	key	The cryptographic key to use.
[in]	key_len	The length in bytes of the key.
[in]	iv	The initialization vector.
[in]	iv_len	The length in bytes of the IV.
[in]	in	The input plaintext/ciphertext buffer.
[in]	in_len	The length of the input buffer.
[out]	out	The output ciphertext/plaintext buffer.
[out]	out_len	The length of the output buffer.

Returns

ORDO_SUCCESS on success, else an error code.

Remarks

The out buffer should be large enough to accomodate the entire ciphertext which may be larger than the plaintext if a mode where padding is enabled and used, see padding notes in enc_block.h.

ORDO_PUBLIC int ordo_enc_stream	(	prim_t	cipher,
		const void *	params,
		const void *	key,
		size_t	key_len,
		void *	inout,
		size_t	len
	)

Encrypts or decrypts data using a stream cipher.

Parameters

[in]	cipher	The stream cipher to use.
[in]	params	The stream cipher parameters.
[in,out]	inout	The plaintext or ciphertext buffer.
[in]	len	The length, in bytes, of the buffer.
[in]	key	The cryptographic key to use.
[in]	key_len	The length, in bytes, of the key.

Returns

ORDO_SUCCESS on success, else an error code.

Remarks

Stream ciphers do not strictly speaking require an initialization vector - if such a feature is needed, it is recommended to use a key derivation function to derive an encryption key from a master key using a pseudorandomly generated nonce.

Encryption is always done in place. If you require out-of-place encryption, make a copy of the plaintext prior to encryption.

Warning

By design, encryption and decryption are equivalent for stream ciphers - an implication is that encrypting a message twice using the same key yields the original message.

ORDO_PUBLIC int ordo_digest	(	prim_t	hash,
		const void *	params,
		const void *	in,
		size_t	in_len,
		void *	digest
	)

Calculates the digest of a buffer using any hash function.

Parameters

[in]	hash	The hash function to use.
[in]	params	The hash function parameters.
[in]	in	The input buffer to hash.
[in]	in_len	The length in bytes of the buffer.
[out]	digest	The output buffer for the digest.

Returns

ORDO_SUCCESS on success, else an error code.

ORDO_PUBLIC int ordo_hmac	(	prim_t	hash,
		const void *	params,
		const void *	key,
		size_t	key_len,
		const void *	in,
		size_t	in_len,
		void *	fingerprint
	)

Calculates the HMAC fingerprint of a buffer using any hash function.

Parameters

[in]	hash	The hash function to use.
[in]	params	The hash function parameters.
[in]	key	The key to use for authentication.
[in]	key_len	The length in bytes of the key.
[in]	in	The input buffer to authenticate.
[in]	in_len	The length, in bytes, of the input buffer.
[out]	fingerprint	The output buffer for the fingerprint.

Returns

ORDO_SUCCESS on success, else an error code.