WeOS
5.29.0

# Secure Boot unlock using tokens

## About

This document provides instructions on configuring your device to use vendor-provided unsigned images.

For an overview of all available boot configuration options refer to the configuration guide:

- Boot Configuration Guide

## Introduction

By allowing a device to ignore the security of the loaded OS, one can test various unsigned images. This can typically be needed in debug situations or when the vendor provides trial solutions as images.

The available unlock methods vary depending on the device’s hardware security capabilities and are mutually exclusive:

1. Unlock License Method: For devices using a hardware anchor, i.e.: secure boot with a hardware based root-of-trust, only a cryptographically correct license file will unlock this bypass. This license token can be acquired from your vendor using credentials from the specific device in question. This is called the unlock-license function.

2. Allow Untrusted Method: Devices that do not use a hardware anchor can use the allow-untrusted function.

## Configuration

In order to configure the system to ignore the security, the following parameters can be adjusted. For more information on these options refer to the boot configuration options page.

### allow-untrusted

When a device without hardware anchor is used (hardware anchor indicates disabled), this option is used.

The allow-untrusted is enabled in the following manner:

    example:/boot/#> loader
    example:/boot/loader/#> allow-untrusted
    example:/boot/loader/#> end
    Saving bootloader configuration to FLASH
    100% / [====================================================================]
    example:/boot/#>

After reboot a warning message should be displayed by the bootloader.

    Found allow untrusted token. Ignoring image signatures .......... [WARN]

### unlock-license

When a device with hardware anchor is used (hardware anchor indicates enabled), this option is used. For this to work, you need to a accuire a unlock license. To do so, you will need to send the product article number and the unique IDs presented in `show system-information`. Any mismatch with the unlock license will be displayed during the import and will result in a the function not being enabled.

`[no] unlock-license [media <label>] [proto <ftp|tftp|scp|sftp|http|https>] [user <username>] [password <password>] address[:port] FILENAME.json`
  Starts an upgrade process based on the parameters given.
  no
    Remove set license.
  media
    Label of the media (USB) to import from. Alternative to specifying a file transfer protocol and address.
  proto
    Protocol to use. ftp, tftp, scp, sftp, http or https.
  user
    Username if used by protocol.
  password
    Password if used by protocol.
  address[:port]
    IP-address and optional port of the server from which the image/package should be retrieved.
  FILENAME.json
    The name of the license file. It must be a JSON file and contain the correct format.

The unlock-license is enabled in the following manner:

    example:/boot/#> loader
    example:/boot/loader/#> unlock-license proto tftp 192.168.2.1 licensefile.json
    example:/boot/loader/#> end
    Saving bootloader configuration to FLASH
    100% / [====================================================================]
    example:/boot/#>

After reboot a warning message should be displayed by the bootloader.

    Found valid unlock license. Ignoring image signatures ........... [WARN]

« Previous Next »