Key stores provide key data for protecting messages and the network. More...

Data Structures
struct	_DPS_Key
	Union of supported key types. More...

struct	_DPS_KeyCert
	Certificate key data. More...

struct	_DPS_KeyEC
	Elliptic curve key data. More...

struct	_DPS_KeyId
	An identifier of a key in a key store. More...

struct	_DPS_KeySymmetric
	Symmetric key data. More...

KeyStore
Hooks for implementing an application-defined key store.
enum	DPS_KeyType { DPS_KEY_SYMMETRIC, DPS_KEY_EC, DPS_KEY_EC_CERT }
	A DPS key type. More...

enum	DPS_ECCurve { DPS_EC_CURVE_RESERVED = 0, DPS_EC_CURVE_P384 = 2, DPS_EC_CURVE_P521 = 3 }
	Allowed elliptic curves. More...

typedef struct _DPS_KeySymmetric	DPS_KeySymmetric
	Symmetric key data. More...

typedef struct _DPS_KeyEC	DPS_KeyEC
	Elliptic curve key data. More...

typedef struct _DPS_KeyCert	DPS_KeyCert
	Certificate key data. More...

typedef struct _DPS_Key	DPS_Key
	Union of supported key types.

typedef struct _DPS_KeyId	DPS_KeyId
	An identifier of a key in a key store.

typedef struct _DPS_KeyStore	DPS_KeyStore
	Opaque type for a key store.

typedef struct _DPS_KeyStoreRequest	DPS_KeyStoreRequest
	Opaque type for a key store request.

typedef DPS_Status(*	DPS_KeyAndIdHandler) (DPS_KeyStoreRequest *request)
	Function prototype for a key store handler called when a key and key identifier is requested. More...

typedef DPS_Status(*	DPS_KeyHandler) (DPS_KeyStoreRequest request, const DPS_KeyId keyId)
	Function prototype for a key store handler called when a key with the provided key identifier is requested. More...

typedef DPS_Status(*	DPS_EphemeralKeyHandler) (DPS_KeyStoreRequest request, const DPS_Key key)
	Function prototype for a key store handler called when an ephemeral key with the provided type is requested. More...

typedef DPS_Status(*	DPS_CAHandler) (DPS_KeyStoreRequest *request)
	Function prototype for a key store handler called when the trusted CA chain is requested. More...

DPS_Status	DPS_SetKeyAndId (DPS_KeyStoreRequest request, const DPS_Key key, const DPS_KeyId *keyId)
	Provide a key and key identifier to a key store request. More...

DPS_Status	DPS_SetKey (DPS_KeyStoreRequest request, const DPS_Key key)
	Provide a key to a key store request. More...

DPS_Status	DPS_SetCA (DPS_KeyStoreRequest request, const char ca)
	Provide a trusted CA chain to a key store request. More...

DPS_KeyStore *	DPS_KeyStoreHandle (DPS_KeyStoreRequest *request)
	Returns the `DPS_KeyStore*` of a key store request. More...

DPS_KeyStore *	DPS_CreateKeyStore (DPS_KeyAndIdHandler keyAndIdHandler, DPS_KeyHandler keyHandler, DPS_EphemeralKeyHandler ephemeralKeyHandler, DPS_CAHandler caHandler)
	Creates a key store. More...

void	DPS_DestroyKeyStore (DPS_KeyStore *keyStore)
	Destroys a previously created key store. More...

DPS_Status	DPS_SetKeyStoreData (DPS_KeyStore keyStore, void data)
	Store a pointer to application data in a key store. More...

void *	DPS_GetKeyStoreData (const DPS_KeyStore *keyStore)
	Get application data pointer previously set by DPS_SetKeyStoreData(). More...

#define	DPS_AES_256_KEY_LEN 32
	AES 256 key length, in bytes.

In-memory Key Store
The implementation of an in-memory key store.
typedef struct _DPS_MemoryKeyStore	DPS_MemoryKeyStore
	Opaque type for an in-memory key store.

DPS_MemoryKeyStore *	DPS_CreateMemoryKeyStore (void)
	Creates an in-memory key store. More...

void	DPS_DestroyMemoryKeyStore (DPS_MemoryKeyStore *keyStore)
	Destroys a previously created in-memory key store. More...

DPS_Status	DPS_SetContentKey (DPS_MemoryKeyStore keyStore, const DPS_KeyId keyId, const DPS_Key *key)
	Create or replace a key with the specified key identifier in the key store. More...

DPS_Status	DPS_SetNetworkKey (DPS_MemoryKeyStore keyStore, const DPS_KeyId keyId, const DPS_Key *key)
	Create or replace the network key in the key store. More...

DPS_Status	DPS_SetTrustedCA (DPS_MemoryKeyStore mks, const char ca)
	Create or replace the trusted CA(s) in the key store. More...

DPS_Status	DPS_SetCertificate (DPS_MemoryKeyStore mks, const char cert, const char key, const char password)
	Create or replace a certificate in the key store. More...

DPS_KeyStore *	DPS_MemoryKeyStoreHandle (DPS_MemoryKeyStore *keyStore)
	Returns the `DPS_KeyStore*` of an in-memory key store. More...

Detailed Description

Key stores provide key data for protecting messages and the network.

Typedef Documentation

◆ DPS_CAHandler

typedef DPS_Status(* DPS_CAHandler) (DPS_KeyStoreRequest *request)

Function prototype for a key store handler called when the trusted CA chain is requested.

DPS_SetCA() should be called to provide the CA chain to the caller.

Parameters

request The request, only valid with the body of this callback function.

Returns

DPS_OK when DPS_SetCA() succeeds
DPS_ERR_MISSING when no CA chain is configured
error otherwise

◆ DPS_EphemeralKeyHandler

typedef DPS_Status(* DPS_EphemeralKeyHandler) (DPS_KeyStoreRequest *request, const DPS_Key *key)

Function prototype for a key store handler called when an ephemeral key with the provided type is requested.

DPS_SetKey() should be called to provide the ephemeral key to the caller.

Parameters

request	The request, only valid with the body of this callback function.
key	The requested key type and parameters (e.g. key->type is DPS_KEY_EC and key->ec.curve is DPS_EC_CURVE_P521).

Returns

DPS_OK when DPS_SetKey() succeeds
DPS_ERR_MISSING when no key is located
error otherwise

◆ DPS_KeyAndIdHandler

typedef DPS_Status(* DPS_KeyAndIdHandler) (DPS_KeyStoreRequest *request)

Function prototype for a key store handler called when a key and key identifier is requested.

DPS_SetKeyAndId() should be called to provide the key and identifier to the caller.

Parameters

request The request, only valid with the body of this callback function.

Returns

DPS_OK when DPS_SetKeyAndId() succeeds
DPS_ERR_MISSING when no key is configured for this host
error otherwise

◆ DPS_KeyCert

typedef struct _DPS_KeyCert DPS_KeyCert

Certificate key data.

Note: Need to define this outside of DPS_Key to satisfy SWIG.

◆ DPS_KeyEC

typedef struct _DPS_KeyEC DPS_KeyEC

Elliptic curve key data.

Only x and y are needed for a public key. Similarly, only d is needed for a private key.

Note: Need to define this outside of DPS_Key to satisfy SWIG.

◆ DPS_KeyHandler

typedef DPS_Status(* DPS_KeyHandler) (DPS_KeyStoreRequest *request, const DPS_KeyId *keyId)

Function prototype for a key store handler called when a key with the provided key identifier is requested.

DPS_SetKey() should be called to provide the key to the caller.

Parameters

request	The request, only valid with the body of this callback function.
keyId	The identifier of the key to provide.

Returns

DPS_OK when DPS_SetKey() succeeds
DPS_ERR_MISSING when no key is located
error otherwise

◆ DPS_KeySymmetric

typedef struct _DPS_KeySymmetric DPS_KeySymmetric

Symmetric key data.

Note: Need to define this outside of DPS_Key to satisfy SWIG.

Enumeration Type Documentation

◆ DPS_ECCurve

enum DPS_ECCurve

Allowed elliptic curves.

Enumerator
DPS_EC_CURVE_P384	NIST P-384 also known as secp384r1.
DPS_EC_CURVE_P521	NIST P-521 also known as secp521r1.

◆ DPS_KeyType

enum DPS_KeyType

A DPS key type.

Enumerator
DPS_KEY_SYMMETRIC	DPS_KeySymmetric.
DPS_KEY_EC	DPS_KeyEC.
DPS_KEY_EC_CERT	DPS_KeyCert.

Function Documentation

◆ DPS_CreateKeyStore()

DPS_KeyStore* DPS_CreateKeyStore	(	DPS_KeyAndIdHandler	keyAndIdHandler,
		DPS_KeyHandler	keyHandler,
		DPS_EphemeralKeyHandler	ephemeralKeyHandler,
		DPS_CAHandler	caHandler
	)

Creates a key store.

Parameters

keyAndIdHandler	Optional handler for receiving key and key identifier requests
keyHandler	Optional handler for receiving key requests
ephemeralKeyHandler	Optional handler for receiving ephemeral key requests
caHandler	Optional handler for receiving CA chain requests

Returns: The key store or NULL if there were no resources.

◆ DPS_CreateMemoryKeyStore()

DPS_MemoryKeyStore* DPS_CreateMemoryKeyStore ( void )

Creates an in-memory key store.

Returns: The key store or NULL if there were no resources.

◆ DPS_DestroyKeyStore()

void DPS_DestroyKeyStore ( DPS_KeyStore * keyStore )

Destroys a previously created key store.

Parameters

keyStore The key store

◆ DPS_DestroyMemoryKeyStore()

void DPS_DestroyMemoryKeyStore ( DPS_MemoryKeyStore * keyStore )

Destroys a previously created in-memory key store.

Parameters

keyStore An in-memory key store

◆ DPS_GetKeyStoreData()

void* DPS_GetKeyStoreData ( const DPS_KeyStore * keyStore )

Get application data pointer previously set by DPS_SetKeyStoreData().

Parameters

keyStore The keyStore

Returns: A pointer to the data or NULL if the key store is invalid

◆ DPS_KeyStoreHandle()

DPS_KeyStore* DPS_KeyStoreHandle ( DPS_KeyStoreRequest * request )

Returns the DPS_KeyStore* of a key store request.

Parameters

request A key store request

Returns: The DPS_KeyStore* or NULL

◆ DPS_MemoryKeyStoreHandle()

DPS_KeyStore* DPS_MemoryKeyStoreHandle ( DPS_MemoryKeyStore * keyStore )

Returns the DPS_KeyStore* of an in-memory key store.

Parameters

keyStore An in-memory key store

Returns: The DPS_KeyStore* or NULL

◆ DPS_SetCA()

DPS_Status DPS_SetCA	(	DPS_KeyStoreRequest *	request,
		const char *	ca
	)

Provide a trusted CA chain to a key store request.

Parameters

request	The `request` parameter of the handler
ca	The CA chain in PEM format

Returns: DPS_OK or an error

◆ DPS_SetCertificate()

DPS_Status DPS_SetCertificate	(	DPS_MemoryKeyStore *	mks,
		const char *	cert,
		const char *	key,
		const char *	password
	)

Create or replace a certificate in the key store.

Parameters

mks	An in-memory key store
cert	The certificate in PEM format
key	The optional private key in PEM format
password	The optional password protecting the key, may be NULL

Returns: DPS_OK or an error

◆ DPS_SetContentKey()

DPS_Status DPS_SetContentKey	(	DPS_MemoryKeyStore *	keyStore,
		const DPS_KeyId *	keyId,
		const DPS_Key *	key
	)

Create or replace a key with the specified key identifier in the key store.

Specify a previously set key identifier and a NULL key to remove a key from the key store.

Parameters

keyStore	An in-memory key store
keyId	The identifier of the key to create, replace, or remove
key	The key

Returns: DPS_OK or an error

◆ DPS_SetKey()

DPS_Status DPS_SetKey	(	DPS_KeyStoreRequest *	request,
		const DPS_Key *	key
	)

Provide a key to a key store request.

Parameters

request	The `request` parameter of the handler
key	The key

Returns: DPS_OK or an error

◆ DPS_SetKeyAndId()

DPS_Status DPS_SetKeyAndId	(	DPS_KeyStoreRequest *	request,
		const DPS_Key *	key,
		const DPS_KeyId *	keyId
	)

Provide a key and key identifier to a key store request.

Parameters

request	The `request` parameter of the handler
key	The key
keyId	The identifier of the key to provide

Returns: DPS_OK or an error

◆ DPS_SetKeyStoreData()

DPS_Status DPS_SetKeyStoreData	(	DPS_KeyStore *	keyStore,
		void *	data
	)

Store a pointer to application data in a key store.

Parameters

keyStore	The key store
data	The data pointer to store

Returns: DPS_OK or an error

◆ DPS_SetNetworkKey()

DPS_Status DPS_SetNetworkKey	(	DPS_MemoryKeyStore *	keyStore,
		const DPS_KeyId *	keyId,
		const DPS_Key *	key
	)

Create or replace the network key in the key store.

Parameters

keyStore	An in-memory key store
keyId	The identifier of the key to create
key	The key

Returns: DPS_OK or an error

◆ DPS_SetTrustedCA()

DPS_Status DPS_SetTrustedCA	(	DPS_MemoryKeyStore *	mks,
		const char *	ca
	)

Create or replace the trusted CA(s) in the key store.

Parameters

mks	An in-memory key store
ca	The CA chain in PEM format

Returns: DPS_OK or an error

Data Structures

KeyStore

In-memory Key Store

Detailed Description

Typedef Documentation

◆ DPS_CAHandler

◆ DPS_EphemeralKeyHandler

◆ DPS_KeyAndIdHandler

◆ DPS_KeyCert

◆ DPS_KeyEC

◆ DPS_KeyHandler

◆ DPS_KeySymmetric

Enumeration Type Documentation

◆ DPS_ECCurve

◆ DPS_KeyType

Function Documentation

◆ DPS_CreateKeyStore()

◆ DPS_CreateMemoryKeyStore()

◆ DPS_DestroyKeyStore()

◆ DPS_DestroyMemoryKeyStore()

◆ DPS_GetKeyStoreData()

◆ DPS_KeyStoreHandle()

◆ DPS_MemoryKeyStoreHandle()

◆ DPS_SetCA()

◆ DPS_SetCertificate()

◆ DPS_SetContentKey()

◆ DPS_SetKey()

◆ DPS_SetKeyAndId()

◆ DPS_SetKeyStoreData()

◆ DPS_SetNetworkKey()

◆ DPS_SetTrustedCA()