Add Mac Support

[r4gus]

In theory it should be possible to use the same approach as on Linux but using HIDVirtualDevice.

Note to all: If you have experience with development for Mac and want to help out, feel free respond in this thread.

[r4gus]

A virtual human interface device (HID) is a software implementation of a hardware device. The system treats the device as any other external peripheral. HIDVirtualDevice models a virtual device and you communicate with it using HIDDeviceClient. Use a virtual device to transport data back and forth between other apps without the need for a connected device.

This is exactly what we need.

[r4gus]

To actually run the application, one must sign it. The key is probably com.apple.developer.hid.virtual.device

[r4gus]

https://developer.apple.com/documentation/xcode/using-the-latest-code-signature-format

[r4gus]

Looks like this is harder than thought.

The project structure:

• Hid
  • Package.swift
  • entitlements.plist
  • Sources
    • Hid
      • Hid.swift

Package.swift:

// swift-tools-version: 6.2
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "Hid",
    platforms: [.macOS(.v15)],
    targets: [
        // Targets are the basic building blocks of a package, defining a module or a test suite.
        // Targets can depend on other targets in this package and products from dependencies.
        .executableTarget(
            name: "Hid",
            dependencies: [],
            linkerSettings: [
                .linkedFramework("CoreHID"),
            ]
        ),

Sources/Hid/Hid.swfit

// The Swift Programming Language
// https://docs.swift.org/swift-book
import Foundation
import CoreHID

let keyboardDescriptor: Data = Data([0x05, 0x01, 0x09, 0x06, 0xA1, 0x01, 0x05, 0x07, 0x19, 0xE0, 0x29, 0xE7, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x08, 0x81, 0x02, 0x95, 0x01, 0x75, 0x08, 0x81, 0x01, 0x05, 0x08, 0x19, 0x01, 0x29, 0x05, 0x95, 0x05, 0x75, 0x01, 0x91, 0x02, 0x95, 0x01, 0x75, 0x03, 0x91, 0x01, 0x05, 0x07, 0x19, 0x00, 0x2A, 0xFF, 0x00, 0x95, 0x05, 0x75, 0x08, 0x15, 0x00, 0x26, 0xFF, 0x00, 0x81, 0x00, 0x05, 0xFF, 0x09, 0x03, 0x75, 0x08, 0x95, 0x01, 0x81, 0x02, 0xC0])
let properties = HIDVirtualDevice.Properties(descriptor: keyboardDescriptor, vendorID: 1)

final class Delegate : HIDVirtualDeviceDelegate {
    // A handler for system requests to send data to the device.
    func hidVirtualDevice(_ device: HIDVirtualDevice, receivedSetReportRequestOfType type: HIDReportType, id: HIDReportID?, data: Data) throws {
        print("Device received a set report request for report type:\(type) id:\(String(describing: id)) with data:[\(data.map { String(format: "%02x", $0) }.joined(separator: " "))]")
    }


    // A handler for system requests to query data from the device.
    func hidVirtualDevice(_ device: HIDVirtualDevice, receivedGetReportRequestOfType type: HIDReportType, id: HIDReportID?, maxSize: size_t) throws -> Data {
        print("Device received a get report request for report type:\(type) id:\(String(describing: id))")
        assert(maxSize >= 4)
        return (Data([1, 2, 3, 4]))
    }
}

@main
struct Hid {
    static func main() async throws {
        print("Hello, world!")

        guard let device = HIDVirtualDevice(properties: properties) else {
            print("fuck!")
            return
        }

        await device.activate(delegate: Delegate())

        while (true) {}

        try await device.dispatchInputReport(data: Data([5, 6, 7, 8]), timestamp: SuspendingClock.now)
    }
}

When running swift run Hid one gets:

Hello, world!
fuck!

The "fuck" is printed because the HidVirtualDevice can, for some reason, not be created.

This is probably due to a missing entitlement: com.apple.developer.hid.virtual.device (Codepilot says virtualDevice but that thing haluzinates the whole day...)

The entitlements.plist looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.security.get-task-allow</key>
  <true/>
  <key>com.apple.developer.hid.virtual.device</key>
  <true/>
</dict>
</plist>

The get-task_allow is added when using swift build/ swift run Hid so we'll also use it. The second key is added (in the hope) to allow the creation of virtual hid devices.

One can find a signing identity using: security find-identity -v -p codesigning

One can list the entitlements of the test app using: codesign -dv --entitlements :- .build/debug/Hid

Signing is done with: codesign --force --entitlements entitlements.plist --sign "Apple Development: <name> (<id>)" .build/debug/Hid
This will replace the existing signature.

After signing, the app is terminated immediately:

.build/debug/Hid
zsh: killed     .build/debug/Hid

fuck...

It is unclear what the issue is (primarily due to a lack of documentation).

[r4gus]

After asking on StackOverflow I got the answer I feared most:

It was killed with error code 137, query it and it means:

> kill -l 137
KILL

It was killed by AMFI(AppleMobileFileIntegrity) with this detailed message when you check the console:

355	AppleMobileFileIntegrity	amfid	default	error	19:09:50.457638+0800	Failure validating against provisioning profiles: Error Domain=AppleMobileFileIntegrityError Code=-413 "No matching profile found" UserInfo={NSURL=file:///Users/0x67/Downloads/Hid/.build/arm64-apple-macosx/debug/Hid, NSLocalizedDescription=No matching profile found}

So, that's a verify clear hint that we need to fill the form here: https://developer.apple.com/contact/request/system-extension/

On the application page, selected Virtual HID as the entitlement kind:

[r4gus]

This might be helpful for development: https://gist.github.com/macshome/15f995a4e849acd75caf14f2e50e7e98

But at the end, if it really works, I'll have to buy into the developer program to get the "privilege" to apply for the "Virtual HID" entitlement. Otherwise one would have to permanently disable SIP and AMFI and thats probably not what we want.

[r4gus]

Here is a project that creates virtual hid devices using driver kit: https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice