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 theid
was found in the agent’s context and a pointer to it is returned indatastore
.
-
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 theid
was found in the agent’s context and its index is returned inindex
.
-
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 theid
was found in the agent’s context and a pointer to it is returned inkeystore
.
-
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 theid
was found in the agent’s context and its index is returned inindex
.
-
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 validfalse
: 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
- 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
- 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 successIOT_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 successIOT_AGENT_FAILURE
: Upon failure
-
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 bydst
.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 holdlen
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 positionoffset
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.
-
typedef iot_agent_status_t (*
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.
-
typedef iot_agent_status_t (*
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 successIOT_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 successIOT_AGENT_FAILURE
: upon failure
-
iot_agent_status_t
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
- 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
- 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
- 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 validfalse
: Service configuration data of a registered datastores is invalid
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
Functions
-
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.
-
typedef bool (*
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_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 successIOT_AGENT_FAILURE
: upon failure
-
iot_agent_status_t
iot_agent_utils_convert_service2key_id
(uint64_t service_id, uint32_t *key_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 successIOT_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 successIOT_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
.
-