Platform support

hardware keys can be used on the following platforms:

Serial keys on Windows 7 and above, and Linux

ibutton serial

USB keys on Windows 7 and , Linux, Mac OS X 10.9 and later

ibutton usb

In general, three steps are required:

  1. Plugging in the hardware key.

  2. Providing access to the hardware key.

  3. Setting up the necessary native library.

Plugging in the hardware key

To run applications with a hardware key, the key must be plugged into the proper port of your computer. If you have multiple ports, you can freely choose one that is available. Please note that currently only supports a single hardware key per computer.

Providing access to the hardware key

Windows 7 and above

Serial keys are usable without additional drivers.

The first time a USB key is plugged in, Windows pops up a window asking to install the appropriate driver. You can find drivers in the subdirectories of licenses\hardwarekey\install\win32 or win64:

Windows

msi/install_1_wire_drivers_(x86|x64)_v402.msi

Select an .msi file to install the corresponding .sys files in %windir%\SYSTEM32\DRIVERS.

Note that Windows may pop up the installation window for each new port in which the hardware key is used. In that case, repeat the procedure.

If Windows fails to install the driver automatically from the pop-up window, first make sure that the latest Oracle JDK is installed. Next, go to the licenses\hardwarekey\install\ folder, find the appropriate .msi file, and double-click it. Step through the installation wizard to install the driver.

Linux

You must set the device access rights so that the user can access the hardware key. A simple approach is changing the rights on all devices.

Serial keys

chmod ugo+rw /dev/ttyS?

USB keys

chmod ugo+rw /dev/bus/usb/???/???

In some older Linux distributions, the devices are in a different directory:

chmod ugo+rw /proc/bus/usb/???/???

In some older Linux distributions, you must make additional devices accessible:

chmod ugo+rw /dev/usbdev*

In addition, you may want to unload the kernel module ds2490. Many kernels load automatically when the key is plugged in, but which is not used. The module seems to cause spurious keyboard problems. rmmod ds2490

The access mode changes are lost each time a USB key is unplugged and plugged in again. You can automate the access mode change with the help of the UDEV system: put the rules file 10-ds2490.rules (below) in the directory /etc/udev/rules.d. 

# DS2940
ATTRS{idVendor}=="04fa", ATTRS{idProduct}=="2490", MODE:="0666"

Older Linux distributions still support the older hotplug system, which serves the same purpose. You can automatically change the access mode by appending the two lines below to the configuration file /etc/hotplug/usb.usermap. 

# Maxim/Dallas DS2940 USB iButton
ds2490  0x0003  0x04fa  0x2490  0x0000  0x0000  0x00  0x00  0x00  0x00  0x00  0x00  0x00000000

Next, put the following script in the directory /etc/hotplug/usb. 

#!/bin/bash
#
# Sets up newly plugged in Maxim/Dallas USB iButton so that any user can access
# it from user space.
#
# Note that for this script to work, you'll need all of the following:
# a) a line in the file /etc/hotplug/usermap that corresponds to the
#    device.
# b) a Linux kernel supporting hotplug and usbdevfs.
# c) the hotplug package (http://linux-hotplug.sourceforge.net/).
#
# In the usermap file, the first field "usb module" should be named
# "ds2490" like this script.
#

if [ "${ACTION}" = "add" ] && [ -f "${DEVICE}" ]
then
chmod o-rwx "${DEVICE}"
chgrp users "${DEVICE}"
chmod g+rw  "${DEVICE}"
fi

In addition, you can disable the ds2490 module more permanently by adding this line to the file /etc/modprobe.d/blacklist: 

blacklist ds2490

macOS

On macOS you don’t need to perform any additional steps to install the hardware key.

Troubleshooting USB drivers on Windows

If you are having problems with USB keys on Windows, it may help to check for driver problems.

  • Make sure you have properly installed the driver after you plugged in the USB hardware key, as explained in Providing access to the hardware key.

  • The hardware key is a standard USB 1-Wire iButton device, manufactured by Analog Devices. You can check whether Windows has recognized the driver and the hardware key by running devmgmt.msc and navigating to Universal Serial Bus controllers / 1-Wire Devices. Depending on the driver that you have installed, the device and driver have the following details:

    • USB Host Adapter for 1-Wire Network using WinUSB

Device type

Universal Serial Bus controllers

Manufacturer

Dallas Semiconductor Maxim

Location

Location 0 (USB Device)

Driver Provider

Unknown

Driver Date

Not available

Driver Version

Not available

Driver Signer

Not digitally signed

Driver Files

C:\WINDOWS\SYSTEM32\DRIVERS\WinUSB.sys

  • USB Host Adapter for 1-Wire Network

Device type

1-Wire Devices

Manufacturer

Dallas Semiconductor Maxim

Location

USB Device

Driver Provider

Dallas Semiconductor Maxim

Driver Date

21/04/2005

Driver Version

5.0.8.2

Driver Signer

Not digitally signed

Driver Files

C:\WINDOWS\SYSTEM32\DRIVERS\DS2490.sys

  • Dallas Semiconductor LIBUSB 1-Wire USB Adapter, Version 02/15/2004, 0.1.8.0

Device type

Universal Serial Bus controllers

Manufacturer

http://libusb-win32.sourceforge.net

Location

Location 0 (USB Device)

Driver Provider

http://libusb-win32.sourceforge.net

Driver Date

15/02/2004

Driver Version

0.1.8.0

Driver Signer

Not digitally signed

Driver Files

C:\WINDOWS\SYSTEM32\DRIVERS\libusbfl.sys C:\WINDOWS\SYSTEM32\DRIVERS\libusbst.sys C:\WINDOWS\SYSTEM32\DRIVERS\libusb0.dll

  • You can re-install the driver by selecting the device, opening its properties and clicking Update driver on the Driver tab. Choose Search for and specify the correct location as explained in Providing access to the hardware key.

  • You can try plugging the hardware key into a different USB port. For each new port, Windows may ask to install the driver. The latest official driver installer can be downloaded from https://www.analog.com/en/design-center/evaluation-hardware-and-software/1-wire-sdks/download-1wire-ibutton-drivers.html.

  • Analog Devices also has an iButton viewer at https://www.analog.com/en/design-center/evaluation-hardware-and-software/1-wire-sdks/viewer.html. It is simply launched by Java Webstart. It provides another way to verify that the iButtons are functioning, and to actually read out the iButton’s serial number.

  • If the Analog Devices drivers fail to work, you can try the alternative libusb driver. You may first have to uninstall the DS2490 driver:

    1. Uninstall the "USB Host Adapter for 1-Wire Network" driver from the device manager.

    2. Remove %windir%\INF\DS2490.inf and any corresponding OEM*.INF and OEM*.PNF files. You can find these files by typing: find "DS2490" %windir%\INF\OEM*.INF.

    3. Remove %windir%\SYSTEM32\DRIVERS\DS2490.sys.

    4. Remove the following registry keys with regedit:

      \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum\USB\Vid_04fa&Pid_2490
\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceClasses\{a5dcbf10-6530-11d2-901f-00c04fb951ed}\##?#USB#Vid_04fa&Pid_2490#5&2f6f8af0&0&2#{a5dcbf10-6530-11d2-901f-00c04fb951ed}
\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceClasses\{a5dcbf10-6530-11d2-901f-00c04fb951ed}\##?#USB#Vid_04fa&Pid_2490#5&9f3145e&0&6#{a5dcbf10-6530-11d2-901f-00c04fb951ed}

    5. Reboot before installing the new driver.
      The next time a USB key is plugged in, a window pops up to install the appropriate driver. You can find the driver libusbds.inf in lib\native\win32\libusb. It will automatically install the libusb driver. You may have to ignore warnings about the driver not being signed.

Troubleshooting USB access on Linux

If you are having problems with a USB key on Linux, you may want to check if the key is recognized by the OS.

  • The following command should list the device: lsusb -d 0x04fa:0x2490. It should show something like Bus 004 Device 004: ID 04fa:2490 Dallas Semiconductor DS1490F 2-in-1 Fob, 1-Wire adapter, indicating that the device is at /proc/bus/usb/004/004.

  • The file /proc/bus/usb/devices should contain an entry starting with something like: 

T:  Bus=04 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#=  4 Spd=12  MxCh= 0
D:  Ver= 1.00 Cls=ff(vend.) Sub=ff Prot=ff MxPS= 8 #Cfgs=  1
P:  Vendor=04fa ProdID=2490 Rev= 0.02

  • The user should have read permissions and write permissions for the corresponding devices. The devices are any or all of: ls -l /dev/bus/usb/???/???; ls -l /proc/bus/usb/???/???; ls -l /dev/usbdev*. Otherwise, make sure the file `ds2490.rule`s is installed properly, as discussed in Providing access to the hardware key, or change the permissions manually.

  • You should make sure that the libusb library is installed on your system. You can use the ldd command to check if all the necessary shared libraries can be found: ldd libLcdUtil2.so.

  • If the iButton causes spurious behavior of the keyboard and the mouse, this is probably due to kernel module ds2490, which many kernel versions load automatically when a USB key is plugged in. You can check this with: lsmod | grep ds2490. If it is still present, you can disable it temporarily or permanently, as discussed in Providing access to the hardware key.