6.7. API

6.7.1. EdgeLock 2GO Main

group edgelock2go_agent_main

Main API for registering keystores, datastores and connecting to the cloud to update provisionings.

Defines

EDGELOCK2GO_ATTESTATION_KEY_ECC

The attestation keyid on the SSS API to use for the attestation.

EDGELOCK2GO_ATTESTATION_KEY_RSA
EDGELOCK2GO_CERTID_ECC

The certid on the SSS API to use for the keystore to use for connecting to EdgeLock 2GO cloud service.

EDGELOCK2GO_CERTID_RSA
EDGELOCK2GO_KEYID_ECC

The keyid on the SSS API to use for the keystore and keypair to use for connecting to EdgeLock 2GO cloud service.

EDGELOCK2GO_KEYID_RSA
EDGELOCK2GO_KEYSTORE_ID

The keystore that stores the credentials for the EdgeLock 2GO cloud service.

When connecting to the EdgeLock 2GO cloud service, for the client authentication a private key is required. This key is expected to be in a keystore which is registered to the EdgeLock 2GO agent.

In case there is a datastore which holds the information how to connect to the EdgeLock 2GO cloud service this datastore also holds the information where to get the private key.

In case the EdgeLock 2GO agent needs to fall back to compile-time constant connection information, it does assume that the private key for the client authentication is stored in a keystore that is registered with this ID.

EDGELOCK2GO_MANAGED_SERVICE_KEY_MAX

@ brief End of the range of keys to use for keys of cloud services provisioned by EdgeLock 2GO.

EDGELOCK2GO_MANAGED_SERVICE_KEY_MIN

@ brief Start of the range of keys to use for keys of cloud services provisioned by EdgeLock 2GO.

Typedefs

typedef struct _nxp_iot_UpdateStatusReport nxp_iot_UpdateStatusReport
typedef struct pb_field_s pb_field_t
typedef struct pb_istream_s pb_istream_t
typedef struct pb_ostream_s pb_ostream_t

Functions

void iot_agent_free_service_descriptor(nxp_iot_ServiceDescriptor *service_descriptor)

Free all FT_POINTER fields of a service descriptor.

When selecting a service, a service descriptor is read from a datastore. A service descriptor can contain fields of variable length (binary data (certificates, etc.) or text (hostname, etc.)). Those fields use dynamically allocated memory. The memory is freed by calling this function.

Parameters
  • [in] service_descriptor: Reference to service descriptor

void iot_agent_free_update_status_report(nxp_iot_UpdateStatusReport *status_report)

Free all FT_POINTER fields of a update status report.

When a status report is filled during updating a device configuration, it contains pointer fields which use dynamically allocated memory. The memory is freed by calling this function.

Parameters
  • [in] status_report: Reference to status_report

iot_agent_status_t iot_agent_get_datastore_by_id(const iot_agent_context_t *ctx, const uint32_t id, iot_agent_datastore_t **datastore)

Get a reference to a datastore based on its identifier.

Return Value
  • IOT_STATUS_SUCCESS: A datastore with the id was found in the agent’s context and a pointer to it is returned in datastore.

iot_agent_status_t iot_agent_get_datastore_index_by_id(const iot_agent_context_t *ctx, const uint32_t id, size_t *index)

Get the index of a datastore based on its identifier.

Return Value
  • IOT_STATUS_SUCCESS: A datastore with the id was found in the agent’s context and its index is returned in index.

bool iot_agent_get_endpoint_info(void *context, void *endpoint_information)

Get an endpoint information of the endpoint.

Parameters
  • [in] context: Reference to end point context

  • [in] endpoint_information: Reference to end point information

iot_agent_status_t iot_agent_get_keystore_by_id(const iot_agent_context_t *ctx, const uint32_t id, iot_agent_keystore_t **keystore)

Get a reference to a keystore based on its identifier.

Return Value
  • IOT_STATUS_SUCCESS: A keystore with the id was found in the agent’s context and a pointer to it is returned in keystore.

iot_agent_status_t iot_agent_get_keystore_index_by_id(const iot_agent_context_t *ctx, const uint32_t id, size_t *index)

Get the index of a keystore based in its identifier.

Return Value
  • IOT_STATUS_SUCCESS: A keystore with the id was found in the agent’s context and its index is returned in index.

size_t iot_agent_get_number_of_services(const iot_agent_context_t *ctx)

Returns total number of services of all registered datastores.

Parameters
  • [in] ctx: Context for the iot_agent.

Return Value
  • Total: number of services of all registered datastores

iot_agent_status_t iot_agent_get_service_descriptor(const iot_agent_context_t *ctx, nxp_iot_ServiceDescriptor *service_descriptor)

Get the service descriptor of the currently selected service.

Pre

The configuration data associated to the context is valid.

Post

In case of success, the service_descriptor structure is filled and needs to be freed after usage by calling iot_agent_free_service_descriptor. In case of failure no freeing is required. Also in case of failures, the contents of service_descriptor are not guaranteed to remain intact.

Parameters
  • [in] ctx: The context of the agent.

  • [out] service_descriptor: Structure for holding a service descriptor. Must point to a valid service descriptor object upon invocation. Any FT_POINTER fields in the service descriptor are freed before changing the contents to the service_descriptor of the selected service.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

bool iot_agent_handle_request(pb_istream_t *istream, pb_ostream_t *ostream, const pb_field_t *message_type, void *context)

handle request by end point

Parameters
  • [in] istream: Input stream

  • [in] ostream: Output stream

  • [in] message_type: a pointer to the message type fields array

  • [in] context: End point context

iot_agent_status_t iot_agent_init(iot_agent_context_t *ctx)

Initialize EdgeLock 2GO agent context memory with zeros.

Parameters
  • [inout] ctx: EdgeLock 2GO agent context

Return Value
  • IOT_AGENT_SUCCESS: Upon success

iot_agent_status_t iot_agent_init_dispatcher(iot_agent_dispatcher_context_t *dispatcher_context, iot_agent_context_t *agent_context, nxp_iot_ServiceDescriptor *service_descriptor, nxp_iot_UpdateStatusReport *status_report)

Initialize Dispatcher.

Parameters
  • [in] dispatcher_context: Context for the dispatcher

  • [in] agent_context: Context for the agent

  • [in] service_descriptor: The service descriptor containing the connection parameters to connect to the EdgeLock 2GO cloud service.

  • [out] status_report: A pointer to a structure that gets filled with a status report after the update is complete. If NULL is given, no status report is created.

bool iot_agent_is_service_configuration_data_valid(const iot_agent_context_t *ctx)

Checks whether service configuration data of all registered datastores is valid.

Parameters
  • [in] ctx: Context for the iot_agent.

Return Value
  • true: Service configuration data of all registered datastores is valid

  • false: Service configuration data of a registered datastores is invalid

iot_agent_status_t iot_agent_register_datastore(iot_agent_context_t *ctx, iot_agent_datastore_t *datastore)

Register datastore endpoint.

Note that the ownership for the datastore is not transferred. The caller is responsible that the datastore is freed at the appropriate time.

It is not possible to register two endpoints with the same identifier.

Parameters
  • [in] ctx: Context for the iot_agent.

  • [in] datastore: Datastore that is registered.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

iot_agent_status_t iot_agent_register_keystore(iot_agent_context_t *ctx, iot_agent_keystore_t *keystore)

Register a keystore endpoint.

Note that the ownership for the keystore is not transferred. The caller is responsible that the keystore is freed at the appropriate time.

It is not possible to register two endpoints with the same identifier.

Parameters
  • ctx: Context for the iot_agent.

  • [in] keystore: Keystore that is registered.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

iot_agent_status_t iot_agent_select_service_by_id(iot_agent_context_t *ctx, uint64_t service_id, nxp_iot_ServiceDescriptor *service_descriptor)

Select service by given ID.

Pre

The configuration data associated to the context is valid.

Post

In case of success, the service_descriptor structure is filled and needs to be freed after usage by calling iot_agent_free_service_descriptor. In case of failure no freeing is required. Also in case of failures, the contents of service_descriptor are not guaranteed to remain intact.

See

iot_agent_is_service_configuration_data_valid

Parameters
  • [in] ctx: Context for the iot_agent.

  • [in] service_id: ID of the service

  • [out] service_descriptor: Structure for holding a service descriptor. Must point to a valid service descriptor object upon invocation. Any FT_POINTER fields in the service descriptor are freed before changing the contents to the service_descriptor of the selected service.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

iot_agent_status_t iot_agent_select_service_by_index(iot_agent_context_t *ctx, size_t index, nxp_iot_ServiceDescriptor *service_descriptor)

Select service by given index.

Pre

The configuration data associated to the context is valid.

Post

In case of success, the service_descriptor structure is filled and needs to be freed after usage by calling iot_agent_free_service_descriptor. In case of failure no freeing is required. Also in case of failures, the contents of service_descriptor are not guaranteed to remain intact.

See

iot_agent_is_service_configuration_data_valid

Parameters
  • [in] ctx: Context for the iot_agent.

  • [in] index: Index of the service

  • [out] service_descriptor: Structure for holding a service descriptor. Must point to a valid service descriptor object upon invocation. Any FT_POINTER fields in the service descriptor are freed before changing the contents to the service_descriptor of the selected service.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

iot_agent_status_t iot_agent_set_edgelock2go_datastore(iot_agent_context_t *ctx, iot_agent_datastore_t *datastore)

Set the datastore that is used to hold the information to connect to the EdgeLock 2GO cloud service.

Note that the ownership for the datastore is not transferred. The caller is responsible that the datastore is freed at the appropriate time.

iot_agent_status_t iot_agent_update_device_configuration(iot_agent_context_t *ctx, nxp_iot_UpdateStatusReport *status_report)

Update device configuration Reach out to EdgeLock 2GO cloud service for checking and (if applicable) fetching configuration updates for the device.

Post

In case of success, the status_report structure is filled using dynamically allocated fields and needs to be freed after usage by calling #iot_agent_free_status_report.

Parameters
  • [in] ctx: Context for the iot_agent.

  • [out] status_report: Provides a more detailed view on the operations performed during the update and its outcomes. If the argument is NULL, no detailed status is reported.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

  • IOT_AGENT_FAILURE: Upon failure

iot_agent_status_t iot_agent_update_device_configuration_from_constants(iot_agent_context_t *agent_context, uint32_t client_key_object_id, uint32_t client_cert_object_id, nxp_iot_UpdateStatusReport *status_report)

Update device configuration.

Reach out to EdgeLock 2GO cloud service for checking and (if applicable) fetching configuration updates for the device.

The connection details (hostname/port/server root certificates, etc.) are taken from the configuration constants in nxp_iot_agent_config.h.

It is necessary that an sss keystore that contains credentials (client key and client certificate) for connecting to the EdgeLock 2GO cloud service. The object ids to those credentials are settable via function arguments.

Post

In case of success, the status_report structure is filled using dynamically allocated fields and needs to be freed after usage by calling #iot_agent_free_status_report.

Parameters
  • [in] ctx: Context for the iot_agent.

  • [out] status_report: Provides a more detailed view on the operations performed during the update and its outcomes. If the argument is NULL, no detailed status is reported.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

  • IOT_AGENT_FAILURE: Upon failure

iot_agent_status_t iot_agent_update_device_configuration_from_datastore(iot_agent_context_t *agent_context, iot_agent_datastore_t *datastore, nxp_iot_UpdateStatusReport *status_report)
iot_agent_status_t iot_agent_update_device_configuration_from_service_descriptor(iot_agent_context_t *agent_context, nxp_iot_ServiceDescriptor *service_descriptor, nxp_iot_UpdateStatusReport *status_report)

6.7.2. EdgeLock 2GO Datastore

group edgelock2go_agent_datastore

Functions that define how to interact with a datastore. There exist multiple concrete implementations for different microcontrollers.

Typedefs

typedef iot_agent_status_t (*iot_agent_datastore_allocator_t)(void *context, size_t len)
typedef iot_agent_status_t (*iot_agent_datastore_committer_t)(void *context)
typedef iot_agent_status_t (*iot_agent_datastore_destroyer_t)(void *context)
typedef iot_agent_status_t (*iot_agent_datastore_reader_t)(void *context, void *dst, size_t offset, size_t *len)
typedef iot_agent_status_t (*iot_agent_datastore_writer_t)(void *context, size_t offset, const void *src, size_t len)
typedef struct _nxp_iot_ResponsePayload nxp_iot_ResponsePayload

Functions

bool datastore_read_callback(pb_istream_t *stream, uint8_t *buf, size_t count)
iot_agent_status_t iot_agent_datastore_allocate(iot_agent_datastore_t *datastore, size_t len)

Allocate memory in a datastore.

Reserve memory in a datastore that can be written to by subsequent writes.

If the memory allocation fails, this function does not return IOT_AGENT_SUCCESS.

iot_agent_status_t iot_agent_datastore_commit(iot_agent_datastore_t *datastore)

Commit a transaction to a datastore.

A call to this function indicates that all necessary writes of a transaction are done and the datastore contens can be considered valid.

This is the indication to the datastore to invalidate old contents and from point in time onwards use the data that was updated with the transaction tht is committed.

bool iot_agent_datastore_encode_datastore_ok_response(pb_ostream_t *ostream)
iot_agent_status_t iot_agent_datastore_free(iot_agent_datastore_t *datastore)

Destroy the datastore.

Depending on the type of the datastore this is triggering actions on the datastore’s context itself by calling the _destroy() function of the datastore interface.

This does not free the context of the datastore.

The datastore is not usable after a call to iot_agent_datastore_free.

iot_agent_status_t iot_agent_datastore_read(iot_agent_datastore_t *datastore, void *dst, size_t offset, size_t *len)

Read from a datastore to a buffer in memory.

Starting at position offset, len bytes are read from the datastore and copied to the memory pointed to by dst.

If the datastore does not hold len bytes or the read would be out of bounds, only as many bytes as available are read.

len is updated to hold the number of bytes that actually were read from the datastore.

No length checks on dst are performed, the caller is responsible that the memory location is writeable and can hold len bytes.

iot_agent_status_t iot_agent_datastore_write(iot_agent_datastore_t *datastore, size_t offset, const void *src, size_t len)

Write from a buffer in memory to a datastore.

From src, len bytes are copied to the datastore. The first byte is written to the position offset in the datastore.

Length check on the destaination - the datastore - is performed, memory in the datastore needs to be pre-allocated. If the data does not fit, this function does not return IOT_AGENT_SUCCESS.

struct datastore_stream_context_t
#include <nxp_iot_agent_datastore.h>

A stream for reading contents from within a datastore, starting at an offset.

struct iot_agent_datastore_interface_t
#include <nxp_iot_agent_datastore.h>

The interface any datastore needs to implement.

struct iot_agent_datastore_t
#include <nxp_iot_agent_datastore.h>

A context holding the state of a datastore; this is passed to datastore interface functions.

6.7.3. EdgeLock 2GO Keystore

group edgelock2go_agent_keystore

Functions to interact with a keystore. There are concrete implementations of this API for different SEs.

Typedefs

typedef iot_agent_status_t (*iot_agent_keystore_destroyer_t)(void *context)
typedef void (*iot_agent_keystore_session_closer_t)(void *context)
typedef iot_agent_status_t (*iot_agent_keystore_session_opener_t)(void *context)
typedef struct pb_field_s pb_field_t
typedef struct pb_istream_s pb_istream_t
typedef struct pb_ostream_s pb_ostream_t

Functions

void iot_agent_keystore_close_session(iot_agent_keystore_t *keystore)

Close a session/connection to a keystore.

iot_agent_status_t iot_agent_keystore_free(iot_agent_keystore_t *keystore)

Destroy the keystore.

Depending on the type of the keystore this is triggering actions on the keystore’s context itself by calling the _destroy() function of the keystore interface.

This does not free the context of the keystore.

The keystore is not usable after a call to iot_agent_keystore_free.

iot_agent_status_t iot_agent_keystore_open_session(iot_agent_keystore_t *keystore)

Open a session/connection to a keystore.

struct iot_agent_keystore_interface_t
#include <nxp_iot_agent_keystore.h>

The interface any keystore needs to implement.

struct iot_agent_keystore_t
#include <nxp_iot_agent_keystore.h>

A structure binding a keystore interface and a keystore context to a keystore instance.

6.7.4. EdgeLock 2GO Session

group edgelock2go_agent_session

Session handling functions for the EdgeLock 2GO agent. When interacting with the OpenSSL engine, the agent session needs to be closed before and opened after OpenSSL is active.

Functions

iot_agent_status_t iot_agent_session_connect(ex_sss_boot_ctx_t *pSeBootCtx)

Re-create an open a session with secure element

Parameters
  • [in] pCtx: pointer to session context

Return Value
  • IOT_AGENT_SUCCESS: upon success

  • IOT_AGENT_FAILURE: upon failure

void iot_agent_session_disconnect(ex_sss_boot_ctx_t *pSeBootCtx)

Disconnect and close session with secure element

Parameters
  • [in] pCtx: pointer to session context

iot_agent_status_t iot_agent_session_init(int argc, const char *argv[], ex_sss_boot_ctx_t *pCtx)

Create an open a session with secure element

Parameters
  • [in] argc: arguments from command-line if any

  • [in] argv: arguments from command-line if any

  • [in] pCtx: pointer to session context

Return Value
  • IOT_AGENT_SUCCESS: upon success

  • IOT_AGENT_FAILURE: upon failure

6.7.5. EdgeLock 2GO Service

group edgelock2go_agent_service

Functionality to work with service descriptors. A service descriptor represents all information from a single cloud provisioning.

Defines

IOT_AGENT_CONFIGURATION_DATA_VERSION

Typedefs

typedef configuration_data_header_t

The header of configuration data stored in a datastore.

typedef uint8_t public_key_identifier_t[16]
typedef uint8_t service_identifier_t[32]

Functions

void iot_agent_service_free_service_descriptor(nxp_iot_ServiceDescriptor *service_descriptor)

Free all FT_POINTER fields of a service descriptor.

When selecting a service, a service descriptor is read from a datastore. A service descriptor can contain fields of variable length (binary data (certificates, etc.) or text (hostname, etc.)). Those fields use dynamically allocated memory. The memory is freed by calling this function.

Parameters
  • [in] service_descriptor: Reference to service descriptor

size_t iot_agent_service_get_number_of_services(const iot_agent_datastore_t *ctx)

Get the number of services that are available.

Return

The number of services that are avilable.

Parameters
  • [in] ctx: Context for the iot_agent.

iot_agent_status_t iot_agent_service_get_protocol_of_service_as_string(const nxp_iot_ServiceDescriptor *service_descriptor, const char **buffer)

Get a textual description of the protocol.

Protocol strings are internal constant c-strings. This function returns a pointer to such a string, ownership remains with the iot_agent.

Parameters
  • [in] service_descriptor: The service descriptor to get the protocol for.

  • [out] buffer: A pointer to a c-string that is changed to point to the textual representation of the protocol.

Return Value
  • IOT_AGENT_SUCCESS: The service type could be resolved.

  • IOT_AGENT_FAILURE: The service type is invalid.

iot_agent_status_t iot_agent_service_get_service_descriptor_of_service(const iot_agent_datastore_t *datastore, size_t offset, nxp_iot_ServiceDescriptor *service_descriptor)

Get the service descriptor of a service specified by offset.

Pre

The configuration data associated to the context is valid.

Post

In case of success, the service_descriptor structure is filled and needs to be freed after usage by calling iot_agent_free_service_descriptor. In case of failure no freeing is required. Also in case of failures, the contents of service_descriptor are not guaranteed to remain intact.

See

iot_agent_is_service_configuration_data_valid

Parameters
  • [in] ctx: The datastore to query for the service.

  • [in] offset: The offset of the service - the memory location in the given datastore.

  • [out] service_descriptor: Structure for holding a service descriptor. Must point to a valid service descriptor object upon invocation. Any FT_POINTER fields in the service descriptor are freed before changing the contents to the service_descriptor of the selected service.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

iot_agent_status_t iot_agent_service_get_service_offset_by_id(const iot_agent_datastore_t *ctx, uint64_t service_id, size_t *offset, nxp_iot_ServiceDescriptor *service_descriptor)

Get the offset and the service descriptor of a service specified by service_id.

Pre

The configuration data associated to the context is valid.

Post

In case of success, the service_descriptor structure is filled and needs to be freed after usage by calling iot_agent_free_service_descriptor. In case of failure no freeing is required. Also in case of failures, the contents of service_descriptor are not guaranteed to remain intact.

See

iot_agent_is_service_configuration_data_valid

Parameters
  • [in] ctx: The datastore to query for the service.

  • [in] service_id: ID of the service

  • [out] offset: The offset of the service descriptor within the datastore.

  • [out] service_descriptor: Structure for holding a service descriptor. Must point to a valid service descriptor object upon invocation. Any FT_POINTER fields in the service descriptor are freed before changing the contents to the service_descriptor of the selected service.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

iot_agent_status_t iot_agent_service_get_service_offset_by_index(const iot_agent_datastore_t *datastore, size_t index, size_t *offset, nxp_iot_ServiceDescriptor *service_descriptor)

Get the offset and the service descriptor of a service specified by index.

Pre

The configuration data associated to the context is valid.

Post

In case of success, the service_descriptor structure is filled and needs to be freed after usage by calling iot_agent_free_service_descriptor. In case of failure no freeing is required. Also in case of failures, the contents of service_descriptor are not guaranteed to remain intact.

See

iot_agent_is_service_configuration_data_valid

Parameters
  • [in] ctx: The datastore to query for the service.

  • [in] index: The index of the service (within the given datastore).

  • [out] service_descriptor: Structure for holding a service descriptor. Must point to a valid service descriptor object upon invocation. Any FT_POINTER fields in the service descriptor are freed before changing the contents to the service_descriptor of the selected service.

Return Value
  • IOT_AGENT_SUCCESS: Upon success

iot_agent_status_t iot_agent_service_get_service_type_as_string(const nxp_iot_ServiceDescriptor *service_descriptor, const char **buffer)

Get a textual description of the service type.

Service type strings are internal constant c-strings. This function returns a pointer to such a string, ownership remains with the iot_agent.

Parameters
  • [in] service_descriptor: The service descriptor to get the type for.

  • [out] buffer: A pointer to a c-string that is changed to point to the textual representation of the service type.

Return Value
  • IOT_AGENT_SUCCESS: The service type could be resolved.

  • IOT_AGENT_FAILURE: The service type is invalid.

bool iot_agent_service_is_configuration_data_valid(const iot_agent_datastore_t *ctx)

Checks service configuration data of all registered datastores are valid.

Parameters
  • [in] ctx: Context for the iot_agent.

Return Value
  • true: Service configuration data of all registered datastores are valid

  • false: Service configuration data of a registered datastores is invalid

iot_agent_status_t iot_agent_service_read_buffer(const iot_agent_datastore_t *ctx, size_t offset, void *buffer, size_t expected_len)
void iot_agent_service_read_header(const iot_agent_datastore_t *ctx, size_t offset, configuration_data_header_t *header)

Variables

uint32_t length

Total length of the stored data (incl. all fields of configuration_data_header_t).

uint32_t number_of_services

Number of stored service configurations.

uint32_t version

Version number of the structure of the configuration data.

6.7.6. EdgeLock 2GO Dispatcher

group edgelock2go_agent_dispatcher

The dispatcher handles and decodes requests of endpoints.

Typedefs

typedef bool (*get_endpoint_info_callback_t)(void *context, void *endpoint_information)
typedef struct iot_agent_context_t iot_agent_context_t
typedef bool (*request_handler_callback_t)(pb_istream_t *istream, pb_ostream_t *ostream, const pb_field_t *message_type, void *endpoint_context)

Enums

enum _iot_agent_stream_type_t

Values:

STREAM_TYPE_NETWORK = 0U

Network stream

STREAM_TYPE_BUFFER_REQUESTS = 1U

Buffer stream in Requests format

Functions

bool encode_responses_callback(pb_ostream_t *ostream, const pb_field_t *field, void *const *arg)
bool encode_responses_from_payload(pb_ostream_t *ostream, nxp_iot_ResponsePayload *response_payload)
bool handle_request_payload(pb_istream_t *stream, const pb_field_t *field, void **arg)
bool handle_requests(pb_istream_t *stream, const pb_field_t *field, void **arg)
iot_agent_status_t iot_agent_dispatcher(iot_agent_dispatcher_context_t *dispatcher_context, pb_istream_t *input, pb_ostream_t *output)

Dispatcher.

Parameters
  • [in] dispatcher_context: Context for the dispatcher

  • [in] input: Input stream

  • [in] out: Output stream

struct handle_request_payload_args_t
#include <nxp_iot_agent_dispatcher.h>

Context structure for passing dispatcher information to callbacks for message decoding.

6.7.7. EdgeLock 2GO Utils

group edgelock2go_agent_utils

Utility functions for the EdgeLock 2GO agent for writing and generating key references and certificates.

Defines

NXP_IOT_AGENT_EDGELOCK2GO_CLIENT_CERTIFICATE_BUFFER_SIZE

The size of the buffer to reserve for the EdgeLock 2GO cloud service client certificate.

Typedefs

typedef struct iot_agent_context_t iot_agent_context_t

Functions

iot_agent_status_t iot_agent_get_first_found_object(sss_key_store_t *keystore, uint32_t *object_ids, size_t num_objects, uint32_t *object_id)

Maps a given service id to the range of keys that are managed by the EdgeLock 2GO cloud service.

Parameters
  • [in] service_id: Service ID

  • [out] key_id: Key ID

Return Value
  • IOT_AGENT_SUCCESS: upon success

  • IOT_AGENT_FAILURE: upon failure

iot_agent_status_t iot_agent_keystore_file_existence(const char *filename, bool forceCreation)

Checks existence of a file. If required it forces creation of file.

Parameters
  • [in] filename: Name of the file

  • [in] forceCreation: Switch to force creation of the file

Return Value
  • IOT_AGENT_SUCCESS: upon success

  • IOT_AGENT_FAILURE: upon failure

iot_agent_status_t iot_agent_utils_get_certificate_common_name(iot_agent_context_t *ctx, const nxp_iot_ServiceDescriptor *service_descriptor, char *common_name, size_t max_size)

Gets the common name from the client certificte.

Parameters
  • [in] ctx: Context for the iot_agent

  • [in] service_descriptor: Descriptor with service data

  • [inout] common_name: Common name string

  • [in] max_size: Maximum size

Return Value
  • IOT_AGENT_SUCCESS: upon success

  • IOT_AGENT_FAILURE: upon failure

iot_agent_status_t iot_agent_utils_get_edgelock2go_certificate_id(sss_key_store_t *keystore, uint32_t *object_id)

Checks whether a keystore contains the object with the defined certificate to use for authenticating at the EdgeLock 2GO cloud service.

The keystore might contain keys using ECC and/or RSA. If available, it will return the object id of the ECC certificate, otherwise the object id of the RSA certificate.

When neither is found or in case of other issues with the keystore, the function does not return IOT_AGENT_SUCCESS.

iot_agent_status_t iot_agent_utils_get_edgelock2go_key_id(sss_key_store_t *keystore, uint32_t *object_id)

Checks whether a keystore contains the object with the defined key to use for authenticating at the EdgeLock 2GO cloud service.

The keystore might contain keys using ECC and/or RSA. If available, it will return the object id of the ECC key, otherwise the object id of the RSA key.

When neither is found or in case of other issues with the keystore, the function does not return IOT_AGENT_SUCCESS.

iot_agent_status_t iot_agent_utils_write_edgelock2go_datastore(iot_agent_keystore_t *keystore, iot_agent_datastore_t *datastore, const char *hostname, uint32_t port, const pb_bytes_array_t *trusted_root_ca_certificates)

Assemble a service descriptor for the connection to EdgeLock 2GO cloud service and write it to a datastore.

It is assumed that credentials (either ECC or RSA) for client certificate authentication are stored in keystore.

iot_agent_status_t iot_agent_utils_write_edgelock2go_datastore_from_env(iot_agent_keystore_t *keystore, iot_agent_datastore_t *datastore)

Assemble a service descriptor for the connection to EdgeLock 2GO cloud service and write it to a datastore.

Per default this function takes the hostname and port from the defines

  • EDGELOCK2GO_HOSTNAME and

  • EDGELOCK2GO_PORT

For testing purposes, it is possible to set-up the connection parameters to the EdgeLock 2GO cloud service from externally by passing in information via environment variables.

The following env variables are considered:

  • IOT_AGENT_TEST_EDGELOCK2GO_HOSTNAME

  • IOT_AGENT_TEST_EDGELOCK2GO_PORT

It is assumed that credentials (either ECC or RSA) for client certificate authentication are stored in keystore.