Patch Signing

Patch signing makes your app check that every patch it downloads carries a signature matching a public key built into your release, and refuse any patch that doesn’t. Someone who can tamper with your users’ network traffic can’t produce that signature, so they can’t push code to your app.

Starting with Shorebird CLI 1.6.132, every new release is signed by default, with a key Shorebird manages for your organization. There are three modes:

Mode	How you choose it	Who holds the private key
Managed (default)	shorebird release with no key flags	Shorebird, in Google Cloud KMS
Self-managed	--public-key-path or --public-key-cmd on release, a private key on patch	You
Unsigned	--no-patch-signing on release	No one: patches aren’t signed at all

The mode is fixed when you release each platform, because the public key is built into the release. To change it, make a new release. There are no changes to your code in any mode.

Releases made with an older CLI, without a key, are unsigned. Patches to them stay unsigned and keep installing. To protect an app made that way, update the CLI and make a new release; you don’t need to change your Flutter version.

Managed signing

Managed signing is the default. To turn it on for an app, update the Shorebird CLI and make a new release:

shorebird upgrade
shorebird release android

The release summary shows which key the release uses:

🔏 Patch Signing: Shorebird-managed key

Patch as usual with shorebird patch. Shorebird signs each patch for you.

How it works

• Shorebird creates a signing key for your organization in Google Cloud KMS the first time shorebird release needs one. The private key never leaves KMS: Cloud KMS doesn’t let anyone export it, including Shorebird.
• shorebird release fetches the organization’s public key from Shorebird and builds it into the release, the same way --public-key-path does.
• shorebird patch builds the patch with the same public key, so it matches the release. When the patch is uploaded, Shorebird’s servers sign it with the matching private key. A patch to a managed release is never published unsigned: if it can’t be signed, the upload fails.
• Each release keeps the key it was built with, and every patch to it is signed with that key.
• Your app verifies signatures exactly as it does for self-managed keys. See Test and verify signed patch.

Patching a managed release takes no key flags. If you pass --public-key-path, --public-key-cmd, --private-key-path, or --sign-cmd, shorebird patch stops before uploading and names the flags to remove. A CLI older than 1.6.132 can’t patch a managed release; it tells you to run shorebird upgrade.

If shorebird release can’t get the signing key from Shorebird, the release fails rather than going out unsigned. Run it again. If you can’t wait, you can turn signing off for that release, but it stays unsigned for good: every patch to it is unsigned, and only a new release turns signing back on.

What managed signing protects against

Managed signing protects against anyone between your users and Shorebird. It doesn’t protect against someone who controls Shorebird itself. If you need that, use self-managed signing.

An attacker who…	Managed	Self-managed	Unsigned
Controls your users’ network, including with a fraudulent TLS certificate	Protected	Protected	Not protected
Can change patch files in storage or on the CDN, but not Shorebird’s API	Protected	Protected	Protected
Compromises Shorebird’s servers or signing service	Not protected	Protected	Not protected
Compromises Google Cloud	Not protected	Protected, unless your key is in Google Cloud	Not protected
Has your Shorebird credentials (an account, API key, or CI token) and publishes a patch	Not protected	Protected, unless they have your private key	Not protected

Unsigned apps are protected in the second row because your app already rejects a patch whose contents don’t match the hash Shorebird’s API returned for it. Signing adds protection when the attacker can also change what the API returns, as in the first row.

In short, managed signing moves your app’s trust from the network and every certificate authority your app trusts to Shorebird and Google. Self-managed signing removes Shorebird and Google from it too.

Switch to your own key

To move an app from managed signing to your own key, make a new release with --public-key-path or --public-key-cmd, as in Self-managed signing. Releases you made with managed signing keep receiving signed patches. Managed keys can’t be exported, so you can’t take your existing managed key with you.

Turn signing off

You can release without signing, though it leaves your app open to the attacks above:

shorebird release android --no-patch-signing

Patches to that release are unsigned, as before 1.6.132. You can’t combine --no-patch-signing with --public-key-path or --public-key-cmd.

Self-managed signing

With self-managed signing, you sign patches with your own key, so no one, including Shorebird, can change the content of your patches without your private key.

Signing works in two parts. First, shorebird release takes a --public-key-path or --public-key-cmd argument to embed your public key in your released application. The Shorebird updater only loads patches signed with the corresponding private key.

Second, when you build your patch with shorebird patch, you pass --private-key-path or --sign-cmd to sign your patch with your private key. This is required for a release created with your public key.

You will need an RSA key pair. Shorebird supports RSA keys in PEM format, both PKCS#1 and PKCS#8.

Generate keys

If you do not already have an RSA key pair you’d like to use, you can generate a pair with openssl:

# Generate a key pair
openssl genrsa -out private.pem 2048

# Extract the public key
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Note

On Windows, you can use the openssl that comes with your git installation at C:\Program Files\Git\usr\bin\openssl.exe.

The above operation will generate a public/private key pair in private.pem and a public key in public.pem. The file containing the private key should be stored securely and kept secret. While the private key is not itself sufficient to make an update to your application (someone would also need access to your Shorebird credentials), it should not be checked into public source control.

Key storage

If you don’t want to store keys yourself, use managed signing. If you are using self-managed keys, using a cloud key management service instead of just storing keys on disk is highly recommended. If for any reason you were to lose your private key, there is no way to create a patch for an application containing the corresponding public key. Even Shorebird is not able to create a patch for your application without your private key. In such a case, you would need to make and distribute a new release of your application to send patches to it.

Shorebird does support command-based signing for integration with cloud key management services (HashiCorp Vault, GCP Cloud KMS, AWS KMS, Azure Key Vault), hardware security modules (HSMs), and secrets managers (1Password, etc.). Please ensure you are using at least v1.6.81 or greater to use this feature.

See Cloud KMS Examples below for integration examples with popular services.

Create a signed release

Note

These examples use Android, but patch signing works on all platforms.

To create a release that requires signed patches, run the following command:

# Build Release with local path to key file
shorebird release android --public-key-path /path/to/public.pem

# Build Release with command for cloud-managed public key
# Ensure that the command outputs a PEM-encoded public key to stdout
shorebird release android \
  --public-key-cmd="your-command-that-outputs-pem-public-key"

This will include the public key in the release artifact produced by shorebird release and cause the released app to require signed patches.

Create a signed patch

To create a signed patch, run the following command:

# Build Patch with local path to key files
shorebird patch android --track=stable --public-key-path /path/to/public.pem \
 --private-key-path /path/to/private.pem

# Build Patch with cloud-managed signing
# Ensure that the command outputs a PEM-encoded public key to stdout
# sign-cmd should read data from stdin and output a base64 signature to
# stdout
  shorebird patch android --track=stable \
   --public-key-cmd="your-command-that-outputs-pem-public-key" \
   --sign-cmd="your-command-that-signs-stdin-and-outputs-base64"

This tells Shorebird to sign the patch with the key pair you provided.

Patch a release signed with your own key

If shorebird patch stops before building with exit code 64 and this message, the release embeds your public key but the patch command didn’t pass a key pair:

Release 1.0.0+1 was signed with your own key, so its patches must be too. Pass the same public key as the release, with --public-key-path and --private-key-path, or --public-key-cmd and --sign-cmd.

Run the patch again with the same public key the release used and its private key, as in Create a signed patch.

Shorebird 1.6.135 and newer make this check for releases built with Shorebird 1.6.132 or newer. For older releases, or with an older CLI, nothing stops the patch, and devices on the release refuse it because it has no valid signature (see Fallback behavior).

Test and verify signed patch

This works the same for managed and self-managed signing. You can verify that the patch is properly signed using shorebird preview. On the first launch, you should see something like the following in your app logs:

05-22 23:47:51.645  6963  6994 I flutter : updater::updater: [shorebird] Patch 1 successfully downloaded. It will be launched when the app next restarts.
05-22 23:47:51.645  6963  6994 I flutter : updater::updater: [shorebird] Update thread finished with status: Update installed

If you close and relaunch your app, you should see this message telling you that the patch’s signature was verified:

05-23 11:32:33.944  7029  7029 I flutter : updater::cache::signing: [shorebird] Verifying patch signature...
05-23 11:32:33.944  7029  7029 I flutter : updater::cache::signing: [shorebird] Patch signature is valid

If the patch is missing a signature, or fails signature verification for any reason, Shorebird will not load it, and will instead use any previously installed and verifiable patch (if there is one) or the unpatched release version of your app.

With self-managed signing, you can also test the missing signature behavior (managed releases refuse these patches before they’re published). Create a patch without a private key and notice that shorebird preview rejects it. Similarly, you can create a patch with a different private key to do the same.

Fallback behavior

Releases that contain a public key will reject all unsigned patches. If a patch is missing a signature or its signature is invalid, Shorebird will reject this patch at boot time. It will instead boot from the last known good patch (if still on disk) or the release build of the app. This will not cause your app to crash.

Trade-offs

Signature verification, managed or self-managed, adds a small overhead at app launch. During testing this has been observed to be under 50ms with a medium-sized app on a 5-year-old Android phone. This overhead increases with application size. For very large apps, if this overhead shows up on your benchmarks, you can set patch_verification: install_only in shorebird.yaml to verify signatures only when patches are installed rather than on every launch.

Caution

On Shorebird’s builds of Flutter 3.41.9, 3.44.0 to 3.44.9, and 3.47.0 to 3.47.7, patch_verification: install_only skips the signature check entirely, so devices install patches without verifying them. Shorebird 1.6.132 and newer refuse to release with that combination:

`patch_verification: install_only` in shorebird.yaml does not check patch signatures with Flutter 3.47.7 (...).

Shorebird 1.6.134 and newer also warn when you patch a release built on one of these versions while shorebird.yaml still sets install_only. Either remove patch_verification from shorebird.yaml (or set it to strict, the default, which verifies at every launch and is unaffected), or release with a Flutter version outside these ranges, such as 3.41.8 or 3.47.8 and later. A release already built this way keeps installing patches without checking their signatures; changing shorebird.yaml only protects new releases.

Cloud KMS examples

The following examples show how to integrate Shorebird patch signing with popular key management services using --public-key-cmd and --sign-cmd.

Note

Integrating with Cloud KMS requires that the executing environment (your local terminal or CI/CD runner) has sufficient IAM credentials to read keys and sign payloads.

• GCP Cloud KMS: Requires the roles/cloudkms.viewer (to read the public key) and roles/cloudkms.signerVerifier (to sign the patch) roles.
• AWS KMS: Requires the kms:GetPublicKey and kms:Sign IAM policy actions.
• Azure Key Vault: Requires Key Vault key permissions for get and sign.

HashiCorp Vault

# Store your key in Vault Transit
vault write transit/keys/shorebird-signing type=rsa-2048

# Release
shorebird release android \
  --public-key-cmd="vault read -field=public_key transit/keys/shorebird-signing"

# Patch
shorebird patch android --track=stable \
  --public-key-cmd="vault read -field=public_key transit/keys/shorebird-signing" \
  --sign-cmd="vault write -field=signature transit/sign/shorebird-signing \
    hash_algorithm=sha2-256 signature_algorithm=pkcs1v15 input=-"

GCP Cloud KMS

# Create a key ring and key
gcloud kms keyrings create shorebird --location=global
gcloud kms keys create signing-key --keyring=shorebird --location=global \
  --purpose=asymmetric-signing --default-algorithm=rsa-sign-pkcs1-2048-sha256

# Release
shorebird release android \
  --public-key-cmd="gcloud kms keys versions get-public-key 1 \
    --key=signing-key --keyring=shorebird --location=global"

# Patch (using a helper script for signing)
shorebird patch android --track=stable \
  --public-key-cmd="gcloud kms keys versions get-public-key 1 \
    --key=signing-key --keyring=shorebird --location=global" \
  --sign-cmd="gcloud kms asymmetric-sign --version=1 \
    --key=signing-key --keyring=shorebird --location=global \
    --digest-algorithm=sha256 --input-file=- --signature-file=- | base64"

AWS KMS

# Create an RSA signing key
aws kms create-key --key-spec RSA_2048 --key-usage SIGN_VERIFY

# Create a helper script for public key (aws-kms-pubkey.sh).
# Needed to get the format correct from DER to PEM
#!/bin/bash
aws kms get-public-key --key-id alias/shorebird-signing --output text \
  --query PublicKey | base64 -d | openssl rsa -pubin -inform DER -outform PEM

# Create a helper script for signing (aws-kms-sign.sh)
#!/bin/bash
HASH=$(cat - | openssl dgst -sha256 -binary | base64)
aws kms sign --key-id alias/shorebird-signing \
  --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
  --message-type DIGEST --message "$HASH" \
  --output text --query Signature

# Release
shorebird release android --public-key-cmd="./aws-kms-pubkey.sh"

# Patch
shorebird patch android --track=stable \
  --public-key-cmd="./aws-kms-pubkey.sh" \
  --sign-cmd="./aws-kms-sign.sh"

Azure Key Vault

# Create a key in Azure Key Vault
az keyvault key create --vault-name myVault --name shorebird-signing \
  --kty RSA --size 2048

# Helper script for public key (azure-kv-pubkey.sh)
#!/bin/bash
az keyvault key download --vault-name myVault --name shorebird-signing \
  --encoding PEM --file /dev/stdout

# Helper script for signing (azure-kv-sign.sh)
#!/bin/bash
HASH=$(cat - | openssl dgst -sha256 -binary | base64 -w0)
az keyvault key sign --vault-name myVault --name shorebird-signing \
  --algorithm RS256 --digest "$HASH" --query value -o tsv

# Release
shorebird release android --public-key-cmd="./azure-kv-pubkey.sh"

# Patch
shorebird patch android --track=stable \
  --public-key-cmd="./azure-kv-pubkey.sh" \
  --sign-cmd="./azure-kv-sign.sh"

1Password CLI

# Store your keys in 1Password
op item create --category="Secure Note" --title="Shorebird Signing" \
  "public_key[text]=$(cat public.pem)" \
  "private_key[text]=$(cat private.pem)"

# Helper script for signing (1password-sign.sh)
#!/bin/bash
PRIVATE_KEY=$(op item get "Shorebird Signing" --fields private_key)
cat - | openssl dgst -sha256 -sign <(echo "$PRIVATE_KEY") | base64

# Release
shorebird release android \
  --public-key-cmd="op item get 'Shorebird Signing' --fields public_key"

# Patch
shorebird patch android --track=stable \
  --public-key-cmd="op item get 'Shorebird Signing' --fields public_key" \
  --sign-cmd="./1password-sign.sh"