# Begin device provisioning

## Device provisioning overview

Device provisioning requires back-and-forth communication with Guardian Cloud. If the provisioning device has a direct connection to Guardian Cloud, this is referred to as **Connected** provisioning. If the provisioning device does not have a direct connection to Guardian Cloud, this is referred to as **Disconnected** provisioning. **Proxy** provisioning is a special case where a device that can complete Connected provisioning can proxy a Provision Request for a device completing Disconnected provisioning.

## General prerequisites

Before beginning device provisioning, ensure you have:

* Guardian account
* Created and configured your system in Guardian
* Received your provisioning package from Medcrypt
* Downloaded and installed Guardian Library for your platform 
* Installed provisioning package on your device 

Check the method you will be using for additional prerequisites.

## Provisioning methods

Choose the provisioning method that best fits your device's connectivity and integration requirements:

* [**Provision using Guardian API**](https://docs.medcrypt.com/api-reference/api-reference/classes/classmedcrypt-guardian-guardian#device-provisioning-functions)**:** Use the Guardian Library directly in your application code for full programmatic control over the provisioning process. Ideal for devices that need deep integration with Guardian's cryptographic operations.
* [**Provision via the UI**](#provisioning-via-the-ui)**:** Use the Guardian web interface to manually upload provisioning requests and download certified profiles. 
  * **Disconnected devices:** Best for devices without network connectivity where field technicians handle file transfers manually.
* [**Provision using command line**](#provision-via-the-command-line)**:** Use the `mcguard_provision` utility for testing, devices that cannot integrate Guardian Library, or proxy provisioning setups:
  * **Connected devices:** Devices with network connectivity that can communicate directly with Guardian Cloud.
  * **Disconnected devices:** Offline provisioning when devices have no network connectivity.
  * **Proxy provisioning:** Use utility with a gateway device that acts as a proxy for other devices without direct internet access.

### What's covered in this topic

* **Disconnected provisioning:** Users can use the command line or the [Provisioning](https://docs.medcrypt.com/manage-devices/begin-device-provisioning) page to submit provision requests (PRs) and download certified profiles (CPs). They can then manage device provisioning and export the device provisioning report from the **Devices** page. This is an interim solution while we add full provisioning lifecycle support to the **Devices** page. For the full workflow walkthrough, refer to [Understand device provisioning](https://docs.medcrypt.com/manage-devices/understand-device-provisioning).
* **Connected provisioning:** Devices automatically submit requests to the [Devices](https://docs.medcrypt.com/manage-devices/manage-device-provisioning) page, and Guardian automatically sends a CP to the respective device. 
* **Proxy provisioning:** A proxy is provisioned, then used to provision other devices.

## Guardian file types and extensions

Guardian uses several file types with specific extensions during the provisioning process:

**Provision Request:** File used for transmitting information including public keys to the Guardian Cloud backend. This contains the Certificate Signing Requests (CSRs) sent to Guardian Cloud. Extension: `.mcpr`

**TrustStore:** Trust anchors for the Guardian platform. Extension: `.mcts`

**Profile files:**

1. **Certified Profile to be Provisioned:** Signed instructions and configuration for the Guardian library and provisioning operations. This is the initial profile template for this device type created during the provisioning process. Extension: `.mcpp`
2. **Certified Profile:** Signed instructions and configuration for the Guardian library run and reprovisioning operations. This is the final device profile created during the provisioning process. Extension: `.mcp`

**Identity files:** 

1. **Private Identity to be Provisioned:** Key material for initial provisioning operations and connections. This is the initial private identity template. Extension: `.mcpip`
2. **Private Identity:** Key material for reprovisioning and run operations and connections. This is the final private identity file, which contains the private keys that stay on the device. Extension: `.mcpi`

### File usage by operation type

**Files used during provisioning:**

* TrustStore
* Private Identity for Provisioning
* Certified Profile for Provisioning

**Files used during reprovisioning:**

* TrustStore
* Private Identity
* Certified Profile

Files used when running

* TrustStore
* Private Identity
* Certified Profile

## General provisioning steps

### 1. Generate device keys and provision request (PR)

* This step is done on the provisioning device for maximum key security.
* Can be completed using either the Guardian library API or `mcguard_provision` CLI utility
* A PR contains a bundle of multiple certificate signing requests (CSRs) with all information necessary for Guardian Cloud to issue the resulting provisioned profile and certificates.
  * A CSR contains:
    * **Public key** - the cryptographic key that will be embedded in the issued certificate
    * **Identity information** - details like organization name, device identifier, intended use
    * **Digital signature** - proves the requester possesses the corresponding private key
  * How CSRs work:
    1. Device generates a public/private key pair
    2. Device creates CSR containing the public key + identity info
    3. Device signs the CSR with its private key
    4. CSR is sent to Certificate Authority (Guardian Cloud in your case)
    5. CA validates the request and issues a certificate
    6. Private key never leaves the device
* The keys are stored in the generated Private Identity.

### 2. Submit PR to Guardian Cloud

* **Connected provisioning:** 
  * API or CLI: Use the Guardian library API or `mcguard_provision` CLI utility to automatically submit the generated PR to Guardian Cloud and retrieve the respective certified profile. completing that device's provisioning.
* **Disconnected provisioning:** Upload the generated PR using the Guardian Cloud UI.

### 3. Retrieve Certified Profile (CP) from Guardian Cloud

* **Connected provisioning:** 
  * CLI: When the device's PR has been processed, its certified profile will be automatically retrieved.
  * API: Use the Guardian library API to retrieve the certified profile.
* **Disconnected provisioning:** Download the issued certified profile from the Guardian Cloud UI, then install it on the respective device.

## Provision via the UI

### Disconnected provisioning method

Use this method when devices have no network connectivity and field technicians must manually handle file transfers.

**Additional prerequisites:**

* Provisioning request (.mcpr file) extracted from your device

**Steps for disconnected provisioning:**

You can begin the provisioning process from the **Provisioning** page, then [manage provisioning](https://docs.medcrypt.com/manage-devices/manage-device-provisioning) from the Devices page. 

1. **Extract PR from device:** Field technician extracts the provisioning request ( `.mcpr` file) generated by the device.
2. Select a system name from the quick filter drop-downs on this page. You can only select one system name, also known as your system definition.
3. After signing in to Guardian, click the **Provisioning** item in the sidebar. 
4. Click the **Begin provisioning** button. This will prompt you to upload a provisioning request. This is an `.mcpr` file. 
5. **Monitor approval:** PR will appear in [Devices](https://docs.medcrypt.com/manage-devices/manage-device-provisioning) page for approval/processing workflow
   * **Systems with automatic approval:** Guardian will automatically move device PRs through the approval process, then send each device's certified profile (CP) directly to the device.
   * **Systems with manual approval:** Your team will manually approve or reject, then manually complete provisioning. 
6. **Download profile (disconnected):** When the provisioning request has been processed, you'll be prompted to download the certified profile or CP ( `.mcp` file) from the **Provisioning** page.
7. **Complete provisioning (disconnected):** CP is manually downloaded from the [Provisioning](https://docs.medcrypt.com/manage-devices/begin-device-provisioning) page and manually installed on the device. Click **Complete provisioning** to mark it as **Provisioned** in Guardian.

### Connected provisioning method

Connected devices will automatically send their provisioning requests (PRs) to Guardian Cloud. 

* Systems with automatic approval, Guardian will automatically move device PRs through the approval process, then send each device's certified profile (CP) directly to the device.
* Systems with manual approval: Your team will manually approve or reject, then manually complete provisioning in the [Devices](https://docs.medcrypt.com/manage-devices/manage-device-provisioning) page. 

For both approval types, the CP is automatically downloaded from Guardian and automatically installed on the device, then the device is automatically marked as **Provisioned** in Guardian.

## Provision via the command line

Use the `mcguard_provision` utility for testing provisioning workflows, devices that cannot integrate Guardian Library, or proxy provisioning setups. 

The command line tool supports:

* Connected devices with network connectivity
* Disconnected devices requiring offline provisioning
* Proxy scenarios where a gateway device handles provisioning for other devices

For complete command syntax, examples, and troubleshooting guidance, see [Provision devices using command line](https://docs.medcrypt.com/manage-devices/begin-device-provisioning/provision-devices-using-command-line).

## Provision via the API

You can [provision device using the Guardian API](https://docs.medcrypt.com/manage-devices/begin-device-provisioning/provision-devices-using-api), encompassing device setup, generating secure credentials, and establishing trusted connections. To do so, you'll need to integrate the Guardian Library  into your application code. This provides full programmatic control over the provisioning process through function calls rather than external tools or manual steps.

The API supports connected, disconnected, and proxy provisioning workflows. For complete implementation details, function documentation, and code examples, see [Provision devices using API](https://docs.medcrypt.com/manage-devices/begin-device-provisioning/provision-devices-using-api).

#### When to use the API:

* You need to embed provisioning logic directly in your device software
* You need automated provisioning workflows without manual intervention
* You need fine-grained control over the provisioning process
* You need to integrate with existing device management systems

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