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 filesin_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 createdError codes:
FAIL
: General failure. Check the log file for more information.BADPARAM
: One of the inputs is null or emptyFILENOTFOUND
: A required input file is unavailableNOWRITE
: A required output file could not be writtenOUTOFMEMORY
: 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 provisioningin_options
: Additional optional provisioning configuration options, including timeouts
Returns: Status code indicating success or failure.
Success code:
OK
: Online provisioning was successfully startedError codes:
FAIL
: General failure starting provisioning. Check the log file for more information.BADPARAM
: One of the inputs is null or invalidFILENOTFOUND
: 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 successfullyError 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 sizeio_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
orio_size
is null pointer (nullptr
), orio_size
is 0DENIED
- Online provisioning process is still runningFILENOTFOUND
- Provisioning is complete but no provisioned profile is availableBADPARAM
- 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 filledDENIED
: Guardian is not initializedMISCONFIGURED
: 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 listType:
char*
io_size
: Size of buffer on input, actual size on outputProvide 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 sizeio_size
Error codes:
FAIL
- General failure. Check the log file for more information.INCOMPLETE
- Provisioning process did not complete, no revocation list availableBADPARAM
:out_ccrl
orio_size
is null pointer, orio_size
is 0DENIED
- Online provisioning process is still runningFILENOTFOUND
- 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 tounique_ptr
storage for located secure operation
Returns: Status code indicating success or failure.
Success code:
OK
: The pointer inout_secureop
is validError codes:
FAIL
: Could not find the operation specified byin_secureop_name
BADPARAM
:out_secureop
is null pointer and cannot be filledDENIED
: Guardian is not initialized
Action:
Sets
out_secureop
to the located operationWill not modify
out_secureop
if the operationin_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 nullType:
const char*
out_service
: Pointer to unique_ptr storage for found service
Returns: Status code indicating success or failure.
Success code:
OK
: The pointer inout_service
is validError codes:
FAIL
: Could not find the service specified byin_service_name
BADPARAM
:out_service
is null pointer and cannot be filledDENIED
: Guardian is not initialized
Action:
Sets
out_service
to the located serviceWill not modify
out_service
if the service inin_service_name
is not locatedor 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 failureout_task
: Pointer to unique_ptr storage for the task
Returns: Status code indicating success or failure.
Success code:
OK
: out_task has a valid taskError codes:
FAIL
: General failure. Check the log file for more information.BADPARAM
: io_service or out_task is null pointerDENIED
: 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 tounique_ptr
storage for the task
Returns: Status code indicating success or failure.
Success code:
OK
:out_task
has a valid taskError codes:
FAIL
: General failure. Check the log file for more information.BADPARAM
:io_service
orout_task
is null pointerDENIED
: 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 theunique_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 threadout_task
: Pointer tounique_ptr
storage for the task
Returns: Status code indicating success or failure.
Success code:
OK
:out_task
has a valid taskError codes:
FAIL
: General failure. Check the log file for more information.BADPARAM
:io_channelguard
orout_task
is null pointerDENIED
: SpecifiedChannelGuard
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 tounique_ptr
storage for authentication manager
Returns: Status code indicating success or failure.
Success code:
OK
: The pointer inout_authentication_manager
is validError codes:
FAIL
: General failure. Check the log file for more information.BADPARAM
:out_authentication_manager
is null pointer and cannot be filledDENIED
: Guardian is not initializedMISCONFIGURED
: 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 tounique_ptr
storage for telemetry manager
Returns: Status code indicating success or failure.
Success code:
OK
: The pointer inout_telemtry_manager
is validError codes:
FAIL
: General failure. Check the log file for more information.BADPARAM
:out_telemtry_manager
is null pointer and cannot be filledDENIED
: Guardian is not initialized or there is no telemetry manager runningMISCONFIGURED
: 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 isfalse
.
Returns: Status code indicating success or failure.
Success code:
OK
: Guardian is shut down successfullyError 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
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
Last updated
Was this helpful?