Add secure boot support for compile command.

cli/arguments/arguments.go

@@ -37,3 +37,15 @@ func CheckFlagsConflicts(command *cobra.Command, flagNames ...string) {
 	feedback.Errorf(tr("Can't use %s flags at the same time.", "--"+strings.Join(flagNames, " "+tr("and")+" --")))
 	os.Exit(errorcodes.ErrBadArgument)
 }
+
+// CheckFlagsMandatory is a helper function useful to report errors when at least one flag is not used in a group of "required" flags
+func CheckFlagsMandatory(command *cobra.Command, flagNames ...string) {
+	for _, flagName := range flagNames {
+		if command.Flag(flagName).Changed {
+			continue
+		} else {
+			feedback.Errorf(tr("Flag %[1]s is mandatory when used in conjunction with flag %[2]s.", "--"+flagName, "--"+strings.Join(flagNames, " "+tr("and")+" --")))
+			os.Exit(errorcodes.ErrBadArgument)
+		}
+	}
+}

cli/compile/compile.go

@@ -53,6 +53,9 @@ var (
 	buildCachePath          string               // Builds of 'core.a' are saved into this path to be cached and reused.
 	buildPath               string               // Path where to save compiled files.
 	buildProperties         []string             // List of custom build properties separated by commas. Or can be used multiple times for multiple properties.
+	keysKeychain            string               // The path of the dir where to search for the custom keys to sign and encrypt a binary. Used only by the platforms that supports it
+	signKey                 string               // The name of the custom signing key to use to sign a binary during the compile process. Used only by the platforms that supports it
+	encryptKey              string               // The name of the custom encryption key to use to encrypt a binary during the compile process. Used only by the platforms that supports it
 	warnings                string               // Used to tell gcc which warning level to use.
 	verbose                 bool                 // Turns on verbose mode.
 	quiet                   bool                 // Suppresses almost every output.
@@ -100,6 +103,12 @@ func NewCommand() *cobra.Command {
 		tr("List of custom build properties separated by commas. Or can be used multiple times for multiple properties."))
 	compileCommand.Flags().StringArrayVar(&buildProperties, "build-property", []string{},
 		tr("Override a build property with a custom value. Can be used multiple times for multiple properties."))
+	compileCommand.Flags().StringVar(&keysKeychain, "keys-keychain", "",
+		tr("The path of the dir to search for the custom keys to sign and encrypt a binary. Used only by the platforms that support it."))
+	compileCommand.Flags().StringVar(&signKey, "sign-key", "",
+		tr("The name of the custom signing key to use to sign a binary during the compile process. Used only by the platforms that support it."))
+	compileCommand.Flags().StringVar(&encryptKey, "encrypt-key", "",
+		tr("The name of the custom encryption key to use to encrypt a binary during the compile process. Used only by the platforms that support it."))
 	compileCommand.Flags().StringVar(&warnings, "warnings", "none",
 		tr(`Optional, can be: %s. Used to tell gcc which warning level to use (-W flag).`, "none, default, more, all"))
 	compileCommand.Flags().BoolVarP(&verbose, "verbose", "v", false, tr("Optional, turns on verbose mode."))
@@ -142,6 +151,10 @@ func runCompileCommand(cmd *cobra.Command, args []string) {
 
 	sketchPath := arguments.InitSketchPath(path)
 
+	if keysKeychain != "" || signKey != "" || encryptKey != "" {
+		arguments.CheckFlagsMandatory(cmd, "keys-keychain", "sign-key", "encrypt-key")
+	}
+
 	var overrides map[string]string
 	if sourceOverrides != "" {
 		data, err := paths.New(sourceOverrides).ReadFile()
@@ -198,6 +211,9 @@ func runCompileCommand(cmd *cobra.Command, args []string) {
 		CreateCompilationDatabaseOnly: compilationDatabaseOnly,
 		SourceOverride:                overrides,
 		Library:                       library,
+		KeysKeychain:                  keysKeychain,
+		SignKey:                       signKey,
+		EncryptKey:                    encryptKey,
 	}
 	compileStdOut := new(bytes.Buffer)
 	compileStdErr := new(bytes.Buffer)

commands/compile/compile.go

@@ -125,6 +125,15 @@ func Compile(ctx context.Context, req *rpc.CompileRequest, outStream, errStream
 		}
 	}
 
+	// At the current time we do not have a way of knowing if a board supports the secure boot or not,
+	// so, if the flags to override the default keys are used, we try override the corresponding platform property nonetheless.
+	// It's not possible to use the default name for the keys since there could be more tools to sign and encrypt.
+	// So it's mandatory to use all three flags to sign and encrypt the binary
+	securityKeysOverride := []string{}
+	if req.KeysKeychain != "" && req.SignKey != "" && req.EncryptKey != "" {
+		securityKeysOverride = append(securityKeysOverride, "build.keys.keychain="+req.KeysKeychain, "build.keys.sign_key="+req.GetSignKey(), "build.keys.encrypt_key="+req.EncryptKey)
+	}
+
 	builderCtx := &types.Context{}
 	builderCtx.PackageManager = pm
 	builderCtx.FQBN = fqbn
@@ -165,6 +174,7 @@ func Compile(ctx context.Context, req *rpc.CompileRequest, outStream, errStream
 	builderCtx.WarningsLevel = req.GetWarnings()
 
 	builderCtx.CustomBuildProperties = append(req.GetBuildProperties(), "build.warn_data_percentage=75")
+	builderCtx.CustomBuildProperties = append(req.GetBuildProperties(), securityKeysOverride...)
 
 	if req.GetBuildCachePath() != "" {
 		builderCtx.BuildCachePath = paths.New(req.GetBuildCachePath())

docs/guides/secure-boot.md

@@ -0,0 +1,67 @@
+# Secure Boot
+
+A ["secure boot"](https://www.keyfactor.com/blog/what-is-secure-boot-its-where-iot-security-starts/) capability may be
+offered by Arduino boards platforms.
+
+The compiled sketch is signed and encrypted by a [tool](../platform-specification.md#tools) before being flashed to the
+target board. The bootloader of the board is then responsible for starting the compiled sketch only if the matching keys
+are used.
+
+To be able to correctly carry out all the operations at the end of the build we can leverage the
+[post build hooks](../platform-specification.md#pre-and-post-build-hooks-since-arduino-ide-165) to sign and encrypt a
+binary by using `recipe.hooks.objcopy.postobjcopy.NUMBER.pattern` key in
+[`platform.txt`](../platform-specification.md#platformtxt). The security keys used are defined in the
+[`boards.txt`](../platform-specification.md#boardstxt) file, this way there could be different keys for different
+boards.
+
+```
+[...]
+## Create secure image (bin file)
+recipe.hooks.objcopy.postobjcopy.1.pattern={build.postbuild.cmd}
+
+#
+# IMGTOOL
+#
+tools.imgtool.cmd=imgtool
+tools.imgtool.flags=sign --key "{build.keys.keychain}/{build.keys.sign_key}" --encrypt "{build.keys.keychain}/{build.keys.encrypt_key}" "{build.path}/{build.project_name}.bin" "{build.path}/{build.project_name}.bin" --align {build.alignment} --max-align {build.alignment} --version {build.version} --header-size {build.header_size} --pad-header --slot-size {build.slot_size}
+[...]
+
+```
+
+By having only `tools.TOOL_NAME.cmd` and `tools.TOOL_NAME.flags`, we can customize the behavior with a
+[custom board option](../platform-specification.md#custom-board-options). Then in the
+[`boards.txt`](../platform-specification.md#boardstxt) we can define the new option to use a different
+`build.postbuild.cmd`:
+
+```
+[...]
+menu.security=Security setting
+
+envie_m7.menu.security.none=None
+envie_m7.menu.security.sien=Signature + Encryption
+
+envie_m7.menu.security.sien.build.postbuild.cmd="{tools.imgtool.cmd}" {tools.imgtool.flags}
+envie_m7.menu.security.none.build.postbuild.cmd="{tools.imgtool.cmd}" exit
+
+envie_m7.menu.security.sien.build.keys.keychain={runtime.hardware.path}/Default_Keys
+envie_m7.menu.security.sien.build.keys.sign_key=default-signing-key.pem
+envie_m7.menu.security.sien.build.keys.encrypt_key=default-encrypt-key.pem
+[...]
+```
+
+The security keys can be added with:
+
+- `build.keys.keychain` indicates the path of the dir where to search for the custom keys to sign and encrypt a binary.
+- `build.keys.sign_key` indicates the name of the custom signing key to use to sign a binary during the compile process.
+- `build.keys.encrypt_key` indicates the name of the custom encryption key to use to encrypt a binary during the compile
+  process.
+
+It's suggested to use the property names mentioned before, because they can be overridden respectively with
+`--keys-keychain`, `--sign-key` and `--encrypt-key` Arduino CLI [compile flags](../commands/arduino-cli_compile.md).
+
+For example, by using the following command, the sketch is compiled and the resulting binary is signed and encrypted
+with the specified keys located in `/home/user/Arduino/keys` directory:
+
+```
+arduino-cli compile -b arduino:mbed_portenta:envie_m7:security=sien --keys-keychain /home/user/Arduino/keys --sign-key ecsdsa-p256-signing-key.pem --encrypt-key ecsdsa-p256-encrypt-key.pem /home/user/Arduino/MySketch
+```

docs/platform-specification.md

@@ -155,6 +155,20 @@ the name of the architecture is set as well.
 
 There are some other **{build.xxx}** properties available, that are explained in the boards.txt section of this guide.
 
+#### Security credential properties
+
+Some of them allow specifying trusted security credentials (signing and encryption keys) that can be used by a
+["secure boot" system](guides/secure-boot.md):
+
+- `build.keys.keychain`: for the directory containing the keys
+- `build.keys.sign_key`: for the signing key
+- `build.keys.encrypt_key`: for the encryption key
+
+If any of these properties are defined, the others are required.
+
+These properties can be overwritten respectively with `--keys-keychain`, `--sign-key`, `--encrypt-key`
+[compile](commands/arduino-cli_compile.md) flags in the Arduino CLI.
+
 #### Recipes to compile source code
 
 We said that the Arduino development software determines a list of files to compile. Each file can be source code
@@ -1294,7 +1308,7 @@ It can sometimes be useful to provide user selectable configuration options for
 could be provided in two or more variants with different microcontrollers, or may have different crystal speed based on
 the board model, and so on...
 
-When using Arduino CLI, the option can be selected via the FQBN.
+When using Arduino CLI, the option can be selected via the FQBN, or using the `--board-options` flag
 
 In the Arduino IDE the options add extra menu items under the "Tools" menu.
 

legacy/builder/setup_build_properties.go

@@ -26,6 +26,7 @@ import (
 	"github.com/arduino/arduino-cli/legacy/builder/types"
 	properties "github.com/arduino/go-properties-orderedmap"
 	timeutils "github.com/arduino/go-timeutils"
+	"github.com/pkg/errors"
 )
 
 type SetupBuildProperties struct{}
@@ -126,6 +127,14 @@ func (s *SetupBuildProperties) Run(ctx *types.Context) error {
 
 	buildProperties.Merge(ctx.PackageManager.CustomGlobalProperties)
 
+	keychainProp := buildProperties.ContainsKey("build.keys.keychain")
+	signProp := buildProperties.ContainsKey("build.keys.sign_key")
+	encryptProp := buildProperties.ContainsKey("build.keys.encrypt_key")
+	// we verify that all the properties for the secure boot keys are defined or none of them is defined.
+	if (keychainProp || signProp || encryptProp) && !(keychainProp && signProp && encryptProp) {
+		return errors.Errorf("%s platform does not specify correctly default sign and encryption keys", targetPlatform.Platform)
+	}
+
 	ctx.BuildProperties = buildProperties
 
 	return nil