diff --git a/src/content/docs/distribute/Signing/android.mdx b/src/content/docs/distribute/Signing/android.mdx new file mode 100644 index 0000000000..35ac6cdd31 --- /dev/null +++ b/src/content/docs/distribute/Signing/android.mdx @@ -0,0 +1,154 @@ +--- +title: Android Code Signing +sidebar: + label: Android + order: 5 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { Code } from '@astrojs/starlight/components'; + +To publish on the Play Store, you need to sign your app with a digital certificate. + +Android App Bundles and APKs must be signed before being uploaded for distribution. + +Google also provides an additional signing mechanism for Android App Bundles distributed in the Play Store. +See the [official Play App Signing documentation] for more information. + +## Creating a keystore and upload key + +Android signing requires a Java Keystore file that can be generated using the official `keytool` CLI: + + + + +``` +keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload +``` + + + + + +``` +keytool -genkey -v -keystore $env:USERPROFILE\upload-keystore.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias upload +``` + + + + +This command stores the `upload-keystore.jks` file in your home directory. +If you want to store it elsewhere, change the argument you pass to the `-keystore` parameter. + +:::tip + +- The `keytool` command might not be in your PATH. + You may find it installed in the JDK that is installed with Android Studio: + + + + + + **Android Studio directory path depends on your Linux distribution** + + + + + + + + + + + + +::: + +:::caution[Security Warning] + +Keep the `keystore` file private; don't check it into public source control! + +::: + +See the [official documentation](https://developer.android.com/studio/publish/app-signing#generate-key) for more information. + +## Configure the signing key + +Create a file named `[project]/src-tauri/gen/android/keystore.properties` that contains a reference to your keystore: + +``` +password= +keyAlias=upload +storeFile=/upload-keystore.jks or C:\\Users\\\\upload-keystore.jks> +``` + +:::caution[Security Warning] +Keep the `keystore.properties` file private; don't check it into public source control. +::: + +You will usually generate this file in your CI/CD platform. The following snippet contains an example job step for GitHub Actions: + +```yml +- name: setup Android signing + run: | + cd src-tauri/gen/android + echo "keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}" > keystore.properties + echo "password=${{ secrets.ANDROID_KEY_PASSWORD }}" >> keystore.properties + base64 -d <<< "${{ secrets.ANDROID_KEY_BASE64 }}" > $RUNNER_TEMP/keystore.jks + echo "storeFile=$RUNNER_TEMP/keystore.jks" >> keystore.properties +``` + +In this example the keystore was exported to base64 with `base64 -i /path/to/keystore.jks` and set as the `ANDROID_KEY_BASE64` secret. + +### Configure Gradle to use the signing key + +Configure gradle to use your upload key when building your app in release mode by editing the `[project]/src-tauri/gen/android/app/build.gradle.kts` file. + +1. Add the needed import at the beginning of the file: + + ```kotlin + import java.io.FileInputStream + ``` + +2. Add the `release` signing config before the `buildTypes` block: + + ```kotlin {3-12} + signingConfigs { + create("release") { + val keystorePropertiesFile = rootProject.file("keystore.properties") + val keystoreProperties = Properties() + if (keystorePropertiesFile.exists()) { + keystoreProperties.load(FileInputStream(keystorePropertiesFile)) + } + + keyAlias = keystoreProperties["keyAlias"] as String + keyPassword = keystoreProperties["password"] as String + storeFile = file(keystoreProperties["storeFile"] as String) + storePassword = keystoreProperties["password"] as String + } + } + + buildTypes { + ... + } + ``` + +3. Use the new `release` signing config in the `release` config in `buildTypes` block: + + ```kotlin {3} + buildTypes { + getByName("release") { + signingConfig = signingConfigs.getByName("release") + } + } + ``` + +Release builds of your app will now be signed automatically. + +[official Play App Signing documentation]: https://support.google.com/googleplay/android-developer/answer/9842756?hl=en&visit_id=638549803861403647-3347771264&rd=1 diff --git a/src/content/docs/distribute/Signing/ios.mdx b/src/content/docs/distribute/Signing/ios.mdx new file mode 100644 index 0000000000..25b07267b7 --- /dev/null +++ b/src/content/docs/distribute/Signing/ios.mdx @@ -0,0 +1,98 @@ +--- +title: iOS Code Signing +sidebar: + label: iOS + order: 4 +--- + +Code signing on iOS is required to distribute your application through the official [Apple App Store] or possibly alternative marketplaces in the European Union and in general to install and execute on end user devices. + +## Prerequisites + +Code signing on iOS requires enrolling to the [Apple Developer] program, which at the time of writing costs 99$ per year. +You also need an Apple device where you perform the code signing. This is required by the signing process and due to Apple's Terms and Conditions. + +To distribute iOS applications you must have your bundle identifier registered in the App Store Connect, +an appropriate iOS code signing certificate and a mobile provisioning profile that links them together and enables the iOS capabilities used by your app. +These requirements can be either automatically managed by Xcode or provided manually. + +## Automatic Signing + +Letting Xcode manage the signing and provisioning for your app is the most convenient way to export your iOS app to be distributed. +It automatically registers your bundle identifier, manages iOS capabilities changes, and configures an appropriate certificate based on your export method. + +Automatic signing is enabled by default, and uses the account configured in Xcode to authenticate when used on your local machine.\ +To register your account, open the Xcode application and open the Settings page in the `Xcode > Settings` menu, switch to the Accounts tab and click the `+` icon. + +To use the automatic signing in CI/CD platforms you must create an App Store Connect API key +and define the `APPLE_API_ISSUER`, `APPLE_API_KEY` and `APPLE_API_KEY_PATH` environment variables.\ +Open the [App Store Connect's Users and Access page], select the Keys tab, click on the Add button and select a name and the Developer access. +The `APPLE_API_ISSUER` (Issuer ID) is presented above the keys table, and the `APPLE_API_KEY` is the value on the Key ID column on that table. +You also need to download the private key, which can only be done once and is only visible after a page reload (the button is shown on the table row for the newly created key). +The private key file path must be set via the `APPLE_API_KEY_PATH` environment variable. + +## Manual Signing + +To manually sign your iOS app you can provide the certificate and mobile provisioning profile via environment variables: + +- **IOS_CERTIFICATE**: base64 representation of the certificate exported from the Keychain. +- **IOS_CERTIFICATE_PASSWORD**: password of the certificate set when exporting it from the Keychain. +- **IOS_MOBILE_PROVISION**: base64 representation of the provisioning profile. + +The following sections explain how to get these values. + +### Signing Certificate + +After enrolling, navigate to the [Certificates] page to create a new Apple Distribution certificate. +Download the new certificate and install it to the macOS Keychain. + +To export the certificate key, open the "Keychain Access" app, expand the certificate's entry, +right-click on the key item and select "Export \" item. +Select the path of the exported .p12 file and remember its password. + +Run the following `base64` command to convert the certificate to base64 and copy it to the clipboard: + +``` +base64 -i | pbcopy +``` + +The value in the clipboard is now the base64 representation of the signing certificate. +Save it and use it as the `IOS_CERTIFICATE` environment variable value. + +The certificate password must be set to the `IOS_CERTIFICATE_PASSWORD` variable. + +:::tip[Choose Certificate Type] +You must use an appropriate certificate type for each export method: + +- **debugging**: Apple Development or iOS App Development +- **app-store-connect**: Apple Distribution or iOS Distribution (App Store Connect and Ad Hoc) +- **ad-hoc**: Apple Distribution or iOS Distribution (App Store Connect and Ad Hoc) + +::: + +### Provisioning Profile + +Additionally, you must provide the provisioning profile for your application. +In the [Identifiers](https://developer.apple.com/account/resources/identifiers/list) page, +create a new App ID and make sure its "Bundle ID" value matches the identifier set in the [`identifier`] configuration. + +Navigate to the [Profiles](https://developer.apple.com/account/resources/profiles/list) page to create a new provisioning profile. +For App Store distribution, it must be an "App Store Connect" profile. +Select the appropriate App ID and link the certificate you previously created. + +After creating the provisioning profile, download it and run the following `base64` command to convert the profile and copy it to the clipboard: + +``` +base64 -i | pbcopy +``` + +The value in the clipboard is now the base64 representation of the provisioning profile. +Save it and use it as the `IOS_MOBILE_PROVISION` environment variable value. + +Now you can build your iOS application and distribute on the App Store! + +[Certificates]: https://developer.apple.com/account/resources/certificates/list +[Apple Developer]: https://developer.apple.com +[Apple App Store]: https://www.apple.com/app-store/ +[App Store Connect's Users and Access page]: https://appstoreconnect.apple.com/access/users +[`identifier`]: /reference/config/#identifier diff --git a/src/content/docs/distribute/Signing/linux.mdx b/src/content/docs/distribute/Signing/linux.mdx new file mode 100644 index 0000000000..44c92e2f31 --- /dev/null +++ b/src/content/docs/distribute/Signing/linux.mdx @@ -0,0 +1,56 @@ +--- +title: Linux Code Signing +sidebar: + label: Linux + order: 3 +--- + +This guide provides information on code signing for Linux packages. +While artifact signing is not required for your application to be deployed on Linux, +it can be used to increase trust into your deployed application. +Signing the binaries allows your end user to verify that these are genuine and have not been modified by another untrusted entity. + +## Signing for AppImages + +The AppImage can be signed using either gpg or gpg2. + +### Prerequisites + +A key for signing must be prepared. A new one can be generated using: + +```shell +gpg2 --full-gen-key +``` + +Please refer to the gpg or gpg2 documentation for additional information. +You should take additional care to back up your private and public keys in a secure location. + +### Signing + +You can embed a signature in the AppImage by setting the following environment variables: + +- **SIGN**: set to `1` to sign the AppImage. +- **SIGN_KEY**: optional variable to use a specific GPG Key ID for signing. +- **APPIMAGETOOL_SIGN_PASSPHRASE**: the signing key password. If unset, gpg shows a dialog so you can input it. You must set this when building in CI/CD platforms. +- **APPIMAGETOOL_FORCE_SIGN**: by default the AppImage is generated even if signing fails. To exit on errors, you can set this variable to `1`. + +You can display the signature embedded in the AppImage by running the following command: + +```shell +./src-tauri/target/release/bundle/appimage/$APPNAME_$VERSION_amd64.AppImage --appimage-signature +``` + +Note that you need to change the $APPNAME and $VERSION values with the correct ones based on your configuration. + +:::caution The signature is not verified + +AppImage does not validate the signature, so you can't rely on it to check whether the file has been tampered with or not. +To validate the signature, you must provide an external tool for your users. +This requires you to publish your public key on an authenticated channel (e.g. your website served via TLS), +so the end user can download and verify. + +See [the official AppImage documentation] for additional information. + +::: + +[the official appimage documentation]: https://docs.appimage.org/packaging-guide/optional/signatures.html diff --git a/src/content/docs/distribute/Signing/macos.mdx b/src/content/docs/distribute/Signing/macos.mdx new file mode 100644 index 0000000000..35486a60ba --- /dev/null +++ b/src/content/docs/distribute/Signing/macos.mdx @@ -0,0 +1,109 @@ +--- +title: macOS Code Signing +sidebar: + label: macOS + order: 1 +--- + +Code signing is required on macOS to allow your application to be listed in the [Apple App Store] and to prevent a warning that your application is broken and can not be started, when downloaded from the browser. + +## Prerequisites + +Code signing on macOS requires enrolling to the [Apple Developer] program, which at the time of writing costs 99$ per year. +You also need an Apple device where you perform the code signing. This is required by the signing process and due to Apple's Terms and Conditions. + +## Signing + +To setup code signing for macOS you must create an Apple code signing certificate and +install it to your Mac computer keychain or export it to be used in CI/CD platforms. + +### Creating a signing certificate + +To create a new signing certificate, you must generate a Certificate Signing Request (CSR) file from your Mac computer. +See [creating a certificate signing request] to learn how to create the CSR for code signing. + +On your Apple Developer account, navigate to the [Certificates, IDs & Profiles page] +and click on the `Create a certificate` button to open the interface to create a new certificate. +Choose the appropriate certificate type (`Apple Distribution` to submit apps to the App Store, and `Developer ID Application` to ship apps outside the App Store). +Upload your CSR, and the certificate will be created. + +:::note + +Only the Apple Developer `Account Holder` can create _Developer ID Application_ certificates. But it can be associated with a different Apple ID by creating a CSR with a different user email address. + +::: + +### Downloading the certificate + +On the [Certificates, IDs & Profiles page], click on the certificate you want to use and click on the `Download` button. +It saves a `.cer` file that installs the certificate on the keychain once opened. + +### Configuring Tauri + +You can configure Tauri to use your certificate when building macOS apps on your local machine or when using CI/CD platforms. + +#### Signing locally + +With the certificate installed in your Mac computer keychain, you can configure Tauri to use it for code signing. + +The name of the certificate's keychain entry represents the `signing identity`, which can also be found by executing: + +```` +security find-identity -v -p codesigning +``` + +This identity can be provided in the [`tauri.conf.json > bundle > macOS > signingIdentity`] configuration option or +via the `APPLE_SIGNING_IDENTITY` environment variable. + +:::note + +A signing certificate is only valid if associated with your Apple ID. +An invalid certificate won't be listed on the _Keychain Access > My Certificates_ tab +or the _security find-identity -v -p codesigning_ output. +If the certificate does not download to the correct location, make sure the "login" option is selected in _Keychain Access_ +under "Default Keychains" when downloading the .cer file. + +::: + +#### Signing in CI/CD platforms + +To use the certificate in CI/CD platforms, you must export the certificate to a base64 string +and configure the `APPLE_CERTIFICATE` and `APPLE_CERTIFICATE_PASSWORD` environment variables: + +1. Open the `Keychain Access` app, click the _My Certificates_ tab in the _login_ keychain and find your certificate's entry. +2. Expand the entry, double-click on the key item, and select `Export "$KEYNAME"`. +3. Select the path to save the certificate's `.p12` file and define a password for the exported certificate. +4. Convert the `.p12` file to base64 running the following script on the terminal: + ``` + openssl base64 -in /path/to/certificate.p12 -out certificate-base64.txt + ``` +5. Set the contents of the `certificate-base64.txt` file to the `APPLE_CERTIFICATE` environment variable. +6. Set the certificate password to the `APPLE_CERTIFICATE_PASSWORD` environment variable. + +## Notarization + +To notarize your application, you must provide credentials for Tauri to authenticate with Apple: + +- APPLE_API_ISSUER, APPLE_API_KEY and APPLE_API_KEY_PATH: authenticate using an App Store Connect API key + + Open the [App Store Connect's Users and Access page], select the Keys tab, click on the Add button and select a name and the Developer access. + The APPLE_API_ISSUER (Issuer ID) is presented above the keys table, and the APPLE_API_KEY is the value on the Key ID column on that table. + You also need to download the private key, which can only be done once and is only visible after a page reload (the button is shown on the table row for the newly created key). + The private key file path must be set via the APPLE_API_KEY_PATH environment variable. + +- APPLE_ID, APPLE_PASSWORD and APPLE_TEAM_ID: authenticate using your Apple ID + + Alternatively, to authenticate with your Apple ID, set the APPLE_ID to your Apple account email and the APPLE_PASSWORD to an app-specific password for the Apple account. + +:::note +Notarization is required when using a _Developer ID Application_ certificate. +::: + +[Certificates]: https://developer.apple.com/account/resources/certificates/list +[Apple Developer]: https://developer.apple.com +[Apple App Store]: https://www.apple.com/app-store/ +[App Store Connect's Users and Access page]: https://appstoreconnect.apple.com/access/users +[`tauri.conf.json > bundle > macOS > signingIdentity`]: /reference/config/#signingidentity +[creating a certificate signing request]: https://developer.apple.com/help/account/create-certificates/create-a-certificate-signing-request +[Certificates, IDs & Profiles page]: https://developer.apple.com/account/resources/certificates/list +```` diff --git a/src/content/docs/distribute/Signing/windows.mdx b/src/content/docs/distribute/Signing/windows.mdx new file mode 100644 index 0000000000..e95d328acd --- /dev/null +++ b/src/content/docs/distribute/Signing/windows.mdx @@ -0,0 +1,287 @@ +--- +title: Windows Code Signing +sidebar: + label: Windows + order: 2 +--- + +import { Steps } from '@astrojs/starlight/components'; + +Code signing is required on Windows to allow your application to be listed in the [Microsoft Store] and to prevent a [SmartScreen] warning that your application is not trusted and can not be started, when downloaded from the browser. + +It is not required to execute your application on Windows, as long as your end user is okay with ignoring the [SmartScreen] warning or your user does not download via the browser. +This guide covers signing via OV (Organization Validated) certificates and Azure Key Vault. +If you use any other signing mechanism not documented here, such as EV (Extended Validation) certificates, +check out your certificate issuer documentation and refer to the [custom sign command](#custom-sign-command) section. + +## OV Certificates + +:::danger + +This guide only applies to OV code signing certificates acquired before June 1st 2023! For code signing with EV certificates and OV certificates received after that date please consult the documentation of your certificate issuer instead. + +::: + +:::note + +If you sign the app with an EV Certificate, it'll receive an immediate reputation with Microsoft SmartScreen and won't show any warnings to users. + +If you opt for an OV Certificate, which is generally cheaper and available to individuals, Microsoft SmartScreen will still show a warning to users when they download the app. It might take some time until your certificate builds enough reputation. You may opt for [submitting your app] to Microsoft for manual review. Although not guaranteed, if the app does not contain any malicious code, Microsoft may grant additional reputation and potentially remove the warning for that specific uploaded file. + +See the [comparison](https://www.digicert.com/difference-between-dv-ov-and-ev-ssl-certificates) to learn more about OV vs EV certificates. + +::: + +### Prerequisites + +- Windows - you can likely use other platforms, but this tutorial uses Powershell native features. +- A working Tauri application +- Code signing certificate - you can acquire one of these on services listed in [Microsoft's docs]. There are likely additional authorities for non-EV certificates than included in that list, please compare them yourself and choose one at your own risk. + - Please make sure to get a **code signing** certificate, SSL certificates do not work! + +### Getting Started + +There are a few things we have to do to get Windows prepared for code signing. This includes converting our certificate to a specific format, installing this certificate, and decoding the required information from the certificate. + + + +1. #### Convert your `.cer` to `.pfx` + + - You will need the following: + + - certificate file (mine is `cert.cer`) + - private key file (mine is `private-key.key`) + + - Open up a command prompt and change to your current directory using `cd Documents/Certs` + + - Convert your `.cer` to a `.pfx` using `openssl pkcs12 -export -in cert.cer -inkey private-key.key -out certificate.pfx` + + - You should be prompted to enter an export password **DON'T FORGET IT!** + +2. #### Import your `.pfx` file into the keystore. + + - We now need to import our `.pfx` file. + + - Assign your export password to a variable using `$WINDOWS_PFX_PASSWORD = 'MYPASSWORD'` + + - Now Import the certificate using `Import-PfxCertificate -FilePath certificate.pfx -CertStoreLocation Cert:\CurrentUser\My -Password (ConvertTo-SecureString -String $WINDOWS_PFX_PASSWORD -Force -AsPlainText)` + +3. #### Prepare Variables + + - Start ➡️ `certmgr.msc` to open Personal Certificate Management, then open Personal/Certificates. + + - Find the certificate we just imported and double-click on it, then click on the Details tab. + + - The Signature hash algorithm will be our `digestAlgorithm`. (Hint: this is likely `sha256`) + + - Scroll down to Thumbprint. There should be a value like `A1B1A2B2A3B3A4B4A5B5A6B6A7B7A8B8A9B9A0B0`. This is our `certificateThumbprint`. + + - We also need a timestamp URL; this is a time server used to verify the time of the certificate signing. I'm using `http://timestamp.comodoca.com`, but whoever you got your certificate from likely has one as well. + + + +### Prepare `tauri.conf.json` file + +1. Now that we have our `certificateThumbprint`, `digestAlgorithm`, & `timestampUrl` we will open up the `tauri.conf.json`. + +2. In the `tauri.conf.json` you will look for the `tauri` -> `bundle` -> `windows` section. There are three variables for the information we have captured. Fill it out like below. + +```json tauri.conf.json +"windows": { + "certificateThumbprint": "A1B1A2B2A3B3A4B4A5B5A6B6A7B7A8B8A9B9A0B0", + "digestAlgorithm": "sha256", + "timestampUrl": "http://timestamp.comodoca.com" +} +``` + +3. Save and run `tauri build` + +4. In the console output, you should see the following output. + +``` +info: signing app +info: running signtool "C:\\Program Files (x86)\\Windows Kits\\10\\bin\\10.0.19041.0\\x64\\signtool.exe" +info: "Done Adding Additional Store\r\nSuccessfully signed: APPLICATION FILE PATH HERE +``` + +Which shows you have successfully signed the `.exe`. + +And that's it! You have successfully set up your Tauri application for Windows signing. + +### Sign your application with GitHub Actions. + +We can also create a workflow to sign the application with GitHub actions. + +#### GitHub Secrets + +We need to add a few GitHub secrets for the proper configuration of the GitHub Action. These can be named however you would like. + +- You can view the [encrypted secrets] guide on how to add GitHub secrets. + +The secrets we used are as follows + +| GitHub Secrets | Value for Variable | +| :--------------------------: | :-------------------------------------------------------------------------------------------------------------------------------: | +| WINDOWS_CERTIFICATE | Base64 encoded version of your .pfx certificate, can be done using this command `certutil -encode certificate.pfx base64cert.txt` | +| WINDOWS_CERTIFICATE_PASSWORD | Certificate export password used on creation of certificate .pfx | + +#### Workflow Modifications + +1. We need to add a step in the workflow to import the certificate into the Windows environment. This workflow accomplishes the following + + 1. Assign GitHub secrets to environment variables + 2. Create a new `certificate` directory + 3. Import `WINDOWS_CERTIFICATE` into tempCert.txt + 4. Use `certutil` to decode the tempCert.txt from base64 into a `.pfx` file. + 5. Remove tempCert.txt + 6. Import the `.pfx` file into the Cert store of Windows & convert the `WINDOWS_CERTIFICATE_PASSWORD` to a secure string to be used in the import command. + +2. We will be using the [`tauri-action` publish template]. + +```yml +name: 'publish' +on: + push: + branches: + - release + +jobs: + publish-tauri: + strategy: + fail-fast: false + matrix: + platform: [macos-latest, ubuntu-latest, windows-latest] + + runs-on: ${{ matrix.platform }} + steps: + - uses: actions/checkout@v2 + - name: setup node + uses: actions/setup-node@v1 + with: + node-version: 12 + - name: install Rust stable + uses: actions-rs/toolchain@v1 + with: + toolchain: stable + - name: install webkit2gtk (ubuntu only) + if: matrix.platform == 'ubuntu-latest' + run: | + sudo apt-get update + sudo apt-get install -y webkit2gtk-4.0 + - name: install app dependencies and build it + run: yarn && yarn build + - uses: tauri-apps/tauri-action@v0 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tagName: app-v__VERSION__ # the action automatically replaces \_\_VERSION\_\_ with the app version + releaseName: 'App v__VERSION__' + releaseBody: 'See the assets to download this version and install.' + releaseDraft: true + prerelease: false +``` + +3. Right above `-name: install app dependencies and build it` you will want to add the following step + +```yml +- name: import windows certificate + if: matrix.platform == 'windows-latest' + env: + WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }} + WINDOWS_CERTIFICATE_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }} + run: | + New-Item -ItemType directory -Path certificate + Set-Content -Path certificate/tempCert.txt -Value $env:WINDOWS_CERTIFICATE + certutil -decode certificate/tempCert.txt certificate/certificate.pfx + Remove-Item -path certificate -include tempCert.txt + Import-PfxCertificate -FilePath certificate/certificate.pfx -CertStoreLocation Cert:\CurrentUser\My -Password (ConvertTo-SecureString -String $env:WINDOWS_CERTIFICATE_PASSWORD -Force -AsPlainText) +``` + +4. Save and push to your repo. + +5. Your workflow can now import your windows certificate and import it into the GitHub runner, allowing for automated code signing! + +## Azure Key Vault + +You can sign the Windows executables by providing an Azure Key Vault certificate and credentials. + +:::note +This guide uses [relic] due to its support to secret-based authentication, though you can configure alternative tools if you prefer. +To download relic, check its [releases page][relic releases page] or run `go install github.com/sassoftware/relic/v8@latest`. +::: + +1. Key Vault + +In the [Azure Portal] navigate to the [Key vaults service] to create a new key vault by clicking the "Create" button. +Remember the "Key vault name" as you will need that information to configure the certificate URL. + +2. Certificate + +After creating a key vault, select it and go to the "Objects > Certificates" page to create a new certificate and click the "Generate/Import" button. +Remember the "Certificate name" as you will need that information to configure the certificate URL. + +3. Tauri Configuration + +[relic] uses a configuration file to determine which signing key it should use. For Azure Key Vault you also need the certificate URL. +Create a `relic.conf` file in the `src-tauri` folder and configure relic to use your certificate: + +```yml title=src-tauri/relic.conf +tokens: + azure: + type: azure + +keys: + azure: + token: azure + id: https://\.vault.azure.net/certificates/\ +``` + +Note that you must replace \ and \ with the appropriate names from the previous steps. + +To configure Tauri to use your Azure Key Vault configuration for signing change the [bundle > windows > signCommand] config value: + +```json title=tauri.conf.json +{ + "bundle": { + "windows": { + "signCommand": "relic sign --file %1 --key azure --config relic.conf" + } + } +} +``` + +4. Credentials + +[relic] must authenticate with Azure in order to load the certificate. +In the Azure portal landing page, go to the "Microsoft Entra ID" service and head to the "Manage > App registrations" page. +Click "New registration" to create a new app. After creating the app, you are redirected to the application details page where you can see the "Application (client) ID" and "Directory (tenant) ID" values. +Set these IDs to the `AZURE_VAULT_ID` and `AZURE_TENANT_ID` environment variables respectively. + +In the "Manage > Certificates & secrets" page click the "New client secret" button and set the text in the "Value" column as the `AZURE_CLIENT_SECRET` environment variable. + +After setting up all the credentials, head back to your key vault's page and navigate to the "Access control (IAM)" page. +You must assign the "Key Vault Certificate User" and "Key Vault Crypto User" roles to your newly created application. + +After setting up all these variables, running `tauri build` will produce signed Windows installers! + +## Custom Sign Command + +In the [Azure Key Vault](#azure-key-vault) documentation above we used a powerful Tauri Windows signing configuration to force the Tauri CLI to use +a special shell command to sign Windows installer executables. The [bundle > windows > signCommand] configuration option can be used to use any codesign tool +that can sign Windows executables. + +:::tip +When cross compiling Windows installers from Linux and macOS machines, you **must** use a custom sign command as the default implementation only works on Windows machines. +::: + +[Azure Portal]: https://portal.azure.com +[Key vaults service]: https://portal.azure.com/#browse/Microsoft.KeyVault%2Fvaults +[microsoft's docs]: https://learn.microsoft.com/en-us/windows-hardware/drivers/dashboard/code-signing-cert-manage +[submitting your app]: https://www.microsoft.com/en-us/wdsi/filesubmission/ +[encrypted secrets]: https://docs.github.com/en/actions/reference/encrypted-secrets +[`tauri-action` publish template]: https://github.com/tauri-apps/tauri-action +[relic]: https://github.com/sassoftware/relic +[relic releases page]: https://github.com/sassoftware/relic/releases/ +[bundle > windows > signCommand]: /reference/config/#signcommand +[SmartScreen]: https://en.wikipedia.org/wiki/Microsoft_SmartScreen +[Microsoft Store]: https://apps.microsoft.com/ diff --git a/src/content/docs/distribute/apk-sign.mdx b/src/content/docs/distribute/apk-sign.mdx deleted file mode 100644 index da151c49b2..0000000000 --- a/src/content/docs/distribute/apk-sign.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Android APK/AAB Signing -sidebar: - order: 1 ---- - -import { Steps } from '@astrojs/starlight/components'; - -To publish on the Play Store, you need to sign your app with a digital certificate. - -Android uses two signing keys: upload and app signing. - -Developers upload an `.aab` or `.apk` file signed with an upload key to the Play Store. -The end-users download the `.apk` file signed with an app signing key. -To create your app signing key, use Play App Signing as described in the [official Play Store documentation](https://support.google.com/googleplay/android-developer/answer/9842756?hl=en&visit_id=638549803861403647-3347771264&rd=1). - -To sign your app, use the following instructions. - - -1. Create an `upload` Keystore - - If you have an existing keystore, skip to the next step. If not, create one using one of the following methods: - - 1. Following the [Android Studio key generation steps](https://developer.android.com/studio/publish/app-signing#sign-apk) - 2. Running the following at the command line: - On Mac/Linux, use the following command: - - ``` - keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload - ``` - - On Windows, use the following command: - - ``` - keytool -genkey -v -keystore $env:USERPROFILE\upload-keystore.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias upload - ``` - - This command stores the `upload-keystore.jks` file in your home directory. If you want to store it elsewhere, change the argument you pass to the `-keystore` parameter. However, keep the `keystore` file private; don't check it into public source control! - - :::note - - - The `keytool` command might not be in your path—it's part of Java, which is installed as part of Android Studio. You may find it installed in the JDK that is installed with Android Studio, for example: - - - Linux: `/opt/android-studio/jbr/bin/keytool` - - macOS: `/Applications/Android Studio.app/Contents/jbr/Contents/Home/bin/keytool` - - Windows: `C:\\Program Files\\Android\\Android Studio\\jbr\\bin\\keytool.exe` - - Then use that fully qualified path. If your path includes space-separated names, such as Program Files, use platform-appropriate notation for the names. For example, on Mac/Linux use `Program\ Files`, and on Windows use `"Program Files"`. - - - The `-storetype JKS` tag is only required for Java 9 or newer. As of the Java 9 release, the keystore type defaults to PKS12. - ::: - -3. Reference the Keystore from the App - - Create a file named `[project]/src-tauri/gen/android/keystore.properties` that contains a reference to your keystore: - - ``` - storePassword= - keyPassword= - keyAlias=upload - storeFile=/upload-keystore.jks or C:\\Users\\\\upload-keystore.jks> - ``` - - :::caution - Keep the `keystore.properties` file private; don't check it into public source control. - ::: - -4. Configure Signing in Gradle - - Configure gradle to use your upload key when building your app in release mode by editing the `[project]/src-tauri/gen/android/app/build.gradle.kts` file. - - 1. Add the needed imports at the beginning of the file: - - ```kotlin - import java.util.Properties - import java.io.FileInputStream - ``` - - 2. Add the `release` signing config before the `buildTypes` block: - - ```kotlin {3-12} - signingConfigs { - create("release") { - val keystorePropertiesFile = rootProject.file("keystore.properties") - val keystoreProperties = Properties() - if (keystorePropertiesFile.exists()) { - keystoreProperties.load(FileInputStream(keystorePropertiesFile)) - } - - keyAlias = keystoreProperties["keyAlias"] as String - keyPassword = keystoreProperties["keyPassword"] as String - storeFile = file(keystoreProperties["storeFile"] as String) - storePassword = keystoreProperties["storePassword"] as String - } - } - - buildTypes { - ... - } - ``` - - 3. Use the new `release` signing config in the `release` config in `buildTypes` block: - - ```kotlin {3} - buildTypes { - getByName("release") { - signingConfig = signingConfigs.getByName("release") - } - } - ``` - - - -Release builds of your app will now be signed automatically. diff --git a/src/content/docs/distribute/index.mdx b/src/content/docs/distribute/index.mdx index b6b6a6aa13..2002da413f 100644 --- a/src/content/docs/distribute/index.mdx +++ b/src/content/docs/distribute/index.mdx @@ -10,26 +10,58 @@ sidebar: import { CardGrid, LinkCard } from '@astrojs/starlight/components'; +## Signing + +Code signing enhances the security of your application by applying a digital signature to your +application's executables and bundles, validating your identity of the provider of your application. + +Signing is required on most platforms. See the documentation for each platform for more information. + + + + + + + + + +## Distributing + - .p8': './private_keys', '\~/private_keys', '\~/.private_keys', and '\~/.appstoreconnect/private_keys'. +- `APPLE_API_KEY_PATH` - path to the API key `.p8` file. If not specified, the bundler searches the following directories in sequence for a private key file with the name of 'AuthKey\_\.p8': './private_keys', '\~/private_keys', '\~/.private_keys', and '\~/.appstoreconnect/private_keys'. **For iOS this variable is required**. - `APPLE_SIGNING_IDENTITY` — The identity used to code sign. Overwrites `tauri.conf.json > bundle > macOS > signingIdentity`. - `APPLE_PROVIDER_SHORT_NAME` — If your Apple ID is connected to multiple teams, you have to specify the provider short name of the team you want to use to notarize your app. Overwrites `tauri.conf.json > bundle > macOS > providerShortName`. -- `APPLE_DEVELOPMENT_TEAM` — TODO +- `APPLE_DEVELOPMENT_TEAM` — The team ID used to code sign on iOS. Overwrites `tauri.conf.json > bundle > iOS > developmentTeam`. Can be found in https://developer.apple.com/account#MembershipDetailsCard. - `TAURI_WEBVIEW_AUTOMATION` — Enables webview automation (Linux Only). - `TAURI_ANDROID_PROJECT_PATH` — Path of the tauri android project, usually will be `/src-tauri/gen/android`. - `TAURI_IOS_PROJECT_PATH` — Path of the tauri iOS project, usually will be `/src-tauri/gen/ios`.