WibuKey User Manual Version 5.0

Documentation Team (ha) - WIBU-SYSTEMS AG

WIBU-SYSTEMS AG, Karlsruhe (Germany)

email:  

This is version 5.0 of WibuKey user manuals and describes the WibuKey Runtime Kit for Mac OS X and Linux.

WibuKey is an intellectual property protection system. It works to prevent the use of illegal copies of software and data files. WibuKey consists of encryption and driver software and a hardware component called the WibuBox. The principle of the protection is the encryption of the intellectual property. Queries and encryption are built into the software or data file to be protected. These access the WibuBox, which is connected to the computer. The WibuBox confirms the queries and implements the decryption of the encrypted program or data file. Without the WibuBox the protected software cannot be used and the protected data files cannot be read. This decryption cannot be replicated by a software process, because it relies on certain secrets which are built directly into the WibuBox. WIBU-SYSTEMS guarantees the non-reproducibility of the WibuBox. This way no more copies of the program than defined in the WibuBox hardware can be used.

For more information please consult http://www.wibu.com/.


Table of Contents
1. WibuKey - A protection system
2. What is a WibuBox?
2.1. WibuBox/P
2.2. WibuBox/U
2.3. WibuBox/ST
2.4. WibuBox/RP
2.5. WibuBox/RU
2.6. European Community Declaration of Conformity
2.7. FCC Declaration of Conformity
2.8. VDE Approval
2.9. UL Approval
2.10. VCCI Approval
3. WibuKey Runtime Kit
3.1. Install
3.1.1. Linux - RPM
3.1.2. Linux - DEB
3.1.3. MacOS X
3.2. Deinstall
3.2.1. Linux - RPM
3.2.2. Linux - DEB
3.2.3. MacOS X
3.3. Update
4. WibuBox Remote Programming
5. Configuration tool - WkConfig
6. User tool - wku
6.1. General
6.2. wku - Parameters
6.3. wku - Remote Programming
6.4. wku - Network
7. WibuKey Network Server
7.1. General
7.2. Configuration
7.2.1. Settings
7.2.2. WkLAN
7.2.3. RemoteAccess
7.2.4. HlmFiles
7.2.5. HTTP
7.3. WibuKey WebMonitor
8. Appendix A
8.1. Example Linux
8.2. Example MacOS X

1. WibuKey - A protection system

WibuKey is an intellectual property protection system. It works to prevent the use of illegal copies of software and data files. WibuKey consists of encryption and driver software and a hardware component called the WibuBox. The principle of the protection is the encryption of the intellectual property. Queries and encryption are built into the software or data file to be protected. These access the WibuBox, which is connected to the computer. The WibuBox confirms the queries and implements the decryption of the encrypted program or data file. Without the WibuBox the protected software cannot be used and the protected data files cannot be read. This decryption cannot be replicated by a software process, because it relies on certain secrets which are built directly into the WibuBox. WIBU-SYSTEMS guarantees the non-reproducibility of the WibuBox. This way no more copies of the program than defined in the WibuBox hardware can be used.


2. What is a WibuBox?

The WibuBox is the WibuKey hardware component. There are many different variants of WibuBoxes, all of which contain the same intelligence: the WibuKey ASIC.

The WibuKey ASIC is a small but powerful encryption/decryption microprocessor. All memory used by the ASIC is integrated directly into the ASIC chip for even greater security.

The WibuBox is the encryption hardware of WIBU-SYSTEMS. It is a small colored connector for PCs, Macintosh and Unix machines. The WibuBox can have different colors, the default color is turquoise. There are different variants for different interfaces. Because all of the different WibuBox hardware variants contain the same ASIC, they all operate identically. In fact, no special work is necessary to support any specific WibuBox.

The WibuBoxes comply with international and national standards. A detailed declaration of conformity is available for each WibuBox variant.

Figure 1. WibuKey ASIC


2.1. WibuBox/P

The WibuBox/P or WibuBox/P+ (with 16kB memory) is for the parallel printer port of IBM-PCs or compatible systems. The WibuBox/P supports the enhanced parallel port (EPP) with its bi-directional mode that is compatible to IEEE 1284.

You simply connect the WibuBox/P to the 25-pin printer interface, the arrows on the case pointing to the direction of the PC. The thumb screws allow an easy connection with no need of tools. If the WibuBox/P is connected in combination with dongles of other manufacturers, the WibuBox/P should possibly be connected first.

Figure 2. WibuBox/P

Note

The WibuBox/P and WibuBox/P+ is supported on Microsoft Windows (tm) and on Linux (kernel 2.4 or higher).


2.2. WibuBox/U

The WibuBox/U or WibuBox/U+ (with 16kB memory) is designed for the USB interface of both PC and Macintosh. The WibuBox/U can be used with any USB interface or hub. There are no conflicts with other devices since the appropriate operating system controls and synchronizes the access to all connected USB devices.

Figure 3. WibuBox/U

Figure 4. WibuBox/U (old case)

Note

The WibuBox/U is supported on Mac OS version 8 or higher, Microsoft Windows (tm) and on Linux (kernel 2.4 or higher).


2.3. WibuBox/ST

The WibuBox/ST works like the WibuBox/P, but is for the serial, asynchronous interface (RS232) of any system (for example Unix, PC, Macintosh). The WibuBox/ST recognizes the used baud rate between 4.800 baud and 19.200 baud automatically.

Figure 5. WibuBox/ST

Note

The WibuBox/ST is supported on Microsoft Windows (tm) and on Linux (kernel 2.4 or higher).


2.4. WibuBox/RP

The WibuBox/RP or WibuBox/RP+ (with 16kB memory) is for the parallel printer port of IBM-PCs or compatible systems. The WibuBox/P supports the enhanced parallel port (EPP) with its bi-directional mode that is compatible to IEEE 1284.

You simply connect the WibuBox/RP to the 25-pin printer interface, the arrows on the case pointing to the direction of the PC. The thumb screws allow an easy connection with no need of tools. If the WibuBox/RP is connected together with dongles of other manufacturers, the WibuBox/RP should possibly be connected first.

Figure 6. WibuBox/RP

Note

The WibuBox/RP is supported on Microsoft Windows (tm) and on Linux (kernel 2.4 or higher).


2.5. WibuBox/RU

The WibuBox/RU or WibuBox/RU+ (with 16kB memory) is designed for the USB interface of both PC and Macintosh. The WibuBox/U can be used with any USB interface or hub. There are no conflicts with other devices since the appropriate operating system controls and synchronizes the access to all connected USB devices.

Figure 7. WibuBox/RU

Note

The WibuBox/U is supported on Mac OS version 8 or higher, Microsoft Windows (tm) and on Linux (kernel 2.4 or higher).


2.6. European Community Declaration of Conformity

All WibuBoxes comply with the CE EMC directive and meet the requirements of protection standards (89/336/EEC) and have the CE sign. They correspond to the valid norms for electromagnetic compatibility, Immunity and Sensitivity. The products comply with the limits for a Class B digital device according to EN55022.

The resistance to interference is fulfilled according to EN50082-1 and EN55024. A detailed declaration of conformity is available for each WibuBox variant.


2.7. FCC Declaration of Conformity

The WibuBoxes have been tested and found to comply with the limits for a Class B digital device, pursuant to Part 15 of the FCC Rules. Operation is subject to the following conditions:

  • these devices may not cause harmful interference, and

  • these devices must accept any interference received, including interference that may cause undesired operation.

The device generates and uses radio frequency energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a particular installation.

In case interferences do occur, consult your system instruction manual that should contain suggestions concerning the elimination of such interferences. Current remedial actions are: Increase the separation between the equipment and receiver or connect the equipment into an outlet on a circuit different from that to which the receiver is connected. A modification of the product without the explicit agreement of WIBU-SYSTEMS may cause a non-compliance of the FCC Rules. In that case the right of use of the user for that product expires.

The WibuBoxes have been tested, wherever possible, with a shielded interconnecting cable and approved. Thus, for the use of that product a shielded cable is necessary.

A detailed FFC DoC (Declaration of Conformity) is available on request.


2.8. VDE Approval

All WibuBoxen comply with the requirements of product safety according to EN60950 (VDE 0805).


2.9. UL Approval

WibuBoxes have been successfully undergone the UL94 test concerning the combustibility of the plastics contained in parts and devices. The WibuBoxes comply with the requirements of UL1950 (Safety of Information Technology Equipment) and are UL listed.


2.10. VCCI Approval

All WibuBoxes comply with the requirements of product safety according to VCCI in Japan (Voluntary Control Council for Interface by Information Technology Equipment).


3. WibuKey Runtime Kit

The WibuKey Runtime Kit contains all necessary files for the usage of the WibuKey intellectual property protection system.


3.1. Install

Depending on the used operating system WIBU-SYSTEMS provides different types of installation packages. Each of them contain the complete WibuKey Runtime Kit.


3.1.1. Linux - RPM

For Linux distributions based on RPM packages (Red Hat Package Manager) like Red Hat Linux or SuSE Linux you can easily install the WibuKey Runtime Kit by using the console based rpm command line tool. Alternatively you can use your favorite graphical package manager.

To install the WibuKey Runtime Kit use:

 rpm -ivh WkRt-Lin-5.0.500-1.i386.rpm 

Tip

Sometimes it is also possible to double click the installation package file inside a file browser to open your favorite graphical package manager and to install the WibuKey Runtime Kit.


3.1.2. Linux - DEB

For Linux distributions based on DEB packages (Debian Package Format) like Debian 3.0 (woody) or Debian 3.1 (sarge) you can easily install the WibuKey Runtime Kit by using the console based dpkg command line tool. Alternatively you can use your favorite graphical package manager.

 dpkg -i wkrt-lin-5.0.500-1.i386.deb 

Tip

Sometimes it is also possible th doubleclick the installation package file inside a file browser to open your favorite graphical package manager and to install the WibuKey Runtime Kit.


3.1.3. MacOS X

On MacOS X you can install the WibuKey Runtime Kit easily by doubleclicking on the WkRtMacXbase.hqx file. Then you can start as result the graphical installation program. Follow the instructions of the installation to install the WibuKey Runtime Kit.


3.2. Deinstall

Depending on the used operating system different ways to uninstall the WibuKey Runtime Kit are possible.


3.2.1. Linux - RPM

For Linux distributions based on RPM packages (Red Hat Package Manager) like Red Hat Linux or SuSE Linux you can easily uninstall the WibuKey Runtime Kit by using the console based rpm command line tool.

To uninstall the WibuKey Runtime Kit use:

 rpm -e WkRt-Lin 


3.2.2. Linux - DEB

For Linux distributions based on DEB packages (Debian Package Format) you can easily uninstall the WibuKey Runtime Kit by using the console based dpkg command line tool.

To uninstall the WibuKey Runtime Kit use:

 dpkg -r WkRt-Lin 


3.2.3. MacOS X

On MacOS X you can easily uninstall the WibuKey Runtime Kit by doubleclicking the WkRtMacXbase.hqx file. Then you can start the WibuKey installation program. As result the WibuKey installation program will be started. Choose the menu item 'uninstall' to uninstall the WibuKey Runtime Kit and follow the instructions.


3.3. Update

The latest information about WibuKey can always be found on the internet. Check our web site

http://www.wibu.com

The latest version of the WibuKey Runtime Kit can be downloaded from

http://www.wibu.com/down_wibukey.php


4. WibuBox Remote Programming

WibuKey makes it possible to reprogram entries in a WibuBox while it is located at the customer's site. This option is called Remote Programming

Remote Programming is accomplished by exchanging encrypted data files. These data files can be exchanged by many media such as email, fax or even by phone.

To update a WibuBox entry the following steps are required:

Note

You can easily create a context file (*.rtc) or apply an update file (*.rtu) into your WibuBox using wku or WkConfig.


5. Configuration tool - WkConfig

WkConfig is a WibuKey tool. With WkConfig you can browse the content of each WibuBox connected locally or to a network server. Using WkConfig you can also set parameters to configure the local WibuKey subsystem or the WibuKey network server. In addition to that it's possible to update WibuBoxes with WkConfig by creating a WibuBox context file (*.rtc) and to reprogram your WibuBox by using an update-file (*.rtu).

See also Remote Programming.

Note

WkConfig is available on MacOS X as WkConfig and on Linux as WkConfigLin. Remember WkConfig requires an installed Java Runtime Enviroment.

WkConfig provides four tabs with different settings:


6. User tool - wku

6.1. General

wku is the universal WibuKey console application for the WibuKey user. The program is available as wkuLin for Linux and as wkuMacX for MacOS X. A symbolical link to wku also exists.


6.2. wku - Parameters

wku has a lot of features, which are defined by the following arguments:

  • If the program is called without arguments it lists all found WibuKey ports and the number of connected WibuBoxes.

  • With the wku LIST command, the content of one or more WibuBoxes at one or more ports is displayed.

  • With the wku TEST command, the encryption functionality of all or of the specified WibuBoxes is checked in greater detail by a specific number of checks.

  • With the wku DATA command, the user can list and modify User Data entries in the WibuBox.

  • With the wku REMOTE command, the user can create a remote programming context information file or apply a remote programming update file to a WibuBox to change its content.

  • wku NETWORK searches for WkLAN servers on the local network.

For more details about the use of wku see the online help of the application. A general help can be displayed via the command input:

 wku -h

A subcommand specific help can be printed by entering the subcommand name, followed by the help option -h, for example:

 wku LIST -h


6.3. wku - Remote Programming

wku can create a remote context file for one or more connected WibuBoxes via the REMOTE GET command:

 wku REMOTE GET ALL TO x.rtc

writes the content of all connected WibuBoxes to the x.rtc file. To minimize the size of this file, a user can select the ports or the connected WibuBoxes of which content should be stored. The port and WibuBox selection is done like other wku commands:

 wku REMOTE USB:1 GET ALL TO x.rtc 

writes the content of the first WibuBox at USB to the x.rtc file.

A further reduction of the remote programming context file size can be reached by specifying the number of needed entries. This is done by one or more numbers in the range of 1 to 10 instead of the ALL keyword.

 wku REMOTE USB:2 GET 1,5 TO x.rtc

writes only the content of entries 1 and 5 of the second WibuBox at USB to the remote context file.

To add a new entry, the programmer on the other side of the remote programming process only needs a list of empty entries in the WibuBox. This can be achieved by the EMPTY keyword:

 wku REMOTE GET EMPTY TO x.rtc

Note

The file (for example x.rtc) can now be sent in any form (floppy disk, email, printed as letter or facsimile or verbal via phone) to the software producer. Here the file is used for modifications of the WibuBox.

The software producer sends a remote programming update file back to the WibuBox user. This new file contains commands to modify the specific content of the WibuBox. To execute the WibuBox programming commands, wku is also used, which is explained now.

To transfer remote programming update information into a connected WibuBox, the SET command of wku is used:

 wku REMOTE SET FROM x.rtu

searches at all ports for WibuBoxes matching the remote update data. An optional list of WibuKey ports or specific WibuBoxes can limit the update process to a subset of connected WibuBoxes.


6.4. wku - Network

With the AT command all other wku commands can be redirected to other computers via network. To do this, wku uses the WkLAN network protocol. An example to list all WibuBox entries on hostname:

 wku AT hostname LIST


7. WibuKey Network Server

7.1. General

The WibuKey network server enables the access to WibuBoxes over the network. This allows copy protection of an application as well as limitation of the number of users that access the application at the same time. Such a WibuKey network server can run on any computer in the network, it is not necessary to run it on a primary network server, like your mail or file server.

WibuKey offers two different methods to protect an application in the network with the WkNet and WkLAN. network subsystems. On Linux and Mac OS only the WkLAN protocol is supported.

WkLAN is protocol based, data is transferred synchronously between server and clients. WkLAN is based on TCP/IP. The current implementation runs on Mac OS, Linux and Microsoft Windows.

Note

Depending on the operating system the WibuKey WkLAN network server is called:

  • WkSvMac, on Mac OS 8/9.

  • WkSvMacX, on Mac OS X.

  • WkSvLin, on Linux.

  • WkSvW32, on Microsoft Windows.

Figure 8. WibuKey Network Server (WkSvLin)

Only one instance of the WibuKey network server can be running at the same time on one system.

Note

On Mac OS X and Linux you can start the WibuKey network server as daemon or as application. The features of both are equal, but the daemon will run as UNIX like background service without screen output.

Tip

On Linux you start the WkSvLin daemon by using the init script:

 /etc/init.d/wksvlin {start|stop|status}

Tip

On Mac OS X you start the WkSvMacX daemon by using the SystemStarter:

 SystemStarter start "WibuKey Server"


7.2. Configuration

All configuration for the WibuKey network server is stored in the Server.ini configuration file . Most settings can also be changed by using WkConfig.

Note

If you modify the Server.ini configuration file the WibuKey network server must not run.

The configuration options for the WibuKey network server are divided into five sections:

  • Settings

  • HTTP

  • HlmFiles

  • RemoteAccess

  • WkLAN


7.2.1. Settings

The basic configuration settings of the WibuKey network server are stored in the [Server] section of the Server.ini file. The following values can be specified:

Table 1. Settings

Entry Key WordMeaning
BindAddressSpecifies the IP address which is used by the WibuKey server.
WkLANEnables (1) or disables (0) the WkLAN functionality.
LoggingActivates (1) or deactivates (0) the logging of all actions to a file.
LoggingPathSpecifies the location of the logfile. The server process must have write permissions for this location.
AccessFsbIf this option is active (1), access to Firm Codes in the range of 90-99 is possible from the network. This range is reserved for Firm Security Boxes (FSB). This option has to be activated if a Firm Security Box is connected to a WkLAN server and every network user should have access to this FSB to program WibuBoxes.
NoBoxPgmMust be activated (1) to avoid the reprogramming of the WibuBoxes connected to this WkLAN server from other stations.
WkLanTimeOut Specifies the timeout value in minutes. An allocated slot in the WkLAN client list is freed automatically if the allocating process has not accessed its slot in the specified time. If this entry is not set, a default timeout value of 1440 (24 hrs) is used.


7.2.2. WkLAN

The WkLAN configuration settings of the WibuKey network server are stored in the [WkLAN] section of the Server.ini file. Following values can be specified:

Table 2. WkLAN

Entry Key WordMeaning
IpPortSpecifies the TCP/UDP port number to be used for the WkLAN communication. WkLAN uses the default port 22347 for communication. If this port is already used by another process it can be changed here. This change also has to be done for the WkLAN clients. Otherwise there will be no communication between clients and server.

7.2.3. RemoteAccess

Access rights to control the access to the WibuKey server can be specified in the [RemoteAccess] section. The corresponding entries are "ip_address = Permission" where 'Permission' can be:

Table 3. RemoteAccess

PermissionMeaning
1 Read content.
2 Read content (Details) (not implemented yet).
4 Allocate license.
8 Delete user.
16 Delete all users (not implemented yet).

Combinations are possible, e.g. 7 = 'Read content and Allocate license' is permitted, 'Delete user' is denied. The entry "Default"=31 specifies the rights of users which aren't explicitly declared. These rights can be restricted, too. Due to compability reasons all these actions are permitted by default.


7.2.4. HlmFiles

HLM control files are specified in the Server.ini configuration file in the [HlmFiles] section. Each variable in this section has the following form (and is a argument for a path of the HLM Control File):

FileN=hlm_file

Remember, the N behind the File is a number from 1 to 9.

The HLM setting is interpreted only when the WibuKey Server is started. If the HLM settings are changed, the server process must be stopped and restarted to read the new settings.


7.2.5. HTTP

The HTTP configuration settings of the WibuKey network server are stored in the [HTTP] section of the Server.ini file. Following values can be specified:

Table 4. HTTP

Entry Key WordMeaning
HtmlArchive Path to WebMonitor HTTP interface container.
RemoteRead Enables (1) or disables (0) remote read access to the WebMonitor.
RemoteCommand Enables (1) or disables (0) support for remote commands from the WebMonitor (i.e. for cancelling of users from remote computers).
RemoteWrite Enables (1) or disables (0) support for RemoteCommand operations.

7.3. WibuKey WebMonitor

The WibuKey WebMonitor provides information about the running WibuKey network server. The WibuKey WebMonitor is only available if the WibuKey network server is running.

The number of users currently accessing a WibuKey server, at what time they logged on and at what time they did the last access can be viewed from any network station. You can cancel users retrieve internal status information of the network server process and the driver that handles the WibuBox access.

Note

The WibuKey WebMonitor is available as HTTP frontend for any internet browser like Mozilla, Konqueror, Firefox or Safari. To access the WibuKey WebMonitor use the URL http://127.0.0.1:22347 . (Remember: The number 22347 meaning the TCP port configured in Server.ini.)

Figure 9. WibuKey WebMonitor


8. Appendix A

The WIBUKEY.INI configuration file defines the parameters for the WibuKey framework. The following table describes all possible parameters. Remember that WkConfig provides a graphical interface to define some selected parameters stored in WIBUKEY.INI.

Note

Remember: The WIBUKEY.INI config file is used on Mac OS X and Linux. But not all parameters are also used on Mac OS X because the WibuBox/ST, WibuBox/P and WibuBox/RP are not supported on Mac OS X. Inside the table these options are marked with a flag for the supported operation system.

Table 5. Configuration file WIBUKEY.INI

Entry Key WordMac OSLinuxMeaning
[General]    
WkPortname No Yes Defines the device prefix for the serial interface (WibuBox/ST) , typically '/dev/ttyS'
WkPortEnum No Yes Defines the suffix for WkPortname. Typically this value is 'DIGIT' (alternative 'ALPHA'). That means the '/dev/ttyS0' device is used as example.
    
[Server]    
WkLAN No Yes Enables (1) or disables (0) the usage of the WkLAN protocol for WibuKey network communication.
    
[Driver]    
SubSystem Yes Yes Defines the subsystems to use. Possible value are: Kernel (for local WibuBox access) and WkLAN.
WkPort No Yes Defines the interfaces to be used. Possible value are: Com, Lpt, USB.
WkCom No Yes Defines the serial interfaces that can be used. WkCom is defined as a set, each asterix (*) means enable, each '/D' means disable. Example: *,/D,/D,/D - Only use the first serial interface. All other serial interfaces are disabled.
BaudRate No Yes Defines the baud rate to be used for the serial interfaces for the WibuBox/ST, typically 19200.
WkLpt No Yes Defines the parallel interfaces that can be used. WkLPT is defined as a set, each asterix (*) means enable, each '/D' means disable. Example: *,/D,/D - Only use the first parallel interface. All other parallel interfaces are disabled. (Remember: On Linux we use the user space parallel port device '/dev/parport[0-2]'. The User must have valid (read/write) access permissions for this device and the Linux kernel must provide the '/dev/parport' device.
    
[WkLAN]    
IpPort Yes Yes Defines the TCP/UDP port to be used for WkLAN communication. (Default 22347)
    
[WkLAN Client]    
ServerN Yes Yes Contains a server search list. Typically this section ist empty and WibuKey will used a broadcast message to find a WibuKey network server. If you do not wish to use a broadcast a set of servers to be queried can be set here. A valid entry has a number between 1 to 9 for N. Example: Server1=10.20.30.40


8.1. Example Linux

WIBUKEY.INI example file for Linux:


  [General]
  WkPortname=/dev/ttyS
  WkPortEnum=DIGIT
 
 
  [Server]
  WkLAN=1
 
  [Driver]
  SubSystem=Kernel, WkLAN
  WkPort=Com,USB
  WkCom=*,/D,*,/D
  BaudRate=19200
  WkLpt=*,/D,/D
 
  WkLang=TRUE
 
  [WkLAN]
  IpPort=22347
  
  [WkLAN Client]
  Server1=127.0.0.1
  Server2=10.20.30.40
  Server3=255.255.255.255
  


8.2. Example MacOS X

WIBUKEY.INI example file for MacOS X:


  [Driver]
  SubSystem=Kernel, WkLAN
 
  [WkLAN]
  IpPort=22347
  
  [WkLAN Client]
  Server1=127.0.0.1
  Server2=10.20.30.40
  Server3=255.255.255.255