Search code examples
usbiokitentitlementsmacos-system-extensiondriverkit

How to set `com.apple.developer.driverkit.transport.usb` entitlement?

I am unsure about how to set the com.apple.developer.driverkit.transport.usb key in my dext entitlements file. The Info.plist file already contains the IOKitPersonalities dictionary, and reading about the com.apple.developer.driverkit.transport.usb dictionary it looks like it should contains entries with the same information as the entries of IOKitPersonalities.

The entitlements file for a project that is very similar to what is being shown in the WWDC video about driver kit sets this to:

<key>com.apple.developer.driverkit.transport.usb</key>
<true/>

When I set it to <true/>, the system extension starts. I do see some lines like this before I see log lines from the app:

...
2020-05-06 12:23:19.229709+0200 0x51ac2    Default     0x0                  0      0    kernel: DK: IOUserServer(sc.example.MyUserUSBInterfaceDriver-0x100002aad)::exit(CDHash check failed)

Should this entitlement just reflect what is in the IOKitPersonalities dictionary?

With the key completely removed I get:

...
2020-05-06 12:23:19.229709+0200 0x51ac2    Default     0x0                  0      0    kernel: DK: IOUserServer(sc.example.MyUserUSBInterfaceDriver-0x100002aad)::exit(CDHash check failed)
2020-05-06 12:23:19.253517+0200 0x51ac2    Default     0x0                  0      0    kernel: DK: IOUserServer(sc.example.MyUserUSBInterfaceDriver-0x100002aae)::exit(Entitlements check failed)

.. so I guess the key must be there.

I am viewing log lines related to the app with log stream --source | grep MyUserUSBInterfaceDriver

Solution

  • Updated answer
    As I have shipped some USB DriverKit based drivers, I've found that in practice it's slightly different than I originally stated in the answer, although my original answer matched Apple's documentation.

    Although Apple mentions both Product ID and Vendor ID in the documentation for the USB transport entitlement, in practice only the vendor ID is relevant for entitlements/code signing purposes. This means that if your driver needs to support any number of USB devices with vendor IDs 1234 and 2345 (Decimal! Usual notation for vendor IDs is hex, so don't forget to convert first!) you will need to include the following in your dext's entitlements:

    <key>com.apple.developer.driverkit.transport.usb</key>
<array>
    <dict>
        <key>idVendor</key>
        <integer>1234</integer>
    </dict>
    <dict>
        <key>idVendor</key>
        <integer>2345</integer>
    </dict>
</array>

    To be clear, that means the entitlement must be of the type array -> dictionaries, even if you only need to support one vendor ID.

    The idVendor values listed must also be embedded in your provisioning profile by Apple, which is why you must include them when you apply for DriverKit entitlements. Note that the form only supports a single vendor ID, so if you need to support more than one you must list them all in the free-form text field.

    Update 2:

    Since mid/late 2022 Apple has been making certain DriverKit entitlements available to all members of the dev programme without special application, for development signing only. This includes the USB transport entitlement. The “free” version of this is in a wildcard form and consists of the string “*” instead of a number. When using a provisioning profile with this version of the entitlement, your dext’s entitlement file will also need to use the asterisk.

    Platforms

    Although the documentation (which we have established above is also incorrect in other ways) only mentions macOS, this entitlement is also needed for developing and deploying USBDriverKit based drivers for iPadOS. Make sure to request it for all platforms relevant to your project when applying. The previous paragraph about the self-service wildcard development-only entitlement applies to iPadOS in all regards as well.