How to sign a DEXT

Question

DTS Engineer OP

Apple

Created 1w

Replies 1

Boosts 1

Participants 1

Kevin's Guide to DEXT Signing

The question of "How do I sign a DEXT" comes up a lot, so this post is my attempt to describe both what the issue are and the best current solutions are. So...

The Problems:

When DEXTs were originally introduced, the recommended development signing process required disabling SIP and local signing. There is a newer, much simpler process that's built on Xcode's integrated code-signing support; however, that newer process has not yet been integrated into the documentation library. In addition, while the older flow still works, many of the details it describes are no longer correct due to changes to Xcode and the developer portal.
DriverKit's use of individually customized entitlements is different than the other entitlements on our platform, and Xcode's support for it is somewhat incomplete and buggy. The situation has improved considerably over time, particularly from Xcode 15 and Xcode 16, but there are still issues that are not fully resolved.

To address #1, we introduced "development" entitlement variants of all DriverKit entitlements. These entitlement variants are ONLY available in development-signed builds, but they're available on all paid developer accounts without any special approval. They also allow a DEXT to match against any hardware, greatly simplifying working with development or prototype hardware which may not match the configuration of a final product.

Unfortunately, this also means that DEXT developers will always have at least two entitlement variants (the public development variant and the "private" approved entitlement), which is what then causes the problem I mentioned in #2.

The Automatic Solution:

If you're using Xcode 16 or above, then Xcode's Automatic code sign support will work all DEXT Families, with the exception of distribution signing the PCI and USB Families.

For completeness, here is how that Automatic flow should work:

Change the code signing configuration to "Automatic".
Add the capability using Xcode.

If you've been approved for one of these entitlements, the one oddity you'll see is that adding your approved capability will add both the approved AND the development variant, while deleting either will delete both. This is a visual side effect of #2 above; however, aside from the exception described below, it can be ignored.

Similarly, you can sign distribution builds by creating a build archive and then exporting the build using the standard Xcode flow.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Boost

Answer 1

DTS Engineer OP

Apple

3d

Signing a distribution USB or PCI DEXT

The issues described above mean that the standard Xcode GUI flow cannot be used to directly export a distribution release of a USB or PCI DEXT. Here is that flow I've found that will work:

Note: The instructions below reference macOS-specific documentation, but the flow I'm describing was actually tested using an iOS project.

Start by building the final version of your DEXT.
On the portal, generate and download a provisioning profile for whatever environment you're going to try to build. Generate a profile for both the DEXT and the app it will be embedded in.
Rename the DEXT profile you downloaded in #2 to "embedded.provisionprofile”.
Show the packaged contents of your DEXT and replace the existing "embedded.provisionprofile" (development profile) profile with the file from #3 (the release profile).
Use this command to resign the DEXT with the final entitlement configuration you'll be shipping. See the "Sign each code item" section of "Creating distribution-signed code for macOS" for more detailed guidance on constructing this command.

codesign -s <signing cert name> -f --timestamp -o runtime --entitlements <release entitlement.plist path> <dext path>

Configure the project for your release project to use manual codesigning and the profile you app profile you downloaded in #2.
Add the DEXT you resigned in #5 into your shipping project.
Configure the "Copy Files" build phase to copy the DEXT as a System Extension.
Archive the build.
Use the Organizer to distribute the build to the same environment as the profile you generated in #2.

Note: The flow above relies on the fact that Xcode is using the DEXT's signing configuration "as is" instead of attempting to resign it. That means you'll need to go through the entire flow above for every build type you need to export (App Store, Mac App Store, Developer ID, Ad Hoc, etc.).

Debugging Export Failures

It is VERY likely that step #10 will fail, saying the entitlements don't match. This occurs because the entitlements.plist file you used in #5 did not EXACTLY match the configuration of the profiles Xcode needs/expects. This happens because you either:

Didn't include "all" the necessary entitlements.
The entitlement configuration isn't exactly right.

You can debug these issues using two tools:

The "Show Logs" button in the Xcode organizer will show you the detailed logs from Xcode. In my test, the issues were in "IDEDistribution.verbose.log", near the end of the log. Searching for "match" will get you to the entry, and replacing "\n" with a newline character will make the output readable. Add whatever entitlements are missing from this logging to correct #1 (I was missing several).
You can use the instructions found here to view the signing configuration of your archived build. This will let you sort out issues like format types (I had several issues here as well).

Note that in both cases the solution will involve changing the entitlement.plist configuration used in #5 above, NOT the provisioning profile. Quoting myself:

"One thing to be aware of here is that Xcode has a "bias" in the way it presents codesign errors where it assumes the Entitlement.plist is "correct" and the profile is "wrong". However, in practice that's basically "never" the case with DriverKit entitlements and tends to lead to a lot of "flailing" trying to somehow "fix" the provisioning profile..."

In practice, that means changes to the provisioning profile should only be necessary if the entitlement was granted with an incorrect configuration, in which case you'd need to submit a new entitlement request to get that issue corrected.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

0