docs/engine/release/Code-signing-metadata.md - mirrors/flutter - Git at Google

 # Code signing

 This covers the process of how to add / update code signing metadata of flutter
 engine binaries.

 ## Overview

 Flutter engine binaries are built with GN and ninja, referencing pre-defined
 configurations such as ci/builders
 [JSON files](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_host_engine.json).
 During flutter releases, engineers need to code sign mac engine binaries to
 assure users that they come from a known source, have not been tampered with,
 and should not be quarantined by Gatekeepers.

 Each of the Flutter engine binaries are either code signed with entitlements, or
 code signed without entitlements. (An entitlement, along with information from
 the developer account, grant particular permissions to binaries, such as
 capability to access the user's home automation network.) For example, impellerc
 is code signed with flutter entitlements, whereas .dylib files are usually code
 signed without entitlements.

 ## Add / Update code signing metadata

 ### Glossary

 1.  BUILD.gn files: files that include build rules of GN targets. An example is
     the
     [BUILD.gn file of flutter engine](https://github.com/flutter/flutter/blob/main/engine/src/flutter/BUILD.gn).
 2.  leaf node of an engine binary: the minimal gn target that could produce such
     an engine binary. That is, this target does not have any dependencies on
     other gn targets that could build this engine binary.
 3.  dependencies: Every gn target could have dependencies on other gn targets.
     The dependency of a gn target is defined in the `deps` field of the target's
     build rule.

 ### ways to generate engine binary

 Generally, there are two ways to generate an engine binary:

 1.  Through build rules defined in BUILD.gn files.

 2.  Through global generator scripts. (these scripts are normally .py files)

 To distinguish between the two, an engine binary is built through global
 generator if it is listed in the `archives` -> `destination` field of the
 builder JSON
 ([mac_ios_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_ios_engine.json)
 or
 [mac_host_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_host_engine.json)).
 For example, `darwin-x64/FlutterEmbedder.framework.zip`. Whereas binaries built
 with BUILD.gn files are listed among the `builds` field of the JSON file. For
 example, `darwin-x64/artifacts.zip`. We will provide examples for both
 scenarios.

 ### To add / update code signing metadata in BUILD.gn files:

 1.  Find the leaf node where the target engine binary is built. To do so,
     Recursively trace the `deps` field of the engine artifact. The paths in
     `deps` field of the GN target correspond to the paths of other GN targets
     that are dependencies of the current GN target.

 2.  Add / Update the `metadata` field of the leaf node. For a new engine binary:

     2.1 if it should be code signed with entitlements, add [the name of the
     engine binary] to the `entitlement_file_path` field in `metadata` .

     2.2 if the binary shouldn't be code signed with entitlements, add [the name
     of the engine binary] to the `without_entitlement_file_path` field in
     `metadata` .

 3.  If a `entitlement_file_path` or a `without_entitlement_file_path` field does
     not exist:

     **note**: this step is only needed if the target includes solely binaries
     that have never been code signed before. This step also requires some
     background on flutter engine and gn build rules.

     Add a `metadata` field in the gn target of the leaf node, and put the name
     of the binary in this field. e.g.

     ```
     metadata = {
         entitlement_file_path = [ "libtessellator.dylib" ]
     }
     ```

     In the same file that produces the engine artifact(zip file), add a build
     rule to collect the data keys. e.g.

     ```
     generated_file("artifacts_entitlement_config") {
         outputs = [ "$target_gen_dir/entitlements.txt" ]

         data_keys = [ "entitlement_file_path" ]

         deps = [ "//flutter/lib/snapshot:generate_snapshot_bin" ]
         if (flutter_runtime_mode == "debug") {
             deps += [
             "//flutter/impeller/compiler:impellerc",
             "//flutter/impeller/tessellator:tessellator_shared",
             "//flutter/shell/testing:testing",
             "//flutter/tools/path_ops:path_ops",
             ]
         }
     }
     ```

     Finally, embed the file with collected data keys in the zip artifact. e.g.

     ```
     if (host_os == "mac") {
         deps += [ ":artifacts_entitlement_config" ]
         files += [
             {
             source = "$target_gen_dir/entitlements.txt"
             destination = "entitlements.txt"
             },
         ]
     }
     ```

 #### Example

 Suppose impellerc is a binary that exist in a zip bundle called artifacts.zip.
 Then impellerc is the name of the binary, and artifacts.zip is the flutter
 engine artifact.

 1.  Following step 1, the `deps` field of the GN target of artifacts.zip
     includes the path of impeller dependency:
     `//flutter/impeller/compiler:impellerc`. Following this path, we locate the
     GN file at `flutter/impeller/compiler/BUILD.gn`, and find the leaf node that
     builds impellerc: `impeller_component("impellerc")`.

 2.  Following step 2, since `impellerc` should be code signed with entitlements,
     we go to the `metadata` field of the impellerc target, and add the name
     `impellerc` to the `entitlement_file_path` array inside the `metadata`
     field.

 You can reference the
 [BUILD.gn file of impellerc](https://github.com/flutter/flutter/blob/main/engine/src/flutter/impeller/compiler/BUILD.gn).

 ### To add / update code signing metadata in global generator files:

 1.  Find the generator script path listed under `generators` -> `tasks` ->
     `script` of the ci/builder JSON files
     ([mac_ios_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_ios_engine.json)
     or
     [mac_host_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_host_engine.json)).

     The generator script related to iOS is located at
     `sky/tools/create_ios_framework.py`, and generator script related to
     macOS is located at `sky/tools/create_macos_framework.py`.

 2.  Add / Update the variables ending with `with_entitlements` /
     `without_entitlements` suffix from the generator script you found in step
     one.

     As an example, you can find variables `ios_file_without_entitlements` and
     `ios_file_with_entitlements` in sky/tools/create_ios_framework.py; and
     find variables `filepath_without_entitlements` and
     `filepath_with_entitlements` in sky/tools/create_macos_framework.py

     2.1 if the binary should be code signed with entitlements, add [the name of
     the binary] to the variable name with the `with_entitlements` suffix.
     (`ios_file_with_entitlements` or `filepath_with_entitlements` depending on
     which script)

     2.2 if the binary shouldn't be code signed with entitlements, add [the name
     of the binary] to the variable name with the `without_entitlements` suffix.

 #### Example

 Suppose `Flutter.xcframework/ios-arm64/Flutter.framework/Flutter` is a binary
 that exist in a zip bundle called `ios/artifacts.zip`.

 1.  Following step 1, in
     [mac_ios_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_ios_engine.json),
     it builds the artifact with the
     `flutter/sky/tools/create_ios_framework.py` script.

 2.  Following step 2, since
     `Flutter.xcframework/ios-arm64/Flutter.framework/Flutter` shouldn't be code
     signed with entitlements, we add the binary name
     `Flutter.xcframework/ios-arm64/Flutter.framework/Flutter` to the
     `ios_file_without_entitlements` variable.

 You can reference the generator script
 [create_ios_framework.py](https://github.com/flutter/flutter/blob/main/engine/src/flutter/sky/tools/create_ios_framework.py).

 ## Code signing artifacts other than flutter engine binaries

 The code signing functionality is implemented as [a recipe module in flutter recipes](https://cs.opensource.google/flutter/recipes/+/master:recipe_modules/signing/api.py). Therefore it can also be used to
 code sign arbitrary flutter artifacts built through recipe, for example, flutter iOS usb dependencies.

 To code sign, after the artifacts are built, pass the file paths into
 the code signing recipe module and invoke the function. An example is [how engine V2 invokes the code signing recipe module](https://cs.opensource.google/flutter/recipes/+/master:recipes/engine_v2/engine_v2.py;l=197-212).
	# Code signing

	This covers the process of how to add / update code signing metadata of flutter
	engine binaries.

	## Overview

	Flutter engine binaries are built with GN and ninja, referencing pre-defined
	configurations such as ci/builders
	[JSON files](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_host_engine.json).
	During flutter releases, engineers need to code sign mac engine binaries to
	assure users that they come from a known source, have not been tampered with,
	and should not be quarantined by Gatekeepers.

	Each of the Flutter engine binaries are either code signed with entitlements, or
	code signed without entitlements. (An entitlement, along with information from
	the developer account, grant particular permissions to binaries, such as
	capability to access the user's home automation network.) For example, impellerc
	is code signed with flutter entitlements, whereas .dylib files are usually code
	signed without entitlements.

	## Add / Update code signing metadata

	### Glossary

	1. BUILD.gn files: files that include build rules of GN targets. An example is
	the
	[BUILD.gn file of flutter engine](https://github.com/flutter/flutter/blob/main/engine/src/flutter/BUILD.gn).
	2. leaf node of an engine binary: the minimal gn target that could produce such
	an engine binary. That is, this target does not have any dependencies on
	other gn targets that could build this engine binary.
	3. dependencies: Every gn target could have dependencies on other gn targets.
	The dependency of a gn target is defined in the `deps` field of the target's
	build rule.

	### ways to generate engine binary

	Generally, there are two ways to generate an engine binary:

	1. Through build rules defined in BUILD.gn files.

	2. Through global generator scripts. (these scripts are normally .py files)

	To distinguish between the two, an engine binary is built through global
	generator if it is listed in the `archives` -> `destination` field of the
	builder JSON
	([mac_ios_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_ios_engine.json)
	or
	[mac_host_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_host_engine.json)).
	For example, `darwin-x64/FlutterEmbedder.framework.zip`. Whereas binaries built
	with BUILD.gn files are listed among the `builds` field of the JSON file. For
	example, `darwin-x64/artifacts.zip`. We will provide examples for both
	scenarios.

	### To add / update code signing metadata in BUILD.gn files:

	1. Find the leaf node where the target engine binary is built. To do so,
	Recursively trace the `deps` field of the engine artifact. The paths in
	`deps` field of the GN target correspond to the paths of other GN targets
	that are dependencies of the current GN target.

	2. Add / Update the `metadata` field of the leaf node. For a new engine binary:

	2.1 if it should be code signed with entitlements, add [the name of the
	engine binary] to the `entitlement_file_path` field in `metadata` .

	2.2 if the binary shouldn't be code signed with entitlements, add [the name
	of the engine binary] to the `without_entitlement_file_path` field in
	`metadata` .

	3. If a `entitlement_file_path` or a `without_entitlement_file_path` field does
	not exist:

	note: this step is only needed if the target includes solely binaries
	that have never been code signed before. This step also requires some
	background on flutter engine and gn build rules.

	Add a `metadata` field in the gn target of the leaf node, and put the name
	of the binary in this field. e.g.

	```
	metadata = {
	entitlement_file_path = [ "libtessellator.dylib" ]
	}
	```

	In the same file that produces the engine artifact(zip file), add a build
	rule to collect the data keys. e.g.

	```
	generated_file("artifacts_entitlement_config") {
	outputs = [ "$target_gen_dir/entitlements.txt" ]

	data_keys = [ "entitlement_file_path" ]

	deps = [ "//flutter/lib/snapshot:generate_snapshot_bin" ]
	if (flutter_runtime_mode == "debug") {
	deps += [
	"//flutter/impeller/compiler:impellerc",
	"//flutter/impeller/tessellator:tessellator_shared",
	"//flutter/shell/testing:testing",
	"//flutter/tools/path_ops:path_ops",
	]
	}
	}
	```

	Finally, embed the file with collected data keys in the zip artifact. e.g.

	```
	if (host_os == "mac") {
	deps += [ ":artifacts_entitlement_config" ]
	files += [
	{
	source = "$target_gen_dir/entitlements.txt"
	destination = "entitlements.txt"
	},
	]
	}
	```

	#### Example

	Suppose impellerc is a binary that exist in a zip bundle called artifacts.zip.
	Then impellerc is the name of the binary, and artifacts.zip is the flutter
	engine artifact.

	1. Following step 1, the `deps` field of the GN target of artifacts.zip
	includes the path of impeller dependency:
	`//flutter/impeller/compiler:impellerc`. Following this path, we locate the
	GN file at `flutter/impeller/compiler/BUILD.gn`, and find the leaf node that
	builds impellerc: `impeller_component("impellerc")`.

	2. Following step 2, since `impellerc` should be code signed with entitlements,
	we go to the `metadata` field of the impellerc target, and add the name
	`impellerc` to the `entitlement_file_path` array inside the `metadata`
	field.

	You can reference the
	[BUILD.gn file of impellerc](https://github.com/flutter/flutter/blob/main/engine/src/flutter/impeller/compiler/BUILD.gn).

	### To add / update code signing metadata in global generator files:

	1. Find the generator script path listed under `generators` -> `tasks` ->
	`script` of the ci/builder JSON files
	([mac_ios_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_ios_engine.json)
	or
	[mac_host_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_host_engine.json)).

	The generator script related to iOS is located at
	`sky/tools/create_ios_framework.py`, and generator script related to
	macOS is located at `sky/tools/create_macos_framework.py`.

	2. Add / Update the variables ending with `with_entitlements` /
	`without_entitlements` suffix from the generator script you found in step
	one.

	As an example, you can find variables `ios_file_without_entitlements` and
	`ios_file_with_entitlements` in sky/tools/create_ios_framework.py; and
	find variables `filepath_without_entitlements` and
	`filepath_with_entitlements` in sky/tools/create_macos_framework.py

	2.1 if the binary should be code signed with entitlements, add [the name of
	the binary] to the variable name with the `with_entitlements` suffix.
	(`ios_file_with_entitlements` or `filepath_with_entitlements` depending on
	which script)

	2.2 if the binary shouldn't be code signed with entitlements, add [the name
	of the binary] to the variable name with the `without_entitlements` suffix.

	#### Example

	Suppose `Flutter.xcframework/ios-arm64/Flutter.framework/Flutter` is a binary
	that exist in a zip bundle called `ios/artifacts.zip`.

	1. Following step 1, in
	[mac_ios_engine.json](https://github.com/flutter/flutter/blob/main/engine/src/flutter/ci/builders/mac_ios_engine.json),
	it builds the artifact with the
	`flutter/sky/tools/create_ios_framework.py` script.

	2. Following step 2, since
	`Flutter.xcframework/ios-arm64/Flutter.framework/Flutter` shouldn't be code
	signed with entitlements, we add the binary name
	`Flutter.xcframework/ios-arm64/Flutter.framework/Flutter` to the
	`ios_file_without_entitlements` variable.

	You can reference the generator script
	[create_ios_framework.py](https://github.com/flutter/flutter/blob/main/engine/src/flutter/sky/tools/create_ios_framework.py).

	## Code signing artifacts other than flutter engine binaries

	The code signing functionality is implemented as [a recipe module in flutter recipes](https://cs.opensource.google/flutter/recipes/+/master:recipe_modules/signing/api.py). Therefore it can also be used to
	code sign arbitrary flutter artifacts built through recipe, for example, flutter iOS usb dependencies.

	To code sign, after the artifacts are built, pass the file paths into
	the code signing recipe module and invoke the function. An example is [how engine V2 invokes the code signing recipe module](https://cs.opensource.google/flutter/recipes/+/master:recipes/engine_v2/engine_v2.py;l=197-212).