Karabiner-DriverKit-VirtualHIDDevice

Virtual devices (keyboard and mouse) implementation for macOS using DriverKit.

Supported systems

• macOS 14 Sonoma
  • Both Intel-based Macs and Apple Silicon Macs
• macOS 13 Ventura
  • Both Intel-based Macs and Apple Silicon Macs

Status

• Implemented:
  • Extension manager
  • Virtual HID keyboard
  • Virtual HID pointing
  • Virtual HID device client

Documents

• How to be close to DriverKit
• Extracts from xnu

Screenshots

• macOS Settings (macOS detects the virtual keyboard)
  
  
  
  

---

Usage

1. Open dist/Karabiner-DriverKit-VirtualHIDDevice-x.x.x.pkg.

2. Install files via installer.

3. Execute the following command in Terminal.

   /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

4. Run a client program to test the driver extension.

   git clone --depth 1 https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice.git
   cd Karabiner-DriverKit-VirtualHIDDevice/examples/virtual-hid-device-service-client
   brew install xcodegen
   make
   make run

Uninstallation

1. Run uninstaller in Terminal.

   bash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/deactivate_driver.sh'
   sudo bash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/remove_files.sh'

Installed files

• /Applications/.Karabiner-VirtualHIDDevice-Manager.app
• /Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice
• /Library/LaunchDaemons/org.pqrs.Karabiner-DriverKit-VirtualHIDDeviceClient.plist
• /Library/Application Support/org.pqrs/tmp
• /var/log/karabiner

---

For developers

How to build

System requirements to build Karabiner-Elements:

• macOS 14+
• Xcode 15+
• Command Line Tools for Xcode
• XcodeGen

Steps

1. Obtain DriverKit entitlements to create a provisioning profile that supports com.apple.developer.driverkit. Specifically, follow the instructions on Requesting Entitlements for DriverKit Development

   Note: This process may take some time to be completed on Apple's side.

2. Create App IDs on the Apple Developer site.

Bundle ID	Capabilities	App Services	Additional Capabilities
org.pqrs.Karabiner-DriverKit-VirtualHIDDevice	---	---	com.apple.developer.driverkit com.apple.developer.driverkit.family.hid.device com.apple.developer.driverkit.family.hid.eventservice com.apple.developer.driverkit.transport.hid com.apple.developer.hid.virtual.device
org.pqrs.Karabiner-DriverKit-VirtualHIDDeviceClient	---	---	---
org.pqrs.Karabiner-VirtualHIDDevice-Manager	System Extension	---	---

3. Create a profile corresponding to the App IDs on the Apple Developer site.

4. Replace the *.provisionprofile files in the repository with your own provision profile files.

   • src/Client/Developer_ID_VirtualHIDDeviceClient.provisionprofile
   • src/DriverKit/Developer_ID_KarabinerDriverKitVirtualHIDDevice.provisionprofile
   • src/Manager/Developer_ID_Karabiner_VirtualHIDDevice_Manager.provisionprofile

5. Replace CODE_SIGN_IDENTITY at src/scripts/codesign.sh with yours.

   Find your codesign identity by executing the following command in Terminal.

   security find-identity -p codesigning -v

   The result is as follows.

   1) 8D660191481C98F5C56630847A6C39D95C166F22 "Developer ID Application: Fumihiko Takayama (G43BCU2T37)"
   2) 6B9AF0D3B3147A69C5E713773ADD9707CB3480D9 "Apple Development: Fumihiko Takayama (YVB3SM6ECS)"
   3) 637B86ED1C06AE99854E9F5A5DCE02DA58F2BBF4 "Mac Developer: Fumihiko Takayama (YVB3SM6ECS)"
   4) 987BC26C6474DF0C0AF8BEA797354873EC83DC96 "Apple Distribution: Fumihiko Takayama (G43BCU2T37)"
       4 valid identities found
   

   Choose one of them (e.g., 8D660191481C98F5C56630847A6C39D95C166F22) and replace existing CODE_SIGN_IDENTITY with yours as follows.

   # Replace with your identity
   readonly CODE_SIGN_IDENTITY=8D660191481C98F5C56630847A6C39D95C166F22

6. Replace team identifier, domain and embedded.provisionprofile.

   • Search G43BCU2T37 and replace them with your team identifier.

     git grep G43BCU2T37 src/

7. Build by the following command in terminal.

   make package

   dist/Karabiner-DriverKit-VirtualHIDDevice-X.X.X.pkg will be generated.

8. Notarize the pkg.

   make notarize

Components

Karabiner-DriverKit-VirtualHIDDevice consists the following components.

• Extension Manager (including DriverKit driver)
  • /Applications/.Karabiner-VirtualHIDDevice-Manager.app
  • It provides a command line interface to activate or deactivate DriverKit driver.
• VirtualHIDDeviceClient
  • /Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-DriverKit-VirtualHIDDeviceClient.app
  • It mediates between the client app and the driver.
  • It allows apps to communicate with the virtual device even if the app is not signed with pqrs.org's code signing identity. (The client app must be running with root privileges.)
• Client apps
  • Client apps are not included in the distributed package.
  • For example, you can build the client app from examples/virtual-hid-device-service-client in this repository.
  • Client apps can send input events by communicating with VirtualHIDDeviceClient via UNIX domain socket. (/Library/Application Support/org.pqrs/tmp/rootonly/vhidd_server/*.sock)

Version files

Version is defined in version.json.

• package_version:
  • Karabiner-DriverKit-VirtualHIDDevice package version.
  • Increment this when any components are updated.
• driver_version:
  • DriverKit driver internal version.
  • Increment this when the driver source code is updated.
• client_protocol_version:
  • The version for communication between VirtualHIDDeviceClient and the DriverKit driver.
  • Increment this when the communication specifications are changed.