WibuKey Developer Guide for Windows, Mac OS, Linux/UNIX on IBM compatible PCs and Macintosh Version 6.11, Edition February 2013 WibuKey Developer Guide © Copyright 2003-2013 by WIBU-SYSTEMS AG, Rueppurrer Strasse 52-54, 76137 Karlsruhe, Germany Printed in Germany All rights reserved. No part of this documentation, the accompanying software, or other components of the described product may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose other than the personal use of the purchaser without the express written permission of Wibu-Systems. While the data contained in this document has been written with all due care, Wibu-Systems does not warrant or assume responsibility that the data is free from errors or omissions. Wibu-Systems expressly reserves the right to change programs or this documentation without prior notice. Trademarks WIBU®, CodeMeter®, SmartShelter® are registered trademarks of Wibu- Systems. All other brand names and product names used in this documentation are trade names, service marks, trademarks, or registered trademarks of their respective owners. Wibu-Systems is member of: PCMCIA since 1993 USB Implementers Forum since 1997 SD Card Association since 2007 SIIA Software & Information Industry Association since 1998 Bitkom, Bundesverband Informationswirtschaft, Telekommunikation und Neue Medien (German Association of Information Technology, Telecommunications, and New Media) since 2003 VDMA, Verband Deutscher Maschinen- und Anlagenbau e.V. (German Engineering Federation) since 2008 and also member of the Developers programs of Autodesk, Apple, HP, IBM, Intel and Microsoft. Microsoft Gold Certified Partner Microsoft Embedded Partner 2 Contents Table of Contents Table of Contents 3 Part I Preface 11 1 About this Guide 11 2 Other Help Documents 12 3 Typographic Convention 12 4 Contacting Support 13 5 About Wibu-Systems 14 Part II Introduction 16 1 The WibuKey concept 16 1.1 What is WibuKey? 16 1.2 What is a WibuBox? 16 1.3 What are the FIRM CODE and the USER CODE? 18 1.4 WibuKey protection by encryption 20 1.5 Summary 23 1.6 Operating systems for WibuKey 24 2 WibuKey features 26 2.1 Storing data in the WibuBox 28 2.2 Storing sensitive data 29 2.3 Using the additional memory 31 2.4 Software metering 32 2.5 EXPIRATION DATE 34 2.6 Protecting modular software 37 3 Network support – WibuKey Server 38 3.1 The WibuKey network concept 39 3.2 Network license management 39 3.2.1 Licensing a single application 40 3.2.2 Licensing modular software 41 3.2.3 Huge license management 44 3.3 Advantages of WibuKey network license management 46 4 WibuKey hardware in the field 47 4.1 Delivering customer-specific updates 47 4.2 WibuBox remote programming 48 5 Checklist for copy protection 52 5.1 Degree of protection 52 5.2 Automatic or individual protection 52 5.3 Product or customer-specific protection 52 5.4 Protection with a local WibuBox and/or across the network 53 5.5 Protection of modular software with a single WibuBox 54 5.6 Simulation of multiple USER CODES with MASTER ENTRIES 55 6 WibuBox reprogramming 57 3 WibuKey Developer Guide 7 Additional WibuKey features 58 7.1 Pay-per-use, software leasing, software metering 58 7.2 EXPIRATION DATE 59 7.3 Saving data in the WibuBox 59 7.4 Data protection 60 7.5 Use of the EXTENDED MEMORY 60 7.6 Web authentication 61 8 Protection checklist 61 Part III Installing WibuKey Software 62 1 WibuKey CD-ROM 62 2 Installation process 62 3 Installation on Macintosh 63 4 Installation on Linux 64 Part IV Protecting software and digital content 65 1 AxProtector: Automatic software protection 65 1.1 Structure and Navigation 67 1.1.1 Menu Bar 68 1.1.2 Navigation Window 69 1.1.3 Input Window 69 1.1.4 Error and Warning Window 69 1.2 Project Dialog 70 1.3 Project Types 70 2 Windows Applications (32-bit/64-bit) 71 2.1 File to Protect 71 2.2 Licensing systems 72 2.3 License Handling 73 2.4 Runtime Settings 75 2.5 Advanced Runtime Settings 77 2.6 Security Options 78 2.7 Advanced Security Options 81 2.8 Error Messages 82 2.9 Advanced Options 83 2.9.1 License Lists 84 2.9.2 Add License Lists 85 2.9.3 IxProtector 88 2.9.4 Add Function Lists 88 2.9.5 File Encryption 90 2.10 Summary 94 2.11 Protection Result 95 3 .NET Applications 97 3.1 File to protect 98 3.2 Licensing Systems 99 3.3 License Handling 100 3.4 Runtime Settings 101 4 Contents 3.5 Advanced Runtime Settings 103 3.6 Security Options 104 3.7 Error Messages 105 3.8 .NET Options 107 3.9 Advanced Options 108 3.9.1 License Lists 109 3.9.2 Add License Lists 110 3.9.3 IxProtector 112 3.10 Summary 115 3.11 Protection Result 116 4 Mac OS X Applications 117 4.1 File to protect 117 4.2 Licensing Systems 118 4.3 License Handling 120 4.4 Runtime Settings 122 4.5 Advanced Runtime Settings 123 4.6 Error Messages 124 4.7 Advanced Options 125 4.8 Summary 126 4.9 Protection Result 127 5 Linux Applications 128 6 Java Applications 129 6.1 File to Protect 131 6.2 Licensing Systems 132 6.3 License Handling 133 6.4 Runtime Settings 135 6.5 Advanced Runtime Settings 137 6.6 Security Options 138 6.7 Advanced Security Options 139 6.8 Error Messages 140 6.9 Java Options 140 6.10 Advanced Options 142 6.11 Summary 143 6.12 Protection Result 144 7 File Encryption 146 7.1 File to Protect 146 7.2 Licensing Systems 147 7.3 License Handling 148 7.4 Advanced Options 150 7.4.1 License Lists 151 7.4.2 Add License Lists 152 7.4.3 File Encryption 154 7.5 Summary 158 7.6 Protection Result 159 8 IxProtector only 160 8.1 File to Protect 160 8.2 Error Messages 161 8.3 Advanced Options 162 8.3.1 License Lists 163 5 WibuKey Developer Guide 8.3.2 Add License Lists 164 8.3.3 IxProtector 166 8.3.4 Add Function Lists 167 8.4 Summary 169 8.5 Protection Result 170 9 Commandline options for AxProtector 172 9.1 Basic Options 172 9.2 Options for the Copy Protection System 173 9.3 Options for Encryption and Decryption 175 9.4 Runtime Options 184 9.5 Java-specific Options 187 9.6 Operational Options 189 10 IxProtector and the Software Protection API – WUPI 191 11 WUPI Functions 192 12 Individual Software Protection using WUPI: an Example 196 12.1 Definition of Modules 197 12.2 Placeholders in IxProtector License and Function Lists 198 12.3 Programming of the WibuBox 204 12.4 Integration into the Source Code 205 12.5 Encryption using AxProtector 207 Part V Programming WibuBox Hardware 208 1 WkList - Interactive programming 209 1.1 Storing and modifying BASE ENTRIES 211 1.2 Storing and modifying Added Entries 213 1.3 Storing and modifying User Data and Protected Data 213 1.4 Modifying WibuBox configuration attributes 215 2 WKCRYPT - Commandline programming 216 2.1 Programming WibuBoxes 216 2.2 Modifying WibuBox contents 221 2.3 Listing WibuBox contents 223 2.4 Modifying WibuBox configuration attributes 223 2.5 Initializing WibuBox hardware 224 2.6 Output of programming sequences 224 3 Remote programming 226 3.1 Remote programming at the custome 227 3.2 Remote programming using the WibuKey symbol 227 3.2.1 Context file generation 227 3.2.2 Updating WibuBox contents 228 3.3 Commandline actions at the customer 229 3.4 Actions at the developer's side 230 3.4.1 Remote programming with WkList 230 3.4.2 Commandline syntax remote programming (WKCRYPT) 232 3.4.3 Activating remote programming 232 3.4.4 Creating an update file 232 3.4.5 Creating a modified context file 233 3.4.6 File format of remote programming files 233 3.4.7 Additional options and tips 233 6 Contents Part VI Implementing network protection 235 1 WibuKey network technology 235 1.1 Features of WkLAN 236 2 WkLAN – protocol-based protection 236 2.1 WkLAN configuration 237 2.1.1 WkLAN server configuration 237 2.1.2 Adapting WkLAN to custom TCP/IP ports 240 2.1.3 Binding to specific IP addresses 240 2.1.4 Access permissions for the clients 240 2.1.5 WKLAN client configuration 241 2.1.6 Protecting software for WkLAN 242 2.2 First evaluation test 243 3 How does the WibuKey Server work? 245 3.1 Starting the WibuKey Server on Windows 245 3.2 Starting the WibuKey Server on Linux 246 3.3 Starting WibuKey Server on Mac OS X 247 3.4 WibuBox network entries 249 4 WibuBox network cluster 252 4.1 The basics 252 4.2 Network clusters 254 4.3 Cluster management 256 5 Handling of network users 257 5.1 Sharing local and network access 257 5.2 WibuKey Server without user limitation 257 5.2.1 Unlimited access 258 5.2.2 User limitation 258 5.3 Setting of a fixed slot by a client 259 6 Huge license management 260 6.1 Creating a HLM control file 261 6.2 Setting a server-sided HLM control file 263 6.3 Mixing of HLM and WibuBox network clusters 264 6.4 HLM in the extended memory 265 6.5 The WibuBox entries 265 7 WibuKey network tools 268 7.1 Control Panel Applet 268 7.2 WibuKey Network Server Monitor 269 7.3 Server process HTTP interface 270 Part VII Controlling and configuring WibuKey 272 1 WibuKey Control Panel Applet 272 1.1 Contents page 273 1.2 Test page 275 1.3 Server page 276 1.3.1 Cluster Name 276 1.3.2 HLM Files 276 1.3.3 WkLAN Configuration 277 7 WibuKey Developer Guide 1.4 Server access page 278 1.5 Server WkNet page 278 1.5.1 WkNet configuration 279 1.6 Network page 281 1.6.1 WkNet settings 281 1.6.2 WkLAN settings 282 1.6.3 Subsystem settings 283 1.7 WibuBox context page 283 1.8 WibuBox update page 284 1.9 Setup page 285 1.9.1 General settings 286 1.9.2 Special settings for WibuBox/P and WibuBox/RP 286 1.9.3 Special settings for WibuBox/SP and WibuBox/ST 287 1.9.4 Special settings for WibuBox/U and WibuBox/RU 289 1.9.5 Special settings for WibuBox/M 289 1.9.6 Special settings