Configuring Hardware Security Token USB Passthrough in vSphere Environment

Products

• VMware vSphere ESXi

Issue/Introduction

Users need to configure USB passthrough for hardware security tokens in a VMware ESXi environment to enable authentication within virtual machines. This configuration requires specific host settings and VM configurations to ensure proper device recognition and functionality. This can be used for a variety of hardware security tokens, including YubiKey, RSA SecurID, and more.

Environment

- VMware ESXi host
- Virtual Machine(s) with USB 3.0 or newer controllers
- Hardware security token compatible with USB interface
- ESXi license that supports USB passthrough for smart card readers

Cause

Hardware security tokens require specific USB passthrough configuration at both the ESXi host and virtual machine levels to function properly. Default configurations may not recognize these devices correctly.

Resolution

Stage 1: Identify Device Information

1. Configure the security token (if applicable):
   1. Disable any interfaces you don't need
   2. Configure the device for your required functionality only
      
      
2. Identify the device's specific hardware IDs:
   1. Connect the security token to a USB 3.0 port on the ESXi host
   2. Run the following command:
      
      • lsusb
        
        
   3. Note the Device ID output, which will be in the format: `Bus ### Device ###: ID VVVV:PPPP Manufacturer.name Device.name`
      • VVVV represents the vendor ID (e.g., 1050)
      • PPPP represents the product ID (e.g., 0404)
             Example output:
                 Bus 004 Device 002: ID 1050:0404 Yubico.com Yubikey 4 CCID
        
         **Important**: Your device's vendor and product IDs will likely be different from this example. Use the IDs displayed by the lsusb command for your specific device.

Stage 2: Configure ESXi Host Recognition

1. Enable required modules:
   • esxcli system module list | grep vmkusb
   • esxcli system module load -m vmkusb    # If not already loaded
     
     
2. Configure USB device recognition using your device's specific IDs:
   1. Edit /etc/vmware/config and add:
      • usb.quirks.device0 = "0xVVVV:0xPPPP allow"
        
           Replace VVVV:PPPP with your device's vendor and product IDs from Step 1
        
        
   2. Edit /bootbank/boot.cfg, adding to kernelopt line:
      • CONFIG./USB/quirks=0xVVVV:0xPPPP::0xffff:UQ_KBD_IGNORE
        
           Replace VVVV:PPPP with the same IDs used above
        
        
3. Restart the ESXi host to apply changes
   
   
4. Verify device recognition:
   • esxcli hardware usb passthrough device list
     
        Your device should appear in the list of available devices

Stage 3: Configure Virtual Machine USB Passthrough

1. Add USB controller to VM:
   1. Ensure USB 3.0 or newer controller is present
   2. Add if not already configured
      
      
2. Configure VM settings:
   1. Edit the VM's .vmx file to add:
      • usb.generic.allowCCID = "TRUE"
      • usb.quirks.device0 = "0xVVVV:0xPPPP allow"
        
           Replace VVVV:PPPP with your device's vendor and product IDs
        
        
3. Power on the VM and verify device recognition

Additional Information

• Ensure your ESXi license supports USB passthrough functionality for smart card readers
  
  
• For troubleshooting device recognition issues, verify the pcscd service status:
  • /etc/init.d/pcscd stop
    
    
• Configuration supports vMotion within properly configured clusters
  
  
• Test configuration in non-production environment before implementing in production
  
  
• Device IDs may change depending on the security token's mode or configuration
  
  
• Some security tokens may present multiple interfaces (HID, CCID, etc.). Disabling unnecessary interfaces may improve compatibility