medcrypt::guardian::Guardian

Overview

The Guardian class is the main interface for the Guardian security platform. It provides device provisioning, secure communication, and cryptographic operations for medical devices. It handles the following throughout the device lifecycle:

• Device identity establishment

• Secure connections

• Certificate management

Include

#include <Guardian.h>

Device provisioning functions

• Guardian : The constructor does no work besides initializing member variables.

• Initialize: Uses the provided profile, identity, and trust files to initialize the Guardian system.

• GenerateProvisionRequest: This is the first device provisioning step for the provisioning process.

• StartProvisioningOnline: Start the online device provisioning process.

• IsProvisioningRunning: Check if provisioning process is active.

• GetProvisionedProfile: Extract provisioned certified profile for device after successful device provisioning.

Certificate management functions

• GetCertificateManager: Retrieve the running certificate manager.

• GetProvisionedRevocationList: Retrieve certificate revocation list and populate into buffer.

Security operations functions

• FindSecureOperation: Perform a lookup to get secure operation handler for signing/verification

Service management functions

• FindService: Perform a service name lookup to locate a configured service.

• CreateTask: Create a task for service, session, or channel operations that separates the provided object and all children from Run.

System management functions

• GetAuthenticationManager: Retrieve the running authentication manager.

• GetTelemetryManager: Retrieve the running telemetry manager.

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

• Shutdown: Clean shutdown of Guardian

Device setup and provisioning workflow

Steps overview

Prerequisites: Create Guardian instance

Function: Guardian()

• Creates new Guardian instance

• First step before any other operations

• Initializes member variables and puts system in startup state

Step 1: Device setup

Function: Initialize()

• Must be called first after creating Guardian instance

• Sets up Guardian with initial configuration

• Required before any provisioning operations

Step 2: Generate provisioning request

Function: GenerateProvisionRequest()

• Creates provisioning request (.mcpr) and private identity (.mcpi) files

• Uses provisioning package to generate device keys

• Must be called once before any other provisioning actions

Step 3: Submit and process request

Function: StartProvisioningOnline()

• Initiates online provisioning state machine

• Submits provisioning request to Guardian Cloud

• Begins automated processing workflow

Step 4: Monitor provisioning and retrieve device's certified profile

Functions: Run(), IsProvisioningRunning(), GetProvisionedProfile()

• Run() : Executes background provisioning tasks

• IsProvisioningRunning() : Checks if provisioning process is still running

• GetProvisionedProfile() - Retrieve completed certified profile for device

Step 1: Run Guardian()

• Description:

  • Creates a new Guardian instance.

  • This is the first step before initializing Guardian with device credentials.

  • 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.

• Action: Gets Guardian instance into startup state, ready for initialization (m_p_guardian).

Syntax

Guardian()

Step 2: Run Initialize()

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

• Dependencies:

  • Must be called after creating a Guardian instance (Guardian() constructor).

  • Must be called before any other Guardian operations

• 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.

  • See also: All status codes

• Action: Sets up Guardian with device identity and prepares it for secure operations.

Syntax

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

Step 3: Run GenerateProvisionRequest()

• Description: Creates a provisioning request for device identity establishment.

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

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

  • Uses input files to generate a provisioning request and private identity

• 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

  • See also: All status codes

• Actions:

  • Generates device keys and creates provisioning request.

  • Will create a private identity ( PrivateIdentity ) for the device, as well as the device's provisioning request ( ProvisionRequest ).

    • The PrivateIdentity includes the generated device keys. This is the .mcpi file.

    • The ProvisionRequest can be manually uploaded to Guardian Cloud or sent using available online methods in the profile. This is the .mcpr file.

Syntax

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

Step 4: StartProvisioningOnline()

• Description: Starts the online provisioning process to submit a provisioning request to Guardian Cloud.

• 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

  • See also: All status codes

• Action: Starts internal provisioning state machine and begins communication with Guardian Cloud

Syntax

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

Step 5: Monitor provisioning and retrieve device's certified profile

Process overview:

1. Call Run() repeatedly to process provisioning tasks

2. Call IsProvisioningRunning() to check if provisioning is complete

3. When IsProvisioningRunning() returns false, call GetProvisionedProfile() to retrieve the certified profile

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().

• 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.

  • See also: All status codes

• Action: Processes internal state machines and handles communication with Guardian Cloud

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.

• Action: Indicates whether provisioning process is still active

Syntax

bool IsProvisioningRunning()

GetProvisionedProfile()

• Description:

  • Extracts the provisioned profile after successful online provisioning.

• 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

  • See also: All status codes

• Action: Copies completed provisioned profile to provided buffer.

Syntax

Status GetProvisionedProfile(
    char * out_profile,
    size_t * io_size
)

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.

  • See also: All status codes

• 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

  • See also: All status codes

• 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

• See also: All status codes

• 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

  • See also: All status codes

• 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

  • See also: All status codes

• 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

  • See also: All status codes

• 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

  • See also: All status codes

• 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

  • See also: All status codes

• 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
)

Retrieve the running 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

  • See also: All status codes

• 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

  • See also: All status codes

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

Syntax

Status Shutdown(
    const bool & in_force =false
)

Debugging and logging

Guardian does not create log files. Instead, logging is controlled by the application:

• Guardian logs to stdout and stderr, which appear in the terminal/CLI of the running application during execution. Look for specific error codes or connection failures in the output.

• Custom logging: Use SetLoggingCallback to redirect log messages to a callback function, stopping terminal output and allowing custom log handling

• Log control: Applications can control log level and verbosity.

• Guardian Cloud UI: Check the Guardian Cloud interface for additional error details and provisioning status.