API overview

Provisioning functions

Guardian()

Description: Creates new Guardian instance and puts it into startup state, ready for initialization.

  • First step before any other operations

  • This constructor only initializes member variables

Dependencies: None - this is the first function to call

Parameters: None - default constructor takes no parameters

Returns: Nothing since it is a constructor

Syntax:

Guardian()

Initialize()

Description: Initializes Guardian with device credentials and configuration files. Uses the provided profile, identity, and trust files to initialize the Guardian system.

Dependencies:

Parameters:

  • in_files: Device credentials and configuration files

  • in_component_handle: This is the unique component identifier used for provisioning.

    • Type: const char*

  • in_hardware_identifier: This is the unique hardware identifier.

    • Character limitations: 36 (37 with null terminator)

    • Type: const char*

  • in_options: Additional initialization configuration options

Returns: Status code indicating success or failure.

  • Success code: OK. Guardian system was successfully initialized.

  • Error codes:

    • FAIL: General failure. Guardian did not initialize successfully. Check the log file for more information.

    • BADPARAM: One of the inputs is null or empty.

    • FILENOTFOUND: A required input file is unavailable.

    • OUTOFMEMORY : Not enough memory to initialize Guardian.

Syntax

Status Initialize(
    const utilities::InitializeFiles & in_files,
    const char * in_component_handle,
    const char * in_hardware_identifier,
    const InitializeOptions & in_options
)

GenerateProvisionRequest()

Description: The GenerateProvisionRequest() function creates provisioning request (.mcpr) and private identity (.mcpi) files.

  • This is the first provisioning step for the provisioning process.

  • This is the only step in the offline provisioning process.

  • The private identity (.mcpi file) includes the generated device keys.

  • The provision request (.mcpr file) can be manually uploaded to Guardian Cloud or sent using available online methods in the profile.

Dependencies:

  • Must be called after Initialize()

  • Must be called once before any other provisioning or re-provisioning actions occur.

  • Required before StartProvisioningOnline()

Parameters:

  • io_files : Provisioning files structure. in_provisioning_component_handle : This is the unique component identifier used for provisioning.

    • Type: const char*

  • in_provisioning_system : This is the unique system name identifier which is sent to Guardian Cloud.

    • Character limitations: 36 (37 with null terminator)

    • Type: const char*

  • in_hardware_identifier - This is the unique hardware identifier.

    • Character limitations: 36 (37 with null terminator)

    • Type: const char*

Returns: Status code indicating success or failure.

  • Success code: OK. Provisioning request was successfully created

  • Error codes:

    • FAIL: General failure. Check the log file for more information.

    • BADPARAM: One of the inputs is null or empty

    • FILENOTFOUND: A required input file is unavailable

    • NOWRITE: A required output file could not be written

    • OUTOFMEMORY : Not enough memory to provision \

Syntax

Status GenerateProvisionRequest(
    utilities::ProvisionFiles & io_files,
    const char * in_provisioning_component_handle,
    const char * in_provisioning_system,
    const char * in_hardware_identifier
)

StartProvisioningOnline()

The StartProvisioningOnline() function starts the online provisioning process to submit a provisioning request to Guardian Cloud. It submits the provisioning request and begins the automated processing workflow.

  • Dependencies: Must be run after GenerateProvisionRequest().

  • Parameters:

    • in_files: Files required for online provisioning

    • in_options: Additional optional provisioning configuration options, including timeouts

  • Returns: Status code indicating success or failure.

    • Success code: OK : Online provisioning was successfully started

    • Error codes:

      • FAIL : General failure starting provisioning. Check the log file for more information.

      • BADPARAM : One of the inputs is null or invalid

      • FILENOTFOUND : A required provisioning file is unavailable

Syntax

Status StartProvisioningOnline(
    const utilities::ProvisionOnlineFiles & in_files,
    const ProvisioningOptions & in_options
)

Run()

  • Description:

    • Executes Guardian background tasks including provisioning state machine processing.

    • Includes provisioning, telemetry, handshakes, authentication, services, sessions, and channels that have not been placed or had a parent placed on another thread by CreateTask. This should be called by the program/thread's main loop.

    • Must be called regularly and repeatedly during online provisioning.

    • Use IsProvisioningRunning() to check when provisioning is complete and stop calling Run().

    • Processes internal state machines and handles communication with Guardian Cloud

  • Dependencies:

    • Must be called after StartProvisioningOnline()

  • Parameters: No parameters

  • Returns: Status code indicating success or failure.

    • Success code: OK - Background tasks executed successfully

    • Error codes:

      • FAIL - General failure in background processing. Check the log file for more information.

      • SHUTDOWN : Guardian is in a shutdown state and must be reinitialized before calling run again.

IsProvisioningRunning()

  • Description: Checks whether the provisioning process is still active.

  • Dependencies:

    • Must be called after StartProvisioningOnline()

    • Used to determine when to stop calling Run() and attempt to retrieve the provisioned profile.

  • Parameters: None - this function takes no parameters

  • Returns: Boolean value indicating provisioning status

    • true - Provisioning is still in progress. Continue calling Run()

    • false - Provisioning has completed (successfully or failed). You should now call GetProvisionedProfile().

    • Before the online provisioning process has started, will return false.

    • After online provisioning has either succeeded or failed, will again return false.

Syntax

bool IsProvisioningRunning()

GetProvisionedProfile()

  • Description:

    • Extracts the provisioned profile after successful online provisioning.

    • Copies completed provisioned profile to provided buffer.

  • Dependencies:

    • Must be called only after IsProvisioningRunning() returns false.

    • Requires successful completion of StartProvisioningOnline() and Run() loop

  • Parameters:

    • out_profile: Buffer that will receive the provisioned profile.

      • Type: char

    • io_size:

      • Provide size of buffer ( out_profile ) on input. After successful provisioning, out_profile sets to actual size of profile.

      • Type: size_t

  • Returns: Status code indicating success or failure.

    • Success code: OK : Provisioned profile successfully retrieved.

      • Buffer contains a valid certified profile in out_profile of size io_size.

    • Error codes:

      • FAIL : General failure. Check the log file for more information.

      • INCOMPLETE : Provisioning process did not complete, thus no profile is available.

      • BADPARAM - out_profile or io_size is null pointer (nullptr), or io_size is 0

      • DENIED - Online provisioning process is still running

      • FILENOTFOUND - Provisioning is complete but no provisioned profile is available

      • BADPARAM - Buffer or size parameter is invalid

Syntax

Status GetProvisionedProfile(
    char * out_profile,
    size_t * io_size
)

Implementation examples

Certificate management functions

GetCertificateManager()

  • Description: Retrieves the certificate manager for handling device certificates. Provides access to certificate operations and lifecycle management.

  • Dependencies:

    • Can optionally be called after Initialize()

  • Parameters:

    • out_certificate_manager: Output pointer to receive the certificate manager instance

  • Returns: Status code indicating success or failure.

    • Success code: OK :

      • Certificate manager successfully retrieved

      • The pointer in out_certificate_manager is valid

    • Error codes:

      • FAIL : General failure. Check the log file for more information.

      • BADPARAM : out_certificate_manager is a null pointer and cannot be filled

      • DENIED : Guardian is not initialized

      • MISCONFIGURED : The loaded provisioned profile is not configured to allow certificate operations.

  • Action:

    • Use the retrieved certificate manager to import and export certificates.

Syntax

Status GetCertificateManager(
    std::unique_ptr< CertificateManager > * out_certificate_manager
)

GetProvisionedRevocationList()

  • Description:

    • Retrieves the certificate revocation list (CRL) for checking certificate validity.

    • Used to identify revoked certificates that should no longer be trusted.

  • Dependencies:

    • Can optionally be called after successful provisioning (after GetProvisionedProfile())

  • Parameters:

    • out_ccrl: Buffer to receive the certificate revocation list

      • Type: char*

    • io_size: Size of buffer on input, actual size on output

      • Provide size of buffer ( out_ccrl ) on input. After successful provisioning, out_ccrl sets to actual size of CRL.

      • Type: size_t

  • Returns: Status code indicating success or failure.

    • Success code: OK

      • out_ccrl has a valid revocation list of size io_size

    • Error codes:

      • FAIL - General failure. Check the log file for more information.

      • INCOMPLETE - Provisioning process did not complete, no revocation list available

      • BADPARAM : out_ccrl or io_size is null pointer, or io_size is 0

      • DENIED - Online provisioning process is still running

      • FILENOTFOUND - Provisioning is complete but no revocation list is available

  • Action: Copies certificate revocation list to provided buffer

Syntax

Status GetProvisionedRevocationList(
    char * out_ccrl,
    size_t * io_size
)

Security operations function

FindSecureOperation()

  • Description:

    • Perform lookup for secure operation name.

    • Get secure operation handler for signing and verification operations.

  • Dependencies:

    • Can optionally be called after Initialize()

  • Parameters:

    • in_secureop_name: Secure operation name, terminated by null.

      • Type: const char*

    • out_secureop: Pointer to unique_ptr storage for located secure operation

  • Returns: Status code indicating success or failure.

  • Success code: OK : The pointer in out_secureop is valid

  • Error codes:

    • FAIL : Could not find the operation specified by in_secureop_name

    • BADPARAM : out_secureop is null pointer and cannot be filled

    • DENIED : Guardian is not initialized

  • Action:

    • Sets out_secureop to the located operation

    • Will not modify out_secureop if the operation in_secureop_name is not located

Syntax

Status FindSecureOperation(
    const char * in_secureop_name,
    std::unique_ptr< SecureOperation > * out_secureop
)

Service management functions

FindService()

  • Description:

    • Performs lookup for service name to locate a configured service.

  • Dependencies:

    • Must be called after Initialize()

  • Parameters:

    • in_service_name: Service name, terminated by null

      • Type: const char*

    • out_service: Pointer to unique_ptr storage for found service

  • Returns: Status code indicating success or failure.

    • Success code: OK : The pointer in out_service is valid

    • Error codes:

      • FAIL : Could not find the service specified by in_service_name

      • BADPARAM : out_service is null pointer and cannot be filled

      • DENIED : Guardian is not initialized

  • Action:

    • Sets out_service to the located service

    • Will not modify out_service if the service in in_service_name is not located

    • or leaves unmodified if the service is not found

Syntax

Status FindService(
    const char * in_service_name,
    std::unique_ptr< Service > * out_service
)

CreateTask() - Service variant

  • Description:

    • Create a task for service operations that separates the provided object and all children from Run.

    • Allows for threading of separate objects by removing them from the main Guardian Run loop.

  • Dependencies:

    • Must be called after Initialize()

    • Service object must be valid

  • Parameters:

    • io_service: Service component to place on a thread, will be consumed on success, unmodified on failure

    • out_task: Pointer to unique_ptr storage for the task

  • Returns: Status code indicating success or failure.

    • Success code: OK : out_task has a valid task

    • Error codes:

      • FAIL : General failure. Check the log file for more information.

      • BADPARAM : io_service or out_task is null pointer

      • DENIED : Specified service is already in a task

  • Action: A component placed on a Task along with all children will not run when Guardian Run is called, allowing for threading of separate objects

Syntax

Status CreateTask(
    std::unique_ptr< Service > * io_service,
    std::unique_ptr< Task > * out_task
)

CreateTask() - Session variant

  • Description:

    • Create a task for service operations that separates the provided object and all children from Run.

    • Allows for threading of separate objects by removing them from the main Run loop.

  • Dependencies:

    • Can optionally be called after Initialize()

    • Service object must be valid

  • Parameters:

    • io_service: Service component to place on a thread. This will be consumed on success, but not modified if not successful.

    • out_task: Pointer to unique_ptr storage for the task

  • Returns: Status code indicating success or failure.

    • Success code: OK : out_task has a valid task

    • Error codes:

      • FAIL : General failure. Check the log file for more information.

      • BADPARAM : io_service or out_task is null pointer

      • DENIED : Specified service is already in a task

  • Action:

    • A component placed on a Task along with all children will not run when Run is called, allowing for threading of separate objects.

    • To return an object to the main Run loop, destroy the unique_ptr.

Syntax

Status CreateTask(
    std::unique_ptr< Session > * io_session,
    std::unique_ptr< Task > * out_task
)

CreateTask() - ChannelGuard Variant

  • Description:

    • Create a task for channel operations that separates the provided object and all children from Run().

    • Allows for threading of separate objects by removing them from the main Run() loop.

  • Dependencies:

    • Must be called after Initialize()

    • ChannelGuard object must be valid

  • Parameters:

    • io_channelguard: ChannelGuard component to place on a thread

    • out_task: Pointer to unique_ptr storage for the task

  • Returns: Status code indicating success or failure.

    • Success code: OK : out_task has a valid task

    • Error codes:

      • FAIL : General failure. Check the log file for more information.

      • BADPARAM : io_channelguard or out_task is null pointer

      • DENIED : Specified ChannelGuard is already in a task and has not been returned

  • Action:

    • A component placed on a Task along with all children will not run when Run() is called, allowing for threading of separate objects.

    • To return an object to the main Run() loop, destroy the unique_ptr.

Syntax

Status CreateTask(
    std::unique_ptr< ChannelGuard > * io_channelguard,
    std::unique_ptr< Task > * out_task
)

System management functions

GetAuthenticationManager()

  • Description:

    • Retrieve the running authentication manager.

    • Provides access to authentication operations and allow/deny lists for user-managed connections.

  • Dependencies:

    • Can optionally be called after Initialize()

  • Parameters:

    • out_authentication_manager: Pointer to unique_ptr storage for authentication manager

  • Returns: Status code indicating success or failure.

    • Success code: OK : The pointer in out_authentication_manager is valid

    • Error codes:

      • FAIL : General failure. Check the log file for more information.

      • BADPARAM : out_authentication_manager is null pointer and cannot be filled

      • DENIED : Guardian is not initialized

      • MISCONFIGURED : The loaded profile is not configured to allow external authentication operations

  • Action: Use the retrieved authentication manager to get allow/deny lists for user managed connections

Syntax

Status GetAuthenticationManager(
    std::unique_ptr< AuthenticationManager > * out_authentication_manager
)

GetTelemetryManager()

  • Description:

    • Retrieve the running telemetry manager.

    • Provides access to telemetry service interactions.

  • Dependencies:

    • Can optionally be called after Initialize()

  • Parameters:

    • out_telemtry_manager: Pointer to unique_ptr storage for telemetry manager

  • Returns: Status code indicating success or failure.

    • Success code: OK : The pointer in out_telemtry_manager is valid

    • Error codes:

      • FAIL : General failure. Check the log file for more information.

      • BADPARAM : out_telemtry_manager is null pointer and cannot be filled

      • DENIED : Guardian is not initialized or there is no telemetry manager running

      • MISCONFIGURED : The loaded profile is not configured for telemetry

  • Action: Use the retrieved telemetry manager to interact with the telemetry service

Syntax

Status GetTelemetryManager(
    std::unique_ptr< Telemetry > * out_telemtry_manager
)

~Guardian()

  • Description: The destructor attempts a graceful shutdown of Guardian.

  • Dependencies: None - destructor is automatically called when object goes out of scope or is explicitly deleted

  • Parameters: None - destructor takes no parameters

  • Returns: Nothing since it is a destructor.

  • Action: The destructor will attempt to call Shutdown() for a graceful shutdown, then Guardian will destruct.

Syntax

~Guardian()

Shutdown()

  • Description:

    • Attempts to stop all internal state machines, shutting down Guardian.

    • Includes provisioning, telemetry, handshakes, authentication, services, sessions, and channels, INCLUDING those that have been placed or had a parent placed on another thread by CreateTask.

  • Dependencies:

    • Can optionally be called after Initialize()

    • If there is data waiting to be sent it will return a failure code or require in_force

  • Parameters:

    • in_force: Drop all queued send data and shut down. Default value is false.

  • Returns: Status code indicating success or failure.

    • Success code: OK : Guardian is shut down successfully

    • Error codes:

      • FAIL : General failure. Check the log file for more information.

      • AGAIN : One or more transports has queued data to send

  • Action: Stops all internal state machines including provisioning, telemetry, handshakes, authentication, services, sessions, and channels.

Syntax

Status Shutdown(
    const bool & in_force =false
)

The medcrypt namespace contains the guardian namespace, which includes the following classes and structures.

Core classes

  • Guardian class:

    • Description: Root of Guardian system.

    • Location: medcrypt::guardian::Guardian

  • AuthenticationManager class:

    • Description: Container for authentication restrictions.

    • Location: medcrypt::guardian::AuthenticationManager

  • ChannelGuard class:

    • Description: Name channel within a Session.

    • Location: medcrypt::guardian::ChannelGuard

  • SecureOperation class:

    • Description: Named standalone operation.

    • Location: medcrypt::guardian::SecureOperation

  • Service class:

    • Description: Named group of connection and channel configurations.

    • Location: medcrypt::guardian::Service

  • Session class:

    • Description: Individual connection within a Service.

    • Location: medcrypt::guardian::Session

  • Task class:

    • Description: Multithreading container.

    • Location: medcrypt::guardian::Task

  • TransportInterface class:

    • Description: ConfigureTransport() required interface.

    • Location: medcrypt::guardian::TransportInterface

Data structures

Utility namespace & structures

The guardian namespace also includes the utilities namespace, which includes the following structures:

Other namespaces

  • AuthenticationAllowDenyEnum namespace:

    • Description: Determines whether a specified list is in an allow or deny list.

    • Location: medcrypt::guardian::AuthenticationAllowDenyEnum

  • GuardianStatusEnum namespace:

    • Description: Status codes returned by Guardian functions.

    • Location: medcrypt::guardian::GuardianStatusEnum

  • LogLevelEnum namespace:

    • Description: Log levels returned by Guardian functions.

    • Location: medcrypt::guardian::LogLevelEnum

Last updated

Was this helpful?