knx application level security More...

#include <stddef.h>
#include "oc_ri.h"

Data Structures
struct	oc_auth_at_t
	Access Token (at) Information payload for a unicast message Example(JSON): More...

Typedefs
typedef struct oc_auth_at_t	oc_auth_at_t
	Access Token (at) Information payload for a unicast message Example(JSON): More...

Enumerations
enum	oc_at_profile_t { OC_PROFILE_UNKNOWN = 0 , OC_PROFILE_COAP_DTLS = 1 , OC_PROFILE_COAP_OSCORE = 2 , OC_PROFILE_COAP_TLS , OC_PROFILE_COAP_PASE = 255 }
	The token profiles see section 3.5.4.2 Access Token Resource Object. More...

Functions
int	oc_at_delete_entry (size_t device_index, int index)
	delete the /auth/at table entry More...

char *	oc_at_profile_to_string (oc_at_profile_t at_profile)
	access token profile to string More...

int	oc_core_find_at_entry_empty_slot (size_t device_index)
	find empty slot More...

int	oc_core_find_at_entry_with_context_id (size_t device_index, char *context_id)
	find the entry with context_id as id More...

int	oc_core_find_at_entry_with_osc_id (size_t device_index, uint8_t *osc_id, size_t osc_id_len)
	Find an entry with a given OSCORE ID. More...

int	oc_core_get_at_table_size ()
	returns the size (amount of total entries) of the auth/at table More...

int	oc_core_set_at_table (size_t device_index, int index, oc_auth_at_t entry, bool store)
	set an entry in the auth/at table More...

void	oc_create_knx_sec_resources (size_t device)
	Creation of the KNX security resources. More...

void	oc_delete_at_table (size_t device_index)
	delete the /auth/at table will be used in reset of the device More...

oc_auth_at_t *	oc_get_auth_at_entry (size_t device_index, int index)
	retrieve auth/at entry More...

bool	oc_if_method_allowed_according_to_mask (oc_interface_mask_t iface_mask, oc_method_t method)
	is the method allowed according to the interface mask More...

void	oc_init_oscore (size_t device_index)
	initialize OSCORE for the device More...

void	oc_init_oscore_from_storage (size_t device_index, bool from_storage)
	initialize OSCORE for the device More...

bool	oc_knx_contains_interface (oc_interface_mask_t at_interface, oc_interface_mask_t resource_interface)
	function to check if the at_interface is listed in the resource interfaces More...

bool	oc_knx_sec_check_acl (oc_method_t method, const oc_resource_t resource, oc_endpoint_t endpoint)
	check access control based on acl and resource interfaces More...

uint64_t	oc_oscore_get_osndelay ()
	retrieve the oscore sequence number delay value More...

uint64_t	oc_oscore_get_rplwdo ()
	retrieve the replay window More...

void	oc_oscore_set_auth_device (char client_senderid, int client_senderid_size, char clientrecipient_id, int clientrecipient_id_size, uint8_t *shared_key, int shared_key_size)
	set shared (SPAKE) key to the auth at table, on the Device side More...

void	oc_oscore_set_auth_mac (char client_senderid, int client_senderid_size, char clientrecipient_id, int clientrecipient_id_size, uint8_t *shared_key, int shared_key_size)
	set shared (SPAKE) key to the auth at table, on the Management Client side More...

void	oc_print_auth_at_entry (size_t device_index, int index)
	print the auth/at entry More...

void	oc_reset_at_table (size_t device_index, int erase_code)
	reset the /auth/at table will be used in reset of the device erase_code: More...

oc_at_profile_t	oc_string_to_at_profile (oc_string_t str)
	string to access token profile More...

Detailed Description

knx application level security

Definition in file oc_knx_sec.h.

Typedef Documentation

◆ oc_auth_at_t

typedef struct oc_auth_at_t oc_auth_at_t

Access Token (at) Information payload for a unicast message Example(JSON):

*{
  "id": "OC5BLLhkAG ...",
  "profile": "coap_oscore",
  "aud" : "<iid>.<ia>"
  "scope": ["if.sec", "if.b"],
  "cnf": {
  "osc": {
  "alg": "AES-CCM-16-64-128", (decimal 10)
  "id": "<kid>/<sid>",
  "rid": "SID for response",
  "ms": "f9af8s.6bd94e6f"
  }}}

second example of (JSON) payload for a group address:

*{
  "id": "OC5BLLhkAG ...",
  "profile": "coap_oscore",
  "scope": [0, 1, 2],
  "cnf": {
  "osc": {
  "alg": "AES-CCM-16-64-128",
  "id": "<kid>/<sid>",
  "ms": "f9af8s.6bd94e6f"
  }}}

scope : "coap_oscore" [OSCORE] or "coap_dtls"

name	CBOR key	CBOR type	mandatory
id	0	string	yes
profile	38	unsigned	yes
scope	9	string/int array	yes
cnf	8	map	yes
osc	4	map	oscore
kid	2	string	optional
nbf	5	integer	optional
sub	2	string	conditional

Specific oscore values (ACE):

https://datatracker.ietf.org/doc/html/draft-ietf-ace-oscore-profile-19#section-3.2.1

name	CBOR label	CBOR type	description	default value
id	0	string	full ctx identifier	-
ms	18:4:2	byte string	Master Secret value (shall be PSK)	-
version	18:4:1	uint	OSCORE Version	1
hkdf	18:4:3	integer	HKDF value	HKDF SHA-256 (-10)
alg	18:4:4	integer	AEAD Algorithm	AES-CCM-16-64-128 (10)
salt	18:4:5	byte string	Master Salt	Default empty byte

Example payload:

{
  "alg" : "AES-CCM-16-64-128",
  "id" : b64'AQ=='
  "ms" : b64'+a+Dg2jjU+eIiOFCa9lObw'
}

Note: maps are not stored.

Enumeration Type Documentation

◆ oc_at_profile_t

enum oc_at_profile_t

The token profiles see section 3.5.4.2 Access Token Resource Object.

Enumerator
OC_PROFILE_UNKNOWN	unknown profile
OC_PROFILE_COAP_DTLS	"coap_dtls"
OC_PROFILE_COAP_OSCORE	"coap_oscore"
OC_PROFILE_COAP_TLS	coap_tls" [OSCORE] for [X.509] certificates with TLS
OC_PROFILE_COAP_PASE	"coap_pase" [OSCORE] with PASE credentials

Definition at line 36 of file oc_knx_sec.h.

              {
   OC_PROFILE_UNKNOWN = 0,     
   OC_PROFILE_COAP_DTLS = 1,   
   OC_PROFILE_COAP_OSCORE = 2, 
   OC_PROFILE_COAP_TLS =
     254, 
   OC_PROFILE_COAP_PASE = 255 
 } oc_at_profile_t;

Function Documentation

◆ oc_at_delete_entry()

int oc_at_delete_entry	(	size_t	device_index,
		int	index
	)

delete the /auth/at table entry

Parameters

device_index	the device index
index	the index in the table return 0 == success

◆ oc_at_profile_to_string()

char* oc_at_profile_to_string ( oc_at_profile_t at_profile )

access token profile to string

Parameters

at_profile the access token profile

Returns: char* the string denoting the at access token profile

◆ oc_core_find_at_entry_empty_slot()

int oc_core_find_at_entry_empty_slot ( size_t device_index )

find empty slot

Parameters

device_index The device index

Returns: int -1 : no space left; int >=0 : index to place entry

◆ oc_core_find_at_entry_with_context_id()

int oc_core_find_at_entry_with_context_id	(	size_t	device_index,
		char *	context_id
	)

find the entry with context_id as id

Parameters

device_index	The device index
context_id	the context id to search for

Returns: int -1 : no entry with that name; int >=0 : index of found entry

◆ oc_core_find_at_entry_with_osc_id()

int oc_core_find_at_entry_with_osc_id	(	size_t	device_index,
		uint8_t *	osc_id,
		size_t	osc_id_len
	)

Find an entry with a given OSCORE ID.

Parameters

device_index	The device index
osc_id	the oscore ID to search for
osc_id_len	length of the context

Returns: int -1 : no entry with that oscore id; int >= index of found entry

◆ oc_core_get_at_table_size()

int oc_core_get_at_table_size ( )

returns the size (amount of total entries) of the auth/at table

Returns: the allocated amount of entries of the auth/at table

◆ oc_core_set_at_table()

int oc_core_set_at_table	(	size_t	device_index,
		int	index,
		oc_auth_at_t	entry,
		bool	store
	)

set an entry in the auth/at table

Note: does not write to persistent storage

Parameters

device_index	index of the device
index	the index in the table, will overwrite if something is there
entry	the auth/at entry
store	the store the entry to persistent storage

Returns: int 0 == successful

◆ oc_create_knx_sec_resources()

void oc_create_knx_sec_resources ( size_t device )

Creation of the KNX security resources.

creates the following resources:

/auth/o
/auth/o/rplwdo
/auth/o/osndelay
/auth optional:
a/sen

Parameters

device index of the device to which the resources are to be created

◆ oc_delete_at_table()

void oc_delete_at_table ( size_t device_index )

delete the /auth/at table will be used in reset of the device

Parameters

device_index the device index

◆ oc_get_auth_at_entry()

oc_auth_at_t* oc_get_auth_at_entry	(	size_t	device_index,
		int	index
	)

retrieve auth/at entry

Parameters

device_index	the device index
index	the index in the table

Returns: oc_auth_at_t* the auth at entry

◆ oc_if_method_allowed_according_to_mask()

bool oc_if_method_allowed_according_to_mask	(	oc_interface_mask_t	iface_mask,
		oc_method_t	method
	)

is the method allowed according to the interface mask

Parameters

iface_mask	the interface mask
method	the method to be checked

Returns: true method allowed; false method not allowed

◆ oc_init_oscore()

void oc_init_oscore ( size_t device_index )

initialize OSCORE for the device

Note: does not read the context from storage

Parameters

device_index The device index

◆ oc_init_oscore_from_storage()

void oc_init_oscore_from_storage	(	size_t	device_index,
		bool	from_storage
	)

initialize OSCORE for the device

Parameters

device_index	The device index
from_storage	contents read from storage

◆ oc_knx_contains_interface()

bool oc_knx_contains_interface	(	oc_interface_mask_t	at_interface,
		oc_interface_mask_t	resource_interface
	)

function to check if the at_interface is listed in the resource interfaces

Parameters

at_interface	interface to be checked
resource_interface	list of interfaces.

Returns: true one of the at_interface listed in resource_interface list; false none of the at_interfaces listed in resource_interface list

◆ oc_knx_sec_check_acl()

bool oc_knx_sec_check_acl	(	oc_method_t	method,
		const oc_resource_t *	resource,
		oc_endpoint_t *	endpoint
	)

check access control based on acl and resource interfaces

Parameters

method	invocation method for this call
resource	the resource being called
endpoint	the used endpoint

Returns: true has access; false does not have access

◆ oc_oscore_get_osndelay()

uint64_t oc_oscore_get_osndelay ( )

retrieve the oscore sequence number delay value

Returns: uint64_t the osn delay value

◆ oc_oscore_get_rplwdo()

uint64_t oc_oscore_get_rplwdo ( )

retrieve the replay window

Returns: uint64_t the replay window

◆ oc_oscore_set_auth_device()

void oc_oscore_set_auth_device	(	char *	client_senderid,
		int	client_senderid_size,
		char *	clientrecipient_id,
		int	clientrecipient_id_size,
		uint8_t *	shared_key,
		int	shared_key_size
	)

set shared (SPAKE) key to the auth at table, on the Device side

Parameters

client_senderid	the client_senderid of the device that has been negotiated with spake2plus. This will become the Sender ID within the OSCORE context. This value is an ASCII-encoded string representing the hexadecimal serial number
client_senderid_size	the size of the serial number
clientrecipient_id	the clientrecipient_id (delivered during the handshake). This will become the Receiver ID. This value is in HEX
clientrecipient_id_size	the size of the clientrecipient_id
shared_key	the master key after SPAKE2 handshake
shared_key_size	the key size

◆ oc_oscore_set_auth_mac()

void oc_oscore_set_auth_mac	(	char *	client_senderid,
		int	client_senderid_size,
		char *	clientrecipient_id,
		int	clientrecipient_id_size,
		uint8_t *	shared_key,
		int	shared_key_size
	)

set shared (SPAKE) key to the auth at table, on the Management Client side

Parameters

client_senderid	the client_senderid of the device that has been negotiated with spake2plus. This will become the Receiver ID within the OSCORE context. This value is an ASCII-encoded string representing the hexadecimal serial number
client_senderid_size	the size of the serial number
clientrecipient_id	the clientrecipient_id (delivered during the handshake). This will become the Sender ID. This value is in HEX
clientrecipient_id_size	the size of the clientrecipient_id
shared_key	the master key after SPAKE2 handshake
shared_key_size	the key size

◆ oc_print_auth_at_entry()

void oc_print_auth_at_entry	(	size_t	device_index,
		int	index
	)

print the auth/at entry

Parameters

device_index	the device index
index	the index in the table to be printed

◆ oc_reset_at_table()

void oc_reset_at_table	(	size_t	device_index,
		int	erase_code
	)

reset the /auth/at table will be used in reset of the device erase_code:

2 : reset all entries (using oc_delete_at_table())
7 : reset all entries without scope = "if.sec"
Parameters

device_index the device index

erase_code the erase code

◆ oc_string_to_at_profile()

oc_at_profile_t oc_string_to_at_profile ( oc_string_t str )

string to access token profile

Parameters

str	input string

Returns: oc_at_profile_t the token profile

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ oc_auth_at_t

Enumeration Type Documentation

◆ oc_at_profile_t

Function Documentation

◆ oc_at_delete_entry()

◆ oc_at_profile_to_string()

◆ oc_core_find_at_entry_empty_slot()

◆ oc_core_find_at_entry_with_context_id()

◆ oc_core_find_at_entry_with_osc_id()

◆ oc_core_get_at_table_size()

◆ oc_core_set_at_table()

◆ oc_create_knx_sec_resources()

◆ oc_delete_at_table()

◆ oc_get_auth_at_entry()

◆ oc_if_method_allowed_according_to_mask()

◆ oc_init_oscore()

◆ oc_init_oscore_from_storage()

◆ oc_knx_contains_interface()

◆ oc_knx_sec_check_acl()

◆ oc_oscore_get_osndelay()

◆ oc_oscore_get_rplwdo()

◆ oc_oscore_set_auth_device()

◆ oc_oscore_set_auth_mac()

◆ oc_print_auth_at_entry()

◆ oc_reset_at_table()

◆ oc_string_to_at_profile()