# Example
./mcguard_cert_extract --component my_device --hardware-id my_device_001 --service my_service --key-dir /home/user/guardian/keys --cert-dir /home/user/guardian/certs /home/user/guardian/provisioned_profile
```
# 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:**
```cpp
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) (`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**
```cpp
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**
```cpp
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**
```cpp
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](#function-createtask). This should be called by the program/thread's main loop.
* Must be called regularly and repeatedly during online provisioning.
* Use [IsProvisioningRunning()](#function-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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
~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](#createtask-service-variant).
* **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**
```cpp
Status Shutdown(
const bool & in_force =false
)
```
The [medcrypt namespace ](/api-reference/api-reference/namespaces/namespacemedcrypt)contains the [guardian namespace](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian), which includes the following classes and structures.
## **Core classes**
* [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian) class:
* **Description:** Root of Guardian system.
* **Location:** medcrypt::guardian::Guardian
* [AuthenticationManager](/api-reference/api-reference/classes/classmedcrypt-guardian-authenticationmanager) class:
* **Description:** Container for authentication restrictions.
* **Location:** medcrypt::guardian::AuthenticationManager
* [ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard) class:
* **Description:** Name channel within a [Session](/api-reference/api-reference/classes/classmedcrypt-guardian-session).
* **Location:** medcrypt::guardian::ChannelGuard
* [SecureOperation](/api-reference/api-reference/classes/classmedcrypt-guardian-secureoperation) class:
* **Description:** Named standalone operation.
* **Location:** medcrypt::guardian::SecureOperation
* [Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service) class:
* **Description:** Named group of connection and channel configurations.
* **Location:** medcrypt::guardian::Service
* [Session](/api-reference/api-reference/classes/classmedcrypt-guardian-session) class:
* **Description:** Individual connection within a [Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service).
* **Location:** medcrypt::guardian::Session
* [Task](/api-reference/api-reference/classes/classmedcrypt-guardian-task) class:
* **Description:** Multithreading container.
* **Location:** medcrypt::guardian::Task
* [TransportInterface](/api-reference/api-reference/classes/classmedcrypt-guardian-transportinterface) class:
* **Description:** [ConfigureTransport()](/api-reference/api-reference/classes/classmedcrypt-guardian-service#function-configuretransport) required interface.
* **Location:** medcrypt::guardian::TransportInterface
## **Data structures**
* [AuthenticationDomain](/api-reference/api-reference/classes/structmedcrypt-guardian-authenticationdomain) struct:
* **Description:** Authentication restriction container. Restrictions for use by an authentication agent.
* **Location:** medcrypt::guardian::AuthenticationDomain
* [InitializeOptions](/api-reference/api-reference/classes/structmedcrypt-guardian-initializeoptions) struct:
* **Description:** Options used by [Initialize()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize) during setup.
* **Location:** medcrypt::guardian::InitializeOptions
* [ProvisioningOptions](/api-reference/api-reference/classes/structmedcrypt-guardian-provisioningoptions) struct:
* **Description:** Options used by [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline).
* **Location:** medcrypt::guardian::ProvisioningOptions
### Utility namespace & structures
The [guardian namespace](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian) also includes the [utilities](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities) namespace, which includes the following structures:
* [InitializeFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-initializefiles) struct:
* **Description:** Storage for initialization files used by [Initialize()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize).
* **Location:** medcrypt::guardian::utilities::InitializeFiles
* [ProvisionFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisionfiles) struct:
* **Description:** Storage for generating provision request files in [GenerateProvisionRequest()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-3-run-generateprovisionrequest).
* **Location:** medcrypt::guardian::utilities::ProvisionFiles
* [ProvisionOnlineFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisiononlinefiles) struct:
* **Description:** Storage for online provisioning files in [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline).
* **Location:** medcrypt::guardian::utilities::ProvisionOnlineFiles
## **Other namespaces**
* [AuthenticationAllowDenyEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum) namespace:
* **Description:** Determines whether a specified list is in an allow or deny list.
* **Location:** medcrypt::guardian::AuthenticationAllowDenyEnum
* [GuardianStatusEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum) namespace:
* **Description:** Status codes returned by Guardian functions.
* **Location:** medcrypt::guardian::GuardianStatusEnum
* [LogLevelEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum) namespace:
* **Description:** Log levels returned by Guardian functions.
* **Location:** medcrypt::guardian::LogLevelEnum
# API reference
## Frequently Used References
{% content-ref url="/pages/-MD0rw0qMat4rv0A8KkC" %}
[medcrypt::guardian::Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian)
{% endcontent-ref %}
{% content-ref url="/pages/-MD0rw0rvf8xwC5NyFm3" %}
[medcrypt::guardian::Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service)
{% endcontent-ref %}
{% content-ref url="/pages/-MD0rw0swjxc7ttgDQEp" %}
[medcrypt::guardian::Session](/api-reference/api-reference/classes/classmedcrypt-guardian-session)
{% endcontent-ref %}
{% content-ref url="/pages/-MD0rw0tIPg5W3RM6Lnr" %}
[medcrypt::guardian::ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard)
{% endcontent-ref %}
{% content-ref url="/pages/-MD0rw0ukks2kY9K3ns-" %}
[medcrypt::guardian::SecureOperation](/api-reference/api-reference/classes/classmedcrypt-guardian-secureoperation)
{% endcontent-ref %}
# Namespaces
* **namespace** [**medcrypt**](/api-reference/api-reference/namespaces/namespacemedcrypt)
* **namespace** [**guardian**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian)
* **namespace** [**AuthenticationAllowDenyEnum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum)
* **namespace** [**GuardianStatusEnum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **namespace** [**LogLevelEnum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum)
* **namespace** [**utilities**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities)
# medcrypt
## Namespaces
| Name |
| -------------------------------------------------------------------------------------------- |
| [**medcrypt::guardian**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian) |
# medcrypt::guardian
## Namespaces
| Name |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**medcrypt::guardian::AuthenticationAllowDenyEnum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum) |
| [**medcrypt::guardian::GuardianStatusEnum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum) |
| [**medcrypt::guardian::LogLevelEnum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum) |
| [**medcrypt::guardian::utilities**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities) |
## Classes
| | Name |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| struct | medcrypt::guardian::AuthenticationDomain
Authentication restriction container. Restrictions for use by an authentication agent.
|
| class | medcrypt::guardian::AuthenticationManager
Container for authentication restrictions.
|
| class | medcrypt::guardian::ChannelGuard
Name channel within a Session.
|
| class | medcrypt::guardian::Guardian
Root of guardian system.
|
| struct | medcrypt::guardian::InitializeOptions
Options used by Guardian::Initialize.
|
| struct | medcrypt::guardian::ProvisioningOptions
Options used by Guardian::StartProvisioningOnline.
|
| class | medcrypt::guardian::SecureOperation
Named standalone operation.
|
| class | medcrypt::guardian::Service
Named group of connection and channel configurations.
|
| class | medcrypt::guardian::Session
Individual connection within a Service.
|
| class | medcrypt::guardian::Task
Multithreading container.
|
| class | medcrypt::guardian::TransportInterface
Service::ConfigureTransport required interface.
|
## Types
| | Name |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| typedef uint32\_t | [**Status**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian#typedef-status) |
## Types Documentation
### typedef Status
```cpp
typedef uint32_t medcrypt::guardian::Status;
```
# medcrypt::guardian::AuthenticationAllowDenyEnum
## Types
| | Name |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| enum | [**Type**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum#enum-type) { Allow = 0, Deny = 1 } |
## Functions
| | Name |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| std::string | [**NameOf**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum#function-nameof)(const [Type](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum#enum-type) & in\_enum) |
| [Type](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum#enum-type) | [**Enum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum#function-enum)(const std::string & in\_string) |
| bool | [**IsValid**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum#function-isvalid)(const int & in\_value) |
## Types Documentation
### enum Type
| Enumerator | Value | Description |
| ---------- | ----- | --------------------------------------------------------- |
| Allow | 0 | specified list is an allow list, an empty list blocks all |
| Deny | 1 | specified list is a deny list, an empty list allows all |
## Functions Documentation
### function NameOf
```cpp
std::string NameOf(
const Type & in_enum
)
```
### function Enum
```cpp
Type Enum(
const std::string & in_string
)
```
### function IsValid
```cpp
bool IsValid(
const int & in_value
)
```
# medcrypt::guardian::GuardianStatusEnum
## Types
| | Name |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enum | [**Type**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum#enum-type) { OK = 0x00, FAIL = 0x01, BADPARAM = 0x02, MISCONFIGURED = 0x03, INCOMPLETE = 0x04, DENIED = 0x05, BADINIT = 0x06, PROTOCOL = 0x07, OUTOFMEMORY = 0x08, VERIFYFAIL = 0x09, FILENOTFOUND = 0x0A, ZEROSIZEFILE = 0x0B, NOWRITE = 0x0C, SHUTDOWN = 0x0D, AGAIN = 0x0E, HANDSHAKEREQUIRED = 0x0F, TIMEOUT = 0x10, BINDFAIL = 0x11 } |
## Functions
| | Name |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| std::string | [**NameOf**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum#function-nameof)(const [Type](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum#enum-type) & in\_enum) |
| [Type](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum#enum-type) | [**Enum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum#function-enum)(const std::string & in\_string) |
| bool | [**IsValid**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum#function-isvalid)(const int & in\_value) |
## Types Documentation
### enum Type
| Enumerator | Value | Description |
| ----------------- | ----- | -------------------------------------- |
| OK | 0x00 | call completed successfully |
| FAIL | 0x01 | call completed unsuccessfully |
| BADPARAM | 0x02 | issue with provided parameter |
| MISCONFIGURED | 0x03 | a configuration blocked the call |
| INCOMPLETE | 0x04 | the process started but did not finish |
| DENIED | 0x05 | operation not allowed |
| BADINIT | 0x06 | call on non-initialized object |
| PROTOCOL | 0x07 | guardian protocol error |
| OUTOFMEMORY | 0x08 | not enough memory |
| VERIFYFAIL | 0x09 | signature verification failed |
| FILENOTFOUND | 0x0A | could not read all necessary files |
| ZEROSIZEFILE | 0x0B | provided file is zero length |
| NOWRITE | 0x0C | could not write file |
| SHUTDOWN | 0x0D | the object is shutdown |
| AGAIN | 0x0E | non-blocking call, try again |
| HANDSHAKEREQUIRED | 0x0F | complete handshake before retry |
| TIMEOUT | 0x10 | the process timed out |
| BINDFAIL | 0x11 | could not bind to socket or handle |
## Functions Documentation
### function NameOf
```cpp
std::string NameOf(
const Type & in_enum
)
```
### function Enum
```cpp
Type Enum(
const std::string & in_string
)
```
### function IsValid
```cpp
bool IsValid(
const int & in_value
)
```
# medcrypt::guardian::LogLevelEnum
## Types
| | Name |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enum | [**Type**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum#enum-type) { Critical = 0, Error, Warn, Info, Debug, Trace } |
## Functions
| | Name |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| std::string | [**NameOf**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum#function-nameof)(const [Type](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum#enum-type) & in\_enum) |
| [Type](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum#enum-type) | [**Enum**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum#function-enum)(const std::string & in\_string) |
| bool | [**IsValid**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum#function-isvalid)(const int & in\_value) |
## Types Documentation
### enum Type
| Enumerator | Value | Description |
| ---------- | ----- | ---------------------------------------- |
| Critical | 0 | probable crash |
| Error | | could not complete requested action |
| Warn | | action completed with unexpected outcome |
| Info | | relevant information |
| Debug | | debug output, debug builds only |
| Trace | | trace output, internal builds only |
## Functions Documentation
### function NameOf
```cpp
std::string NameOf(
const Type & in_enum
)
```
### function Enum
```cpp
Type Enum(
const std::string & in_string
)
```
### function IsValid
```cpp
bool IsValid(
const int & in_value
)
```
# medcrypt::guardian::utilities
## Classes
| | Name |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| struct | medcrypt::guardian::utilities::InitializeFiles
Storage for initialization files used by Guardian::Initialize.
|
| struct | medcrypt::guardian::utilities::ProvisionFiles
Storage for generating provision request files in Guardian::GenerateProvisionRequest.
|
| struct | medcrypt::guardian::utilities::ProvisionOnlineFiles
Storage for online provisioning files in Guardian::StartProvisioningOnline.
|
## Functions
| | Name |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bool | GetInitializeFilesFromPath(const std::string & in\_filespath, const bool & in\_use\_provision\_files, InitializeFiles \* io\_files, const std::string & in\_prefix ="")
Populate file buffers required by Guardian::Initialize from path.
|
| void | DeleteInitializeFileBuffers(InitializeFiles \* io\_files)
Delete dynamic memroy in created by GetInitializeFilesFromPath()
|
| bool | GetProvisionFilesFromPath(const std::string & in\_filespath, const bool & in\_use\_provision\_files, ProvisionFiles \* io\_files, const std::string & in\_prefix ="")
Populate file buffers required by Guardian::GenerateProvisionRequest from path.
|
| void | DeleteProvisionFileBuffers(ProvisionFiles \* io\_files)
Delete dynamic memroy in created by GetProvisionFilesFromPath()
|
## Attributes
| | Name |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| const char | [**kRequestExtension**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#variable-krequestextension) |
| const char | [**kProfileExtension**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#variable-kprofileextension) |
| const char | [**kRunProfileExtension**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#variable-krunprofileextension) |
| const char | [**kIdentityExtension**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#variable-kidentityextension) |
| const char | [**kRunIdentityExtension**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#variable-krunidentityextension) |
| const char | [**kTrustExtension**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#variable-ktrustextension) |
| const char | [**kRevocationExtension**](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#variable-krevocationextension) |
## Functions Documentation
### function GetInitializeFilesFromPath
```cpp
static inline bool GetInitializeFilesFromPath(
const std::string & in_filespath,
const bool & in_use_provision_files,
InitializeFiles * io_files,
const std::string & in_prefix =""
)
```
Populate file buffers required by [Guardian::Initialize](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/classmedcrypt-guardian-Guardian.md#function-initialize) from path.
**Parameters**:
* **in\_filespath** absolute or working directory relative path to profile files
* **in\_use\_provision\_files** used to return provisioning profiles for initializing to run online provisioning
* **io\_files** file structure to populate
* **in\_prefix** prefix that each found file is required to have, allows multiple profile sets in the same folder separated by file prefix
**Returns**:
* **true** io\_files populated successfully
* **false** io\_files not populated
**Return**: bool
Searches for files in in\_filepath with prefix in\_prefix. Sorts alphanumerically after applying prefix and uses the first result.
Note: This function creates memory in [InitializeFiles](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md) char\* buffers using new\[], its paired [DeleteInitializeFileBuffers()](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#function-deleteinitializefilebuffers) function will delete the created dynamic memory.
### function DeleteInitializeFileBuffers
```cpp
static inline void DeleteInitializeFileBuffers(
InitializeFiles * io_files
)
```
Delete dynamic memroy in created by [GetInitializeFilesFromPath()](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#function-getinitializefilesfrompath)
**Parameters**:
* **io\_files** file structure to clean up
**Return**: none
Calls delete\[] on all [InitializeFiles](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md) char\* buffers.
### function GetProvisionFilesFromPath
```cpp
static inline bool GetProvisionFilesFromPath(
const std::string & in_filespath,
const bool & in_use_provision_files,
ProvisionFiles * io_files,
const std::string & in_prefix =""
)
```
Populate file buffers required by [Guardian::GenerateProvisionRequest](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/classmedcrypt-guardian-Guardian.md#function-generateprovisionrequest) from path.
**Parameters**:
* **in\_filespath** absolute or working directory relative path to profile files
* **in\_use\_provision\_files** used to return provisioning profiles, usually should be true
* **io\_files** file structure to populate
* **in\_prefix** prefix that each found file is required to have, allows multiple profile sets in the same folder separated by file prefix
**Returns**:
* **true** io\_files populated successfully
* **false** io\_files not populated
**Return**: bool
Searches for files in in\_filepath with prefix in\_prefix. Sorts alphanumerically after applying prefix and uses the first result.
Note: This function creates memory in [ProvisionFiles](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-ProvisionFiles.md) char\* buffers using new\[], its paired [DeleteProvisionFileBuffers()](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#function-deleteprovisionfilebuffers) function will delete the created dynamic memory.
Note: This function does not create memory for outputs [ProvisionFiles::ProvisionRequest](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-ProvisionFiles.md#variable-provisionrequest) or [ProvisionFiles::GeneratedPrivateIdentity](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-ProvisionFiles.md#variable-generatedprivateidentity)
### function DeleteProvisionFileBuffers
```cpp
static inline void DeleteProvisionFileBuffers(
ProvisionFiles * io_files
)
```
Delete dynamic memroy in created by [GetProvisionFilesFromPath()](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities#function-getprovisionfilesfrompath)
**Parameters**:
* **io\_files** file structure to clean up
**Return**: none
Calls delete\[] on all [ProvisionFiles](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-ProvisionFiles.md) char\* buffers except for outputs [ProvisionFiles::ProvisionRequest](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-ProvisionFiles.md#variable-provisionrequest) and [ProvisionFiles::GeneratedPrivateIdentity](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-ProvisionFiles.md#variable-generatedprivateidentity)
## Attributes Documentation
### variable kRequestExtension
```cpp
static const char kRequestExtension = ".mcpr";
```
Provision request file extension
### variable kProfileExtension
```cpp
static const char kProfileExtension = ".mcpp";
```
Certified provisioning profile file extension
### variable kRunProfileExtension
```cpp
static const char kRunProfileExtension = ".mcp";
```
Certified profile file extension
### variable kIdentityExtension
```cpp
static const char kIdentityExtension = ".mcpip";
```
Provisioning private identity file extension
### variable kRunIdentityExtension
```cpp
static const char kRunIdentityExtension = ".mcpi";
```
Private identity file extension
### variable kTrustExtension
```cpp
static const char kTrustExtension = ".mcts";
```
Trust store file extension
### variable kRevocationExtension
```cpp
static const char kRevocationExtension = ".mccrl";
```
Certificate revocation list file extension
# Classes
The [medcrypt namespace ](/api-reference/api-reference/namespaces/namespacemedcrypt)contains the [guardian namespace](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian), which includes the following classes, structures, and enumerations:
## **Core classes**
* [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian) class:
* **Description:** Root of Guardian system.
* **Location:** medcrypt::guardian::Guardian
* [AuthenticationManager](/api-reference/api-reference/classes/classmedcrypt-guardian-authenticationmanager) class:
* **Description:** Container for authentication restrictions.
* **Location:** medcrypt::guardian::AuthenticationManager
* [ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard) class:
* **Description:** Name channel within a [Session](/api-reference/api-reference/classes/classmedcrypt-guardian-session).
* **Location:** medcrypt::guardian::ChannelGuard
* [SecureOperation](/api-reference/api-reference/classes/classmedcrypt-guardian-secureoperation) class:
* **Description:** Named standalone operation.
* **Location:** medcrypt::guardian::SecureOperation
* [Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service) class:
* **Description:** Named group of connection and channel configurations.
* **Location:** medcrypt::guardian::Service
* [Session](/api-reference/api-reference/classes/classmedcrypt-guardian-session) class:
* **Description:** Individual connection within a [Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service).
* **Location:** medcrypt::guardian::Session
* [Task](/api-reference/api-reference/classes/classmedcrypt-guardian-task) class:
* **Description:** Multithreading container.
* **Location:** medcrypt::guardian::Task
* [TransportInterface](/api-reference/api-reference/classes/classmedcrypt-guardian-transportinterface) class:
* **Description:** [ConfigureTransport()](/api-reference/api-reference/classes/classmedcrypt-guardian-service#function-configuretransport) required interface.
* **Location:** medcrypt::guardian::TransportInterface
## **Data structures**
* [AuthenticationDomain](/api-reference/api-reference/classes/structmedcrypt-guardian-authenticationdomain) struct:
* **Description:** Authentication restriction container. Restrictions for use by an authentication agent.
* **Location:** medcrypt::guardian::AuthenticationDomain
* [InitializeOptions](/api-reference/api-reference/classes/structmedcrypt-guardian-initializeoptions) struct:
* **Description:** Options used by [Initialize()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize) during setup.
* **Location:** medcrypt::guardian::InitializeOptions
* [ProvisioningOptions](/api-reference/api-reference/classes/structmedcrypt-guardian-provisioningoptions) struct:
* **Description:** Options used by [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline).
* **Location:** medcrypt::guardian::ProvisioningOptions
### Utility namespace & structures
The [guardian namespace](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian) also includes the [utilities](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-utilities) namespace, which includes the following structures:
* [InitializeFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-initializefiles) struct:
* **Description:** Storage for initialization files used by [Initialize()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize).
* **Location:** medcrypt::guardian::utilities::InitializeFiles
* [ProvisionFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisionfiles) struct:
* **Description:** Storage for generating provision request files in [GenerateProvisionRequest()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-3-run-generateprovisionrequest).
* **Location:** medcrypt::guardian::utilities::ProvisionFiles
* [ProvisionOnlineFiles](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisiononlinefiles) struct:
* **Description:** Storage for online provisioning files in [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline).
* **Location:** medcrypt::guardian::utilities::ProvisionOnlineFiles
## **Other namespaces**
* [AuthenticationAllowDenyEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-authenticationallowdenyenum) namespace:
* **Description:** Determines whether a specified list is in an allow or deny list.
* **Location:** medcrypt::guardian::AuthenticationAllowDenyEnum
* [GuardianStatusEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum) namespace:
* **Description:** Status codes returned by Guardian functions.
* **Location:** medcrypt::guardian::GuardianStatusEnum
* [LogLevelEnum](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-loglevelenum) namespace:
* **Description:** Log levels returned by Guardian functions.
* **Location:** medcrypt::guardian::LogLevelEnum
# medcrypt::guardian::AuthenticationDomain
Authentication restriction container. Restrictions for use by an authentication agent.
`#include `
## Public Attributes
| | Name |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| std::string | [**service\_name**](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-AuthenticationDomain.md#variable-service_name) |
| std::string | [**domain**](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-AuthenticationDomain.md#variable-domain) |
| [AuthenticationAllowDenyEnum::Type](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian-AuthenticationAllowDenyEnum.md#enum-type) | [**ip\_allow\_deny**](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-AuthenticationDomain.md#variable-ip_allow_deny) |
| std::list< std::string > | [**ip\_addresses**](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-AuthenticationDomain.md#variable-ip_addresses) |
| [AuthenticationAllowDenyEnum::Type](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian-AuthenticationAllowDenyEnum.md#enum-type) | [**key\_allow\_deny**](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-AuthenticationDomain.md#variable-key_allow_deny) |
| std::list< std::vector< uint8\_t > > | [**public\_keys**](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-AuthenticationDomain.md#variable-public_keys) |
## Public Attributes Documentation
### variable service\_name
```cpp
std::string service_name;
```
the name of the service the contained
### variable domain
```cpp
std::string domain;
```
transport specific authentication domain, usually string representation of a port
### variable ip\_allow\_deny
```cpp
AuthenticationAllowDenyEnum::Type ip_allow_deny;
```
are the addresses in the following list allowed or denied
### variable ip\_addresses
```cpp
std::list< std::string > ip_addresses;
```
string representations of IP addresses
### variable key\_allow\_deny
```cpp
AuthenticationAllowDenyEnum::Type key_allow_deny;
```
are the keys in the following list allowed or denied
### variable public\_keys
```cpp
std::list< std::vector< uint8_t > > public_keys;
```
vectors of public key bytes
## 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.
# medcrypt::guardian::AuthenticationManager
Container for authentication restrictions.
`#include `
## Public functions
### function \~AuthenticationManager
```cpp
~AuthenticationManager()
```
The destructor.
**Parameters**:
* **none**
**Return**: none
The destructor does no work.
### function GetRestrictions
```cpp
Status GetRestrictions(
std::list< AuthenticationDomain > * out_restrictions_by_domain
)
```
Get all restrictions.
**Parameters**:
* **out\_restrictions\_by\_domain** list of domains and their restrictions,
**Returns**:
* **OK** out\_restrictions\_by\_domain is populated with restrictions
* **FAIL** general failure, out\_restrictions\_by\_domain is unmodified
* **BADPARAM** out\_restrictions\_by\_domain is nullptr
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Returns a list of all AuthenticationRestrictions in the system.
### function GetRestrictionByService
```cpp
Status GetRestrictionByService(
const char * in_service_name,
AuthenticationDomain * out_restriction
)
```
Get restrictions by service.
**Parameters**:
* **in\_service\_name** null terminated string of service name
* **out\_restriction** restriction set for in\_service\_name
**Returns**:
* **OK** out\_restriction is populated with restrictions for in\_service\_name
* **FAIL** general failure, out\_restriction is unmodified
* **BADPARAM** in\_service\_name is nullptr or empty, or out\_restriction is nullptr
* **MISCONFIGURED** in\_service\_name cannot be found or is not configured to share restrictions
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Returns a single AuthenticationRestriction for the specified service name
## 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.
# 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**
```cpp
#include
```
### Device provisioning functions
* [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-guardian) : The constructor does no work besides initializing member variables.
* [Initialize](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-initialize): Uses the provided profile, identity, and trust files to initialize the Guardian system.
* [GenerateProvisionRequest](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-generateprovisionrequest): This is the first device provisioning step for the provisioning process.
* [StartProvisioningOnline](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-startprovisioningonline): Start the online device provisioning process.
* [IsProvisioningRunning](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-isprovisioningrunning): Check if provisioning process is active.
* [GetProvisionedProfile](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-getprovisionedprofile): Extract provisioned certified profile for device after successful device provisioning.
### Certificate management functions
* [GetCertificateManager:](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-getcertificatemanager) Retrieve the running certificate manager.
* [GetProvisionedRevocationList](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-getprovisionedrevocationlist): Retrieve certificate revocation list and populate into buffer.
### **Security operations functions**
* [FindSecureOperation](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-findsecureoperation): Perform a lookup to get secure operation handler for signing/verification
### **Service management functions**
* [FindService](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-findservice): Perform a service name lookup to locate a configured service.
* [CreateTask](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-createtask): Create a task for service, session, or channel operations that separates the provided object and all children from [Run](#function-run).
### **System management functions**
* [GetAuthenticationManager](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-getauthenticationmanager): Retrieve the running authentication manager.
* [GetTelemetryManager](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-gettelemetrymanager): Retrieve the running telemetry manager.
* [\~Guardian](https://docs.medcrypt.com/api-reference/api-reference/classes/pages/-MD0rw0qMat4rv0A8KkC#function-~guardian) : The destructor attempts a graceful shutdown of Guardian.
* [Shutdown](#function-shutdown): Clean shutdown of Guardian
## Device setup and provisioning workflow
### Steps overview
#### [Prerequisites: Create Guardian instance](#guardian)
**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)
**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](#generateprovisionrequest)
**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)
**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](#function-getprovisionedprofile)
**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**
```cpp
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) (`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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:** Sets up Guardian with device identity and prepares it for secure operations.
**Syntax**
```cpp
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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **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**
```cpp
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()](#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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:** Starts internal provisioning state machine and begins communication with Guardian Cloud
**Syntax**
```cpp
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()`](#run) repeatedly to process provisioning tasks
2. Call [`IsProvisioningRunning()`](#isprovisioningrunning) to check if provisioning is complete
3. When `IsProvisioningRunning()` returns false, call [`GetProvisionedProfile()`](#function-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](#function-createtask). This should be called by the program/thread's main loop.
* Must be called regularly and repeatedly during online provisioning.
* Use [IsProvisioningRunning()](#function-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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **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()](#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()](#run)
* `false` - Provisioning has completed (successfully or failed). You should now call [GetProvisionedProfile()](#function-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**
```cpp
bool IsProvisioningRunning()
```
#### GetProvisionedProfile()
* **Description:**
* Extracts the provisioned profile after successful online provisioning.
* **Dependencies:**
* Must be called only after [IsProvisioningRunning()](#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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:** Copies completed provisioned profile to provided buffer.
**Syntax**
```cpp
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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:**
* Use the retrieved certificate manager to import and export certificates.
**Syntax**
```cpp
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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:** Copies certificate revocation list to provided buffer
**Syntax**
```cpp
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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:**
* Sets `out_secureop` to the located operation
* Will not modify `out_secureop` if the operation `in_secureop_name` is not located
**Syntax**
```cpp
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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **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**
```cpp
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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **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**
```cpp
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](#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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:**
* A component placed on a Task along with all children will not run when [Run](#run) is called, allowing for threading of separate objects.
* To return an object to the main Run loop, destroy the unique\_ptr.
**Syntax**
```cpp
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](#run).
* Allows for threading of separate objects by removing them from the main [Run](#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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:**
* A component placed on a Task along with all children will not run when [Run](#run) is called, allowing for threading of separate objects.
* To return an object to the main Run loop, destroy the unique\_ptr.
**Syntax**
```cpp
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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:** Use the retrieved authentication manager to get allow/deny lists for user managed connections
**Syntax**
```cpp
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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:** Use the retrieved telemetry manager to interact with the telemetry service
**Syntax**
```cpp
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](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#function-shutdown) for a graceful shutdown, then Guardian will destruct.
**Syntax**
```cpp
~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](#createtask-service-variant).
* **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](/api-reference/api-reference/namespaces/namespacemedcrypt-guardian-guardianstatusenum)
* **Action:** Stops all internal state machines including provisioning, telemetry, handshakes, authentication, services, sessions, and channels.
**Syntax**
```cpp
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.
# medcrypt::guardian::InitializeOptions
## Overview
These are the initialization configuration options to [initialize Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize).
**Include:**
```cpp
#include
```
**Syntax:**
```cpp
struct medcrypt::guardian::InitializeOptions;
```
### Structure members
* **is\_mocked:** Mocked profile flag
* **log\_level:** Log level enumeration
### Member details
#### is\_mocked:
* **Description:** Mocked profile flag that determines whether the profile provided for initialization is a non-node locked 'mocked' testing profile.
* **Type:** `bool`
* **Default value:** `false`
* **Syntax:**
```cpp
bool is_mocked = false;
```
#### log\_level:
* **Description:** Log level enumeration. See LogLevelEnum.h for accepted levels.
* **Type:** `LogLevelEnum::Type`
* **Default value:** `LogLevelEnum::Warn`
* `Syntax:`
```cpp
LogLevelEnum::Type log_level = [LogLevelEnum::Warn](/Namespaces/namespacemedcrypt-guardian-LogLevelEnum.md#enumvalue-warn);
```
### Related classes
* [Guardian class](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#overview): Uses `InitializeFiles` in [Initialize()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize) function
* LogLevelEnum namespace: Contains log level values
## 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.
# medcrypt::guardian::ProvisioningOptions
Options used by [Guardian::StartProvisioningOnline](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/classmedcrypt-guardian-Guardian.md#function-startprovisioningonline).
`#include `
## Public Functions
| | Name |
| - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | [**\~ProvisioningOptions**](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-ProvisioningOptions.md#function-~provisioningoptions)() |
## Public Attributes
| | Name |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| std::chrono::system\_clock::duration | connection\_timeout
Initial connection timeout.
|
| std::chrono::system\_clock::duration | response\_timeout
Time to wait for server response.
|
| std::chrono::system\_clock::duration | packet\_resend
Server polling time.
|
## Public Functions Documentation
### function \~ProvisioningOptions
```cpp
~ProvisioningOptions()
```
## Public Attributes Documentation
### variable connection\_timeout
```cpp
std::chrono::system_clock::duration connection_timeout = std::chrono::seconds(10);
```
Initial connection timeout.
If the connection does not complete within connection\_timeout the online provisioning process will fail.
### variable response\_timeout
```cpp
std::chrono::system_clock::duration response_timeout = std::chrono::seconds(10);
```
Time to wait for server response.
If the server does not respond with any status within response\_timeout the online provisioning process will fail.
### variable packet\_resend
```cpp
std::chrono::system_clock::duration packet_resend = std::chrono::seconds(10);
```
Server polling time.
Once the server has responded with any non-failing status, do not send another polling request until packet\_resend has elapsed since the last request was sent.
Example: if packet\_resend is 10 seconds, and the server response occurs 5 seconds after the initial request was sent, the next request will be sent approximately 5 seconds later.
## 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.
# medcrypt::guardian::Service
## Overview
This is a named group of connection and channel configurations.
**Usage:** This class is used to manage network connections and communication channels in Guardian applications.
**Include:**
```cpp
#include
```
**Syntax:**
```cpp
struct medcrypt::guardian::utilities::ProvisionOnlineFiles;
```
### Public functions
* [\~Service](#service): This is the destructor.
* [IsReady](#isready): Checks whether service is ready for operation.
* [IsFailed](#isfailed): Checks whether the service in a failed state.
* [Listen](#listen): Allows a managed server service to listen for new connections.
* [ConfigureTransport](#start): Secures the provided transport based on the loaded profile.
* [Shutdown](#shutdown): Stops all contained connections, blocking for any queued data to send or fail to send.
* [Start](/api-reference/api-reference/classes/classmedcrypt-guardian-service#function-start) (no override): Starts connection. This is blocking.
* [Start](#start-with-override) (with override): Starts connection using the provided override string. This is blocking.
* [AsyncStart](/api-reference/api-reference/classes/classmedcrypt-guardian-service#function-asyncstart): Starts connection. This is non-blocking.
* [AsyncStart](/api-reference/api-reference/classes/classmedcrypt-guardian-service#function-asyncstart): Starts connection using the provided override string. This is non-blocking.
* [ClientWaiting](/api-reference/api-reference/classes/classmedcrypt-guardian-service#function-clientwaiting): Checks whether a client is waiting to connect. This is non-blocking.
### Function details
#### \~Service()
* **Description:** The destructor will not affect the internal [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian) representation of the [Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service)..
* **Dependencies:** None - destructor is called automatically
* **Parameters:** None - destructor takes no parameters
* **Returns:** Nothing since it is a destructor.
* **Action:** Cleans up service resources without affecting Guardian's internal representation.
* **Syntax:**
```cpp
~Service()
```
#### IsReady()
* **Description:** Check if the service is ready for operation.
* **Dependencies:** Must be called after service is created
* **Parameters:** None
* **Returns:** Boolean value indicating service readiness
* `true` - Service is ready for its configured operations
* `false` - Service is not ready or is a server service that is not listening
* **Action:**
* **For client/unmanaged services:** Ready to create new sessions using [Start](/api-reference/api-reference/classes/classmedcrypt-guardian-service#function-start) asynchronously.
* **For server services:** Transport is listening and ready to accept connections.
* **Syntax:**
```cpp
bool IsReady()
```
#### IsFailed()
* **Description:** Used for server services when underlying transport fails during listening. Checks if the service is in a failed state.
* **Dependencies:** Used for server services to check transport status
* **Parameters:** None
* **Returns:** Boolean value indicating failure state
* `true` - The underlying server transport has failed
* `false` - The underlying server transport has not failed
* **Action:** Service should be shutdown and [Listen](#function-listen) called again.
* **Syntax:**
```cpp
bool IsFailed()
```
#### Listen()
* **Description:**
* Allows a managed server service to listen for new connections.
* Equivalent to calling 'bind' and 'listen' on a server socket.
* This function is not applicable to unmanaged or client services.
* **Dependencies:** Only applicable to managed server services
* **Parameters:**
* `in_override`: Null terminated transport specific override string
* **Default value:** nullptr (no override)
* **Returns:** Status code indicating success or failure.
* **Success code:** `OK` - Successfully started listening for connections
* **Error codes:**
* `FAIL` - General failure, did not start listening for connections
* `MISCONFIGURED` - Service is configured as unmanaged or as a a client
* **Action:**
* Starts listening for incoming connections on configured transport.
* **Example:** zeromq ex: "tcp\://127.0.0.1:12345"
* (default: no override)
* **See also:** "Override Strings" documentation
* **Syntax:**
```cpp
Status Listen(
const char * in_override =nullptr
)
```
#### ConfigureTransport()
* **Description:**
* Secures the provided transport based on the loaded profile.
* Uses profile configuration to secure and/or enable authentication for the provided transport based on unmanaged service configuration.
* **Dependencies:** Must have loaded profile with transport configuration
* **Parameters:**
* `in_transport`: Transport to be configured
* **Returns:** Status code indicating success or failure.
* **Success code:** `OK` - Successfully configured provided transport
* **Error codes:**
* `FAIL` - General failure, transport is unconfigured
* `BADPARAM` - `in_transport` is empty
* `MISCONFIGURED` - Profile does not support configuring transport on this service
* `HANDSHAKEREQUIRED` - Current CertificateManager lacks necessary keys/trust
* **See also:** "Unmanaged Handshaking" documentation
* **Action:** Applies security configuration from profile to the provided transport.
* **See also:** "Unmanaged Handshaking" documentation.
* **Syntax:**
```cpp
Status ConfigureTransport(
std::shared_ptr< TransportInterface > in_transport
)
```
#### Shutdown()
* **Description:**
* Stops all contained connections, blocking for any queued data to send or fail to send.
* Includes all sessions, connections, and channels, even those placed on other threads by [CreateTask](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#createtask-service-variant).
* **Dependencies:** Can be called on active service
* **Parameters:**
* `in_force`: After the timeout (or immediately if the timeout is 0), drop all waiting data and shut down.
* **Default value:** `false`
* **Returns:** Status code indicating success or failure.
* **Success code:** `OK` - Service is shut down
* **Error codes:**
* `FAIL` - General failure. Check the log.
* `AGAIN` - One or more transports has queued data to send
* **Action:** Stops all contained connections and cleans up resources.
* **Syntax:**
```cpp
Status Shutdown(
const bool & in_force =false
)
```
#### Start(): No override
* **Description:**
* Starts connection via blocking call.
* Behavior varies by service type:
* **Managed:**
* **Client services:** Block until connection succeeds/fails.
* **Server services:** Block until client connects.
* **Unmanaged services:** Always succeed unless transport configuration is required and no transport has been provided.
* **Dependencies:** Service must be ready and properly configured
* **Parameters:**
* `out_session`: Pointer populated with resulting session on success
* **Returns:** Status code indicating success or failure.
* **Success code:** `OK` - Successfully started a connection
* **Error codes:**
* `FAIL` - Could not connect to endpoint or server service was shut down
* `BADPARAM` - `out_session` is null pointer
* `MISCONFIGURED` - Profile has insufficient data to create connection
* **Action:** Creates and establishes a connection, returning a session object.
* **Syntax:**
```cpp
Status Start(
std::unique_ptr< Session > * out_session
)
```
#### Start(): With override
* **Description:**
* Blocking call to create connection using provided override string.
* Not applicable to server services.
* **Dependencies:** Service must support override strings
* **Parameters:**
* `in_override`: Transport specific override string, terminated by null
* `out_session`: Pointer populated with resulting session on success
* **Returns:** Status code indicating success or failure.
* **Success code:** `OK` - Successfully started a connection
* **Error codes:**
* `FAIL` - Could not connect to endpoint or server service was shutdown
* `BADPARAM` - out\_session is null pointer
* `MISCONFIGURED` - Profile has insufficient data or unmanaged connection needs configured transport
* `DENIED` - This is a server service, override not possible
* **See also:** All status codes for complete reference
* **Action:** Creates connection using custom transport parameters.
* **Syntax:**
```cpp
Status Start(
const char * in_override,
std::unique_ptr< Session > * out_session
)
```
Starts connection using the provided override string(blocking).
**Parameters**:
* **in\_override** null terminated transport specific override string see "Override Strings" documentation. zeromq ex: "tcp\://127.0.0.1:12345", defaults to no override
* **out\_session** on success this pointer is populated with the resulting session
**Returns**:
* **OK** successfully started a connection
* **FAIL** could not connect to endpoint or server service was shutdown
* **BADPARAM** out\_session is nullptr
* **MISCONFIGURED** profile has insufficient data to create a connection OR this is an unmanaged connection that needs a configured transport
* **DENIED** this is a server service, an override is not possible
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Blocking call to create a connection. Managed: Client: Will block until a connection succeeds or fails. Server: Not applicable.
Unmanaged: This call will always succeed unless the loaded profile requires a configured transport and no transport has been provided.
#### AsyncStart()
* **Description:** Non-blocking call to create connection. Client services return once connection process begins. Server services return waiting client if available. Unmanaged services equivalent to Start().
* **Dependencies:** Service must be ready for connections
* **Parameters:**
* `out_session`: Pointer populated with resulting session on success
* **Returns:** Status code indicating success or failure.
* **Success code:** `OK` - Successfully started the connection process
* **Error codes:**
* `FAIL` - Could not connect to endpoint
* `BADPARAM` - out\_session is null pointer
* `MISCONFIGURED` - Profile has insufficient data to create connection
* `AGAIN` - Server only, no client waiting to connect
* **See also:** All status codes for complete reference
* **Action:** Initiates connection process without blocking.
* **Syntax:**
#### AsyncStart() - With Override
* **Description:** Non-blocking call to create connection using override string. Not applicable to server services already listening.
* **Dependencies:** Service must support override and not be listening server
* **Parameters:**
* `in_override`: Transport specific override string, terminated by null
* `out_session`: Pointer populated with resulting session on success
* **Returns:** Status code indicating success or failure.
* **Success code:** `OK` - Successfully started a connection
* **Error codes:**
* `FAIL` - Could not connect to endpoint
* `BADPARAM` - out\_session is null pointer
* `MISCONFIGURED` - Profile has insufficient data to create connection
* `DENIED` - Server service already listening, override not possible
* `AGAIN` - Server only, no client waiting to connect
* **See also:** All status codes for complete reference
* **Action:** Initiates connection with custom parameters without blocking.
**Syntax:**
#### ClientWaiting()
* **Description:** Check if a client is waiting to connect (non-blocking). Always returns false for client services.
* **Dependencies:** Only relevant for server services
* **Parameters:** None
* **Returns:** Boolean value indicating client availability
* `true` - There is a client waiting
* `false` - No client waiting or this is a client service
* **Action:** If true, AsyncStart() will succeed and Start() will not block.
* **Syntax:**
| | Name |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | \~Service()
The destructor.
|
| bool | IsReady()
Is the service ready for operation.
|
| bool | IsFailed()
Is the service in a failed state.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | Listen(const char \* in\_override =nullptr)
Allows a managed server service to listen for new connections.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | ConfigureTransport(std::shared\_ptr< TransportInterface > in\_transport)
Secures the provided transport based on the loaded profile.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | Shutdown(const bool & in\_force =false)
Stops all contained connections, blocking for any queued data to send or fail to send.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | Start(std::unique\_ptr< Session > \* out\_session)
Starts connection (blocking).
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | Start(const char in\_override, std::unique\_ptr< Session > out\_session)
Starts connection using the provided override string(blocking).
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | AsyncStart(std::unique\_ptr< Session > \* out\_session)
Starts connection (non-blocking).
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | AsyncStart(const char in\_override, std::unique\_ptr< Session > out\_session)
Starts connection using the provided override string (non-blocking).
|
| bool | ClientWaiting()
Check if a client is waiting to connect (non-blocking)
|
## Public Functions Documentation
###
###
### function Start
```cpp
Status Start(
std::unique_ptr< Session > * out_session
)
```
Starts connection (blocking).
**Parameters**:
* **out\_session** on success this pointer is populated with the resulting session
**Returns**:
* **OK** successfully started a connection
* **FAIL** could not connect to endpoint or server service was shutdown
* **BADPARAM** out\_session is nullptr
* **MISCONFIGURED** profile has insufficient data to create a connection
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Blocking call to create a connection. Managed: Client: Will block until a connection succeeds or fails. Server: Will block until a client connects.
Unmanaged: This call will always succeed unless the loaded profile requires a configured transport and no transport has been provided.
### function Start
```cpp
Status Start(
const char * in_override,
std::unique_ptr< Session > * out_session
)
```
Starts connection using the provided override string(blocking).
**Parameters**:
* **in\_override** null terminated transport specific override string see "Override Strings" documentation. zeromq ex: "tcp\://127.0.0.1:12345", defaults to no override
* **out\_session** on success this pointer is populated with the resulting session
**Returns**:
* **OK** successfully started a connection
* **FAIL** could not connect to endpoint or server service was shutdown
* **BADPARAM** out\_session is nullptr
* **MISCONFIGURED** profile has insufficient data to create a connection OR this is an unmanaged connection that needs a configured transport
* **DENIED** this is a server service, an override is not possible
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Blocking call to create a connection. Managed: Client: Will block until a connection succeeds or fails. Server: Not applicable.
Unmanaged: This call will always succeed unless the loaded profile requires a configured transport and no transport has been provided.
### function AsyncStart
```cpp
Status AsyncStart(
std::unique_ptr< Session > * out_session
)
```
Starts connection (non-blocking).
**Parameters**:
* **out\_session** on success this pointer is populated with the resulting session
**Returns**:
* **OK** successfully started the connection process
* **FAIL** could not connect to endpoint
* **BADPARAM** out\_session was set to nullptr
* **MISCONFIGURED** profile has insufficient data to create a connection
* **AGAIN** server only, no client waiting to connect, try again
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Non-blocking call to create a connection. Managed: Client: Will return once the underlying connection process has begun or failed. Server: return a waiting client connection if available.
Unmanaged: Equivalent to calling Start.
### function AsyncStart
```cpp
Status AsyncStart(
const char * in_override,
std::unique_ptr< Session > * out_session
)
```
Starts connection using the provided override string (non-blocking).
**Parameters**:
* **in\_override** null terminated transport specific override string see "Override Strings" documentation. zeromq ex: "tcp\://127.0.0.1:12345", defaults to no override
* **out\_session** on success this pointer is populated with the resulting session
**Returns**:
* **OK** successfully started a connection
* **FAIL** could not connect to endpoint
* **BADPARAM** out\_session was set to nullptr
* **MISCONFIGURED** profile has insufficient data to create a connection
* **DENIED** this is a server service that is already listening and an override is not possible
* **AGAIN** server only, no client waiting to connect, try again
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Non-blocking call to create a connection. Managed: Client: Will return once the underlying connection process has begun or failed. Server: Not applicable.
Unmanaged: Equivalent to calling Start.
### function ClientWaiting
```cpp
bool ClientWaiting()
```
Check if a client is waiting to connect (non-blocking)
**Parameters**:
* **none**
**Returns**:
* **true** there is a client waiting
* **false** there is not a client waiting or this is a client service
**Return**: bool
If true Async start will succeed and Start will not block. Will always return false for a client service.
## 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.
# medcrypt::guardian::Session
Individual connection within a [Service](/api-reference/api-reference/classes/classmedcrypt-guardian-service).
`#include `
## Public Functions
| | Name |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | \~Session()
The destructor.
|
| bool | IsReady()
Are the underlying channels and tranport ready for operation.
|
| bool | IsFailed()
Have the underlying transport or channels failed.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | FindChannel(const char in\_channel\_name, std::unique\_ptr< ChannelGuard > out\_channelguard)
Searches for session channel instance based on provided name.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | Shutdown(const bool & in\_force =false)
Stops contained connection and channelguards, blocking any further data from being queued for send.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | DataForSocket(char out\_data, size\_t io\_data\_size)
Provides data to send over a customer managed transport (blocking)
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | AsyncDataForSocket(char out\_data, size\_t io\_data\_size)
Provides data to send over a customer managed transport (non-blocking)
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | DataFromSocket(const char \* in\_data, size\_t in\_data\_size)
Accepts data to process from a customer managed transport (blocking)
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | AsyncDataFromSocket(const char \* in\_data, size\_t in\_data\_size)
Accepts data to process from a customer managed transport (non-blocking)
|
| bool | IsDataGone()
Indicates if the session has data waiting to be sent.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | SetDataForSocketCallback(const std::function< bool(const char \*, const size\_t &)> & in\_callback)
Registers a callback for sending data through a user managed transport.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | SetDataFromSocketCallback(const std::function< bool(char \*, size\_t )> & in\_callback)
Registers a callback for receiving data from a user managed transport.
|
## Public Functions Documentation
### function \~Session
```cpp
~Session()
```
The destructor.
**Parameters**:
* **none**
**Return**: none
The destructor will not affect the internal [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian) representation of the [Session](/api-reference/api-reference/classes/classmedcrypt-guardian-session).
### function IsReady
```cpp
bool IsReady()
```
Are the underlying channels and tranport ready for operation.
**Parameters**:
* **none**
**Returns**:
* **true** the session and contained channels are ready to send/receive data
* **false** the session and contained channels are not ready to send/receive data
**Return**: bool
If the session is ready all contained channels are ready to send and receive data over the contained connected tranport mechanism.
Already received and processed data can still be retrieved through ChannelGuards even if the session is not ready.
### function IsFailed
```cpp
bool IsFailed()
```
Have the underlying transport or channels failed.
**Parameters**:
* **none**
**Returns**:
* **true** an error has occurred that is blocking future send/receive operations
* **false** no error has occurred
**Return**: bool
If the session is failed, it should be destroyed and recreated with Start
Already received and processed data can still be retrieved through ChannelGuards even if the session is failed.
### function FindChannel
```cpp
Status FindChannel(
const char * in_channel_name,
std::unique_ptr< ChannelGuard > * out_channelguard
)
```
Searches for session channel instance based on provided name.
**Parameters**:
* **in\_channel\_name** null terminated channel name
* **out\_channelguard** pointer to unique\_ptr storage for found channelguard
**Returns**:
* **OK** the pointer in out\_channelguard is valid
* **FAIL** could not find the channelguard specified by in\_channel\_name
* **BADPARAM** in\_channel\_name is nullptr or empty or out\_channelguard is nullptr
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Uses the loaded profile to secure and/or enable authentication based on unmanged service configuration for the provided transport.
### function Shutdown
```cpp
Status Shutdown(
const bool & in_force =false
)
```
Stops contained connection and channelguards, blocking any further data from being queued for send.
**Parameters**:
* **in\_force** after the timeout (or immediately if the timeout is 0) drop all waiting data and shutdown.
**Returns**:
* **OK** session is shutdown
* **FAIL** general failure, check the log
* **AGAIN** one or more transports has queued data to send
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Includes all contained channelguard and any contained transport, even those that have been placed or had a parent placed on another thread by CreateTask.
### function DataForSocket
```cpp
Status DataForSocket(
char * out_data,
size_t * io_data_size
)
```
Provides data to send over a customer managed transport (blocking)
**Parameters**:
* **out\_data** binary data buffer to store output data
* **io\_data\_size** provide size of provided out\_data buffer, on successful return is set to size of the data in out\_data, on failure is set to 0
**Returns**:
* **OK** out\_data is populated with data to send
* **FAIL** general failure, check the log
* **BADPARAM** out\_data is nullptr or io\_data\_size is nullptr or 0
* **DENIED** session is managed
* **OUTOFMEMORY** provided buffer too small
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Blocking call only applicable to unmanaged service sessions. out\_data should be a user allocated buffer to store data intended to be sent over the user managed transport. The call will return immediately under any of the below error conditions, otherwise it will block until data is ready to send.
### function AsyncDataForSocket
```cpp
Status AsyncDataForSocket(
char * out_data,
size_t * io_data_size
)
```
Provides data to send over a customer managed transport (non-blocking)
**Parameters**:
* **out\_data** binary data buffer to store output data
* **io\_data\_size** provide size of provided out\_data buffer, on successful return is set to size of the data in out\_data, on failure is set to 0
**Returns**:
* **OK** out\_data is populated with data to send
* **FAIL** general failure, check the log
* **BADPARAM** out\_data is nullptr or io\_data\_size is nullptr or 0
* **DENIED** session is managed
* **OUTOFMEMORY** provided buffer too small
* **AGAIN** there is no data waiting to send, out\_data unmodified
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Non-blocking call only applicable to unmanaged service sessions. out\_data should be a user allocated buffer to store data intended to be sent over the user managed transport.
### function DataFromSocket
```cpp
Status DataFromSocket(
const char * in_data,
size_t in_data_size
)
```
Accepts data to process from a customer managed transport (blocking)
**Parameters**:
* **in\_data\_size** size of binary data in in\_data
* **in\_data** binary data buffer of received data
**Returns**:
* **OK** in\_data has been processed
* **FAIL** unable to process in\_data
* **DENIED** session is managed
* **OUTOFMEMORY** provided buffer is too large to send
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Blocking call only applicable to unmanaged service sessions. in\_data should contain information received from a customer managed transport. On return data will be available for retrieval from a channelguard.
### function AsyncDataFromSocket
```cpp
Status AsyncDataFromSocket(
const char * in_data,
size_t in_data_size
)
```
Accepts data to process from a customer managed transport (non-blocking)
**Parameters**:
* **in\_data\_size** size of binary data in in\_data
* **in\_data** binary data buffer of received data
**Returns**:
* **OK** in\_data has been queued for processing or processed
* **FAIL** unable to process in\_data
* **DENIED** session is managed
* **OUTOFMEMORY** provided buffer is too large
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Non-blocking call only applicable to unmanaged service sessions. in\_data should contain information received from a customer managed transport. On return data will may be availble for retrieval from a channelguard.
### function IsDataGone
```cpp
bool IsDataGone()
```
Indicates if the session has data waiting to be sent.
**Parameters**:
* **none**
**Returns**:
* **false** data is waiting to be sent
* **true** no data is waiting to be sent
**Return**: bool
If false there is data waiting to be sent over the contained managed transport or retrieved using \[Async]DataForSocket to be sent over a user managed transport. If false AsyncDataForSocket will return OK and DataForSocket will not block. No guarantees are made on if a non-forcing Shutdown call will block since in a multi-threaded environment more data could be queued for send between a call to IsDataGone and Shutdown.
### function SetDataForSocketCallback
```cpp
Status SetDataForSocketCallback(
const std::function< bool(const char *, const size_t &)> & in_callback
)
```
Registers a callback for sending data through a user managed transport.
**Parameters**:
* **in\_callback** blocking function that will send data over the user managed transport when called,returns false on failure.
**Returns**:
* **OK** callback registered
* **FAIL** general failure
* **DENIED** session is managed
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Provides a callback for use with user managed transport and blocking [ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard) calls. The provided function must be a blocking call and return only when data has been successfully sent or a failure makes it impossible to send the data.
### function SetDataFromSocketCallback
```cpp
Status SetDataFromSocketCallback(
const std::function< bool(char **, size_t *)> & in_callback
)
```
Registers a callback for receiving data from a user managed transport.
**Parameters**:
* **in\_callback** blocking function that will receive data from the user managed transport when called, returns false on failure.
**Returns**:
* **OK** callback registered
* **FAIL** general failure
* **DENIED** session is managed
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Provides a callback for use with user managed transport and blocking [ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard) calls. The provided function must be a blocking call and return only when data has been successfully received or a failure makes it impossible to receive data. The callback should follow the same rules for the size\_t parameters as DataFromSocket.
## 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.
# medcrypt::guardian::ChannelGuard
Name channel within a [Session](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard).
`#include `
## Public Functions
| | Name |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | \~ChannelGuard()
The destructor.
|
| bool | IsReady()
The ChannelGuard is ready to send data.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | DataForChannel(const char \* in\_data, const size\_t & in\_data\_size)
Accepts data to encode and send over parent session (blocking)
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | AsyncDataForChannel(const char \* in\_data, const size\_t & in\_data\_size)
Accepts data to encode and send over parent session (non-blocking)
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | DataFromChannel(char out\_data, size\_t io\_data\_size)
Returns decoded data received by parent session (blocking)
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | [**AsyncDataFromChannel**](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard#function-asyncdatafromchannel)(char *out\_data, size\_t* io\_data\_size) |
| bool | IsDataGone()
Indicates if all data provided to \[Async]DataForChannel has has been sent.
|
| bool | IsDataWaiting()
Indicates if there is data waiting to be received with \[Async]DataFromChannel.
|
## Public Functions Documentation
### function \~ChannelGuard
```cpp
~ChannelGuard()
```
The destructor.
**Parameters**:
* **none**
**Return**: none
The destructor will not affect the internal [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian) representation of the [ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard).
### function IsReady
```cpp
bool IsReady()
```
The [ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard) is ready to send data.
**Parameters**:
* **none**
**Returns**:
* **true** the channel is ready to send data
* **false** the channel is not ready to send data
**Return**: bool
[ChannelGuard](/api-reference/api-reference/classes/classmedcrypt-guardian-channelguard) will always return any available data with DataFromChannel no matter the internal state. It will block from sending new data unless it is ready.
### function DataForChannel
```cpp
Status DataForChannel(
const char * in_data,
const size_t & in_data_size
)
```
Accepts data to encode and send over parent session (blocking)
**Parameters**:
* **in\_data** binary data buffer to encode and send
* **in\_data\_size** size of binary data in in\_data
**Returns**:
* **OK** in\_data has been processed
* **FAIL** general failure, check log
* **BADPARAM** in\_data is nullptr
* **OUTOFMEMORY** provided buffer is too large
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Blocking call to send data. When this call completes successfully the provided data has been secured based on the loaded profile and handed to the configured managed network library or unmanaged callback.
If this is a channel in an unmanaged session/service the session must have a registered DataForSocket callback.
### function AsyncDataForChannel
```cpp
Status AsyncDataForChannel(
const char * in_data,
const size_t & in_data_size
)
```
Accepts data to encode and send over parent session (non-blocking)
**Parameters**:
* **in\_data** binary data buffer to encode and send
* **in\_data\_size** size of binary data in in\_data
**Returns**:
* **OK** in\_data has been processed
* **FAIL** general failure, check log
* **BADPARAM** in\_data is nullptr
* **OUTOFMEMORY** provided buffer is too large
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Non-blocking call to send data. When this call completes successfully the provided data has been secured based on the loaded profile and queued in the parent session to be sent.
### function DataFromChannel
```cpp
Status DataFromChannel(
char * out_data,
size_t * io_data_size
)
```
Returns decoded data received by parent session (blocking)
**Parameters**:
* **out\_data** binary data buffer to store output data
* **io\_data\_size** provide size of provided out\_data buffer, on a successful return is set to size of the data in out\_data
**Returns**:
* **OK** out\_data is populated with application data
* **FAIL** general failure
* **BADPARAM** out\_data is nullptr or io\_data\_size is nullptr or 0
* **VERIFYFAIL** out\_data may be populated with data but any contained data failed signature verification
* **OUTOFMEMORY** provided buffer is too small
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Blocking call to receive data. When this call completes successfully out\_data is populated with valid data.
If this is a channel in an unmanaged session/service the session must have a registered DataFromSocket callback.
### function AsyncDataFromChannel
```cpp
Status AsyncDataFromChannel(
char * out_data,
size_t * io_data_size
)
```
**Parameters**:
* **out\_data** binary data buffer to store output data
* **io\_data\_size** provide size of provided out\_data buffer, on a successful return is set to size of the data in out\_data
**Returns**:
* **OK** out\_data is populated with application data
* **FAIL** general failure
* **BADPARAM** out\_data is nullptr or io\_data\_size is nullptr or 0
* **VERIFYFAIL** out\_data may be populated with data but any contained data failed signature verification
* **OUTOFMEMORY** provided buffer is too small
* **AGAIN** no data is currently available, try again
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Returns decoded data received by parent session (non-blocking)
Non-blocking call to receive data. When this call completes successfully out\_data is populated with valid data.
### function IsDataGone
```cpp
bool IsDataGone()
```
Indicates if all data provided to \[Async]DataForChannel has has been sent.
**Parameters**:
* **none**
**Returns**:
* **false** data is waiting to be sent
* **true** no data is waiting to be sent
**Return**: bool
If false there is data that has not been handed to the network layer or user managed transport.
### function IsDataWaiting
```cpp
bool IsDataWaiting()
```
Indicates if there is data waiting to be received with \[Async]DataFromChannel.
**Parameters**:
* **none**
**Returns**:
* **false** no data is waiting to be received
* **true** data is waiting to be received
**Return**: bool
If true \[Async]DataFromChannel will return successfully and DataFromChannel will not block.
## 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.
# medcrypt::guardian::SecureOperation
Named standalone operation.
`#include `
## Public Functions
| | Name |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| | \~SecureOperation()
The destructor.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | Sign(const char in\_data, const size\_t & in\_data\_size, char out\_signature, size\_t \* io\_signature\_size)
Create signature.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | Verify(const char in\_data, const size\_t & in\_data\_size, const char in\_signature, const size\_t & in\_signature\_size, bool \* out\_is\_verified)
Verify existing signature.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | SignatureMultipartInit(const bool & in\_force =true)
Prepare for multipart sign/verify.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | SignatureMultipartUpdate(const char \* in\_data, const size\_t & in\_data\_size)
Add data to multipart sign/verify operation.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | SignatureMultipartSignFinal(char out\_signature, size\_t io\_signature\_size)
Create signature from previously provided data.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | SignatureMultipartVerifyFinal(const char in\_signature, const size\_t & in\_signature\_size, bool out\_is\_verified)
Verify signature from previously provided data.
|
## Public Functions Documentation
### function \~SecureOperation
```cpp
~SecureOperation()
```
The destructor.
**Parameters**:
* **none**
**Return**: none
The destructor will return the contained object to the main [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian) Run thread.
### function Sign
```cpp
Status Sign(
const char * in_data,
const size_t & in_data_size,
char * out_signature,
size_t * io_signature_size
)
```
Create signature.
**Parameters**:
* **in\_data** binary data buffer
* **in\_data\_size** bytes in in\_data
* **out\_signature** binary data buffer
* **io\_signature\_size** provide size of out\_signature buffer, on return is set to size of the data in out\_signature or the required size of out\_signature
**Returns**:
* **OK** out\_signature populated with the signature
* **FAIL** general failure, check the log
* **BADPARAM** a provided parameter is nullptr or a size is 0
* **MISCONFIGURED** this secure operation is not configured for signatures
* **OUTOFMEMORY** out\_signature is too small, see io\_signature\_size for required size
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Signature created based on loaded profile.
### function Verify
```cpp
Status Verify(
const char * in_data,
const size_t & in_data_size,
const char * in_signature,
const size_t & in_signature_size,
bool * out_is_verified
)
```
Verify existing signature.
**Parameters**:
* **in\_data** binary data buffer
* **in\_data\_size** bytes in in\_data
* **in\_signature** binary data buffer
* **in\_signature\_size** bytes in in\_signature
* **out\_is\_verified** true if in\_data matches in\_signature
**Returns**:
* **OK** signature checked against data, see out\_is\_verified for if signature matched the data
* **FAIL** general failure
* **BADPARAM** a provided parameter is nullptr or a size is 0
* **MISCONFIGURED** this secure operation is not configured for signatures
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Verification based on loaded profile.
Note: return value will be OK for a successful verify operation even if the signature does not match the data. Check out\_is\_verified to see if the data and signature match.
### function SignatureMultipartInit
```cpp
Status SignatureMultipartInit(
const bool & in_force =true
)
```
Prepare for multipart sign/verify.
**Parameters**:
* **in\_force** optional parameter, true will start a new operation even if another is already in progress
**Returns**:
* **OK** secure operation is ready for data to sign/verify
* **FAIL** general failure
* **MISCONFIGURED** this secure operation is not configured for signatures
* **DENIED** another secure operation is already in progress
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Initializes secure operation for a multipart signature or multipart signature verification.
### function SignatureMultipartUpdate
```cpp
Status SignatureMultipartUpdate(
const char * in_data,
const size_t & in_data_size
)
```
Add data to multipart sign/verify operation.
**Parameters**:
* **in\_data\_size** bytes in in\_data
* **in\_data** binary data buffer
**Returns**:
* **OK** data added successfully
* **FAIL** general failure
* **BADPARAM** in\_data is nullptr or in\_data\_size is 0
* **DENIED** this secure operation has not been initialized for a multipart sign/verify operation
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
Add data in full or chunked pieces to the secure operation, finish the process with one of the Complete functions.
### function SignatureMultipartSignFinal
```cpp
Status SignatureMultipartSignFinal(
char * out_signature,
size_t * io_signature_size
)
```
Create signature from previously provided data.
**Parameters**:
* **io\_signature\_size** provide size of out\_signature buffer, on return is set to size of the data in out\_signature or the required size of out\_signature
* **out\_signature** binary data buffer
**Returns**:
* **OK** out\_signature populated with the signature
* **FAIL** general failure
* **BADPARAM** out\_signature is nullptr or io\_signature\_size is nullptr or 0
* **DENIED** multipart signature has not been intiailzed
* **OUTOFMEMORY** out\_signature is too small, see io\_signature\_size for required size
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
### function SignatureMultipartVerifyFinal
```cpp
Status SignatureMultipartVerifyFinal(
const char * in_signature,
const size_t & in_signature_size,
bool * out_is_verified
)
```
Verify signature from previously provided data.
**Parameters**:
* **in\_signature\_size** bytes in in\_signature
* **in\_signature** binary data buffer
* **out\_is\_verified** true if in\_data matches in\_signature
**Returns**:
* **OK** out\_verified reflects if signature matched the data
* **FAIL** general failure
* **BADPARAM** in\_signature or out\_is\_verified is nullptr or in\_signature\_size is 0
* **DENIED** no data has been added to this secure operation
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
## 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.
# medcrypt::guardian::Task
Multithreading container.
`#include `
## Public Functions
| | Name |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | \~Task()
The destructor.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | Run()
Runs the contained object.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | GetService(std::unique\_ptr< Service > \* out\_service)
Returns the contained service.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | GetSession(std::unique\_ptr< Session > \* out\_session)
Returns the contained session.
|
| [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | GetChannelGuard(std::unique\_ptr< ChannelGuard > \* out\_channelguard)
Returns the contained channelguard.
|
## Public Functions Documentation
### function \~Task
```cpp
~Task()
```
The destructor.
**Parameters**:
* **none**
**Return**: none
The destructor will return the contained object to the main [Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian) Run thread.
### function Run
```cpp
Status Run()
```
Runs the contained object.
**Parameters**:
* **none**
**Returns**:
* **OK** contained object ran successfully
* **FAIL** general failure
* **SHUTDOWN** the contained object is shutdown
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
This run call should be called by the thread's main loop.
### function GetService
```cpp
Status GetService(
std::unique_ptr< Service > * out_service
)
```
Returns the contained service.
**Parameters**:
* **out\_service** pointer to unique\_ptr storage for contained service
**Returns**:
* **OK** the pointer in out\_service is valid
* **FAIL** general failure
* **BADPARAM** out\_service is nullptr
* **MISCONFIGURED** the task does not contain a service
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
### function GetSession
```cpp
Status GetSession(
std::unique_ptr< Session > * out_session
)
```
Returns the contained session.
**Parameters**:
* **out\_session** pointer to unique\_ptr storage for contained session
**Returns**:
* **OK** the pointer in out\_session is valid
* **FAIL** general failure
* * **BADPARAM** out\_session is nullptr
* **MISCONFIGURED** the task does not contain a session
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
### function GetChannelGuard
```cpp
Status GetChannelGuard(
std::unique_ptr< ChannelGuard > * out_channelguard
)
```
Returns the contained channelguard.
**Parameters**:
* **out\_channelguard** pointer to unique\_ptr storage for contained channelguard
**Returns**:
* **OK** the pointer in out\_channelguard is valid
* **FAIL** general failure
* **BADPARAM** out\_channelguard is nullptr
* **MISCONFIGURED** the task does not contain a channelguard
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
## 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.
# medcrypt::guardian::TransportInterface
[Service::ConfigureTransport](/api-reference/api-reference/classes/classmedcrypt-guardian-service#function-configuretransport) required interface.
`#include `
## Public Functions
| | Name |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| virtual | [**\~TransportInterface**](https://docs.medcrypt.com/api-reference/api-reference/classes/pages/-Mgn-MdBHdORu8Qn95JG#function-~transportinterface)() |
| virtual [Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status) | ApplySecurity(const std::unique\_ptr< medcrypt::guardian::utilities::SafeString > & in\_parameters) =0
Security parameters receiver.
|
## Public Functions Documentation
### function \~TransportInterface
```cpp
inline virtual ~TransportInterface()
```
### function ApplySecurity
```cpp
virtual Status ApplySecurity(
const std::unique_ptr< medcrypt::guardian::utilities::SafeString > & in_parameters
) =0
```
Security parameters receiver.
**Parameters**:
* **in\_parameters** implementation dependent encoding of security parameters
**Returns**:
* **OK** successfully applied security
* **other** any non zero failure code
**Return**: [medcrypt::guardian::Status](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian.md#typedef-status)
The contents of in\_parameters are dependent on the type of transport implemented by the derived class.
An implemented ApplySecurity function should return [GuardianStatusEnum::OK](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian-GuardianStatusEnum.md#enumvalue-ok) on success, and a non zero derivation defined code on failure.
The SafeString type can be treated as a normal std::string.
## 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.
# medcrypt::guardian::utilities::InitializeFiles
## Overview
This is the storage for initialization files used to [initialize Guardian](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize).
**Requirements:**
* All `const char*` inputs should be set to the beginning of the loaded buffer.
* All `size_t` inputs should be set to the size of the data loaded in the buffer.
**Usage example:**
* See [GetInitializeFilesFromPath()](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian-utilities.md#function-getinitializefilesfrompath) and [DeleteInitializeFileBuffers()](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Namespaces/namespacemedcrypt-guardian-utilities.md#function-deleteinitializefilebuffers) in [FileHelpers.h](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Files/FileHelpers_8h.md#file-filehelpers.h) for an example of how to use.
**Include:**
```cpp
#include
```
**Syntax:**
```cpp
struct medcrypt::guardian::utilities::InitializeFiles;
```
### Structure members
* [TrustStore](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md#variable-truststore): Root certificate authority trust store
* [TrustStoreSize](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md#variable-truststoresize): Device private identity and keys
* [PrivateIdentity](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md#variable-privateidentity): Device private identity and keys
* [PrivateIdentitySize](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md#variable-privateidentitysize): Size of the PrivateIdentity data
* [CertifiedProfile](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md#variable-certifiedprofile): Device certified profile and certificates
* [CertifiedProfileSize](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md#variable-certifiedprofilesize): Size of the CertifiedProfile data
* [CertifiedCertificateRevocations](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md#variable-certifiedcertificaterevocations): Certificate revocation list
* [CertifiedCertificateRevocationsSize](https://github.com/MedCrypt/docs/tree/cc6d7e9e4565d200e300a7e4ea03af7b3d489502/Classes/structmedcrypt-guardian-utilities-InitializeFiles.md#variable-certifiedcertificaterevocationssize): Size of the CertifiedCertificateRevocations data
### Member details
#### TrustStore variable
* **Description:** Root certificate authority TrustStore file buffer for validating certificates.
* **Type:** `const char*`
* **Syntax:**
```cpp
const char * TrustStore;
```
#### TrustStoreSize variable
* **Description:** Size of the TrustStore file buffer.
* **Type:** `size_t`
* **Syntax:**
```
size_t TrustStoreSize;
```
#### PrivateIdentity variable
* **Description:** Device private identity containing cryptographic keys.
* **Type:** `const char*`
* **Security:** Must be kept secure and never transmitted.
* **Syntax:**
```cpp
const char * PrivateIdentity;
```
#### PrivateIdentitySize variable
* **Description:** Size of the PrivateIdentity file buffer.
* **Type:** `size_t`
* **Syntax:**
```cpp
size_t PrivateIdentitySize;
```
#### CertifiedProfile variable
* **Description:** Device certified profile containing certificates and configuration.
* **Type:** `const char*`
* **Syntax:**
```cpp
const char * CertifiedProfile;
```
#### CertifiedProfileSize variable
* **Description:** Size of the CertifiedProfile file buffer.
* **Type:** `size_t`
* **Syntax:**
```
size_t CertifiedProfileSize;
```
#### CertifiedCertificateRevocations variable
* **Description:** File buffer for Certificate Revocation List (CRL).
* **Type:** `const char*`
* **Syntax:**
```cpp
const char * CertifiedCertificateRevocations;
```
#### CertifiedCertificateRevocationsSize variable
* **Description:** Size of the CertifiedCertificateRevocations data in bytes.
* **Type:** `size_t`
#### CertifiedCertificateRevocationsSize variable
* **Description:** File buffer size for Certificate Revocation List (CRL).
* **Type:** `const char*`
* **Syntax:**
```cpp
size_t CertifiedCertificateRevocationsSize;
```
### Related classes
* [Guardian class](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#overview): Uses `InitializeFiles` in [Initialize()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-2-run-initialize) function
* [ProvisionFiles struct](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisionfiles): Similar file structure used for provisioning operations
* [ProvisionOnlineFiles struct](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisiononlinefiles): File structure used for online provisioning
## 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.
# medcrypt::guardian::utilities::ProvisionFiles
## Overview
This is the storage for generating provision request files in [GenerateProvisionRequest()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-3-run-generateprovisionrequest).
**Requirements:**
* **Input:**
* All `const char*` inputs should be set to the beginning of the loaded buffer.
* All `size_t` inputs should be set to the size of the data loaded in the buffer.
* **Output:**
* All `char*` outputs should be set to the beginning of an allocated buffer.
* All `size_t` outputs should be set to the size of the allocated buffer. After success, they will be set to the size of the data written.
**Usage:**
* This structure is used with [GenerateProvisionRequest()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-3-run-generateprovisionrequest) to generate provisioning files.
* See GetProvisionFilesFromPath() and DeleteProvisionFileBuffers() in FileHelpers.h for examples.
**Include:**
```cpp
#include
```
**Syntax:**
```cpp
struct medcrypt::guardian::utilities::ProvisionFiles;
```
### Structure members
**Input members:**
* **TrustStore:** Trust store file buffer
* **TrustStoreSize:** Trust store file buffer size
* **PrivateIdentity:** Private identity file buffer
* **PrivateIdentitySize:** Private identity file buffer size
* **CertifiedProfile:** Certified profile file buffer
* **CertifiedProfileSize:** Certified profile file buffer size
* **CertifiedCertificateRevocations:** Certificate revocations file buffer
* **CertifiedCertificateRevocationsSize:** Certificate revocations file buffer size
**Output members:**
* **ProvisionRequest:** Provision request file buffer
* **ProvisionRequestSize:** Provision request file buffer size
* **GeneratedPrivateIdentity:** Generated private identity file buffer
* **GeneratedPrivateIdentitySize:** Generated private identity file buffer size
### Member details
#### Input members:
#### TrustStore
* **Description:** Trust store file buffer.
* **Type:** `const char*`
* **Usage:** Input
* **Syntax:**
```cpp
const char * TrustStore;
```
#### TrustStoreSize
* **Description:** Trust store file buffer size.
* **Type:** `size_t`
* **Usage:** Input
* **Syntax:**
```cpp
size_t TrustStoreSize;
```
#### PrivateIdentity
* **Description:** Private identity file buffer.
* **Type:** `const char*`
* **Usage:** Input
* **Syntax:**
```cpp
const char * PrivateIdentity;
```
#### PrivateIdentitySize
* **Description:** Private identity file buffer size.
* **Type:** `size_t`
* **Usage:** Input
* **Syntax:**
```cpp
size_t PrivateIdentitySize;
```
#### CertifiedProfile
* **Description:** Certified profile file buffer.
* **Type:** `const char*`
* **Usage:** Input
* **Syntax:**
```cpp
const char * CertifiedProfile;
```
#### CertifiedProfileSize
* **Description:** Certified profile file buffer size.
* **Type:** `size_t`
* **Usage:** Input
* **Syntax:**
```cpp
size_t CertifiedProfileSize;
```
#### CertifiedCertificateRevocations
* **Description:** Certificate revocations file buffer.
* **Type:** `const char*`
* **Usage:** Input
* **Syntax:**
```cpp
const char * CertifiedCertificateRevocations;
```
#### CertifiedCertificateRevocationsSize
* **Description:** Certificate revocations file buffer size.
* **Type:** `size_t`
* **Usage:** Input
* **Syntax:**
```cpp
size_t CertifiedCertificateRevocationsSize;
```
#### Output members:
#### ProvisionRequest
* **Description:** Provision request file buffer.
* **Type:** `char*`
* **Usage:** Output
* **Syntax:**
```cpp
char * ProvisionRequest;
```
#### ProvisionRequestSize
* **Description:** Provision request file buffer size.
* **Input:** allocated buffer size.
* **Output:** actual data size written.
* **Type:** `size_t`
* **Usage:** Input/Output
* **Syntax:**
```cpp
size_t ProvisionRequestSize;
```
#### GeneratedPrivateIdentity
* **Description:** Generated private identity file buffer.
* **Type:** `char*`
* **Usage:** Output
* **Syntax:**
```cpp
char * GeneratedPrivateIdentity;
```
#### GeneratedPrivateIdentitySize
* **Description:** Generated private identity file buffer size.
* **Input:** allocated buffer size.
* **Output:** actual data size written.
* **Type:** `size_t`
* **Usage:** Input/Output
* **Syntax:**
```cpp
size_t GeneratedPrivateIdentitySize;
```
### Related classes
* [Guardian class](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#overview): Uses `ProvisionFiles` in [GenerateProvisionRequest()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-3-run-generateprovisionrequest)
* [InitializeFiles struct](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-initializefiles) - Similar file structure used for initialization
* [ProvisionOnlineFiles struct](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisiononlinefiles) - File structure used for online provisioning
## 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.
# medcrypt::guardian::utilities::ProvisionOnlineFiles
## Overview
This is the storage for online provisioning files in [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline).
**Requirements:**
* All `const char*` inputs should be set to the beginning of the loaded buffer.
* All `size_t` inputs should be set to the size of the data loaded in the buffer.
**Usage:**
* This structure is used with [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline) to provide the provision request for online processing.
**Include:**
```cpp
#include
```
**Syntax:**
```cpp
struct medcrypt::guardian::utilities::ProvisionOnlineFiles;
```
### Structure members
* **ProvisionRequest:** Provision request file buffer
* **ProvisionRequestSize:** Provision request file buffer size
### Member details
#### ProvisionRequest
* **Description:** Provision request file buffer.
* **Type:** `const char*`
* **Usage:** Input
* **Syntax:**
```cpp
const char * ProvisionRequest;
```
#### ProvisionRequestSize
* **Description:** Provision request file buffer size.
* **Type:** `size_t`
* **Usage:** Input
* **Syntax:**
```cpp
size_t ProvisionRequestSize;
```
### Related classes
* [Guardian class](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#overview): Uses `ProvisionOnlineFiles` in [StartProvisioningOnline()](/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#step-4-startprovisioningonline).
* [ProvisionFiles struct](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-provisionfiles): File structure used to generate the provision request
* [InitializeFiles struct](/api-reference/api-reference/classes/structmedcrypt-guardian-utilities-initializefiles) - Similar file structure used for initialization
## 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.
# User roles and permissions
## Role overview
You can work with Medcrypt to assign and manage roles for each of your users. [Contact us](mailto:support@medcrypt.co) to add or modify user permissions.
* **Admin:** This role full access to everything in Guardian for your organization.
* **Reporter (Auditing):** This role has view-only access to everything in Guardian for your organization.
* **Limited:** This is a specialized role for third parties who need to provision devices but shouldn't have broader system access.
### Admin role
This role has full access to all products and vulnerabilities in the organization and is the only role that can:
* Manage users
* Implement Guardian:
* Download Guardian Library
* View and export Root of Trust certificates (root and intermediate level)
* Manage device provisioning
* Approve and reject PRs and complete device provisioning
* [Manual approval type](/manage-devices/manage-device-provisioning#manual-approval-type)
* [Automatic approval type](/manage-devices/manage-device-provisioning#automatic-approval-type)
* Export device provisioning report
* View and export root and intermediate certificates
### Reporter (Auditing) role
This role has view-only access to all systems in an organization.
* View certificates:
* View and export root and intermediate certificates
* View systems monitoring
* View device provisioning
* Export device provisioning report
### Limited role
This is a special role for third parties who need to be able to provision devices at hospitals, but not view anything else. This could be a field engineer.
* Provision devices
* Upload provision request (PR)
* Download certified profile (CP)
* View devices that they have personally provisioned
* Export device provisioning report
# Modify your organization's name
If you need your organization name modified to accommodate company name changes, mergers, or acquisitions, just [contact us](mailto:support@medcrypt.com)!
# Changelog
{% hint style="info" %}
**Versioning schema**
To get new features to you as quickly as possible, if you are tracking versions in QMS, note that we currently have five versions within our Guardian platform:
* **Web:** User-facing UI
* **Core:** Core infrastructure
* **Arbiter:** Our back-end orchestration service that manages the secure device provisioning lifecycle, handles authentication requests, enforces access policies, and coordinates cryptographic operations between system components.
* **Vault:** Our secure storage service that manages encryption keys, certificates, and sensitive credentials with strict access controls.
* **Guardian Library:** Client-side integration libraries available in multiple language formats (Java, C++, C#, C, Python, Node.js). Library versions may vary depending on the language format you download
**Version ordering**
Versions are listed in the following order: Core | Web | Library | Vault | Arbiter. \
\
**How can I see my Guardian versioning?**
Click **Help > About** in the sidebar to view version information.
{% endhint %}
## 1.4.1 | 2.3.6
*June 13, 2025*
### **Summary**
* Manage device provisioning with manual or automatic approval workflows
* Bulk approve or reject provisioning requests to streamline operations
* Enhanced device provisioning filters for better device management
### **Manage device provisioning with manual or automatic approval workflows**
Choose between manual approval for complete control over device provisioning or automatic approval for streamlined operations. Manual mode gives your team review and approval capabilities for each provisioning request, ideal for high-security environments or initial rollouts. Automatic mode processes trusted device requests without intervention, perfect for production environments with established trust policies, reducing manual work and accelerating deployment timelines.
### Bulk approve or reject provisioning requests to streamline operations
Process multiple provisioning requests simultaneously with new bulk operations functionality. This dramatically reduces administrative time for large device deployments, enabling you to quickly get your devices out in the field. Perfect for manufacturing environments deploying hundreds or thousands of devices where individual approval would be time-prohibitive.
### Enhanced device provisioning filters for better device management
Added comprehensive search and filter capabilities for device provisioning activities. Quickly locate specific devices, provisioning statuses, or time-based activities with improved navigation tools. These enhancements reduce time spent managing large device inventories to seconds, improving operational efficiency for teams managing complex device ecosystems.
***
## 1.4.0 | 2.3.5
*April 22, 2025*
### Summary
* Add customer-facing manual approval workflow interface
* Enhanced security and integrity checking
### Add customer-facing manual approval workflow
You can now manage approval workflows directly within Guardian's UI, featuring a visual approval pipeline with status tracking, provisioning request review capabilities, and comprehensive audit trail for all approval decisions. This supports FDA cybersecurity documentation requirements with complete approval records and gives teams full visibility into their provisioning process.
### Enhanced security and integrity checking
Added enhanced validation and integrity checking, strengthening the overall security posture of your device provisioning workflow.
## 1.3.0
*April 3, 2025*
### Summary
* Monitor device provisioning with real-time status tracking
* View and export comprehensive provisioning request reports
* Enhanced API performance and reliability
* Enhanced RBAC security
### Monitor device provisioning with real-time status tracking
Track the current provisioning status of all devices in your fleet with real-time monitoring capabilities and historical progression views. Manufacturing teams can monitor production line provisioning, field service teams can track deployment progress, and security teams can audit provisioning compliance. This provides complete visibility into your device deployment pipeline.
### View and export comprehensive provisioning request reports
Customers can now view and [export](#export-device-provisioning-report) a comprehensive device provisioning report showing current device status snapshots and complete provisioning journey documentation for your regulatory documentation requirements. This provides better visibility into device deployment progress, audit trails for compliance requirements, and operational insights for manufacturing and deployment teams to optimize their provisioning processes.
### Enhanced API performance and reliability
Optimized all user-facing APIs with improved error handling, reliability, and response consistency. These enhancements provide better reliability for automated workflows and third-party integrations, reducing integration complexity and improving overall system stability.
### Enhanced RBAC security
Enhanced foundational role-based access control infrastructure to support stronger user session security and customer-facing user access management.
## 1.2.3
*February 13, 2025*
### Bug fix
* Fixed issue where download action for Certified Profile was disabled in Actions column of UI
## 1.2.2
*January 14, 2025*
### Bug fix
* Fixed issue where device data of devices provisioning in that session was not populating into the Devices list
## 1.2.1
*December 18, 2024*
### Summary
* Enhanced self-provisioning endpoints for adding self-provisioning to UI in future
### Enhanced self-provisioning endpoints
Made significant backend improvements to self-provisioning capabilities that prepare the foundation for upcoming UI self-provisioning features. These infrastructure enhancements improve API reliability and performance for automated provisioning workflows while setting the stage for more advanced user-facing provisioning capabilities.
## 1.2.0
*November 15, 2024*
### Summary
* Enhanced security and stability of organization verification
### Enhanced security and stability of organization verification
Enhanced security and stability of organization verification processes with better validation of organizational boundaries and access controls.
## 1.1.1
*October 4, 2024*
### Summary
* Added support for importing x509 certificates to multiple organizations
* Bug fix
### Added support for importing x509 certificates to multiple organizations
Added capability to import X.509 certificates across multiple organizations, enabling cross-organizational trust relationships and certificate sharing. This supports complex enterprise deployments where devices or systems need to establish trust across different business units or organizational boundaries while maintaining security isolation.
### Bug fix:
* Resolved issue where the certificates API wasn't returning all Certified Profiles
## 1.0.3
*September 10, 2024*
### Bug fix
* Fixed key configuration issue with vault signer keys