IoTivity-Lite
oc_obt.h File Reference

Collection of functions to onboard and provision clients and servers. More...

#include "oc_acl.h"
#include "oc_api.h"
#include "oc_cred.h"
#include "oc_pki.h"
#include "oc_role.h"
#include "oc_uuid.h"

Macros

#define DISCOVERY_CB_PERIOD   (60)
 The amount of time the stack will wait for a response from a discovery request. More...
 

Typedefs

typedef void(* oc_obt_acl_cb_t) (oc_sec_acl_t *acl, void *data)
 Callback containing the Access Control List (ACL) owned by a remote device. More...
 
typedef void(* oc_obt_creds_cb_t) (struct oc_sec_creds_t *creds, void *data)
 Callback containing the credentials owned by a remote device. More...
 
typedef void(* oc_obt_device_status_cb_t) (const oc_uuid_t *uuid, int status, void *data)
 Callback invoked to report the status resulting from many of the onboarding tools actions on a device. More...
 
typedef void(* oc_obt_discovery_cb_t) (const oc_uuid_t *uuid, const oc_endpoint_t *eps, void *data)
 Callback invoked in response to device discovery. More...
 
typedef void(* oc_obt_status_cb_t) (int status, void *data)
 Callback invoked to report the status resulting from many of the onboarding tools actions. More...
 

Functions

void oc_obt_ace_add_permission (oc_sec_ace_t *ace, oc_ace_permissions_t permission)
 Set the access permissions the ACE will grant. More...
 
oc_ace_res_toc_obt_ace_new_resource (oc_sec_ace_t *ace)
 Add an ACE resource (oc_ace_res_t) to the ACE. More...
 
void oc_obt_ace_resource_set_href (oc_ace_res_t *resource, const char *href)
 Set the href on the ACE resource. More...
 
void oc_obt_ace_resource_set_wc (oc_ace_res_t *resource, oc_ace_wildcard_t wc)
 Set the wildcard type on the ACE resource. More...
 
oc_role_t * oc_obt_add_roleid (oc_role_t *roles, const char *role, const char *authority)
 Build a linked list of roles to provision a role certificate. More...
 
int oc_obt_delete_ace_by_aceid (const oc_uuid_t *uuid, int aceid, oc_obt_status_cb_t cb, void *data)
 Remove an Access Control Entry (ACE) from a remote device's Access Control List (ACL) More...
 
int oc_obt_delete_cred_by_credid (const oc_uuid_t *uuid, int credid, oc_obt_status_cb_t cb, void *data)
 Delete a credential identified by its credid off a remote device. More...
 
int oc_obt_delete_own_cred_by_credid (int credid)
 Delete a one of the onboarding tools credentials by credid. More...
 
int oc_obt_device_hard_reset (const oc_uuid_t *uuid, oc_obt_device_status_cb_t cb, void *data)
 RESET the remote device back to the ready for ownership transfer method (RFOTM) state. More...
 
int oc_obt_discover_all_resources (const oc_uuid_t *uuid, oc_discovery_all_handler_t handler, void *data)
 Discover all resources on the device identified by its uuid. More...
 
int oc_obt_discover_owned_devices (oc_obt_discovery_cb_t cb, void *data)
 Discover all devices owned by the onboarding tool. More...
 
int oc_obt_discover_owned_devices_realm_local_ipv6 (oc_obt_discovery_cb_t cb, void *data)
 Discover all devices owned by the onboarding tool using the realm-local address scope. More...
 
int oc_obt_discover_owned_devices_site_local_ipv6 (oc_obt_discovery_cb_t cb, void *data)
 Discover all devices owned by the onboarding tool using the site-local address scope. More...
 
int oc_obt_discover_unowned_devices (oc_obt_discovery_cb_t cb, void *data)
 Discover all unowned devices. More...
 
int oc_obt_discover_unowned_devices_realm_local_ipv6 (oc_obt_discovery_cb_t cb, void *data)
 Discover all unowned devices using the realm-local address scope. More...
 
int oc_obt_discover_unowned_devices_site_local_ipv6 (oc_obt_discovery_cb_t cb, void *data)
 Discover all unowned devices using the site-local address scope. More...
 
void oc_obt_free_ace (oc_sec_ace_t *ace)
 Free the memory associated with the ACE object. More...
 
void oc_obt_free_acl (oc_sec_acl_t *acl)
 Free an Access Control List (ACL) More...
 
void oc_obt_free_creds (oc_sec_creds_t *creds)
 Free a list of credentials. More...
 
void oc_obt_free_roleid (oc_role_t *roles)
 Free the oc_role_t list. More...
 
int oc_obt_init (void)
 Initialize the IoTivity stack so it can be used as an onboarding tool (OBT) More...
 
oc_sec_ace_toc_obt_new_ace_for_connection (oc_ace_connection_type_t conn)
 Create a new Access Control Entry (ACE) with connection type as the subject. More...
 
oc_sec_ace_toc_obt_new_ace_for_role (const char *role, const char *authority)
 Create a new Access Control Entry (ACE) with a role as the subject. More...
 
oc_sec_ace_toc_obt_new_ace_for_subject (const oc_uuid_t *uuid)
 Create a new Access Control Entry (ACE) with device UUID as subject. More...
 
int oc_obt_perform_cert_otm (const oc_uuid_t *uuid, oc_obt_device_status_cb_t cb, void *data)
 Perform ownership transfer method (OTM) using Manufacturer Certificate. More...
 
int oc_obt_perform_just_works_otm (const oc_uuid_t *uuid, oc_obt_device_status_cb_t cb, void *data)
 Perform ownership transfer method (OTM) on the device using Just-Works. More...
 
int oc_obt_perform_random_pin_otm (const oc_uuid_t *uuid, const unsigned char *pin, size_t pin_len, oc_obt_device_status_cb_t cb, void *data)
 Perform ownership transfer method (OTM) using Random PIN based OTM. More...
 
int oc_obt_provision_ace (const oc_uuid_t *subject, oc_sec_ace_t *ace, oc_obt_device_status_cb_t cb, void *data)
 Provision an ACE to a device. More...
 
int oc_obt_provision_auth_wildcard_ace (const oc_uuid_t *subject, oc_obt_device_status_cb_t cb, void *data)
 Provision auth-crypt ACE for the wildcard "*" resource with RW permissions. More...
 
int oc_obt_provision_identity_certificate (const oc_uuid_t *uuid, oc_obt_status_cb_t cb, void *data)
 Provision identity certificates. More...
 
int oc_obt_provision_pairwise_credentials (const oc_uuid_t *uuid1, const oc_uuid_t *uuid2, oc_obt_status_cb_t cb, void *data)
 Provision pairwise 128-bit pre-shared key (PSK) credentials to a Client and Server so they may establish a secure (D)TLS session. More...
 
int oc_obt_provision_role_certificate (oc_role_t *roles, const oc_uuid_t *uuid, oc_obt_status_cb_t cb, void *data)
 Provision a role certificate to a Client application. More...
 
int oc_obt_provision_role_wildcard_ace (const oc_uuid_t *subject, const char *role, const char *authority, oc_obt_device_status_cb_t cb, void *data)
 Provision a role ACE for the wildcard "*" resource with RW permissions. More...
 
int oc_obt_provision_trust_anchor (const char *certificate, size_t certificate_size, const char *subject, const oc_uuid_t *uuid, oc_obt_status_cb_t cb, void *data)
 Provision a trust anchor for an cloud enabled server. More...
 
int oc_obt_request_random_pin (const oc_uuid_t *uuid, oc_obt_device_status_cb_t cb, void *data)
 Ask device being onboarded to produce a random PIN for PIN ownership transfer method (OTM). More...
 
int oc_obt_retrieve_acl (const oc_uuid_t *uuid, oc_obt_acl_cb_t cb, void *data)
 Retrieve an Access Control List (ACL) from a remote device. More...
 
int oc_obt_retrieve_cloud_conf_device (const oc_uuid_t *uuid, const char *url, oc_response_handler_t cb, void *user_data)
 sets the data (POST) for the oic.r.coapcloudconf resource More...
 
int oc_obt_retrieve_creds (const oc_uuid_t *subject, oc_obt_creds_cb_t cb, void *data)
 Retrieve a list of credentials from a remote device owned by the onboarding tool. More...
 
oc_sec_creds_toc_obt_retrieve_own_creds (void)
 Retrieve a list of the onboarding tools own credentials. More...
 
void oc_obt_set_sd_info (const char *name, bool priv)
 sets the secure domain info More...
 
void oc_obt_shutdown (void)
 Free all resources associated with the onboarding tool. More...
 
int oc_obt_update_cloud_conf_device (const oc_uuid_t *uuid, const char *url, const char *at, const char *apn, const char *cis, const char *sid, oc_response_handler_t cb, void *user_data)
 sets the data (POST) for the oic.r.coapcloudconf resource More...
 

Detailed Description

Collection of functions to onboard and provision clients and servers.

This collection of functions is intended to be used by an onboarding tool (OBT)

Macro Definition Documentation

◆ DISCOVERY_CB_PERIOD

#define DISCOVERY_CB_PERIOD   (60)

The amount of time the stack will wait for a response from a discovery request.

Typedef Documentation

◆ oc_obt_acl_cb_t

typedef void(* oc_obt_acl_cb_t) (oc_sec_acl_t *acl, void *data)

Callback containing the Access Control List (ACL) owned by a remote device.

This callback is invoked in response to the oc_obt_retrieve_acl() function. If there was a failure obtaining the ACL, the acl parameter will be NULL.

Parameters
[in]aclA struct containing ACL installed on a remote device
[in]datacontext pointer
See also
oc_obt_retrieve_acl

◆ oc_obt_creds_cb_t

typedef void(* oc_obt_creds_cb_t) (struct oc_sec_creds_t *creds, void *data)

Callback containing the credentials owned by a remote device.

This callback is invoked in response to the oc_obt_retrieve_creds() function. If there was a failure obtaining the credentials the creds parameter will be NULL.

Parameters
[in]credsA struct containing a linked list of oc_sec_cred_t credentials owned by a remote device
[in]datacontext pointer
See also
oc_obt_retrieve_creds

◆ oc_obt_device_status_cb_t

typedef void(* oc_obt_device_status_cb_t) (const oc_uuid_t *uuid, int status, void *data)

Callback invoked to report the status resulting from many of the onboarding tools actions on a device.

Parameters
[in]uuidof the device status is being reported on
[in]statusnumber indicating success or failure of action that invoked this callback. Typically status >= 0 indicates success
[in]datacontext pointer
See also
oc_obt_perform_just_works_otm
oc_obt_request_random_pin
oc_obt_perform_random_pin_otm
oc_obt_perform_cert_otm
oc_obt_device_hard_reset
oc_obt_provition_ace
oc_obt_provision_role_wilecard_ace
oc_obt_provision_auth_wildcard_ace

◆ oc_obt_discovery_cb_t

typedef void(* oc_obt_discovery_cb_t) (const oc_uuid_t *uuid, const oc_endpoint_t *eps, void *data)

Callback invoked in response to device discovery.

Example:

static void
get_device(oc_client_response_t *data)
{
oc_rep_t *rep = data->payload;
char *di = NULL, *n = NULL;
size_t di_len = 0, n_len = 0;
if (oc_rep_get_string(rep, "di", &di, &di_len)) {
printf("Device id: %s\n", di);
}
if (oc_rep_get_string(rep, "n", &n, &n_len)) {
printf("Device name: %s\n", n);
}
}
static void
unowned_device_cb(const oc_uuid_t *uuid, oc_endpoint_t *eps, void *data)
{
(void)data;
char di[OC_UUID_LEN];
oc_endpoint_t *ep = eps;
printf("\nDiscovered unowned device: %s at:\n", di);
while (eps != NULL) {
OC_PRINTipaddr(*eps);
printf("\n");
eps = eps->next;
}
oc_do_get("/oic/d", ep, NULL, &get_device, HIGH_QOS, NULL);
}
oc_obt_discover_unowned_devices(unowned_device_cb, NULL);
bool oc_do_get(const char *uri, const oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, void *user_data)
Issue a GET request to obtain the current value of all properties a resource.
@ HIGH_QOS
confirmable messages
Definition: oc_client_state.h:50
int oc_obt_discover_unowned_devices(oc_obt_discovery_cb_t cb, void *data)
Discover all unowned devices.
bool oc_rep_get_string(const oc_rep_t *rep, const char *key, char **value, size_t *size)
Read a text string value from an oc_rep_t
#define OC_UUID_LEN
The length of a UUID string.
Definition: oc_uuid.h:46
void oc_uuid_to_str(const oc_uuid_t *uuid, char *buffer, size_t buflen)
Convert the 128 bit oc_uuid_t to a string representation.
Client response information.
Definition: oc_client_state.h:59
oc_rep_t * payload
response payload, interpreted as cbor
Definition: oc_client_state.h:60
the endpoint information
Definition: oc_endpoint.h:91
struct oc_endpoint_t * next
pointer to the next structure
Definition: oc_endpoint.h:92
Parameters
[in]uuidthe uuid of the discovered device
[in]epslist of endpoints that can be used to connect with the discovered device
[in]datacontext pointer
See also
oc_obt_discover_unowned_devices
oc_obt_discover_unowned_devices_realm_local_ipv6
oc_obt_discover_unowned_devices_site_local_ipv6
oc_obt_discover_owned_devices
oc_obt_discover_owned_devices_realm_local_ipv6
oc_obt_discover_owned_devices_site_local_ipv6

◆ oc_obt_status_cb_t

typedef void(* oc_obt_status_cb_t) (int status, void *data)

Callback invoked to report the status resulting from many of the onboarding tools actions.

Parameters
[in]statusnumber indicating success or failure of action that invoked this callback. Typically status >= 0 indicates success
[in]datacontext pointer
See also
oc_obt_provision_pairwise_credentials
oc_obt_provision_identity_certificate
oc_obt_provision_role_certificate
oc_obt_delete_cred_by_credid
oc_obt_delete_ace_by_aceid

Function Documentation

◆ oc_obt_ace_add_permission()

void oc_obt_ace_add_permission ( oc_sec_ace_t ace,
oc_ace_permissions_t  permission 
)

Set the access permissions the ACE will grant.

The function oc_obt_ace_add_permission can be called multiple times to add additional permissions.

calling:

@ OC_PERM_RETRIEVE
Read, observe, discover permission is granted.
Definition: oc_enums.h:243
@ OC_PERM_UPDATE
Write, update permission is granted.
Definition: oc_enums.h:245
@ OC_PERM_NOTIFY
Notify permission is granted.
Definition: oc_enums.h:247
void oc_obt_ace_add_permission(oc_sec_ace_t *ace, oc_ace_permissions_t permission)
Set the access permissions the ACE will grant.

will set the same permissions as calling:

The possible values for the oc_ace_permissions_t bitmask are:

  • OC_PERM_NONE : no permissions. Never expected to show up in an ACE entry
  • OC_PERM_CREATE : permission to add a new resource to the client or server
  • OC_PERM_RETRIEVE : permission to read the properties of a resource
  • OC_PERM_UPDATE : permission to update the writable properties of a resource
  • OC_PERM_DELETE : permission to delete a resource on the client or server
  • OC_PERM_NOTIFY : permission to see notifications sent by the client or server
Parameters
[in,out]acethe ACE the permissions are being added to
[in]permissionthe permissions granted to the ace
See also
oc_obt_new_ace_for_subject
oc_obt_new_ace_for_connection
oc_obt_new_ace_for_role
oc_obt_provision_ace

◆ oc_obt_ace_new_resource()

oc_ace_res_t* oc_obt_ace_new_resource ( oc_sec_ace_t ace)

Add an ACE resource (oc_ace_res_t) to the ACE.

Parameters
[in,out]acethe ACE that the ACE resource will be added to
Returns
  • A new oc_ace_res_t
  • NULL if unable to allocate a new ACE resource
See also
oc_obt_new_ace_for_subject
oc_obt_new_ace_for_connection
oc_obt_new_ace_for_role
oc_obt_ace_resource_set_href
oc_obt_ace_resource_set_wc

◆ oc_obt_ace_resource_set_href()

void oc_obt_ace_resource_set_href ( oc_ace_res_t resource,
const char *  href 
)

Set the href on the ACE resource.

Parameters
[in,out]resourcethe ACE resource that the href URL will be added to
[in]hrefthe URL being added to the ACE resource

◆ oc_obt_ace_resource_set_wc()

void oc_obt_ace_resource_set_wc ( oc_ace_res_t resource,
oc_ace_wildcard_t  wc 
)

Set the wildcard type on the ACE resource.

Provisioning of Device Configuration Resources (DCRs) are not affected by the wildcard ACE. Only Non-Configuration Resources (NCRs) are affected by the wildcard resource.

The following resources are DCRs

  • A Discovery Core Resource
  • A Security Virtual Resource
  • A Wi-Fi Easy Setup Resource (oic.r.easysetup, oic.r.wificonf, oic.r.devconf)
  • A Software Update Resource (oic.r.softwareupdate)
  • A Maintenance Resource (oic.r.wk.mnt)

The possible values for oc_ace_wildcard_t are:

  • OC_ACE_NO_WC : no wildcard
  • OC_ACE_WC_ALL : all NCRs "*"
  • OC_ACE_WC_ALL_SECURED : all NCRs that are secure "+"
  • OC_ACE_WC_ALL_PUBLIC : all NCRs that are not secure "-"
Parameters
[in,out]resourcethe ACE resource to set the wildcard value on
[in]wcthe wildcard value

◆ oc_obt_add_roleid()

oc_role_t* oc_obt_add_roleid ( oc_role_t *  roles,
const char *  role,
const char *  authority 
)

Build a linked list of roles to provision a role certificate.

This function will add a single role (role name and authroity) to a list of rules. If the provided list of roles is empty, it will create a new list with the added role.

Example:

oc_role_t *roles = NULL;
roles = oc_obt_add_roleid(roles, "admin", NULL);
roles = oc_obt_add_roleid(roles, "user", NULL);
oc_role_t * oc_obt_add_roleid(oc_role_t *roles, const char *role, const char *authority)
Build a linked list of roles to provision a role certificate.
Parameters
[in]roleshead of the oc_role_t linked list. NULL if the list has not yet been created
[in]rolethe role for the role id
[in]authoritythe role authority for the role id. The role authority is optional if no authority is provided pass in NULL
Returns
The new head of the oc_role_t list of roles

◆ oc_obt_delete_ace_by_aceid()

int oc_obt_delete_ace_by_aceid ( const oc_uuid_t *  uuid,
int  aceid,
oc_obt_status_cb_t  cb,
void *  data 
)

Remove an Access Control Entry (ACE) from a remote device's Access Control List (ACL)

Parameters
[in]uuidthe uuid of the remote device
[in]aceidthe id of the Access Control Entry
[in]cbcallback invoked to indicate the success or failure of the ACE delete request
[in]datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_delete_cred_by_credid()

int oc_obt_delete_cred_by_credid ( const oc_uuid_t *  uuid,
int  credid,
oc_obt_status_cb_t  cb,
void *  data 
)

Delete a credential identified by its credid off a remote device.

Parameters
[in]uuidthe uuid of the device the credential is being deleted from
[in]credidthe credid of the credential being deleted
[in]cbcallback invoked to indicate the success or failure of the oc_obt_delete_cred_by_credid call
[in]datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_delete_own_cred_by_credid()

int oc_obt_delete_own_cred_by_credid ( int  credid)

Delete a one of the onboarding tools credentials by credid.

Parameters
[in]credidnumber identifying the credential to delete
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_device_hard_reset()

int oc_obt_device_hard_reset ( const oc_uuid_t *  uuid,
oc_obt_device_status_cb_t  cb,
void *  data 
)

RESET the remote device back to the ready for ownership transfer method (RFOTM) state.

Example:

static void
reset_device_cb(const oc_uuid_t *uuid, int status, void *data)
{
char di[OC_UUID_LEN];
if (status >= 0) {
printf("Successfully performed hard RESET to device %s\n", di);
} else {
printf("ERROR performing hard RESET to device %s\n", di);
}
}
int ret = oc_obt_device_hard_reset(uuid, reset_device_cb, NULL);
if (ret >= 0) {
printf("Successfully issued request to perform hard RESET\n");
} else {
printf("ERROR issuing request to perform hard RESET\n");
}
int oc_obt_device_hard_reset(const oc_uuid_t *uuid, oc_obt_device_status_cb_t cb, void *data)
RESET the remote device back to the ready for ownership transfer method (RFOTM) state.
Parameters
[in]uuidthe device being reset
[in]cbcallback invoked to indicate the success or failure of the hard reset action
[in]datacontext pointer that is passed to the oc_obt_device_status_cb_t. The pointer must remain valid till the end of the oc_obt_device_status_cb_t function
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_discover_all_resources()

int oc_obt_discover_all_resources ( const oc_uuid_t *  uuid,
oc_discovery_all_handler_t  handler,
void *  data 
)

Discover all resources on the device identified by its uuid.

Parameters
[in]uuidthe uuid of the device the resources are being discovered on
[in]handlerthe oc_discovery_all_handler_t invoked in responce to this discovery request
[in]datacontext pointer that is passed to the oc_discovery_all_handler_t callback function. The pointer must remain valid till the more parameter of the oc_discovery_all_handler_t invoked in response to this discover request is false.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_discover_owned_devices()

int oc_obt_discover_owned_devices ( oc_obt_discovery_cb_t  cb,
void *  data 
)

Discover all devices owned by the onboarding tool.

The discovery request will make a muli-cast request to the IPv6 link-local multicast address scope and over IPv4.

Multicast discovery over IPv4 will only happen if the stack is built with the OC_IPV4 build flag.

Read RFC4291 and RFC7346 for more information about IPv6 Reference Scopes.

Parameters
[in]cbthe oc_obt_discovery_cb_t that will be called for each discovered device
[in]datacontext pointer that is passed to the oc_obt_discovery_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. The context pointer must be valid for DISCOVERY_CB_PERIOD seconds after oc_obt_discover_unowned_devices returns.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_discover_owned_devices_realm_local_ipv6()

int oc_obt_discover_owned_devices_realm_local_ipv6 ( oc_obt_discovery_cb_t  cb,
void *  data 
)

Discover all devices owned by the onboarding tool using the realm-local address scope.

The discovery request will make a muli-cast request to the IPv6 realm-local multicast address scope. The address scope is the domain in which the multicast discovery packet should be propagated.

Read RFC4291 and RFC7346 for more information about IPv6 Reference Scopes.

Parameters
[in]cbthe oc_obt_discovery_cb_t that will be called for each discovered device
[in]datacontext pointer that is passed to the oc_obt_discovery_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. The context pointer must be valid for DISCOVERY_CB_PERIOD seconds after oc_obt_discover_unowned_devices returns.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_discover_owned_devices_site_local_ipv6()

int oc_obt_discover_owned_devices_site_local_ipv6 ( oc_obt_discovery_cb_t  cb,
void *  data 
)

Discover all devices owned by the onboarding tool using the site-local address scope.

The discovery request will make a muli-cast request to the IPv6 site-local multicast address scope. The address scope is the domain in which the multicast discovery packet should be propagated.

Read RFC4291 and RFC7346 for more information about IPv6 Reference Scopes.

Parameters
[in]cbthe oc_obt_discovery_cb_t that will be called for each discovered device
[in]datacontext pointer that is passed to the oc_obt_discovery_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. The context pointer must be valid for DISCOVERY_CB_PERIOD seconds after oc_obt_discover_unowned_devices returns.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_discover_unowned_devices()

int oc_obt_discover_unowned_devices ( oc_obt_discovery_cb_t  cb,
void *  data 
)

Discover all unowned devices.

The discovery request will make a muli-cast request to the IPv6 link-local multicast address scope and over IPv4.

Multicast discovery over IPv4 will only happen if the stack is built with the OC_IPV4 build flag.

Read RFC4291 and RFC7346 for more information about IPv6 Reference Scopes.

Parameters
[in]cbthe oc_obt_discovery_cb_t that will be called for each discovered device
[in]datacontext pointer that is passed to the oc_obt_discovery_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. The context pointer must be valid for DISCOVERY_CB_PERIOD seconds after the oc_obt_discover_unowned_devices function returns.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_discover_unowned_devices_realm_local_ipv6()

int oc_obt_discover_unowned_devices_realm_local_ipv6 ( oc_obt_discovery_cb_t  cb,
void *  data 
)

Discover all unowned devices using the realm-local address scope.

The discovery request will make a muli-cast request to the IPv6 realm-local multicast address scope. The address scope is the domain in which the multicast discovery packet should be propagated.

Read RFC4291 and RFC7346 for more information about IPv6 Reference Scopes.

Parameters
[in]cbthe oc_obt_discovery_cb_t that will be called for each discovered device
[in]datacontext pointer that is passed to the oc_obt_discovery_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. The context pointer must be valid for DISCOVERY_CB_PERIOD seconds after oc_obt_discover_unowned_devices returns.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_discover_unowned_devices_site_local_ipv6()

int oc_obt_discover_unowned_devices_site_local_ipv6 ( oc_obt_discovery_cb_t  cb,
void *  data 
)

Discover all unowned devices using the site-local address scope.

The discovery request will make a muli-cast request to the IPv6 site-local multicast address scope. The address scope is the domain in which the multicast discovery packet should be propagated.

Read RFC4291 and RFC7346 for more information about IPv6 Reference Scopes.

Parameters
[in]cbthe oc_obt_discovery_cb_t that will be called for each discovered device
[in]datacontext pointer that is passed to the oc_obt_discovery_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. The context pointer must be valid for DISCOVERY_CB_PERIOD seconds after oc_obt_discover_unowned_devices returns.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_free_ace()

void oc_obt_free_ace ( oc_sec_ace_t ace)

Free the memory associated with the ACE object.

Parameters
acethe ACE that will be freed

◆ oc_obt_free_acl()

void oc_obt_free_acl ( oc_sec_acl_t acl)

Free an Access Control List (ACL)

This will free all Access Control Entries (ACE) in the ACL as well as the ACL itself

Parameters
aclpointer to the head of an ACL

◆ oc_obt_free_creds()

void oc_obt_free_creds ( oc_sec_creds_t creds)

Free a list of credentials.

Parameters
credsthe list of credentials to free

◆ oc_obt_free_roleid()

void oc_obt_free_roleid ( oc_role_t *  roles)

Free the oc_role_t list.

Parameters
rolesthe head of the oc_role_t list

◆ oc_obt_init()

int oc_obt_init ( void  )

Initialize the IoTivity stack so it can be used as an onboarding tool (OBT)

Call once at startup for OBT initialization

Persistent storage must be initialized before calling oc_obt_init()

example:

static int
app_init(void)
{
int ret = oc_init_platform("OCF", NULL, NULL);
ret |= oc_add_device("/oic/d", "oic.d.dots", "OBT", "ocf.2.0.5",
"ocf.res.1.0.0,ocf.sh.1.0.0", NULL, NULL);
return ret;
}
static void
issue_requests(void)
{
}
static void
signal_event_loop(void)
{
// code not shown
}
static const oc_handler_t handler = { .init = app_init,
.signal_event_loop = signal_event_loop,
.requests_entry = issue_requests };
#ifdef OC_STORAGE
oc_storage_config("./onboarding_tool_creds");
#endif // OC_STORAGE
if (oc_main_init(&handler) < 0)
return init;
void oc_device_bind_resource_type(size_t device, const char *type)
Add a Resource Type "rt" property to the an /oic/d resource.
int oc_add_device(const char *uri, const char *rt, const char *name, const char *spec_version, const char *data_model_version, oc_add_device_cb_t add_device_cb, void *data)
Add an ocf device to the the stack.
int oc_init_platform(const char *mfg_name, oc_init_platform_cb_t init_platform_cb, void *data)
Initialize the platform.
int oc_main_init(const oc_handler_t *handler)
Register and call handler functions responsible for controlling the IoTivity-lite stack.
int oc_obt_init(void)
Initialize the IoTivity stack so it can be used as an onboarding tool (OBT)
int oc_storage_config(const char *store)
open the storage
Call back handlers that are invoked in response to oc_main_init()
Definition: oc_api.h:66
int(* init)(void)
Device initialization callback that is invoked to initialize the platform and device(s).
Definition: oc_api.h:96
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_new_ace_for_connection()

oc_sec_ace_t* oc_obt_new_ace_for_connection ( oc_ace_connection_type_t  conn)

Create a new Access Control Entry (ACE) with connection type as the subject.

Parameters
[in]connthe connection type for the ACE
Returns
  • A new oc_sec_ace_t with an OC_SUBJECT_CONN subject_type and the conn property set to the provided connection type
  • NULL if unable to allocate a new oc_sec_ace_t
See also
oc_obt_new_ace_for_subject
oc_obt_new_ace_for_role
oc_obt_ace_add_permission
oc_obt_provision_ace

◆ oc_obt_new_ace_for_role()

oc_sec_ace_t* oc_obt_new_ace_for_role ( const char *  role,
const char *  authority 
)

Create a new Access Control Entry (ACE) with a role as the subject.

Parameters
[in]rolethe role associated with the ACE
[in]authoritythe role authority for the ACE. The role authority is optional if no authority is provided pass in NULL
Returns
  • A new oc_sec_ace_t with an OC_SUBJECT_ROLE subject_type and the role property set to the provided role and authority
  • NULL if unable to allocate a new oc_sec_ace_t
See also
oc_obt_new_ace_for_subject
oc_obt_new_ace_for_connection
oc_obt_ace_add_permission
oc_obt_provision_ace

◆ oc_obt_new_ace_for_subject()

oc_sec_ace_t* oc_obt_new_ace_for_subject ( const oc_uuid_t *  uuid)

Create a new Access Control Entry (ACE) with device UUID as subject.

Parameters
[in]uuidthe uuid of the device
Returns
  • A pointer to a new oc_sec_ace_t with an OC_SUBJECT_UUID subject_type and the subject id will be set to the passed in device uuid
  • NULL if unable to allocate a new oc_sec_ace_t
See also
oc_obt_new_ace_for_connection
oc_obt_new_ace_for_role
oc_obt_ace_add_permission
oc_obt_provision_ace

◆ oc_obt_perform_cert_otm()

int oc_obt_perform_cert_otm ( const oc_uuid_t *  uuid,
oc_obt_device_status_cb_t  cb,
void *  data 
)

Perform ownership transfer method (OTM) using Manufacturer Certificate.

The manufacturer certificate-based OTM uses a certificate embedded into the device by the manufacturer to perform the OTM.

Parameters
[in]uuidthe device to certificate based OTM is being done on
[in]cbcallback invoked to indicate the success or failure of the Manufacturer Certificate Based OTM
[in]datacontext pointer that is passed to the oc_obt_device_status_cb_t. The pointer must remain valid till the end of the oc_obt_device_status_cb_t function
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_perform_just_works_otm()

int oc_obt_perform_just_works_otm ( const oc_uuid_t *  uuid,
oc_obt_device_status_cb_t  cb,
void *  data 
)

Perform ownership transfer method (OTM) on the device using Just-Works.

Just-Works OTM creates a symmetric key credential that is a pre-shared key used to establish a secure connection.

OTM using this method is subject to a man-in-the-middle attacker. This method assumes onboarding happens in a relatively safe environment absent of an attack device.

Example:

static void
otm_just_works_cb(const oc_uuid_t *uuid, int status, void *data)
{
char di[OC_UUID_LEN];
if (status >= 0) {
printf("Successfully performed OTM on device with UUID %s\n", di);
} else {
printf("ERROR performing ownership transfer on device %s\n", di);
}
}
int ret = oc_obt_perform_just_works_otm(uuid, otm_just_works_cb, NULL);
if (ret >= 0) {
printf("Successfully issued request to perform ownership transfer\n");
} else {
printf("ERROR issuing request to perform ownership transfer\n");
}
int oc_obt_perform_just_works_otm(const oc_uuid_t *uuid, oc_obt_device_status_cb_t cb, void *data)
Perform ownership transfer method (OTM) on the device using Just-Works.
Parameters
[in]uuidthe uuid of the device the OTM is being run on. The uuid is typically obtained in response to an oc_obt_discover_unowned_devices* call.
[in]cbcallback invoked to indicate the success or failure of the OTM
[in]datacontext pointer that is passed to the oc_obt_device_status_cb_t. The pointer must remain valid till the end of the oc_obt_device_status_cb_t function.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_perform_random_pin_otm()

int oc_obt_perform_random_pin_otm ( const oc_uuid_t *  uuid,
const unsigned char *  pin,
size_t  pin_len,
oc_obt_device_status_cb_t  cb,
void *  data 
)

Perform ownership transfer method (OTM) using Random PIN based OTM.

Since the Random PIN establishes physical proximity between the new device and the onboarding tool (OBT) it helps prevent man-in-the-middle attacks.

Example:

static void
otm_rdp_cb(const oc_uuid_t *uuid, int status, void *data)
{
char di[OC_UUID_LEN];
if (status >= 0) {
printf("Successfully performed OTM on device %s\n", di);
} else {
printf("ERROR performing ownership transfer on device %s\n", di);
}
}
static void
random_pin_cb(const oc_uuid_t *uuid, int status, void *data)
{
char di[OC_UUID_LEN];
if (status >= 0) {
printf("Successfully requested device %s to generate a Random PIN\n",
di);
printf("Enter Random PIN: ");
unsigned char pin[24];
if ("%10s", pin) <= 0) {
printf("Error Invalid input\n");
}
size_t pin_len = strlen((const char *)pin);
int ret = oc_obt_perform_random_pin_otm(uuid, pin, pin_len, otm_rdp_cb,
NULL);
if (ret >= 0) {
printf("Successfully issued request to perform Random PIN OTM\n");
} else {
printf("ERROR issuing request to perform Random PIN OTM\n");
}
} else {
printf("ERROR requesting device %s to generate a Random PIN\n", di);
}
}
int ret = oc_obt_request_random_pin(uuid, random_pin_cb, NULL);
if (ret >= 0) {
printf("Successfully issued request to generate a random PIN\n");
} else {
printf("ERROR issuing request to generate random PIN\n");
}
int oc_obt_perform_random_pin_otm(const oc_uuid_t *uuid, const unsigned char *pin, size_t pin_len, oc_obt_device_status_cb_t cb, void *data)
Perform ownership transfer method (OTM) using Random PIN based OTM.
int oc_obt_request_random_pin(const oc_uuid_t *uuid, oc_obt_device_status_cb_t cb, void *data)
Ask device being onboarded to produce a random PIN for PIN ownership transfer method (OTM).
Parameters
[in]uuidthe device the Random PIN based OTM is being done on
[in]pinthe PIN obtained from the remote device in response to the oc_obt_request_random_pin
[in]pin_lenthe length of the PIN
[in]cbcallback invoked to indicate the success or failure of the Random PIN OTM operation
[in]datacontext pointer that is passed to the oc_obt_device_status_cb_t. The pointer must remain valid till the end of the oc_obt_device_status_cb_t function
Returns
  • 0 on success
  • -1 on failure
See also
oc_obt_request_random_pin
oc_obt_device_status_cb_t
oc_set_random_pin_callback
oc_random_pin_cb_t

◆ oc_obt_provision_ace()

int oc_obt_provision_ace ( const oc_uuid_t *  subject,
oc_sec_ace_t ace,
oc_obt_device_status_cb_t  cb,
void *  data 
)

Provision an ACE to a device.

Example:

static void
provision_ace2_cb(const oc_uuid_t *uuid, int status, void *data)
{
char di[OC_UUID_LEN];
if (status >= 0) {
printf("Successfully provisioned ACE to device %s\n", di);
} else {
printf("ERROR provisioning ACE to device %s\n", di);
}
}
oc_sec_ace_t *ace = NULL;
if (!res) {
printf("ERROR: Could not allocate new resource for ACE\n");
return;
}
int ret = oc_obt_provision_ace(uuid, ace, provision_ace2_cb, NULL);
if (ret >= 0) {
printf("Successfully issued request to provision ACE\n");
} else {
printf("ERROR issuing request to provision ACE\n");
}
@ OC_ACE_WC_ALL
all
Definition: oc_acl.h:61
@ OC_CONN_AUTH_CRYPT
auth-crypt, authenticated and encrypted
Definition: oc_acl.h:51
oc_sec_ace_t * oc_obt_new_ace_for_connection(oc_ace_connection_type_t conn)
Create a new Access Control Entry (ACE) with connection type as the subject.
void oc_obt_free_ace(oc_sec_ace_t *ace)
Free the memory associated with the ACE object.
void oc_obt_ace_resource_set_wc(oc_ace_res_t *resource, oc_ace_wildcard_t wc)
Set the wildcard type on the ACE resource.
oc_ace_res_t * oc_obt_ace_new_resource(oc_sec_ace_t *ace)
Add an ACE resource (oc_ace_res_t) to the ACE.
int oc_obt_provision_ace(const oc_uuid_t *subject, oc_sec_ace_t *ace, oc_obt_device_status_cb_t cb, void *data)
Provision an ACE to a device.
ACE resource information.
Definition: oc_acl.h:82
Security ACE information.
Definition: oc_acl.h:109
Parameters
[in]subjectthe uuid of the device being provisioned
[in]acethe ACE being added to the subject
[in]cbcallback invoked to indicate the success or failure of the provisioning
[in]datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_provision_auth_wildcard_ace()

int oc_obt_provision_auth_wildcard_ace ( const oc_uuid_t *  subject,
oc_obt_device_status_cb_t  cb,
void *  data 
)

Provision auth-crypt ACE for the wildcard "*" resource with RW permissions.

This is a helper function to quickly provision an ACE for wildcard access over secure connections.

Parameters
[in]subjectthe uuid or the device being provisioned
[in]cbcallback invoked to indicate the success or failure of the provisioning
[in]datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure
See also
oc_obt_new_ace_for_connection
oc_obt_ace_new_resource
oc_obt_ace_resource_set_wc
oc_obt_ace_add_permission
oc_obt_provision_ace

◆ oc_obt_provision_identity_certificate()

int oc_obt_provision_identity_certificate ( const oc_uuid_t *  uuid,
oc_obt_status_cb_t  cb,
void *  data 
)

Provision identity certificates.

To provision identity certificates the IoTivity stack must be built with OC_PKI defined.

Example:

static void
provision_id_cert_cb(int status, void *data)
{
if (status >= 0) {
printf("Successfully provisioned identity certificate\n");
} else {
printf("ERROR provisioning identity certificate\n");
}
}
int ret = oc_obt_provision_identity_certificate(uuid, provision_id_cert_cb,
NULL);
if (ret >= 0) {
printf("Successfully issued request to provision identity certificate\n");
} else {
printf("ERROR issuing request to provision identity certificate\n");
}
int oc_obt_provision_identity_certificate(const oc_uuid_t *uuid, oc_obt_status_cb_t cb, void *data)
Provision identity certificates.
Parameters
[in]uuidthe uuid of the device to provision
[in]cbcallback invoked to indicate the success or failure of the provisioning
[in]datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_provision_pairwise_credentials()

int oc_obt_provision_pairwise_credentials ( const oc_uuid_t *  uuid1,
const oc_uuid_t *  uuid2,
oc_obt_status_cb_t  cb,
void *  data 
)

Provision pairwise 128-bit pre-shared key (PSK) credentials to a Client and Server so they may establish a secure (D)TLS session.

Example:

static void
provision_credentials_cb(int status, void *data)
{
if (status >= 0) {
printf("Successfully provisioned pairwise credentials\n");
} else {
printf("ERROR provisioning pairwise credentials\n");
}
}
provision_credentials_cb, NULL);
if (ret >= 0) {
printf("Successfully issued request to provision credentials\n");
} else {
printf("ERROR issuing request to provision credentials\n");
}
int oc_obt_provision_pairwise_credentials(const oc_uuid_t *uuid1, const oc_uuid_t *uuid2, oc_obt_status_cb_t cb, void *data)
Provision pairwise 128-bit pre-shared key (PSK) credentials to a Client and Server so they may establ...
Parameters
[in]uuid1uuid of the first device to pair
[in]uuid2uuid of the second device to pair
[in]cbcallback invoked to indicate the success or failure of the pairwise credentials provisioning
[in]datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_provision_role_certificate()

int oc_obt_provision_role_certificate ( oc_role_t *  roles,
const oc_uuid_t *  uuid,
oc_obt_status_cb_t  cb,
void *  data 
)

Provision a role certificate to a Client application.

Example:

static void
provision_role_cert_cb(int status, void *data)
{
if (status >= 0) {
printf("Successfully provisioned role certificate\n");
} else {
printf("ERROR provisioning role certificate\n");
}
}
oc_role_t *roles = NULL;
char *role = "admin";
roles = oc_obt_add_roleid(roles, role, NULL);
int ret = oc_obt_provision_role_certificate(roles, uuid,
provision_role_cert_cb, NULL);
if (ret >= 0) {
printf("\nSuccessfully issued request to provision role certificate\n");
} else {
printf("ERROR issuing request to provision role certificate\n");
}
int oc_obt_provision_role_certificate(oc_role_t *roles, const oc_uuid_t *uuid, oc_obt_status_cb_t cb, void *data)
Provision a role certificate to a Client application.
Parameters
rolesthe role(s) to provision
uuidthe uuid of the device to provision
cbcallback invoked to indicate the success or failure of the provisioning
datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure
See also
oc_obt_status_cb_t
oc_obt_add_roleid
oc_obt_free_roleid

◆ oc_obt_provision_role_wildcard_ace()

int oc_obt_provision_role_wildcard_ace ( const oc_uuid_t *  subject,
const char *  role,
const char *  authority,
oc_obt_device_status_cb_t  cb,
void *  data 
)

Provision a role ACE for the wildcard "*" resource with RW permissions.

This is a helper function to quickly provision a role ACE for wildcard access.

Parameters
[in]subjectthe uuid or the device being provisioned
[in]rolethe role for the ACE
[in]authoritythe role authority for the ACE. The role authority is optional if no authority is provided pass in NULL
[in]cbcallback invoked to indicate the success or failure of the provisioning
[in]datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure
See also
oc_obt_new_ace_for_role
oc_obt_ace_new_resource
oc_obt_ace_resource_set_wc
oc_obt_ace_add_permission
oc_obt_provision_ace

◆ oc_obt_provision_trust_anchor()

int oc_obt_provision_trust_anchor ( const char *  certificate,
size_t  certificate_size,
const char *  subject,
const oc_uuid_t *  uuid,
oc_obt_status_cb_t  cb,
void *  data 
)

Provision a trust anchor for an cloud enabled server.

Parameters
certificatethe certificate data
certificate_sizethe certificate data size
subjectid (the uuid of the cloud)
uuidthe uuid of the device to provision
cbcallback invoked to indicate the success or failure of the provisioning
datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure
See also
oc_obt_status_cb_t
oc_obt_add_roleid
oc_obt_free_roleid

◆ oc_obt_request_random_pin()

int oc_obt_request_random_pin ( const oc_uuid_t *  uuid,
oc_obt_device_status_cb_t  cb,
void *  data 
)

Ask device being onboarded to produce a random PIN for PIN ownership transfer method (OTM).

This will cause the oc_random_pin_cb_t to be invoked on the remote device. The remote device is expected to generate and communicate a random PIN using an Out-of-Band communication channel. For example display the pin on a screen that the user can read. The Out-of-band communication is an implementation detail that is left up to the developer.

The Random PIN establishes physical proximity between the new device and the onboarding tool (OBT).

◆ oc_obt_retrieve_acl()

int oc_obt_retrieve_acl ( const oc_uuid_t *  uuid,
oc_obt_acl_cb_t  cb,
void *  data 
)

Retrieve an Access Control List (ACL) from a remote device.

Parameters
[in]uuidthe uuid of the remote device
[in]cbcallback that will deliver the requested ACL
[in]datacontext pointer that is passed to the oc_obt_acl_cb_t. The pointer must remain valid till after the oc_obt_acl_cb_t has completed.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_retrieve_cloud_conf_device()

int oc_obt_retrieve_cloud_conf_device ( const oc_uuid_t *  uuid,
const char *  url,
oc_response_handler_t  cb,
void *  user_data 
)

sets the data (POST) for the oic.r.coapcloudconf resource

Parameters
[in]uuidthe uuid of the remote device
[in]urlof the resource
[in]cbcallback invoked to indicate the success or failure of the request
[in]user_datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_retrieve_creds()

int oc_obt_retrieve_creds ( const oc_uuid_t *  subject,
oc_obt_creds_cb_t  cb,
void *  data 
)

Retrieve a list of credentials from a remote device owned by the onboarding tool.

Parameters
[in]subjectuuid of the device the credentials will be fetched from
[in]cbcallback that will contain the list of credentials from the remote device
[in]datacontext pointer that is passed to the oc_obt_creds_cb_t. The pointer must remain valid till after the oc_obt_creds_cb_t has completed.
Returns
  • 0 on success
  • -1 on failure

◆ oc_obt_retrieve_own_creds()

oc_sec_creds_t* oc_obt_retrieve_own_creds ( void  )

Retrieve a list of the onboarding tools own credentials.

The credentials returned by oc_obt_retrieve_own_creds() point to an internal data structures that store the security context of the OBT. DO NOT free them. Use oc_obt_delete_own_cred_by_credid() to remove credentials from the OBT.

Returns
A struct containing the onboarding tools uuid and a linked list of oc_sec_cred_t credentials owned by the onboarding tool.

◆ oc_obt_set_sd_info()

void oc_obt_set_sd_info ( const char *  name,
bool  priv 
)

sets the secure domain info

Parameters
[in]namethe name of the secure domain
[in]privprivacy indicator

◆ oc_obt_shutdown()

void oc_obt_shutdown ( void  )

Free all resources associated with the onboarding tool.

Called when the OBT terminates.

◆ oc_obt_update_cloud_conf_device()

int oc_obt_update_cloud_conf_device ( const oc_uuid_t *  uuid,
const char *  url,
const char *  at,
const char *  apn,
const char *  cis,
const char *  sid,
oc_response_handler_t  cb,
void *  user_data 
)

sets the data (POST) for the oic.r.coapcloudconf resource

Parameters
[in]uuidthe uuid of the remote device
[in]urlof the resource
[in]atAccess Token
[in]apnAuth Provider Name
[in]cisOCF Cloud interface URL
[in]sidOCF Cloud UUID
[in]cbcallback invoked to indicate the success or failure of the request
[in]user_datacontext pointer that is passed to the oc_obt_status_cb_t. The pointer must remain valid till the end of the oc_obt_status_cb_t function
Returns
  • 0 on success
  • -1 on failure