sopc_secret_buffer.h File Reference

SecretBuffer (mangled key) and ExposedBuffer (contiguous deciphered buffered) APIs. More...

#include <stdint.h>

Go to the source code of this file.

Typedefs
typedef struct SOPC_SecretBuffer	SOPC_SecretBuffer
typedef uint8_t	SOPC_ExposedBuffer

Functions
SOPC_SecretBuffer *	SOPC_SecretBuffer_NewFromExposedBuffer (const SOPC_ExposedBuffer *buf, uint32_t len)
	Creates a new SecretBuffer from an ExposedBuffer. More...
SOPC_SecretBuffer *	SOPC_SecretBuffer_NewFromFile (const char *path)
	Creates a new SecretBuffer from a file. More...
SOPC_SecretBuffer *	SOPC_SecretBuffer_New (uint32_t len)
	Creates a new empty SecretBuffer. More...
void	SOPC_SecretBuffer_DeleteClear (SOPC_SecretBuffer *sec)
	Clears the SecretBuffer from its secrets and frees it. More...
uint32_t	SOPC_SecretBuffer_GetLength (const SOPC_SecretBuffer *sec)
	Length of the SecretBuffer. More...
const SOPC_ExposedBuffer *	SOPC_SecretBuffer_Expose (const SOPC_SecretBuffer *sec)
	Creates a ExposedBuffer from a SecretBuffer. More...
void	SOPC_SecretBuffer_Unexpose (const SOPC_ExposedBuffer *buf, const SOPC_SecretBuffer *sec)
	Unexposes the buffer. More...
SOPC_ExposedBuffer *	SOPC_SecretBuffer_ExposeModify (SOPC_SecretBuffer *sec)
	Creates a ExposedBuffer from a SecretBuffer for modification. More...
void	SOPC_SecretBuffer_UnexposeModify (SOPC_ExposedBuffer *buf, SOPC_SecretBuffer *sec)
	Unexposes the buffer exposed for modification. More...

Detailed Description

SecretBuffer (mangled key) and ExposedBuffer (contiguous deciphered buffered) APIs.

Sensitive information should be stored as SecretBuffer (e.g. crypto keys, nonces, initialisation vectors). The current implementation of the SecretBuffer is a contiguous buffer, but that could be changed without impact on the API.

Typedef Documentation

SOPC_SecretBuffer

typedef struct SOPC_SecretBuffer SOPC_SecretBuffer

SOPC_ExposedBuffer

typedef uint8_t SOPC_ExposedBuffer

Function Documentation

SOPC_SecretBuffer_NewFromExposedBuffer()

SOPC_SecretBuffer* SOPC_SecretBuffer_NewFromExposedBuffer	(	const SOPC_ExposedBuffer *	buf,
		uint32_t	len
	)

Creates a new SecretBuffer from an ExposedBuffer.

Copies buf, so it can be de-allocated after that call. This function does not clear the exposed secrets from buf.

SecretBuffer shall be de-allocated with SOPC_SecretBuffer_DeleteClear().

Parameters

buf	The ExposedBuffer.
len	Number of bytes of the buffer.

Returns

The SecretBuffer when successful, otherwise a NULL.

SOPC_SecretBuffer_NewFromFile()

SOPC_SecretBuffer* SOPC_SecretBuffer_NewFromFile

(

const char *

path

)

Creates a new SecretBuffer from a file.

Parameters

path	The path to the file

Returns

The created SecretBuffer if successful, or NULL in case of error.

SOPC_SecretBuffer_New()

SOPC_SecretBuffer* SOPC_SecretBuffer_New

(

uint32_t

len

)

Creates a new empty SecretBuffer.

Parameters

len	Number of bytes of the buffer.

Returns

The SecretBuffer when successful, otherwise a NULL.

SOPC_SecretBuffer_DeleteClear()

void SOPC_SecretBuffer_DeleteClear

(

SOPC_SecretBuffer *

sec

)

Clears the SecretBuffer from its secrets and frees it.

Parameters

sec	The SecretBuffer to free.

SOPC_SecretBuffer_GetLength()

uint32_t SOPC_SecretBuffer_GetLength

(

const SOPC_SecretBuffer *

sec

)

Length of the SecretBuffer.

SOPC_SecretBuffer_Expose()

const SOPC_ExposedBuffer* SOPC_SecretBuffer_Expose

(

const SOPC_SecretBuffer *

sec

)

Creates a ExposedBuffer from a SecretBuffer.

Each call to _Expose shoud be followed by a call to SOPC_SecretBuffer_Unexpose().

Warning

sec shall not be de-allocated before the call to SOPC_SecretBuffer_Unexpose().

The exposed buffer shall not be modified by the caller.

Parameters

sec	The SecretBuffer to expose.

Returns

The ExposedBuffer when successful, otherwise a NULL.

SOPC_SecretBuffer_Unexpose()

void SOPC_SecretBuffer_Unexpose	(	const SOPC_ExposedBuffer *	buf,
		const SOPC_SecretBuffer *	sec
	)

Unexposes the buffer.

Parameters

buf	The ExposedBuffer
sec	The SecretBuffer to store the data

SOPC_SecretBuffer_ExposeModify()

SOPC_ExposedBuffer* SOPC_SecretBuffer_ExposeModify

(

SOPC_SecretBuffer *

sec

)

Creates a ExposedBuffer from a SecretBuffer for modification.

Each call to _Expose shoud be followed by a call to SOPC_SecretBuffer_Unexpose().

Warning

sec shall not be de-allocated before the call to SOPC_SecretBuffer_Unexpose().

Parameters

sec	The SecretBuffer to expose.

Returns

The ExposedBuffer when successful, otherwise a NULL.

SOPC_SecretBuffer_UnexposeModify()

void SOPC_SecretBuffer_UnexposeModify	(	SOPC_ExposedBuffer *	buf,
		SOPC_SecretBuffer *	sec
	)

Unexposes the buffer exposed for modification.

Parameters

buf	The ExposedBuffer
sec	The SecretBuffer to store the data