Skip to content

DEVELOPER.md

Latest commit

 

History

History
217 lines (150 loc) · 7.92 KB

DEVELOPER.md

File metadata and controls

217 lines (150 loc) · 7.92 KB
Raw

Info for developers

How to use FakeTokenDriver

create empty file fakeTokenDriver in cwd - so in project root when developing, to enable "Fake token driver"

Trying out CLI mode

Useful command how to run project from CLI.

./mvnw exec:java -Dexec.mainClass="digital.slovensko.autogram.Main" -Dexec.args="--cli ..."

More info about inner workings of builds for MacOS

To run signed mac build add follwing to .vscode/settings.json (or you can do unsigned build by setting mac.sign=0 in build.properties)

  "autogram.APPLE_DEVELOPER_IDENTITY": "Developer ID Application: Sluzby Slovensko.Digital, s.r.o. (44U4JSRX4Z)",
  "autogram.APPLE_KEYCHAIN_PATH": "..../autogram/secret/app-signing.keychain-db"

(Developer ID is visible in signature, so it's ok that its public)

run this before building in any terminal - set app-signing keychain as default and unlock it

Setup

export APPLE_KEYCHAIN_PATH=".../autogram/secret/app-signing.keychain-db"
export APPLE_KEYCHAIN_PASSWORD=""
security unlock-keychain -p $APPLE_KEYCHAIN_PASSWORD $APPLE_KEYCHAIN_PATH
security list-keychains -d user -s $APPLE_KEYCHAIN_PATH login.keychain
security default-keychain -s $APPLE_KEYCHAIN_PATH
export APPLE_DEVELOPER_IDENTITY="Developer ID Application: Sluzby Slovensko.Digital, s.r.o. (44U4JSRX4Z)"

run this after you finish - so app-signing keychain wont be used for your private data

Cleanup

security list-keychains -d user -s login.keychain
security default-keychain -s login.keychain

Timeline

  • jpackage creates "app-image"
  • jpackage signs binary/executable in app-image
  • unpacked "app-image" is edited by Autogram-post-image.sh by adding new executable (from src/main/scripts/resources/mac-launcher/MacOS/Autogram), and some other changes
  • Autogram-post-image.sh signs using codesign both of these executables since they are both changed
  • jpackage finishes creating .app file that gets packaged into installer .pkg
  • xcrun notarytool notarizes pkg with Apple
  • xcrun stapler staple adds (staples) notarization ticket to pkg file so it can be installed without internet
  • 🎉 you have signed and notarized package

Notes:

  • there are two types of pkg 1
    • "component package" - use pkgbuild
    • "product archive" - use productbuild, also known as "distribution packages" or "installer packages" can contain multiple "component packages"

Following is just overview of useful commands and

Creating certificates and keychain

  • create keychain using security create-keychain -p "$APPLE_KEYCHAIN_PASSWORD" $APPLE_KEYCHAIN_PATH
  • create two CSR in that keychain (or not, but you will have to copy-paste it from login keychain) (one for ...Application and one for ...Installer cert)
  • create certificates "Developer ID Application" and "Developer ID Installer" on Apple website
  • add certificates to keychain - when you generate CSR you create private key, when you add generated .cer
  • copy "Developer ID Certification Authority" cert from login keychain if it's missing - or you will get errors about missing chain

Creating .app

Using jpackage

  • Autogram.entitlements - entitlements default is sanbox.plist and we are removing audio recording permission
  • Autogram-post-image.sh - this script gets run during jpackage execution, between when "app-image" is prepared, but before packaging to pkg
  • Autogram-background.png, Autogram-background-darkAqua.png - images for installer background, aligned to bottom left, margins have to be in image

MacOS packaging and signing

Unpacking pkg

pkgutil --expand-full Autogram-1.0.0.pkg Autogram-1.0.0

Signing code

codesign -s "$APPLE_DEVELOPER_IDENTITY" --keychain $APPLE_KEYCHAIN_PATH --options=runtime  --deep --timestamp Autogram-1.0.0.pkg
  • -s <identity> - which identity to use for signing
  • --options=runtime - signs with hardened runtime 1
  • --deep - sign insides of package
  • --timestamp - use secure timestamp 1
  • Autogram-1.0.0.pkg - what to sign

Signing installer

productsign...

Verifying before notarization

Check if pkg is code signed

codesign -vvv --deep --strict Autogram-1.0.0.pkg

Check pkg is product signed

pkgutil --check-signature Autogram-1.0.0.pkg

Check product will run with current policy

spctl -vvv --assess --type exec Autogram-1.0.0.pkg

Check if installer will run with current policy

spctl --assess --ignore-cache --verbose --type install Autogram-1.0.0.pkg

Notarization

Store credentials for notarization

xcrun notarytool store-credentials --keychain $APPLE_KEYCHAIN_PATH

Unlock keychain

security unlock-keychain -p $APPLE_KEYCHAIN_PASSWORD $APPLE_KEYCHAIN_PATH

Set keychain as default

security list-keychains -d user -s $APPLE_KEYCHAIN_PATH
security default-keychain -s $APPLE_KEYCHAIN_PATH

Clean up default keychain

security list-keychains -d user -s login.keychain
security default-keychain -s login.keychain

Submit for notarization

xcrun notarytool submit --keychain-profile "autogram" --keychain $APPLE_KEYCHAIN_PATH --progress --wait Autogram-1.0.0.pkg

Check what went wrong

# get summary/status
xcrun notarytool info  $submission_id --keychain-profile "autogram" --keychain $APPLE_KEYCHAIN_PATH
# get detailed log and individual issues
xcrun notarytool log  $submission_id --keychain-profile "autogram" --keychain $APPLE_KEYCHAIN_PATH

Staple package (so it can be installed offline)

xcrun stapler staple Autogram-1.0.0.pkg

Debugging pkg

extracting

pkgutil --expand-full Autogram.pkg autogram-pkg-extracted

Loading external dylib libraries

By default MacOS Gatekeeper allows loading dylib only from secure paths

Beginning with macOS 10.10.4, Gatekeeper verifies that no libraries are loaded from outside an app bundle.

we can use com.apple.security.cs.disable-library-validation entitlement to disable this check (there may be better workaround with )

https://developer.apple.com/library/archive/technotes/tn2206/_index.html#//apple_ref/doc/uid/DTS40007919-CH1-TNTAG207 https://stackoverflow.com/questions/57667467/dylib-library-not-loaded-due-to-restricted-binary-after-apple-code-signing https://wiki.freepascal.org/Hardened_runtime_for_macOS

More Resources