Skip to content

signing.md

Latest commit

 

History

History
282 lines (207 loc) · 11.3 KB

signing.md

File metadata and controls

282 lines (207 loc) · 11.3 KB
Raw

Signing assets

OpenJoystickDriver contains a DriverKit system extension and uses restricted HID entitlements. Apple issues the certificates and provisioning profiles through Certificates, Identifiers & Profiles.

Who needs signing assets

End user

Install a signed, notarized OpenJoystickDriver release from the project publisher. Do not create certificates or provisioning profiles, and never accept a publisher's private signing key or .p12 file.

Parser or controller-record contributor

You do not need signing assets. swift test and ./scripts/ojd diagnose record cover the source and raw-USB paths documented in CONTRIBUTING.md.

Full-app developer

You must belong to the Apple Developer Program team that owns both exact App IDs:

  • host application: com.openjoystickdriver;
  • generated DriverKit extension: com.openjoystickdriver.VirtualHIDDevice.

App IDs are globally registered. Membership in a different Apple developer team does not let you generate profiles for these identifiers. A fork would need its own configurable identifiers and matching entitlement approval. The current build contract intentionally uses the publisher identifiers.

Release publisher

Release signing also requires the publisher's Developer ID Application identity, Developer ID provisioning, and notarization credentials. Do not distribute these secrets to contributors or end users.

Development setup

1. Obtain entitlement access

Before creating profiles, the team's Account Holder must request or enable the capabilities. Apple documents DriverKit entitlement requests at Requesting Entitlements for DriverKit Development and managed capability requests at Capability Requests.

The host App ID must authorize:

Entitlement Portal capability or purpose
com.apple.developer.system-extension.install System Extension
com.apple.developer.driverkit.userclient-access containing only com.openjoystickdriver.VirtualHIDDevice Communicates with Drivers / exact DriverKit client allowlist
com.apple.developer.hid.virtual.device Compatibility virtual HID device; request it as a managed capability if it is not available for the team

The DriverKit App ID and its selected entitlement group must authorize exactly:

com.apple.developer.driverkit
com.apple.developer.driverkit.family.hid.device
com.apple.developer.driverkit.transport.hid
com.apple.developer.driverkit.family.hid.eventservice

Do not enable com.apple.developer.driverkit.allow-any-userclient-access. OpenJoystickDriver uses the host's exact user-client allowlist by design.

Apple ties approved DriverKit entitlements to the development team. If the DriverKit App ID or entitlement group is unavailable in the portal, the Account Holder must complete the request at Apple's system-extension entitlement page or contact Apple Developer Support. A repository change cannot grant the entitlement.

2. Create an Apple Development identity

On the Mac that will build the app:

  1. Open Xcode > Settings > Accounts.
  2. Select the correct Apple Developer Program team.
  3. Open Manage Certificates and create an Apple Development certificate.
  4. In Keychain Access, confirm it appears under My Certificates with a private key nested beneath it.

Create the identity on the build Mac. A downloaded .cer does not contain the private key required by codesign. Apple lists the certificate types in its certificate overview.

Verify locally:

security find-identity -v -p codesigning

The output must include at least one valid Apple Development identity.

3. Create the two development profiles

An Account Holder or Admin creates these in Certificates, Identifiers & Profiles > Profiles. A team member with access can then download them:

Local filename Portal profile type App ID Certificate/device
OpenJoystickDriver.provisionprofile Mac App Development com.openjoystickdriver Select the Apple Development identity above and the target Mac
OpenJoystickDriver_VirtualHIDDevice.provisionprofile DriverKit Development com.openjoystickdriver.VirtualHIDDevice Select the same Apple Development identity, target Mac, and approved DriverKit entitlement group

Apple's current profile workflow is documented in Create a development provisioning profile and Create a DriverKit development provisioning profile.

Download the profiles, rename them to the exact local filenames above, and put them in:

~/Documents/Profiles/

The portal's profile display name may differ from the local filename. The repository reads the embedded display name for DEXT_BUILD_PROFILE.

4. Install, configure, and verify

./scripts/ojd signing install-profiles
./scripts/ojd signing configure
./scripts/ojd signing audit \
  "$HOME/Library/MobileDevice/Provisioning Profiles"/*.provisionprofile
./scripts/ojd signing doctor

signing configure generates .env.dev. It matches the certificate embedded in each profile to a Keychain identity, then reads the Team ID and profile name from the profiles.

Then build and install:

./scripts/ojd build install dev

macOS must approve the system extension and the app's requested privacy access before live relay and controller checks can pass.

Where each development variable comes from

Variable Source
CODESIGN_IDENTITY SHA-1 of the Apple Development identity whose certificate is embedded in the DriverKit development profile
DEVELOPMENT_TEAM TeamIdentifier in the host development profile
GUI_PROVISIONING_PROFILE Installed path of OpenJoystickDriver.provisionprofile
DEXT_BUILD_PROFILE Name embedded in OpenJoystickDriver_VirtualHIDDevice.provisionprofile
OJD_USE_LOCAL_SWIFTERKIT Developer choice; leave 0 unless intentionally testing the sibling checkout

The first four values are generated by ./scripts/ojd signing configure.

Replace invalid profile entitlements

Profiles created for older OpenJoystickDriver builds may still name com.openjoystickdriver.daemon or grant allow-any DriverKit access. Do not edit the downloaded profile. Apple signs it, so any local edit invalidates it.

signing configure, signing doctor, and DriverKit builds reject profiles unless the host entitlement is exactly ["com.openjoystickdriver.VirtualHIDDevice"]. Replace the Apple capability grant and regenerate the profiles before building.

Host App ID

  1. Open Certificates, Identifiers & Profiles.

  2. Select the App ID com.openjoystickdriver.

  3. Open Capability Requests.

  4. Submit a replacement DriverKit UserClient Access request containing one bundle ID entry:

    com.openjoystickdriver.VirtualHIDDevice

    Do not include com.openjoystickdriver.daemon. Do not paste several bundle IDs into one field separated by newlines. The entitlement must be an array with one string element.

  5. If the portal refuses a replacement because an older request is still active, contact Apple Developer Support. Ask them to remove the existing DriverKit UserClient Access grant and replace it with the single bundle ID above. Include the existing capability request ID.

  6. After approval, open the App ID's Capabilities tab and confirm DriverKit UserClient Access is enabled.

Regenerate both host profiles after the App ID changes:

  • Mac App Development to OpenJoystickDriver.provisionprofile;
  • Developer ID to OpenJoystickDriver_DevID.provisionprofile.

Select the installed certificate of the corresponding type when generating each profile.

DriverKit App ID

  1. Select com.openjoystickdriver.VirtualHIDDevice under Identifiers.
  2. Disable DriverKit Allow Any UserClient Access and its development variant if either is enabled.
  3. Keep the base DriverKit and required HID family capabilities enabled.
  4. If allow-any belongs to an Apple-assigned DriverKit entitlement group rather than a visible toggle, request a replacement group without com.apple.developer.driverkit.allow-any-userclient-access.
  5. Create a new DriverKit Development profile. Select the entitlement group that contains the required HID entitlements and does not contain allow-any.
  6. Download it as OpenJoystickDriver_VirtualHIDDevice.provisionprofile.

The host and dext belong to the same team. The dext does not need allow-any access. The host profile names the one dext it can open.

Replace the files under ~/Documents/Profiles/, then run:

./scripts/ojd signing install-profiles
./scripts/ojd signing configure
./scripts/ojd signing doctor

The doctor must report this host value:

com.apple.developer.driverkit.userclient-access =
  ["com.openjoystickdriver.VirtualHIDDevice"]

The DriverKit profile must not contain com.apple.developer.driverkit.allow-any-userclient-access.

Publisher release assets

The Account Holder creates a Developer ID Application certificate from Apple's Developer ID certificate page. It must be installed with its private key. A Developer ID Installer certificate is not used because OpenJoystickDriver distributes an application/DMG, not a signed installer package.

Create or regenerate the Developer ID provisioning profile for com.openjoystickdriver, selecting that Developer ID Application certificate and the host capabilities listed above. Download it as:

~/Documents/Profiles/OpenJoystickDriver_DevID.provisionprofile

When that optional profile is present, signing install-profiles installs it and signing configure writes .env.release. Without it, development setup still succeeds and release configuration is skipped explicitly.

Notarization should use a Keychain profile rather than a plaintext password:

xcrun notarytool store-credentials "openjoystickdriver-notary" \
  --apple-id "PUBLISHER_ACCOUNT" \
  --team-id "TEAM_ID"

Set NOTARIZE_KEYCHAIN_PROFILE to openjoystickdriver-notary. Apple documents this flow in Customizing the notarization workflow.

A dev-signed dext does not prove that the Developer ID build can be distributed or notarized. Apple requires a distribution profile for the release target.

Safe diagnostics

These commands omit private values from their normal output:

./scripts/ojd env audit
./scripts/ojd signing audit \
  "$HOME/Library/MobileDevice/Provisioning Profiles"/*.provisionprofile
./scripts/ojd signing doctor

Never commit .env.dev, .env.release, certificates, provisioning profiles, notarization passwords, or .p12 files.