====== Set image trust requirement ======

===== Synopsis =====

    imgtrust [--allow] [--permanent]

===== Examples =====

=== Require trusted images ===

    imgtrust

=== Allow untrusted images ===

    imgtrust --allow

=== Permanently require trusted images ===

    imgtrust --permanent

===== Description =====

Require the use of trusted images.  When trusted images are required, any attempts to execute an untrusted image will fail.  All images are untrusted by default.  To become trusted, an image must be verified using the ''[[:cmd:imgverify]]'' command.

If the ''%%--allow%%'' option is specified then the trusted images will no longer be required, and untrusted images may be executed.

If the ''%%--permanent%%'' option is specified, then the image trust requirement will be made permanent.  Any future attempts to change the image trust requirement will fail.  For example:

    iPXE> imgtrust               # Require trusted images
    iPXE> imgtrust --allow       # Allow untrusted images
    
    iPXE> imgtrust --permanent   # Permanently require trusted images
    iPXE> imgtrust --allow       # Try to allow untrusted images
    Could not set image trust requirement: Permission denied (http://ipxe.org/0200823c)

===== Command status =====

^ Success   | The image trust requirement was set successfully             |
^ Failure   | The image trust requirement was not set successfully         |

===== See also =====

  * ''[[:cmd:imgverify]]''
  * iPXE [[:crypto|cryptography]] guide
  * [[:cmd|List of all iPXE commands]]

===== Build options =====

This command is available only when the build option ''[[:buildcfg:IMAGE_TRUST_CMD]]'' is enabled.

===== Notes =====

The default configuration is always to allow untrusted images.  To require the use of trusted images, you must use an [[:embed|embedded script]] that includes the ''imgtrust'' command.  For example:

    #!ipxe
    
    imgtrust --permanent
    dhcp
    imgfetch --name vmlinuz ${filename}
    imgverify vmlinuz ${filename}.sig
    imgexec vmlinuz

There is no way to use trusted images without using an embedded script.((The embedded script is required because there is no standard way to obtain the signature for an image corresponding to the DHCP [[:cfg:filename]].))

The ''imgtrust'' command only prevents iPXE from directly executing an untrusted image.  For example: when executing a Linux kernel image, ''imgtrust'' will prevent the execution of an untrusted kernel image, but will not prevent the use of an untrusted initrd.  If you want to ensure that any additional images (such as an initrd) are also trusted, then you must explicitly verify them using the ''[[:cmd:imgverify]]'' command.