From 4e9ffced249545add6b4fb7d037de1d2c4b6bb85 Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Tue, 14 May 2024 18:48:02 -0700 Subject: [PATCH] feat: add support for and document --deep for subresources (#316) --- README.md | 39 +++++++++++++++++++++++++++++++++++++-- src/sign.ts | 8 +++++++- src/types.ts | 7 +++++++ 3 files changed, 51 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 16bc30c..2fecc9b 100644 --- a/README.md +++ b/README.md @@ -66,15 +66,21 @@ Default to `undefined`. `optionsForFile` - *Function* Function that receives the path to a file and can return the entitlements to use for that file to override the default behavior. The -object this function returns can include any of the following optional keys. +object this function returns can include any of the following optional keys. Any properties that are returned **override** the default +values that `@electron/osx-sign` generates. Any properties not returned use the default value. + +Take care when overriding the `entitlements` property as for security reasons different bundles within Electron are normally signed with +different entitlement files. See the [default implementation](https://github.com/electron/osx-sign/blob/806db73bda1400e82b327619d0c2a793acf576a7/src/sign.ts#L91-L122) +for a reference implementation. | Option | Description | Usage Example | |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| | `entitlements` | String specifying the path to an `entitlements.plist` file. Will default to built-in entitlements files. Can also be an array of entitlement keys that osx-sign will write to an entitlements file for you. | `'path/to/entitlements'` | | `hardenedRuntime` | Boolean flag to enable the Hardened Runtime when signing the app. Enabled by default. | `false` | | `requirements` | Either a string beginning with `=` which specifies in plain text the [signing requirements](https://developer.apple.com/library/mac/documentation/Security/Conceptual/CodeSigningGuide/RequirementLang/RequirementLang.html) that you recommend to be used to evaluate the code signature, or a string specifying a path to a text or properly encoded `.rqset` file which contains those requirements. | `'=designated => identifier com.github.Electron'`
or
`'path/to/requirements.rqset'` | -| `signatureFlags` | List of [code signature flags](https://developer.apple.com/documentation/security/seccodesignatureflags?language=objc). Accepts an array of strings or a comma-separated string. | `['kSecCodeSignatureRestrict']` | +| `signatureFlags` | List of [code signature flags](https://keith.github.io/xcode-man-pages/codesign.1.html#OPTION_FLAGS). Accepts an array of strings or a comma-separated string. | `['runtime']` | | `timestamp` | String specifying the URL of the timestamp authority server. Defaults to the server provided by Apple. Please note that this default server may not support signatures not furnished by Apple. Disable the timestamp service with `none`. | `'https://different.timeserver'` | +| `additionalArguments` | Array of strings specifying additional arguments to pass to the `codesign` command used to sign a specific file. | `['--deep']` | **Note:** Only available via the JS API @@ -142,6 +148,35 @@ Default to latest Electron version. It is recommended to utilize this option for best support of specific Electron versions. This may trigger pre/post operations for signing: For example, automation of setting `com.apple.security.application-groups` in entitlements file and of updating `Info.plist` with `ElectronTeamID` is enabled for all versions starting from `1.1.1`; set `preAutoEntitlements` option to `false` to disable this feature. +#### Signing with `--deep` + +Some subresources that you may include in your Electron app may need to be signed with `--deep`, this is not typically safe to apply to the entire Electron app and therefore should be applied to _just_ your file. + +```js +const { signAsync } = require('@electron/osx-sign') +signAsync({ + app: 'path/to/my.app', + optionsForFile: (filePath) => { + // For our one specific file we can pass extra options to be merged + // with the default options + if (path.basename(filePath) === 'myStrangeFile.jar') { + return { + additionalArguments: ['--deep'], + }; + } + + // Just use the default options for everything else + return null; + } +}) + .then(function () { + // Application signed + }) + .catch(function (err) { + // Handle the error + }) +``` + #### From the Command Line ```sh diff --git a/src/sign.ts b/src/sign.ts index 06a3b84..5fc59f4 100644 --- a/src/sign.ts +++ b/src/sign.ts @@ -126,7 +126,8 @@ function defaultOptionsForFile (filePath: string, platform: ElectronMacPlatform) hardenedRuntime: true, requirements: undefined as string | undefined, signatureFlags: undefined as string | string[] | undefined, - timestamp: undefined as string | undefined + timestamp: undefined as string | undefined, + additionalArguments: [] as string[] | undefined }; } @@ -157,6 +158,7 @@ async function mergeOptionsForFile ( mergedPerFileOptions.signatureFlags = opts.signatureFlags; } if (opts.timestamp !== undefined) mergedPerFileOptions.timestamp = opts.timestamp; + if (opts.additionalArguments !== undefined) mergedPerFileOptions.additionalArguments = opts.additionalArguments; } return mergedPerFileOptions; } @@ -286,6 +288,10 @@ async function signApplication (opts: ValidatedSignOptions, identity: Identity) perFileArgs.push('--options', [...new Set(optionsArguments)].join(',')); } + if (perFileOptions.additionalArguments) { + perFileArgs.push(...perFileOptions.additionalArguments); + } + await execFileAsync( 'codesign', perFileArgs.concat('--entitlements', perFileOptions.entitlements, filePath) diff --git a/src/types.ts b/src/types.ts index ac856ff..2ac9450 100644 --- a/src/types.ts +++ b/src/types.ts @@ -41,6 +41,13 @@ export type PerFileSignOptions = { * timestamp server. */ timestamp?: string; + /** + * Additional raw arguments to pass to the "codesign" command. + * + * These can be things like "--deep" for instance when code signing specific resources that may + * require such arguments. + */ + additionalArguments?: string[]; } type OnlySignOptions = {