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_t *	oc_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_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. More...
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. More...
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. 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_t *	oc_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]	acl	A struct containing ACL installed on a remote device
[in]	data	context 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]	creds	A struct containing a linked list of oc_sec_cred_t credentials owned by a remote device
[in]	data	context 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]	uuid	of the device status is being reported on
[in]	status	number indicating success or failure of action that invoked this callback. Typically status >= 0 indicates success
[in]	data	context 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_uuid_to_str(uuid, 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);

Parameters

[in]	uuid	the uuid of the discovered device
[in]	eps	list of endpoints that can be used to connect with the discovered device
[in]	data	context 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]	status	number indicating success or failure of action that invoked this callback. Typically status >= 0 indicates success
[in]	data	context 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_obt_ace_add_permission(ace, OC_PERM_RETRIEVE);
oc_obt_ace_add_permission(ace, OC_PERM_UPDATE);
oc_obt_ace_add_permission(ace, OC_PERM_NOTIFY);

will set the same permissions as calling:

oc_obt_ace_add_permission(ace, OC_PERM_RETRIEVE | OC_PERM_UPDATE |
                               OC_PERM_NOTIFY);

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]	ace	the ACE the permissions are being added to
[in]	permission	the 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]

ace

the 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]	resource	the ACE resource that the href URL will be added to
[in]	href	the 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]	resource	the ACE resource to set the wildcard value on
[in]	wc	the 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);

Parameters

[in]	roles	head of the oc_role_t linked list. NULL if the list has not yet been created
[in]	role	the role for the role id
[in]	authority	the 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]	uuid	the uuid of the remote device
[in]	aceid	the id of the Access Control Entry
[in]	cb	callback invoked to indicate the success or failure of the ACE delete request
[in]	data	context 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]	uuid	the uuid of the device the credential is being deleted from
[in]	credid	the credid of the credential being deleted
[in]	cb	callback invoked to indicate the success or failure of the oc_obt_delete_cred_by_credid call
[in]	data	context 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]

credid

number 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];
  oc_uuid_to_str(uuid, 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");
}

Parameters

[in]	uuid	the device being reset
[in]	cb	callback invoked to indicate the success or failure of the hard reset action
[in]	data	context 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]	uuid	the uuid of the device the resources are being discovered on
[in]	handler	the oc_discovery_all_handler_t invoked in responce to this discovery request
[in]	data	context 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]	cb	the oc_obt_discovery_cb_t that will be called for each discovered device
[in]	data	context 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]	cb	the oc_obt_discovery_cb_t that will be called for each discovered device
[in]	data	context 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]	cb	the oc_obt_discovery_cb_t that will be called for each discovered device
[in]	data	context 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]	cb	the oc_obt_discovery_cb_t that will be called for each discovered device
[in]	data	context 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]	cb	the oc_obt_discovery_cb_t that will be called for each discovered device
[in]	data	context 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]	cb	the oc_obt_discovery_cb_t that will be called for each discovered device
[in]	data	context 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

ace	the 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

acl	pointer 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

creds

the 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

roles

the 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);
   oc_device_bind_resource_type(0, "oic.d.ams");
   oc_device_bind_resource_type(0, "oic.d.cms");
   return ret;
 }
 
static void
issue_requests(void)
{
  oc_obt_init();
}
 
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;

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]

conn

the 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]	role	the role associated with the ACE
[in]	authority	the 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]

uuid

the 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]	uuid	the device to certificate based OTM is being done on
[in]	cb	callback invoked to indicate the success or failure of the Manufacturer Certificate Based OTM
[in]	data	context 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];
  oc_uuid_to_str(uuid, 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");
}

Parameters

[in]	uuid	the 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]	cb	callback invoked to indicate the success or failure of the OTM
[in]	data	context 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];
  oc_uuid_to_str(uuid, 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];
  oc_uuid_to_str(uuid, 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");
}

Parameters

[in]	uuid	the device the Random PIN based OTM is being done on
[in]	pin	the PIN obtained from the remote device in response to the oc_obt_request_random_pin
[in]	pin_len	the length of the PIN
[in]	cb	callback invoked to indicate the success or failure of the Random PIN OTM operation
[in]	data	context 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];
  oc_uuid_to_str(uuid, 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;
ace = oc_obt_new_ace_for_connection(OC_CONN_AUTH_CRYPT);
oc_ace_res_t *res = oc_obt_ace_new_resource(ace);
 
if (!res) {
  printf("ERROR: Could not allocate new resource for ACE\n");
  oc_obt_free_ace(ace);
  return;
}
oc_obt_ace_resource_set_wc(res, OC_ACE_WC_ALL);
oc_obt_ace_add_permission(ace, OC_PERM_RETRIEVE | OC_PERM_UPDATE |
                               OC_PERM_NOTIFY);
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");
}

Parameters

[in]	subject	the uuid of the device being provisioned
[in]	ace	the ACE being added to the subject
[in]	cb	callback invoked to indicate the success or failure of the provisioning
[in]	data	context 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]	subject	the uuid or the device being provisioned
[in]	cb	callback invoked to indicate the success or failure of the provisioning
[in]	data	context 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");
}

Parameters

[in]	uuid	the uuid of the device to provision
[in]	cb	callback invoked to indicate the success or failure of the provisioning
[in]	data	context 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");
  }
}
 
int ret = oc_obt_provision_pairwise_credentials(uuid1, uuid2,
                               provision_credentials_cb, NULL);
if (ret >= 0) {
  printf("Successfully issued request to provision credentials\n");
} else {
  printf("ERROR issuing request to provision credentials\n");
}

Parameters

[in]	uuid1	uuid of the first device to pair
[in]	uuid2	uuid of the second device to pair
[in]	cb	callback invoked to indicate the success or failure of the pairwise credentials provisioning
[in]	data	context 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");
}

Parameters

roles	the role(s) to provision
uuid	the uuid of the device to provision
cb	callback invoked to indicate the success or failure of the provisioning
data	context 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]	subject	the uuid or the device being provisioned
[in]	role	the role for the ACE
[in]	authority	the role authority for the ACE. The role authority is optional if no authority is provided pass in NULL
[in]	cb	callback invoked to indicate the success or failure of the provisioning
[in]	data	context 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

certificate	the certificate data
certificate_size	the certificate data size
subject	id (the uuid of the cloud)
uuid	the uuid of the device to provision
cb	callback invoked to indicate the success or failure of the provisioning
data	context 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).

• Parameters

  [in]	uuid	the uuid of the device the oc_random_pin_cb_t is being run on. The uuid is typically obtained in response to an oc_obt_discover_unowned_devices* call
  [in]	cb	callback invoked to indicate the success or failure of the random PIN request
  [in]	data	context 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

  See also

  oc_set_random_pin_callback

  oc_random_pin_cb_t

  oc_obt_perform_random_pin_otm

  Returns

  • 0 on success
  • -1 on failure

  See also

  oc_obt_perform_random_pin_otm

  oc_obt_device_status_cb_t

  oc_set_random_pin_callback

  oc_random_pin_cb_t

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]	uuid	the uuid of the remote device
[in]	cb	callback that will deliver the requested ACL
[in]	data	context 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]	uuid	the uuid of the remote device
[in]	url	of the resource
[in]	cb	callback invoked to indicate the success or failure of the request
[in]	user_data	context 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]	subject	uuid of the device the credentials will be fetched from
[in]	cb	callback that will contain the list of credentials from the remote device
[in]	data	context 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]	name	the name of the secure domain
[in]	priv	privacy 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]	uuid	the uuid of the remote device
[in]	url	of the resource
[in]	at	Access Token
[in]	apn	Auth Provider Name
[in]	cis	OCF Cloud interface URL
[in]	sid	OCF Cloud UUID
[in]	cb	callback invoked to indicate the success or failure of the request
[in]	user_data	context 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