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

  • Connected provisioning: Devices automatically submit requests to the Devices 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 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 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 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 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.

Provision via the API

You can provision device using the Guardian 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.

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.

Last updated

Was this helpful?