Demystify code signing for DriverKit
March 15, 2021
Drivers help your Mac’s operating system communicate with external hardware peripherals, and DriverKit helps you create those custom drivers. (For example, a keyboard driver can enable some of the unique functionality of a device, like controlling accent LEDs or performing complex macro functions.)
Because DriverKit drivers (or dexts) communicate with sensitive parts of the operating system, any driver you release needs a valid set of entitlements. We’ll take you through the process of managing entitlements and code signing as you build and test your driver, as well as how to create provisioning profiles for both development and release.
Creating a Driver Using the DriverKit SDK
Develop a driver without entitlements
Before you release a DriverKit driver, you must request entitlements that classify your software as a driver and define any supported hardware. Even if you haven’t requested or received your DriverKit entitlements yet, however, you can develop your driver by temporarily disabling the security checks that macOS performs during driver installation.
Requesting Entitlements for DriverKit Development
Debugging and testing system extensions
To do so, disable System Integrity Protection (SIP) and enable the System Extension Developer mode. (Check out “Debugging and Testing System Extensions” from Developer Documentation for more information.)
Note: Disable SIP only temporarily to perform necessary tasks, and reenable it as soon as possible. Failure to reenable SIP when you are done testing leaves your computer vulnerable to malicious code.
Once you’ve done so, you’ll want to make sure you’ve set the code signing identity of your DriverKit driver to run locally. Within your driver’s Xcode project, open the “Build Settings” tab and change the “Code Signing Identity” value to “Sign to Run Locally” for all of your targets. You should now be able to build, test, and debug your DriverKit driver on a development machine.
Use provisioning profiles for DriverKit development
When you’re ready to test your driver across multiple machines, you’ll need valid DriverKit entitlements so that you can create a provisioning profile.
Set up manual provisioning profiles While Xcode can handle some development identifier and provisioning profile work automatically, DriverKit dexts require manual provisioning work. To start, log in to the developer portal on developer.apple.com and navigate to the “Certificates, Identifiers, and Profiles” section.
Within the “Identifiers” section, you’ll need to create a new identifier to correlate with your dext. You may see a bunch of identifiers in here whose names are prefixed with “XC.” These are automatic identifiers created by Xcode for your projects.
When you create a new identifier, you’ll want to choose the “App ID” option. A DriverKit driver is considered a full-fledged app, so you’ll want to select that option, rather than “app clip.”
Next, give your identifier a good description, so you can recognize it in the future, and provide an explicit bundle ID for your dext. (You can scroll through all of the “capabilities” to get an idea of what options are available to you.)
You may notice an “Additional Entitlements” section. If you’ve been granted a specific vendor ID for use with USBDriverKit, make sure to add your “DriverKit USB Transport - VendorID” entitlement to the identifier.
Your System Extensions entitlement is what allows an app to install a driver; you don’t need to additionally check the “System Extensions” option for a DriverKit driver.
Make a profile Next, you’ll need to make a profile. Because you’re working on a driver in active development, you’ll want to select “macOS App Development” as the profile type.
Associate the profile with your app ID, select the certificates and development devices you want your profile to work with, then select your “System Extension and DriverKit template” in the “Additional Entitlements” section. This will show you all of the DriverKit entitlements that you’ve been granted, and apply those entitlements to the profile. You’ll also want to give your profile a descriptive name. It can often be helpful to include “development” in the title, so you can distinguish from any production profiles.
Once you’ve completed your profile, you can now use it to test your DriverKit driver. (Before you begin, don’t forget to re-enable SIP on your machine!)
Download your profile from developer.apple.com and, in Xcode, select it for your DriverKit target. You’ll also want to switch your code-signing identity from “Sign to Run Locally” to one of your certificates. After completing these steps, your developmental DriverKit driver will now undergo code signing checks by the system, including verifying your entitlements are working and up-to-date.
Distribute and notarize your driver
When you’re ready to release your DriverKit driver to the world, you’ll need an identifier for your dext. You can use the same one you created during the development process; if you opted out of development signing, however, you’ll need to create one now. If you need to make an identifier, you’ll follow a similar process as outlined in the previous section.
Note: Don’t forget that your application and driver must have unique identifiers — you can’t use the same identifier or profile when creating production versions.
Once you have your identifier, you’ll need to make distribution profiles for both the macOS app containing your driver and your DriverKit driver itself. DriverKit drivers can be distributed directly on the Mac App Store or through alternative means. When you create your provisioning profiles for distribution, select “Mac App Store” to distribute via the App Store, or “Developer ID” if you prefer self-distribution. After you’ve done so, select your identifier and target certificate — and don’t forget to add the “DriverKit Template Mac (Dist)” option to the profile for your driver.
Now that you’ve taken care of identification and profiling, you can build a release version of your application within Xcode.
- Navigate to “Product → Archive” in Xcode.
- Select “Distribute App.”
- Follow either the “App Store Connect” or “Developer ID” flows depending on your release scheme, providing your newly created distribution profiles when requested.
After you’ve built your release candidate, you can submit your app for notarization so that you have a properly signed DriverKit driver ready for distribution.
Notarizing macOS software before distribution
Resources
