Security LwM2M object

Detailed Description

Security object implementation for LwM2M client using Wakaama

Warning

This feature is experimental!
This API is considered experimental and may change in future releases without deprecation process.

This implements the LwM2M Security object as specified in the Appendix E1 of the LwM2M specification.

So far only NO_SEC, PSK (Pre-shared key) and RPK (Raw public key) modes are available.

Resources

For an XML description of the object see https://raw.githubusercontent.com/OpenMobileAlliance/lwm2m-registry/prod/version_history/0-1_0.xml.

Name	ID	Mandatory	Type	Range	Units	Implemented
Server URI	0	Yes	String			Yes
Bootstrap Server	1	Yes	Boolean			Yes
Security Mode	2	Yes	Integer	0-3		Yes
Public Key or ID	3	Yes	Opaque			Yes
Server Public Key	4	Yes	Opaque			Yes
Secret Key	5	Yes	Opaque			Yes
SMS Security Mode	6	No	Integer	0-255		No
SMS Binding Key Param.	7	No	Opaque	6 B		No
SMS Binding Secret Keys	8	No	Opaque	32-48 B		No
Server SMS Number	9	No	String			No
Short Server ID	10	No	Integer	1-65535		Yes
Client Hold Off Time	11	No	Integer		s	Yes
BS Account Timeout	12	No	Integer		s	Yes

Usage

Pre-shared keys

// assuming buffers psk_id and psk_key containing credential information
// assuming client_data is a valid lwm2m_client_data_t instance
// [...]
 
 // prepare instance arguments
 lwm2m_obj_security_args_t args = {
     .server_id = CONFIG_LWM2M_SERVER_SHORT_ID,
     .server_uri = CONFIG_LWM2M_SERVER_URI,
     .security_mode = LWM2M_SECURITY_MODE_PRE_SHARED_KEY,
     .pub_key_or_id = psk_id,
     .pub_key_or_id_len = sizeof(psk_id) - 1,
     .secret_key = psk_key,
     .secret_key_len = sizeof(psk_key) - 1,
     .is_bootstrap = false,
     .client_hold_off_time = 5,
     .bootstrap_account_timeout = 0
 };
 
 // initialize the security object and get handle
 lwm2m_object_t *sec_obj = lwm2m_object_security_init(&client_data);
 
 // instantiate a new security object with instance ID 1
 int res = lwm2m_object_security_instance_create(&args, 1);

Raw public keys

To use this security mode the following keys are required:

• server public key (SubjectPublicKeyInfo DER encoded, according to RFC5280)
• own public (SubjectPublicKeyInfo DER encoded) and private (as a ECPrivateKey DER encoded sequence, according to RFC5915)keys. See below on how they can be generated.

It is possible that you may need to increase CONFIG_DTLS_HANDSHAKE_BUFSIZE_EXP when using RPK mode.

// assuming buffers rpk_pub, rpk_priv, and server_rpk_pub containing the elliptic curve keys
// assuming client_data is a valid lwm2m_client_data_t instance
// [...]
 
 // prepare instance arguments
 lwm2m_obj_security_args_t args = {
     .server_id = CONFIG_LWM2M_SERVER_SHORT_ID,
     .server_uri = CONFIG_LWM2M_SERVER_URI,
     .security_mode = LWM2M_SECURITY_MODE_RAW_PUBLIC_KEY,
     .pub_key_or_id = rpk_pub,
     .pub_key_or_id_len = sizeof(rpk_pub),
     .secret_key = rpk_priv,
     .secret_key_len = sizeof(rpk_priv),
     .server_pub_key = server_rpk_pub,
     .server_pub_key_len = sizeof(server_rpk_pub),
     .is_bootstrap = false,
     .client_hold_off_time = 5,
     .bootstrap_account_timeout = 0
 };
 
 // initialize the security object and get handle
 lwm2m_object_t *sec_obj = lwm2m_object_security_init(&client_data);
 
 // instantiate a new security object with next available instance ID
 int id = lwm2m_object_security_instance_create(&args, -1);

Generating the keys

The local key pair can be generated using OpenSSL.

1. Generate the key pair using the secp256r1 parameters:

   $ openssl ecparam -name secp256r1 -genkey -outform der -out keys.der

2. Get the public part of the key:

   $ openssl ec -in keys.der -inform DER -outform DER -pubout | xxd -i

3. Get the private part of the key:

   $ openssl ec -in keys.der -inform DER -no_public -outform DER | xxd -i

4. If your server requires your public key as X-Y coordinates you can dump it as text, remove the first byte and split the rest in two equally-sized parts. The first part will be X, the second Y.

   $ openssl ec -in keys.der -inform DER -text
    
   [...]
   pub:
     04:a0:c3:8e:cb:a1:02:eb:5d:25:96:98:bb:60:8e:
     28:19:56:06:96:70:15:9b:54:ff:d9:60:32:c3:3e:
     89:08:ae:3a:33:2f:54:5f:68:a2:ac:d1:b9:df:2b:
     79:65:49:3f:1c:ae:64:7a:32:02:e4:32:8d:6b:22:
     67:83:0d:7c:b2
   ASN1 OID: prime256v1
   NIST CURVE: P-256
   [...]

Following the example above we have:

X : a0c38ecba102eb5d259698bb608e281956069670159b54ffd96032c33e8908ae
Y : 3a332f545f68a2acd1b9df2b7965493f1cae647a3202e4328d6b2267830d7cb2

Topics
	LwM2M Security object compile configurations

Files
file	security.h

Data Structures
struct	lwm2m_obj_security_args
	Arguments for a new Security object instance creation (lwm2m_object_security_instance_create). More...

Typedefs
typedef struct lwm2m_obj_security_args	lwm2m_obj_security_args_t
	Arguments for a new Security object instance creation (lwm2m_object_security_instance_create).

Functions
lwm2m_object_t *	lwm2m_object_security_init (lwm2m_client_data_t *client_data)
	Initialize the Security object.
int	lwm2m_object_security_instance_create (const lwm2m_obj_security_args_t *args, int32_t instance_id)
	Create a new Security instance and add it to the object list.
credman_tag_t	lwm2m_object_security_get_credential (uint16_t instance_id)
	Get the credential of a given instance of the security object.

LwM2M Security object security modes
#define	LWM2M_SECURITY_MODE_PRE_SHARED_KEY   0
	Pre-Shared keys mode.
#define	LWM2M_SECURITY_MODE_RAW_PUBLIC_KEY   1
	Raw public keys mode.
#define	LWM2M_SECURITY_MODE_CERTIFICATE   2
	Certificate mode.
#define	LWM2M_SECURITY_MODE_NONE   3
	No security mode.

Resource IDs for the LWM2M Security Object
#define	LWM2M_SECURITY_URI_ID   0
	Server URI.
#define	LWM2M_SECURITY_BOOTSTRAP_ID   1
	Bootstrap server.
#define	LWM2M_SECURITY_SECURITY_ID   2
	Security mode.
#define	LWM2M_SECURITY_PUBLIC_KEY_ID   3
	Public key or ID.
#define	LWM2M_SECURITY_SERVER_PUBLIC_KEY_ID   4
	Server public key.
#define	LWM2M_SECURITY_SECRET_KEY_ID   5
	Secret key.
#define	LWM2M_SECURITY_SMS_SECURITY_ID   6
	SMS security mode.
#define	LWM2M_SECURITY_SMS_KEY_PARAM_ID   7
	SMS binding key parameters.
#define	LWM2M_SECURITY_SMS_SECRET_KEY_ID   8
	SMS binding secret keys.
#define	LWM2M_SECURITY_SMS_SERVER_NUMBER_ID   9
	Server SMS number.
#define	LWM2M_SECURITY_SHORT_SERVER_ID   10
	Short server ID.
#define	LWM2M_SECURITY_HOLD_OFF_ID   11
	Client hold-off time.
#define	LWM2M_SECURITY_BOOTSTRAP_TIMEOUT_ID   12
	Bootstrap server account timeout.

Macro Definition Documentation

LWM2M_SECURITY_BOOTSTRAP_ID

#define LWM2M_SECURITY_BOOTSTRAP_ID   1

Bootstrap server.

Definition at line 214 of file security.h.

LWM2M_SECURITY_BOOTSTRAP_TIMEOUT_ID

#define LWM2M_SECURITY_BOOTSTRAP_TIMEOUT_ID   12

Bootstrap server account timeout.

Definition at line 269 of file security.h.

LWM2M_SECURITY_HOLD_OFF_ID

#define LWM2M_SECURITY_HOLD_OFF_ID   11

Client hold-off time.

Definition at line 264 of file security.h.

LWM2M_SECURITY_MODE_CERTIFICATE

#define LWM2M_SECURITY_MODE_CERTIFICATE   2

Certificate mode.

Definition at line 194 of file security.h.

LWM2M_SECURITY_MODE_NONE

#define LWM2M_SECURITY_MODE_NONE   3

No security mode.

Definition at line 199 of file security.h.

LWM2M_SECURITY_MODE_PRE_SHARED_KEY

#define LWM2M_SECURITY_MODE_PRE_SHARED_KEY   0

Pre-Shared keys mode.

Definition at line 184 of file security.h.

LWM2M_SECURITY_MODE_RAW_PUBLIC_KEY

#define LWM2M_SECURITY_MODE_RAW_PUBLIC_KEY   1

Raw public keys mode.

Definition at line 189 of file security.h.

LWM2M_SECURITY_PUBLIC_KEY_ID

#define LWM2M_SECURITY_PUBLIC_KEY_ID   3

Public key or ID.

Definition at line 224 of file security.h.

LWM2M_SECURITY_SECRET_KEY_ID

#define LWM2M_SECURITY_SECRET_KEY_ID   5

Secret key.

Definition at line 234 of file security.h.

LWM2M_SECURITY_SECURITY_ID

#define LWM2M_SECURITY_SECURITY_ID   2

Security mode.

Definition at line 219 of file security.h.

LWM2M_SECURITY_SERVER_PUBLIC_KEY_ID

#define LWM2M_SECURITY_SERVER_PUBLIC_KEY_ID   4

Server public key.

Definition at line 229 of file security.h.

LWM2M_SECURITY_SHORT_SERVER_ID

#define LWM2M_SECURITY_SHORT_SERVER_ID   10

Short server ID.

Definition at line 259 of file security.h.

LWM2M_SECURITY_SMS_KEY_PARAM_ID

#define LWM2M_SECURITY_SMS_KEY_PARAM_ID   7

SMS binding key parameters.

Definition at line 244 of file security.h.

LWM2M_SECURITY_SMS_SECRET_KEY_ID

#define LWM2M_SECURITY_SMS_SECRET_KEY_ID   8

SMS binding secret keys.

Definition at line 249 of file security.h.

LWM2M_SECURITY_SMS_SECURITY_ID

#define LWM2M_SECURITY_SMS_SECURITY_ID   6

SMS security mode.

Definition at line 239 of file security.h.

LWM2M_SECURITY_SMS_SERVER_NUMBER_ID

#define LWM2M_SECURITY_SMS_SERVER_NUMBER_ID   9

Server SMS number.

Definition at line 254 of file security.h.

LWM2M_SECURITY_URI_ID

#define LWM2M_SECURITY_URI_ID   0

Server URI.

Definition at line 209 of file security.h.

Function Documentation

lwm2m_object_security_get_credential()

credman_tag_t lwm2m_object_security_get_credential

(

uint16_t

instance_id

)

Get the credential of a given instance of the security object.

Parameters

[in]

instance_id

ID of the instance.

Returns

Credential tag.

Return values

CREDMAN_TAG_EMPTY

when no credential is assigned.

lwm2m_object_security_init()

lwm2m_object_t * lwm2m_object_security_init

(

lwm2m_client_data_t *

client_data

)

Initialize the Security object.

Parameters

[in]

client_data

LwM2M client data.

Returns

Pointer to the Security object on success

lwm2m_object_security_instance_create()

int lwm2m_object_security_instance_create	(	const lwm2m_obj_security_args_t *	args,
		int32_t	instance_id )

Create a new Security instance and add it to the object list.

Parameters

[in]	args	Initialize structure with the parameter for the instance. May not be NULL.
[in]	instance_id	ID for the new instance. It must be between 0 and (UINT16_MAX - 1), if -1 the next available ID will be used.

Returns

Instance ID (> 0) on success

-EINVAL if an invalid instance_id is given

-ENOMEM if no memory is available to create a new instance