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:

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.

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

AuthenticationDomain struct:
- Description: Authentication restriction container. Restrictions for use by an authentication agent.
- Location: medcrypt::guardian::AuthenticationDomain
InitializeOptions struct:
- Description: Options used by Initialize() during setup.
- Location: medcrypt::guardian::InitializeOptions
ProvisioningOptions struct:
- Description: Options used by StartProvisioningOnline().
- Location: medcrypt::guardian::ProvisioningOptions

Utility namespace & structures

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

InitializeFiles struct:
- Description: Storage for initialization files used by Initialize().
- Location: medcrypt::guardian::utilities::InitializeFiles
ProvisionFiles struct:
- Description: Storage for generating provision request files in GenerateProvisionRequest().
- Location: medcrypt::guardian::utilities::ProvisionFiles
ProvisionOnlineFiles struct:
- Description: Storage for online provisioning files in StartProvisioningOnline().
- Location: medcrypt::guardian::utilities::ProvisionOnlineFiles

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

PreviousExtract certificates from provisioned devices NextAPI reference

Last updated 3 months ago

Was this helpful?