Monster Media 1994 #1

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1994 #1 / monster.zip / monster / PROG_GEN / REGKEY30.ZIP / REGKEY.TXT < prev next >

Wrap

Text File | 1994-03-07 | 201KB | 4,427 lines

R E G K E Y ----------------------------------------------------------------------------- Version 3.00 Registration Key System For Programmers Programmer's Manual NOTE: Since you will probably want to refer to this manual while working with RegKey, it would be a good idea to take a few minutes to print it. To print this manual on any printer, simply type COPY REGKEY.TXT PRN from the DOS Prompt, or choose the FILE|PRINT option from the Windows File Manager, selecting the REGKEY.TXT file. (C) Copyright Brian Pirie, 1993 - 1994. All Rights Reserved. ----------------------------------------------------------------------------- TABLE OF CONTENTS ----------------------------------------------------------------------------- TABLE OF CONTENTS.................................................2 PART 1: INTRODUCTION..............................................3 PART 2: ABOUT YOUR EVALUATION COPY AND REGISTERING................5 THE DEMO VERSION & BENEFITS OF REGISTERING...................5 HOW TO ORDER.................................................7 FILLING OUT THE REGISTRATION FORM............................8 RECEIVING YOUR ORDER BY CONVENTIONAL MAIL....................8 RECEIVING YOUR ORDER BY A CALL TO YOUR BBS...................9 RECEIVING YOUR ORDER BY CALLING THE REGKEY BBS...............9 RECEIVING YOUR ORDER BY INTERNET EMAIL.......................9 RECEIVING YOUR ORDER BY FIDONET CRASHMAIL....................9 SENDING YOUR ORDER FEE......................................11 ORDERING THE SOURCE CODE....................................13 REGKEY 3.00 ORDER FORM......................................15 REGKEY 3.00 USER FEEDBACK FORM..............................16 TERMS OF REGISTRATION AND SOURCE CODE USE...................17 PART 3: USING THE REGKEY SYSTEM..................................18 A QUICK TOUR OF REGKEY......................................18 INTRODUCTION TO REGISTRATION KEYS...........................21 PRINCIPLES OF THE REGKEY SYSTEM.............................23 FILE-BASED VS. USER-ENTERED REGISTRATION KEYS...............25 USING THE KEYGEN PROGRAM....................................27 CREATING GENERATION/VALIDATION CODE SETS....................29 GENERATING REGISTRATION KEYS................................31 VALIDATING REGISTRATION KEYS WITHIN YOUR PROGRAM............34 METHODS FOR ADDING EXPIRY INFORMATION.......................37 SECURITY ISSUES.............................................40 TROUBLESHOOTING GUIDE.......................................43 PART 4: LANGUAGE-SPECIFIC INFORMATION............................46 USING THE REGKEY SYSTEM WITH C OR C++.......................46 USING THE REGKEY SYSTEM WITH QUICKBASIC.....................54 USING THE REGKEY SYSTEM WITH VISUAL BASIC...................60 USING THE REGKEY SYSTEM WITH TURBO PASCAL...................61 USING REGKEY WITH OTHER LANGUAGES OR OPERATING SYSTEMS......68 PART 5: ADDITIONAL INFORMATION...................................69 GETTING HELP................................................69 CONTENTS OF PACKAGE.........................................71 GLOSSARY....................................................73 INDEX.......................................................78 ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 2 ----------------------------------------------------------------------------- PART 1: INTRODUCTION ----------------------------------------------------------------------------- Welcome to RegKey, the registration key system for programmers! RegKey is designed to allow you to quickly and easily add advanced registration key capabilities to your software. If you are unfamiliar with the concept of registration keys, see page 20 of this manual for an introduction to the subject. Among the unique features provided by RegKey are the following: - RegKey is compatible with a wide variety of programming languages and operating systems. This manual provides specific instructions for using RegKey with C compilers from Microsoft and Borland (for both DOS and Windows applications), Microsoft QuickBASIC, Microsoft Visual Basic for Windows , and Borland Turbo Pascal. In addition, you can also use RegKey with many other programming languages, compilers and operating systems. For more information on using RegKey in environments not explicitly discussed in this manual, see page 68. - RegKey is designed to be very flexible. For instance, RegKey supports both file-based and user-entered registration keys. In the first case, the registration key takes the form of a small file that is placed in your application's working directory. In the second case, the registration key takes the form of a twenty digit code that the user enters into your application or configuration program. RegKey also gives you full control of any differences in your application's behavior between registered and unregistered modes. For example, you may elect to have your application display a short "please register" message at startup when operating in unregistered mode. Alternatively, you may decide to make additional feature of your program available after the user has registered. You might also decide prevent your program from being used after a certain period of time if a valid registration key has not been provided. - Every application that uses RegKey chooses its own set of numerical codes that RegKey uses to generate and validate registration keys. This means that you can use RegKey for as many different applications as you wish, requiring different registration keys for each program. - RegKey is designed so that it is virtually impossible for someone to generate counterfeit registration keys for your software. The numerical code required to generate your registration keys is different from the corresponding code used to validate your registration keys. Since only the validation ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 3 code is included in your program's executable file, the secret numerical code used to generate your registration keys cannot be discovered by reverse-engineering your program. It is mathematically infeasible for someone to determine your generation code from the corresponding validation code. - For added security, RegKey uses 96-bit registration keys. Because most compilers and programming languages only support 32-bit arithmetic, registration keys are most often no greater than 32-bits in size. While creating a registration key system that supports 96-bit registration keys involves much more work (creating RegKey has involved writing routines to perform operations as basic as adding, multiplying and dividing two numbers), it makes it virtually impossible to determine a registration key by an exhaustive search. - The source code for RegKey is also available. This presents no security threat to those using RegKey due to the nature of the algorithms used by RegKey. Even knowing how RegKey works in great detail does not make it any easier to generate counterfeit registration keys for an application using RegKey. - Included with RegKey is an example program that demonstrates how you can make use of the RegKey system. This manual also provides a tutorial on how you can best use RegKey, and discusses some of the issues you may want to consider. - RegKey is very low-priced. For only $30 Canadian Dollars, $24 U.S. Dollars, or your country's equivalent, you are entitled to unlimited use of this and all future versions of RegKey. For an additional $30CDN/$24US/equivalent, you may also receive the RegKey source code. If you are using RegKey to encourage people to pay for your software, RegKey will quickly pay for itself! ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 4 ----------------------------------------------------------------------------- PART 2: ABOUT YOUR EVALUATION COPY AND REGISTERING ----------------------------------------------------------------------------- THE DEMO VERSION & BENEFITS OF REGISTERING ----------------------------------------------------------------------------- RegKey is distributed on a try-before-you-buy basis. If you wish to continue using RegKey after an initial one month evaluation period, or if you wish to distribute programs using RegKey, you must pay to register it. The complete RegKey package is freely distributed, and can be freely used for evaluation purposes. All the features and capabilities of RegKey are enabled in the RegKey package that you have. However, prior to registering, you may only use RegKey under the following conditions: 1.) RegKey may only be used for a period up to one month, and only for evaluation purposes prior to registering. 2.) Programs using an unregistered copy of RegKey may not be distributed. Also, when unregistered, RegKey will display a message to the user indicating that RegKey is not registered. This message is, of course, removed when RegKey is registered. If you decided to purchase RegKey, you will become the owner of a powerful tool for adding registration key capabilities to your software. Registered owners of RegKey are entitled to: 1.) Unlimited use of RegKey. You may write as many programs as you wish using RegKey, and do what you please with these programs. There are no additional royalty fees for using RegKey. 2.) You will also continue to be registered for all future versions of RegKey. The best news of all is the low price of RegKey. This version of RegKey costs only $30 Canadian Dollars, $24 U.S. Dollars, or the equivalent in your country's currency. As was pointed out before, if you are using RegKey to encourage people to pay for your software, RegKey will quickly pay for itself! (This price will probably go up for future versions. By registering now, you will save by being able to use all future versions free of charge.) Many people also elect to receive the RegKey source code package. The source code for RegKey is available to registered owners for ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 5 only an additional $30 Canadian / $24 U.S. / equivalent. With the RegKey source code, you will be able to customize it for your own purposes, port it to other operating systems or programming languages, learn about how RegKey works, or increase the security of RegKey by adding your own anti-hacking mechanisms. For more information on ordering the RegKey source code, see page 13. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 6 HOW TO ORDER ----------------------------------------------------------------------------- To order your RegKey registration and/or source code package, simply fill out the order form located on page 15 of this manual, and mail it along with your cheque or money order to the address listed on the order form. The following section is intended to answer any questions that you may have about ordering RegKey. If you have any additional questions or uncertainties about your registration, please feel more than free to contact me. For information on how to contact me, please see page 69 of this manual. For more information on filling out the order form, see page 8. For more information on sending your order fee, see page 11. For more information on ordering the source code, see page 13. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 7 FILLING OUT THE REGISTRATION FORM ----------------------------------------------------------------------------- If you have printed the RegKey manual, you can simply remove and mail the forms on pages 15 and 16. If you have not already printed a copy of the manual, and you have a printer, you can quickly print these forms by printing the ORDER.FRM file included in the RegKey distribution archive. To do this, type COPY ORDER.FRM PRN from your DOS prompt. If you are working with Microsoft Windows, select the ORDER.FRM file and choose the File|Print command from within the Windows File Manager. If you do not have a printer, simply send a handwritten version of the order form. If you have any special instructions for me, or anything that you would like to say when you register, feel free to write this on the back of the registration form, or on a separate sheet of paper. When filling out the RegKey registration form, be sure to indicate how you would prefer to receive your RegKey registration key and/or source code. The following options are available: - Having me send the registration and/or source code by conventional mail - Internet E-Mail - FidoNet "CrashMail" - Having me call to your BBS - You calling the RegKey support BBS Once you have decided which means you would prefer to receive your order by, please read the detailed instructions on your order method, below. Also, if you are ordering the source code, please be sure to read the section on ordering the source code, which begins on page 13. ----------------------------------------------------------------------------- RECEIVING YOUR ORDER BY CONVENTIONAL MAIL To receive your RegKey registration key and/or source code by conventional mail, simply fill out the order form and mail it along with your payment as described below. If you are ordering the source code, it will be sent to you on a 3- 1/2 inch disk unless you specifically request a 5-1/4 inch disk. Because of their smaller size and greater durability, 3-1/2 inch disks are the preferred format for mailing. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 8 ----------------------------------------------------------------------------- RECEIVING YOUR ORDER BY A CALL TO YOUR BBS Since many programmers operate bulletin board systems to provide support for their software, you may elect to receive your RegKey registration and/or source code by a message and/or upload on your BBS. In order to do this, fill out the order form and mail it along with your payment as described below. Be sure to include the phone number, baud rate, and my login and password for the BBS to which you would like me to call. I will cover any long distance costs. If for some reason I am unable to connect to your BBS, I will send your order by conventional mail instead. ----------------------------------------------------------------------------- RECEIVING YOUR ORDER BY CALLING THE REGKEY BBS You may choose to receive your RegKey registration and/or source code by calling the RegKey BBS after your registration form and order fee have been received here. If you are unable to receive your order by any other electronic means (such as a call BBS to your BBS, or by electronic mail), this may be the quickest way for you to receive your registration information and/or source code. The obvious disadvantage with this option is that you will have to estimate when your order will arrive here in order to receive it as quickly as possible. You may end up calling the RegKey BBS more than once before your order has arrived. After your order form has arrived, your registration key and/or source code will be placed on hold for you, and you will be able to receive it on your first call to the BBS. The phone number of the BBS is: +1 613 526 4466 ----------------------------------------------------------------------------- RECEIVING YOUR ORDER BY INTERNET EMAIL If you wish to receive your RegKey registration key by Internet E- Mail (including Internet E-Mail to a CompuServe account), fill out the order form and mail it along with your payment as described below. Be sure to include your e-mail address on your order form. Note that the source code cannot be sent by Internet e-mail. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 9 ----------------------------------------------------------------------------- RECEIVING YOUR ORDER BY FIDONET CRASHMAIL To receive your RegKey registration key and/or source code by FidoNet CrashMail, simply fill out the order form and mail it along with your payment as described below. Be sure to include the FidoNet node address to which you wish to have your registration key and/or source code sent to (by CrashMail). Again I will cover any long distance costs. If, for some reason, I am unable to connect to your FidoNet system, I will send your order by conventional mail instead. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 10 SENDING YOUR ORDER FEE ----------------------------------------------------------------------------- The price of RegKey is 30 Canadian Dollars, 24 U.S. Dollars, or equivalent for the registration. The source code costs an additional 30 Canadian Dollars, 24 U.S. Dollars, or equivalent. For your convenience, the equivalent value in a number of other country's currencies (at the time of this writing) is listed below: ----------------------------------------------- REGISTRATION REGISTRATION ONLY AND SOURCE CODE ----------------------------------------------- 30 Canadian Dollars 40 Canadian Dollars 24 US Dollars 48 US Dollars 15 British Pounds 30 British Pounds 130 French Francs 260 French Francs 38 German Marks 76 German Marks 43 Netherlands Gilders 86 Netherlands Gilders 34 Australian Dollars 68 Australian Dollars ----------------------------------------------- This order fee may be paid using any of the following methods: - Cheque or Money Order in Canadian currency, drawn upon a Canadian bank. In this case, your order fee will be either $30CDN for just the registration, or $60CDN for both the registration and source code. - Cheque or Money Order in U.S. currency, drawn upon a U.S. bank. In this case, your order fee will be either $24US for just the registration, or $48US for both the registration and source code. - An International Money Order or International Bank Draft (available from your bank, post office or organization such as American Express), in Canadian currency. Depending on the particular case, your order fee MAY be sent to me by the postal service, and you will mail your order form by itself. You should have the money order drawn in either $30CDN for just the registration, or $60CDN for both the registration and source code. - A cheque drawn on any bank in the world, IN THAT COUNTRY'S CURRENCY, equivalent to $30 Canadian dollars for just the registration or $60 for both the registration and source code. For instance, a cheque for the appropriate number of British Pounds, drawn on a British bank, is perfectly acceptable. However, I am unable to accept a cheque for $30 Canadian dollars, drawn on a British Bank. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 11 - Cash. Cash orders are also accepted, but it is your responsibility to get that cash to me safely. Please note that it is not usually recommended that cash be sent in the mail, and that I cannot be responsible for any cash lost in the mail. I would like to mention that many people have already ordered RegKey by sending cash, and I have yet to run across any case of cash being lost in the mail. Nonetheless, if you wish to send cash, you may wish to consider doing so by registered mail, for your added security. If you are ordering RegKey from within Canada, you will most likely choose the first option (a Canadian cheque or money order). If you are ordering RegKey from within the United States, you will most likely choose the second option (an American cheque or money order). If you are ordering from outside Canada and the U.S., it would be ideal if you could send your fee by an international money order. However, any of the above order methods will be acceptable from any location. Also, it is quite possible that I may be able to accept other means of sending your order fee. If you are unsure about sending your order fee, please feel free to get in touch with me by any of the means listed on page 69. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 12 ORDERING THE SOURCE CODE ----------------------------------------------------------------------------- Many people who register RegKey also choose to order the source code package. With the RegKey source code, you will be able to customize it for your own purposes, port it to other operating systems or programming languages, learn about how RegKey works, or increase the security of RegKey by adding your own "anti-hacking" mechanisms. As mentioned before, the RegKey source code may be ordered for an additional $30 Canadian Dollars, $24 U.S. Dollars, or the equivalent in your country's currency. The source code may be ordered either at the same time you register RegKey, or separately. If you wish to order the RegKey source code, simply check the appropriate box on the order form, and include the additional fee for ordering the source code. When you order the RegKey source code, you will receive it either on a diskette, or electronically, depending upon how you chose to receive your order. (For more information on these options, see the section that begins on page 8.) Also, as with your RegKey registration, when you order the RegKey source code, you are entitled to receive all future versions of the source code. Whenever you wish to receive an updated version of the source code package, you can either download it from the RegKey support BBS, or send $3 dollars to cover the cost of postage and a diskette to my address. The RegKey source code package includes both the core source code of RegKey itself, and the source code for the DOS and Windows version of the KeyGen program. RegKey itself is written in ANSI- compliant C, and is designed to be easily ported to other platforms or operating systems. In addition to the C source code for RegKey, you will receive optimized 80x86 assembly language source code for some of the RegKey routines. Since the equivalent C source code is included for all assembly language routines, use of the assembly language source code is optional. However, the assembly language routines provide dramatically improved performance. The RegKey source code has been compiled with C compilers from both Microsoft and Borland. The source code package also includes a basic test program that exercises various components of the RegKey source code, and can help you in locating problems when porting RegKey to other platforms. The KeyGen source code is divided into three components - a core module common to both DOS and Windows version, a module containing the DOS-specific interface code, and a module containing the Windows-specific interface code. The source code for the common module is again written in ANSI-compliant C. The DOS-specific interface code is also written in ANSI-compliant C, but contains ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 13 many MS-DOS specific elements. The Windows-specific interface code is written in C++, and uses the "Microsoft Foundation Classes" interface to the Windows operating system. The Microsoft Foundation Classes library is included with recent C++ compilers from Microsoft and others. For information on what you are permitted to do with the RegKey source code, see the terms and conditions on page 17. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 14 ----------------------------------------------------------------------------- REGKEY 3.00 ORDER FORM ----------------------------------------------------------------------------- YOUR NAME : _______________________________ (AS SHOULD APPEAR IN REGISTRATION) POSTAL ADDRESS : ______________________________________________________ ______________________________________________________ VOICE PHONE NUMBER : ______________________ EMAIL ADDRESSES : ____________________________________ (IF APPLICABLE) I WISH TO RECEIVE MY ORDER BY: ___ ___ | | - CONVENTIONAL MAIL | | - FIDONET "CRASHMAIL" |___| |___| ___ ___ | | - CALL TO MY BBS | | - INTERNET E-MAIL |___| (INCLUDE NECESSARY INFO) |___| (REGISTRATION KEY ONLY) ___ | | - CALL TO REGKEY BBS |___| ___ I WOULD LIKE TO ORDER: | | - JUST MY REGISTRATION KEY |___| ($30 CDN, $24US, OR EQUIVALENT) ___ | | - JUST THE SOURCE CODE (ONLY IF ALREADY |___| REGISTERED) ($30 CDN, $24 US, OR EQUIVALENT) ___ | | - BOTH REGISTRATION KEY AND SOURCE CODE |___| ($60 CDN, $48 US, OR EQUIVALENT) I AGREE TO THE REGKEY TERMS, SET ____________________________ FORTH ON PAGE 17 OF THE MANUAL (SIGNATURE) MAKE CHEQUES PAYABLE TO: BRIAN PIRIE APT. 1416 - 2201 RIVERSIDE DR. OTTAWA, ONTARIO CANADA K1H 8K9 +-- OFFICIAL USE ONLY ------------------------------------------------------+ | | | Rcvd : _______ Date : _________ S.N. : _________ Key : _______________ | +---------------------------------------------------------------------------+ ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 15 ----------------------------------------------------------------------------- REGKEY 3.00 USER FEEDBACK FORM ----------------------------------------------------------------------------- YOUR NAME : _______________________________ POSTAL ADDRESS : ______________________________________________________ ______________________________________________________ VOICE PHONE NUMBER : ______________________ EMAIL ADDRESSES : ____________________________________ (IF APPLICABLE) HOW DID YOU FIRST LEARN OF REGKEY? ____________________________________________________________ WHICH LANGUAGE / COMPILER AND VERSION ARE YOU USING? (EG. BORLAND C++ 3.10) ____________________________________________________________ WHAT DO YOU LIKE MOST ABOUT REGKEY? ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ WHAT CHANGES OR ADDITIONS WOULD YOU LIKE TO SEE IN FUTURE VERSIONS? ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ DO YOU HAVE ANY ADDITIONAL COMMENTS? ____________________________________________________________ ____________________________________________________________ ----------------------------------------------------------------------------- ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 16 TERMS OF REGISTRATION AND SOURCE CODE USE ----------------------------------------------------------------------------- When you purchase a RegKey registration and/or source code package, you are entitled to almost unlimited use of all versions of RegKey. However, in order to protect my investment of time and effort in developing RegKey, you must also agree to the terms outlined below when purchasing a RegKey registration and/or the source code. These terms are very reasonable, and are in no way intended to cripple your use of RegKey. The primary intent of these terms is that you are not permitted to disclose your RegKey registration information, or the RegKey source code, to other individuals. The terms of registration and source code use are as follows: For the purpose of these terms, "RegKey" is defined to be the library files, header files, example programs and programmer's manual of all versions, present and future, for all languages and platforms, of the RegKey registration key system. Upon registering RegKey, the individual or organization named on the registration form (the registree) is entitled to use of all versions of RegKey, within the terms set forth below. Violation of these terms will be considered copyright infringement, and grounds for the termination of the registration agreement. The registree is entitled, at no additional cost, to use, distribute or sell the executable (.EXE, .COM, .DLL) files that result from using the RegKey toolkit. The registree is also entitled to use, distribute or sell the example programs or portions thereof. If purchasing the source code, the registree is also entitled to distribute any executable files that result from using altered versions of the source code, or portions thereof. The registree is NOT entitled to distribute the registration key number presented to them at registration, except when imbedded in the executable files of a program which uses RegKey. The registree is not permitted to distribute any portion of the RegKey source code. For the purposes of these terms, an organization is considered to be a company or non-profit organization. If the registree is an organization, the registration key and source code may be shared among members of the organization, under the condition that these individuals are using the registration and/or source code only for official activities of that organization. These terms in no way suggest an agreement on the part of Brian Pirie to develop any future versions of RegKey, or fix any problems in current versions of RegKey. RegKey is offered "as is", and no warrantees are expressed or implied. In no event shall Brian Pirie be liable for any loss of profit or any other damage, including but not limited to special, incidental, consequential or other damages. This means that it is solely the registree's responsibility to determine the suitability of RegKey for the registree's application(s). This also means that no guarantees are made concerning the portability or compatibility of the RegKey system. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 17 ----------------------------------------------------------------------------- PART 3: USING THE REGKEY SYSTEM ----------------------------------------------------------------------------- This portion of the manual contains information about RegKey that is common to all languages supported by RegKey. Part 4 of this manual, which begins on page 46, provides information specific to each programming language supported by RegKey. The following sections describe the basic principles of the RegKey system, provide step-by-step information on how to incorporate RegKey into your applications, and discuss some of the issues that you will want to consider when using RegKey. This information is divided into the following sections: A Quick Tour of RegKey......................................18 Introduction to Registration Keys...........................20 Principles of the RegKey System.............................23 File-Based vs. User-Entered Registration Keys...............25 Using the KeyGen program....................................27 Creating Generation/Validation Code Sets....................29 Generating Registration Keys................................31 Validating Registration Keys................................34 Methods for Adding Expiry Information.......................37 Security Issues.............................................40 A QUICK TOUR OF REGKEY ----------------------------------------------------------------------------- This section provides a quick overview of the RegKey package, and is intended for those who want to see RegKey in action before reading the detailed information in the following sections. This section does not attempt to explain the use of the RegKey package in detail, but simply guides you on a tour of some of the programs and files included in the RegKey package. If at any point you want to learn more about RegKey, or are having trouble understanding a particular concept, you can skip to the following sections of this manual for a more detailed tutorial. You may also find the glossary on page 73 and the troubleshooting guide on page 43 useful. Since RegKey supports a number of different programming languages (C, C++, Pascal and BASIC), in both the MS-DOS and MS-Windows environments, not all the files included in the RegKey package will be of use to you. Depending upon how you received your copy of RegKey, some of the RegKey files may be stored in archive files with the following names. If this is the case, you should extract ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 18 the contents of the file below that are relevant to the programming language you will be using. C_CPP.ZIP Contains C/C++ language specific files QB.ZIP Contains QuickBASIC specific files VB.ZIP Contains Visual Basic specific files TP.ZIP Contains Turbo Pascal specific files (A complete list and description of the files included in the RegKey package is located on page 71.) The RegKey package provides two distinct facilities for implementing registration keys within your applications. The first facility is used for generating registration keys, typically when a user purchases your software. This facility is generally used only by yourself or those responsible for selling your application. Registration keys can be generated using the KeyGen utility included in the RegKey package, or you may write a custom program to manage the generation of registration keys. The second facility provided by RegKey is incorporated into your program itself, and is used to check the validity of registration keys at run time. Although the details of this facility vary depending upon the programming language you are using, they always involve calling a RegKey function/procedure that performs the actual registration key validation. You are then able to adjust the behavior of your program depending upon the result returned by RegKey. This provides you with the option of displaying a special message when the user is not registered, disabling certain features when operating in unregistered "demo" mode, or limiting the length of time someone may use your software before paying for it. Included with RegKey is a very simple demonstration program, named DemoApp, which allows you to test RegKey and learn how to use RegKey within your own programs. The RegKey package includes both MS-DOS and MS-Windows executable versions of DemoApp - DEMOAPPD.EXE and DEMOAPPW.EXE. The RegKey package also includes the equivalent source code for DemoApp in the C, C++, Turbo Pascal, QuickBASIC and Visual Basic languages. To get a better idea of how RegKey's registration key validation facility can be incorporated into your program, have a look at the version of the DemoApp source code for the language you are most familiar with. Also, you should try running DemoApp to see how it behaves before you generate a registration key for it. As mentioned before, you can generate RegKey registration keys using the KeyGen utility. To start the DOS version of KeyGen, type the KEYGEND command at the DOS prompt, while located in the directory where you have placed the RegKey files. To start the Windows version of KeyGen, you can double-click on the KEYGENW.EXE file from within the Windows File Manager. If you are using the ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 19 Windows version of KeyGen, the included CTL3DV2.DLL file should be MOVED to your Windows system directory. (You may also wish to add KeyGen to a group within the Windows Program Manager. For instructions on how to do this, see page 27.) Once you have started the KeyGen program, you will see a list of applications for which you can generate a registration key. Initially, there should be a single application listed: "DemoApp (RegKey Example Program". To generate a registration key for DemoApp, simply select it from the list of applications, and choose the "Generate Key" option. A second dialog box will appear, with which you can provide information on the registration key to generate. Enter your name as the "Registration String", and enter any combination of 10 numbers and upper-case letters as the "Random Seed". "Registration String" is usually the name of the individual or organization that has purchased your software. The "Random Seed" is used by RegKey during the registration key generation process, and is then discarded. You should enter a different random seed for each key you generation. To generate a registration key for DemoApp, you do not need to change any other options in the key generation dialog box. When you select "OK", KeyGen will generate a registration key file for DemoApp, and will then ask you whether you wish to generate another registration key. RegKey supports both file-based and user-entered-string registration keys. With file-based registration keys, the registered user receives a small "key file" which is recognized and read by the application at run-time, in order to determine whether to operate in registered mode. With user-entered-string keys, the user enters their name and a 20 digit registration key into the application, which causes it to operate in registered mode. The DemoApp example program included with RegKey uses file-based registration keys. Now that you have generated a registration key file for RegKey, you can try running DemoApp again. Ensure that the newly generated key file, (named ????????.KEY, unless you changed the default option in the key generation dialog box), is located in the default directory before staring DemoApp. DemoApp will now operate in registered mode, and will display the registered user name you entered when generating the registration key. Congratulations! You have successfully completed your tour of RegKey. The following sections provide you with more detailed information on using RegKey, and part 4 provides information specific to using RegKey with each of the supported languages. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 20 INTRODUCTION TO REGISTRATION KEYS ----------------------------------------------------------------------------- This section provides an introduction to registration keys for those who are unfamiliar with the concept. If you are already familiar with the notion behind registration keys, you may wish to proceed to the following section, "Principles of the RegKey System", on page 23. Registration keys are a form of software protection; they are a mechanism to encourage users to pay for your software or even prevent them from using it without paying for it. Registration keys are often used as an only means of software protection, although they can easily be combined with other mechanisms for added security and effectiveness. Unlike other forms of software protection, such as software copy protection or hardware keys, registration keys are ideal for shareware or "try-before-you-buy" software. Using registration keys, you have the ability to distribute a single copy of your software that serves as both the demonstration version and "full" version. The idea behind registration keys is simple. When a customer pays for your software, they receive a registration key - either in the form of a small additional file or a numeric code - which switches the software into registered mode. The differences between registered and unregistered modes can be as insignificant or as great as you choose. The software may simply display a "please register" message when unregistered, it may only work for a short evaluation period prior to registering, additional features may be enabled after registering, or the software may refuse to operate entirely before registration. While the use of registration key systems is not limited to shareware applications, this is where registration keys are most often used. Many of the advantages of the shareware approach to software marketing are obvious - the user has the opportunity to try the software before buying it, the software producer is able to reach a wide audience of potential customers, and it is often a low-cost approach to software marketing. In general, there are two approaches to shareware marketing. In the first approach, a special demonstration version of the software is freely distributed to users, and when the user registers they receive the "full" registered version of the software. With the registration key approach, only one version of the software is released. This version normally operates in "unregistered" or "demo" mode. However, when the user pays for the software, they receive a registration key which immediately causes the software to switch into "registered" mode. Of these two approaches, the registration key approach has become very popular for a number of reasons: ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 21 - It has proven highly effec tive in encouraging people to pay for the software. - Since the registration key is associated with a single user's name, it discourages illegal sharing of the registration. People are more likely to give away a copy of a generic registered version of the software than they are to share the registration key that is associated with only their name. Although it is possible to "brand" each registered copy of the software for each user who registers, this often proves to be a great deal of work. - Registration keys enable the user to easily switch the software into registered mode upon registering, without having to reinstall a registered version of the software. - Registration keys also allow the option of upgrading to a new version by receiving a widely available copy of the software, rather than having to receive a new registered copy directly from the author. - If user-entered registration keys are used (see page 25 for a comparison between user-entered and file-based registration keys), the registration key can be quickly transmitted to the user by phone, email, fax or conventional mail, rather than sending a registered version of the entire software package. In addition to shareware applications, registration keys can be useful for many other software protection applications. For instance, registration keys can be used in implementing pay-per-use software, where a new registration key is sent to the user when they pay for additional use of the software. Registration keys can also be just as useful in discouraging the copying of non-shareware software as it is for encouraging registration of shareware software. Registration keys can also form the basis of multi-user site licensing systems. Although this manual cannot explicitly deal with all of the potential uses of the RegKey system, it does attempt to provide general information that will be of use regardless of how you are using RegKey. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 22 PRINCIPLES OF THE REGKEY SYSTEM ----------------------------------------------------------------------------- This section provides an introduction to the concepts and terminology used by RegKey. The remainder of this manual assumes that you have read this section. A registration string and corresponding registration key is associated with each person who pays to register your software. The registration string uniquely identifies the individual or organization that has registered, and may contain other information that should not be tampered with. In many cases, the registration string will only be the user's name, but it may also include information such as the registration's expiry date or the version of your software that was registered. (For more help on how to add expiry information to registration keys, see the section that begins on page 37.) In general, the registration string contains information that the user knows before registering, for which your application must be able to recognize your "stamp of approval". One of the key features of RegKey is the fact that every application using RegKey requires different registration keys; a particular user's registration key that is accepted by one application using RegKey will not work with a different application using RegKey. For each application or version for which you wish to require different registration keys, a unique generation / validation code set is created. Choosing a different generation / validation code set results in different registration keys being generated and accepted for the same registration string. The secret generation code is used to generate registration keys for your applications. The generation code is only known by yourself or people responsible for generating registration keys for your application; the generation code would never appear in your program's executable file(s). Every generation code has a corresponding validation code. This validation code is used during your application's execution in order to determine whether the supplied registration string (such as the user's name) corresponds to the supplied registration key. If the registration key is valid for the registration string and validation code, RegKey indicates to your application that it should operate in registered mode. The validation code is contained within your program's executable files. Although it may be possible to determine this validation code by "hacking" your program's executable files, there is no known feasible way to calculate the generation code knowing this validation code. Therefore, knowing the validation code does not permit someone to generate counterfeit registration keys for your software. The registration string and registration key may either be entered directly into your application by the user, or may both be stored ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 23 in a registration key file. The first approach is referred to as user-entered registration keys, and the second approach is referred to as file-based registration keys. The following section of this manual discusses the advantages and disadvantages of each approach. Subsequent sections of this manual discuss how to use the facilities provided by RegKey to create a generation/validation code set for a new application, how to generate a registration key for a user when they pay for your software, and how to use RegKey to deal with registration keys within your application itself. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 24 FILE-BASED VS. USER-ENTERED REGISTRATION KEYS ----------------------------------------------------------------------------- RegKey provides support for two types of registration keys: "user- entered" and "file-based". For a given application, you must choose which of these two types you wish to use. With user-entered registration keys, upon registering the user receives a 20 digit code of numbers and letters, such as: F8T5CQ7LFVXDY6TSC4QU To avoid confusion when copying the registration key, RegKey does not use the letters G, I, O, S, as they may be confused with the numerals 6, 1, 0 and 5. If the user accidentally enters any of these letters in place of the corresponding number, RegKey knows that the number was intended, as treats the letter as being equivalent to the number. Likewise, RegKey only uses upper-case letters when generating registration keys, but is not sensitive to case when validating registration keys. When they pay for your software, the user would typically be required to enter this 20-digit code along with their name (the registration string) into your application or configuration program, for example: Your Name : Brian Pirie Your Registration Key : F8T5CQ7LFVXDY6TSC4QU This information would then be stored by your program in a data file, for access when the program is subsequently executed. Using RegKey, your application could then determine whether or not a valid registration key for the user's name has been presented, and act accordingly. When file-based registration keys are used, rather than receiving a 20 digit code, the user receives a file in electronic form, which they either manually copy to the application's working directory, or install using a simple installation program that you provide. When your application executes, it would then call upon RegKey to read this file and determine whether or not a valid registration key file is present. If RegKey indicates that this file is present and valid, your program would know to operate in registered mode. User-entered and file-base registration keys each provide different advantages and disadvantages. User-entered registration keys have the advantage that no disk or electronic file needs to be sent to the registered user. This allows you full flexibility to send the registration key by conventional mail, electronic mail, facsimile or over the telephone. The RegKey registration key format is specifically designed to be easy to transmit by this means. It's ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 25 use of both letters and numbers makes it a very compact and efficient representation for the 96-bits of information it contains, while its choice of numbers and upper case letters helps to reduce the possibility of mis-copying the string. File-based registration keys, on the other hand, may be easier for the user. Rather than having to enter the registration key and related information manually, the user simply needs to install an additional small file. File-based registration keys may also be preferable if the registration string contains more information than simply the user's name. This might be the case when you are imbedding expiry information in the registration string as described in the section which begins on page 37. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 26 USING THE KEYGEN PROGRAM ----------------------------------------------------------------------------- The RegKey package includes both DOS and Windows versions of a program called "KeyGen". KeyGen can be used for both creating a generation/validation code set for a new application and for quickly generating registration keys for one or more of your applications. KeyGen also provides password security facilities to control access to the registration key generation information that it stores. This section provides some basic information on how to setup, maintain and navigate through the KeyGen program. Later sections of this manual provide information on how to accomplish specific tasks using KeyGen, such as creating a new code set or generating a registration key for a new user. To start the DOS version of KeyGen, simply go to the RegKey directory and type KEYGEND from the DOS prompt. The Windows version of KeyGen requires Microsoft Windows version 3.1 or later. Before using the Windows version of KeyGen, you must MOVE the CTL3DV2.DLL file to your Windows system directory. To start the Windows version of KeyGen, you may simply double-click on the KEYGENW.EXE file, from within in the Windows File Manager. KEYGENW.EXE will be located in the same directory where you have placed your other RegKey files. Rather than starting up KeyGen from the Windows file manager, you may prefer to add KeyGen to one of your Windows program manager groups. To do this, select the existing group to which you wish to add KeyGen, or create a new program manager group. Now choose FILE|NEW|PROGRAM ITEM. In the "Properties" dialog box, enter "KeyGen" as the description, enter the full path to the KEYGENW.EXE file as the command line, and enter the directory where KEYGENW.EXE is located as the working directory. Now choose "OK" to add KeyGen to the current program manager group. You will now be able to start KeyGen by double-clicking on the KeyGen icon. The KeyGen icon appears as a diskette with a golden key in front of it. (This information applies to using KeyGen with MS-Windows versions 3.x. If you are using MS-Windows version 4.0 or later, refer to your Windows manual for information on executing a Windows application given the filename). If you are using an operating system other and MS-DOS or MS-Windows which has the ability to execute DOS or Windows programs (such as OS/2), see your operating system manual(s) for information on how to do this. The filename of the DOS version of KeyGen is KEYGEND.EXE, and the filename of the Windows version of KeyGen is KEYGENW.EXE. The DOS and Windows versions of KeyGen operate very similarly to one another. Both can be used with either keyboard or mouse (or ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 27 similar pointing device such as a trackball or pen), and both provide an identical layout of Windows and dialog boxes. When using a pointing device to navigate through KeyGen, simply point to the item you wish to change or activate, and press the pointing device button. When using a keyboard to navigate through KeyGen, use the [Tab] key to move among items, and press [Enter] or [Spacebar] to activate items. The DOS and Windows version of KeyGen also share the same data file, KEYGEN.DAT. If you are relying on KeyGen to store the generation/validation code sets for your applications, this file is very sensitive. Be careful to control access to this file. You should also be absolutely certain that you maintain backups of this file in the case of hardware failure, fire, accidental erasure, etc. The main KeyGen window displays a list of applications for which it can generate registration keys. When you first install the RegKey package, only one application will be listed - the RegKey test program. When you write your own application that uses RegKey, you can add that program to the list by choosing the "Add Application" option (see page 29). To generate a registration key for one of the applications on the list, simply select the application and choose the "Generate Key" option (see page 31). To obtain or alter information concerning an application, such as the type of registration key generated or the generation/validation code set, select the application and choose the "Application Info" option. To remove an unwanted application from the list, select the application and choose the "Delete Application" option. When you are finished with KeyGen, choose the "Close" option. Only one copy of KeyGen should be running at any time. KeyGen also provides you with the option of password protecting applications. You can enter a password for an application when you add it using the "Add Application" option, or you can add/alter/remove a password using the "Application Info" option. When a password has been entered for an application, that password will be required to generate a registration key for the application or to access or alter the information pertaining to that application. Once again, be sure to maintain a backup copy of your KEYGEN.DAT file. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 28 CREATING GENERATION/VALIDATION CODE SETS ----------------------------------------------------------------------------- As is introduced in "Principles of the RegKey System" on page 23, for each application that uses RegKey you must create a generation/validation code set. It is the uniqueness of this code set that make the registration keys for one of your applications different from those for any other program using RegKey. The secret generation code is required to generate registration keys for a specific application. The validation code is used when checking the validity of the registration key at application run time. The RegKey API provides a function / procedure named RegKeyNewCodeSet(), that can be used to create a generation/validation code set for a new application. However, the quickest and easiest way to create a new code set is to use the KeyGen program included in your RegKey package. KeyGen also stores the new code set in its data file for your future reference. If you would prefer to write your own program that generates a code set using the RegKeyNewCodeSet() function/procedure, see the information on calling RegKeyNewCodeSet() in the section of part 4 that deals with the programming language you are using. The RegKey generation and validation codes are both represented as ten digit strings of numbers and upper-case letters. Although it is mathematically possible for the validation code to be calculated from the generation code, the reverse is not true; there is no easy way to calculate the generation code given the validation code. Therefore, the process of creating a new code set involves RegKey calculating a validation code from a generation code that you provide. To create a code set for a new application (or version), start the KeyGen utility as described on page 27. Select "New Application" to create a new code set, in order to bring up the "New Application" dialog box. Enter the name of the application for which you will be generating a new code set. This name is not used as part of the code set generation process; it is simply used by KeyGen to distinguish between code sets if you generate more than one. Next, enter the 10 character generation code for which a corresponding validation code will be calculated. These two codes will form the new code set. The generation code you enter should consist of numbers and upper case letters, and should be different for each of your applications. KeyGen gives you the option of protecting the new code set with a password. This password can prevent other people who have access to your computer or data files from unauthorized access to the new generation/validation code set. KeyGen will also require this password to be entered before a new registration key can be ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 29 generated for your application. If you choose to enter a password, note that it will not appear when typed. Be very careful to note the spelling and capitalization of the password you choose; the password will have to be entered identically in the future. The best passwords are between six and twelve characters in length. Remember that the password you enter has no effect on the actual validation code that is generated - it only controls access to that information when stored within KeyGen. The "New Application" dialog box also allows you to indicate whether your application will be using user-entered or file-based registration keys. Again, this information does not affect the actual generation/validation codes. This setting only controls the type of registration key that KeyGen will create, if you choose to use KeyGen to generate registration keys for your application (see "Generating Registration Keys" on page 31). For information on the benefits of file-based vs. user-entered registration keys, see "File-Base vs. User-Entered Registration Keys" on page 25. Once you have entered the relevant information into the "New Application" dialog box, choose "OK" to calculate the validation code that corresponds to the generation code you entered. The generation and validation codes will now be stored in the KeyGen data file, KEYGEN.DAT. To view the generation and validation codes for a particular application, select that application in the main KeyGen window, and choose the "Application Info" option. If you have password protected the selected application, KeyGen will prompt for the application's password before displaying any information about the selected application. When you create a generation/validation code set for a new application, you should always write these codes down in a safe location. Otherwise, if the KeyGen data file is lost or damaged, you could loose the ability to generate registration keys for your own software! ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 30 GENERATING REGISTRATION KEYS ----------------------------------------------------------------------------- You will typically generate a registration key once for each user, when they pay for your software. Registration keys may either be generated using the KeyGen program included in your RegKey package, or they may be generated using your own utility which in turn calls upon RegKey to perform the actual registration key generation. You will most likely choose to generate registration keys using the KeyGen program. However, if you wish to integrate the registration key generation process with another program (such as an on-line registration system or an order entry system), you may perform key generation by calling a RegKey API function/procedure. For general information on using the KeyGen program, see the section which begins on page 27. For information on calling RegKey API functions/procedures from your programming language, see part four of this manual, which begins on page 46. If you are generating a registration key using the KeyGen program, first start up KeyGen as described in the section which begins on page 27. Next select the application for which you wish to generate a registration key, and choose the "Generate Key" option. The key generation dialog box will now appear on your screen. This dialog box is used to provide information about the registration key to be generated. (If you have not yet added information about your application to the KeyGen program, it will not appear on the list of available applications. In this case, see "Creating Generation/Validation Code Sets" on page 29.) When generating a registration key, you MUST SUPPLY at least the following two pieces of information: A. The registration string, which is usually the user's name B. A ten digit alphanumeric random seed Depending upon your circumstances, the following information MAY ALSO BE REQUIRED: C. If you are using KeyGen to generate the registration key for a password protected application, this password must be entered to generate a registration key. D. If you are writing your own key generation utility, that utility must specify the generation code for your application. (If you are using KeyGen , it automatically provides this information for the application you selected.) E. When generating a file-base registration key, you may specify the filename to be used for the new registration key. To elaborate: ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 31 A. The registration s tring is usually the user's name, but may also contain other information, such as registration key expiry data. For more information on the registration string, see "Principles of the RegKey System" on page 23. B. In order to generate a registration key, RegKey requires a ten character alphanumeric string which it uses as a simple random number seed. If this string includes more than ten character, the additional characters are ignored. A different random seed should be chosen for each registration key that is generated. C. If you are using KeyGen to generate the registration key, and you have entered a password for the selected application, this password must be entered. The password portion of the key generation dialog box is enabled if and only if a password is required for this application. Note that the password will not appear on the screen when it is typed. If an incorrect password is entered, KeyGen will refuse to generate the registration key. D. If you are writing your own key generation utility, that utility must specify the generation code for your application. The ten digit generation code is passed as a string to the registration key generation function. For information on creating a generation code, see "Creating Generation/Validation Code Sets" on page 29. (If you are using KeyGen to generate the registration key, it automatically provides the generation code for the application you selected.) E. If you are generating a file-based registration key, you may optionally specify the registration key filename to be used. If you do not specify a filename, RegKey will default to using the first eight alphabetical characters in the registration string, with a .KEY extension. For instance, the default filename for the registration string "Brian Pirie" would be "BRIANPIR.KEY". Likewise, for the registration string "1-2-3 Clocks", the default filename would be "CLOCKS.KEY". If the registration string does not contain any alphabetical characters, the default filename is "REGISTER.KEY". If you explicitly specify a registration key filename, that filename may optionally include a path to the directory where the registration key file should be created. If no path/filename is specified, the current directory is used by default. CAVEAT: If a registration key file already exists with the specified filename, it will be overwritten by the new one. If you are using KeyGen to generate the registration key, choosing "OK" will cause a registration key to be generated, based upon the information entered. If the "OK" button of the key generation dialog box is not enabled, be sure that you have specified a ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 32 registration string, a valid 10-digit random seed, and a password if required. When generating user-entered registration keys, the generated registration key will be displayed in a separate dialog box. You will now have the option of either generating another registration key for the current application, or returning to the main KeyGen window. When generating a file-based registration key, the registration key file will be created and another dialog box will appear indicating whether or not you wish to generate additional registration keys for the current application. If you are generating registration keys from within your own program, key generation is performed by one of the following two functions/procedures: RegKeyGenerate() RegKeyFileGenerate() The first function/procedure is used to generate user-entered registration keys, and the second is used to generate file-base registration keys. The registration string, generation code, random seed and other information required for key generation is passed directly to one of these functions/procedures. In the case of RegKeyGenerate(), the 20 character registration key is returned to your program. In the case of RegKeyFileGenerate(), the new registration key file is created. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 33 VALIDATING REGISTRATION KEYS WITHIN YOUR PROGRAM ----------------------------------------------------------------------------- In order to provide registration key validation capabilities, a portion of RegKey is linked into the executable (.EXE, .COM, .DLL, etc.) file of your application. The actual process for linking RegKey with your program varies depending upon the programming language you are using. For more information on doing this with a particular language, consult Part Four of this manual (which begins on page 46) and/or your language's manual(s). To cause the registration key validation to be performed, you call one of two RegKey functions/procedures, depending upon whether you are using user-entered or file-based registration keys. These functions/procedures are as follows: RegKeyValidate() - For user-entered registration keys RegKeyFileValidate() - For file-based registration keys The registration key validation code for your application is passed to either RegKeyValidate() or RegKeyFileValidate() as a ten character alphanumeric string. If RegKeyValidate() is being used, the registration string and registration key are also passed to the function. In the case that RegKeyFileValidate() is being used, the registration key filename and string where the registration string should be stored are passed to the function/procedure. In addition, a variable is passed to RegKeyValidate()/ RegKeyFileValidate() which will be set to indicate whether your program should operate in registered or unregistered mode. Based on how RegKey sets this variable, you can adjust the behavior of your program as you wish. Both of these functions return a value indicating whether or not they executed successfully. The RegKeyValidate() function requires the following parameters, in order: sRegString The registration string to be validated. This sting can consist of up to either 65,535 characters, or the maximum size of strings in your programming language, whichever is less. sRegKey A twenty character string containing the registration key to be validated against the registration string. sValidationCode A ten character string containing your applications validation code. sYourName A string containing your name, if you have registered RegKey. Otherwise, this should be an empty string. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 34 nYourKey A long integer containing your RegKey registration key if you have registered RegKey. Otherwise peRegistered The variable where the result of registration key validation should be stored. Indicates whether the program should operate in registered or unregistered mode. See section four of this manual for the possible values of peRegistered in your programming language. Hence, a typical call to the RegKeyValidate() function might appear as follows (in no particular programming language): result = RegKeyValidate( theRegistrationString, theRegistrationKey, myValidationCode, "A RegKey Programmer", 0, isRegistered) The RegKeyFileValidate() function requires the following parameters, in order: sFileName The filename or file specification of the registration key file. If this string is empty, *.KEY is used. You will likely want to specify the path to your application's main directory, where the registration key file would usually be installed by the user. For instance, sFileName might be "C:\MYAPP\*.KEY". sValidationCode A ten character string containing your applications validation code. sYourName A string containing your name, if you have registered RegKey. Otherwise, this should be an empty string. nYourKey A long integer containing your RegKey registration key if you have registered RegKey. Otherwise sRegString A string where the registration str ing (e.g. user's name) retrieved from the registration key file will be stored. If no valid registration key file was located, RegKey will return an empty string in this variable. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 35 cbMaxStringSize The maximum size of the registration string, expressed in the string size conventions used by the host programming language. In C or C++ programs, this should contain the number of bytes allocated for the string and the string termination character. In Pascal, this should be the number of characters specified when the string was declared, or 255 if no size was specified. In BASIC, this specifies the maximum number of characters that RegKey should retrieve for the registration string. For variable-length strings in QuickBASIC, this can be any value between 1 and 255. For variable-length strings in Visual Basic, this can be any value between 1 and 30,000. peRegistered The variable where the result of registration key validation should be stored. Indicates whether the program should operate in registered or unregistered mode. See section four of this manual for the possible values of peRegistered in your programming language. Hence, a typical call to the RegKeyFileValidate() function might appear as follows (in no particular programming language): result = RegKeyFileValidate( "*.KEY", myValidationCode, "A RegKey Programmer", 0, registrationString, 50, isRegistered) Typically, you will store the value returned in the peRegistered parameter in one or more global variables, that will be accessible at any time your program needs to know whether it is operating in registered or unregistered mode. There are no limitations on how you adjust your program's behavior between registered and unregistered modes. For an example of how to perform registration key validation within your programming language, see the source code for the DemoApp example program. The RegKey package includes equivalent source code of DemoApp in the C, C++, Turbo Pascal, QuickBASIC and Visual Basic languages. For more information on calling the RegKeyValidate() or RegKeyFileValidate() functions, see the section of part four of this manual that deals with the programming language you are using. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 36 METHODS FOR ADDING EXPIRY INFORMATION ----------------------------------------------------------------------------- Often, you will want to provide users of your software with a single registration key that will work with all versions of your application. This is exactly what you achieve by simply generating registration keys with the user's name as the registration string, and using the same generation/ validation code set for all versions of your application. However, in some cases you may only want registration keys to function with particular versions of your application. Alternatively, you may wish to limit the length of time for which the registration key will continue to function. In each of these cases, you are adding some form of expiry information to your registration keys. There are two basic methods for adding expiry information to RegKey registration keys: 1. Using different generation/validation code set s for different versions of your application. 2. Including expiry information in the registration string. The first method, where you are using different code sets for different versions of your application, is only applicable when you wish to generate registration keys that only work with certain versions of your application. If you wish to include any other form of expiry information in your registration keys, you must use the second method, where this information is imbedded in the registration string. Below, both of these methods are described in detail: 1. If you wish different registration keys to be required for different versions of your applications, the easiest approach is to use different generation/validation code sets for versions that you wish to require different registration keys. For instance, if you wish to require the user to pay to upgrade from one major version of your application to the next, you could use one code set for the 1.x version(s), a second code set for the 2.x version(s), and so on. If you are using KeyGen to generate registration keys, you would then end up with both "MyApp 1.x" and "MyApp 2.x" in the list of available applications. When either a new user purchases version 2.x of your application, or a current user pays to upgrade to version 2.x, you would generate a new registration key using the code set for version 2.x. If you only wish to add simple by-version expiry information to your registration keys, this is probably the preferable method, as it does not require the expiry information to be included in the registration string. This is particularly relevant when ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 37 using user-entered registration keys, as the user does not have to enter the expiry method in addition to their name and registration key. 2. The second, more flexible option for adding expiry information to your registration keys is to imbed this information in the registration string. In this case, the registration string does not only contain the user's name, but also includes information such as the version or version(s) registered or the expiry date of the registration key. Since the registration key generated for the registration string proves its validity, the user cannot change the information included in the registration string without invalidating the registration key. When you use this approach, it is important that you choose a strict format for the registration key. For instance, if you wish to include the user's name and the date of expiry in the registration string, you might decide to format the string with four digits for the year, followed by a dash (`-') followed by two digits for the month, and so on. You might also decide that a comma and a space will separate the date and user's name. In this case, the registration string might appear as follows: 1997-11-28, Brian Pirie While the method of using different code sets can be used equally well with file-based and user-entered registration keys, imbedding expiry information in the registration string is better suited to file-based registration keys. While this method can also be used with user-entered registration keys, it does require the user to manually enter any expiry information. If you do choose to use user-entered registration keys with this method, you may wish to provide some mechanism to ensure that the registration string is correctly entered into your application. One approach would be to break the registration string into a number of fields, requiring the user to enter the value for each field. You would then construct the registration string at application run-time, and use RegKey to check the validity of the registration key against this string. As an example, your program might have a registration dialog box with the following fields: Your Full Name : Brian Pirie Year of Registration Expiry : 1997 Month of Registration Expiry : November Day of Registration Expiry : 28 Registration Key : KT4BP0TRX6AQ2MJK8KFU From this information, you could generate an appropriately formatted registration string, such as: 1997-11-28, Brian Pirie ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 38 If, on the other hand, you use file-based registration keys, this difficulty is avoided, as the registration string with any expiry information is stored in the registration key file. Imbedding expiry information in the registration string enables many variations on the use of RegKey. Possibilities include: - Selling registration keys that work with the current and next version of your software. - Giving the user the option of either purchasing a "life-time" registration for all versions of your application, or purchasing a cheaper registration for only the current version. - Implementing a pay-by-use system where the user receives a new registration key when they pay for more time. In such a system, a registration key could expire after a certain date or after a certain number of uses. - Providing multiple levels of functionality depending upon the level of the user's registration. - Creating special "beta-user" registration keys that work for both beta-test and final release versions, while "normal" registration keys work only for final release versions. - Implementing an on-line "trial" registration system that allows the user to obtain trail-period registration keys without purchasing a full registration. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 39 SECURITY ISSUES ----------------------------------------------------------------------------- When using RegKey in any program, it is your responsibility to decide whether employing RegKey alone provides enough security for your needs. While using RegKey alone does provide enough security for the vast majority of applications, there may be times when you wish to augment or combine RegKey with other software protection mechanisms. This section provides a brief discussion of some of the issues you may wish to consider when using RegKey, and attempts to answer the question "how secure is RegKey?" When evaluating any software protection scheme, such as registration key mechanisms, it is important to keep in mind that no such mechanism is 100% secure. If your program can be executed, it can be reverse-engineered and altered. Fortunately, the fact that it is possible to beat a software protection scheme does not necessarily render that scheme as ineffective. In general, it is sufficient for a software protection mechanism to be difficult enough to beat that most users will be more likely to pay for your software than attempt to "beat the system". Yet as was said before, it is up to you to decide how much security you require for your software. In general, there are three basic ways in which someone might try to bypass the software protection of a program that uses RegKey. 1. By always using the program in unregistered mode 2. By producing a "counterfeit" registration key for your program 3. By "hacking" or somehow modifying your software in order that it operates in registered mode without a valid registration key being present. Each of these possibilities are discussed below: 1. By far the most common way that users bypass registration key systems is by always using the program in unregistered mode without paying for it. The likelihood of users doing this with your software depends largely upon the type of application and the incentives you offer for registering. In some cases, the majority of people using a software package that uses registration keys will be using it without registering. In other cases, almost everyone using the software will have paid to register it. There are a number of things that you can do to encourage users to pay for your software rather than using it in unregistered mode: - If the output of your software will be seen by many people in addition to the user who is responsible for registering ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 40 it (such as communications software, on-line bulletin board software, programming library or other program that produces unalterable output), then displaying or outputting an "unregistered" message can be sufficient to encourage users to pay for your software. In this case, the unregistered message has the potential to advertise to many people that it is an evaluation copy and must be paid for. - A common and effective incentive to encourage users to register software is the enabling of additional capabilities when operating in registered mode. These additional capabilities could be the additional helpful features for an application, additional "levels" of a video game, or the removal of demonstration-version limitations such as a maximum data file size. If you are taking this approach, be careful not to cripple your software's capabilities in unregistered mode too severely. If the user becomes frustrated with your software, it is unlikely that they will want to pay for it. Likewise, you will want to be sure that the user has an opportunity to examine all of your software's important capabilities. - Another common incentive is to offer additional services to registered users, such as printed documentation, product support, free upgrade to new versions, source code, etc. - Another possible approach is to have your software only work for a certain period of time without registering. To make it more difficult for users to bypass this scheme by reinstalling the software, you might want to store information about the date and time of the first installation in your program's data file (if applicable). - An alternative to causing the software itself to expire is to require the user to obtain a temporary "evaluation" key from you to even operate in unregistered mode. This key could expire after any length of time you choose. For more information on adding expiry information to registration keys, see the section that begins on page 37. 2. A second way a user might try to bypass a RegKey protected application is by producing a "counterfeit" registration key for your software. However, RegKey is designed to make it extremely difficult to do this. There are two conceivable ways someone might try to generate a counterfeit RegKey registration key: A by an exhaustive search of all possible registration keys B by determining your application's generation code and using RegKey's KeyGen program to produce a registration key. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 41 An exhaustive search would not be feasible, even with the world's fastest supercomputer. There are nearly 2^96 possible RegKey registration keys, of which nearly 2^48 are valid for a given registration string. This means that on average, 2^47 (1 followed by 14 zeros) registration keys must be tried before a valid registration key is found. To put this into context, a fully optimized version of the RegKeyValidate () function would require over more than 1 millisecond to determine the validity of a RegKey registration key on a 66-Mhz Pentium based machine. Even being able to test 1000 registration keys per second, such a machine would require over 4,400 years to guess a RegKey registration key on average. Determining the generation code for your application by guessing would be just as difficult as guessing a correct registration key. Also, although a RegKey validation code can be quickly calculated from the generation code, the reverse is not the case. There is no known mathematical method that would allow you to quickly determine the generation code given the validation code. As a result, even if the user was able to obtain the validation code from your application's executable file(s), they would be no closer to knowing the generation code. 3. A third way someone might try to defeat a program using RegKey is by someone modifying the program to cause it to always operate in registered mode. The vast majority of users would not have the ability to do this. However, there is always the fear that someone with the ability to do so may "hack" your program and even distribute an altered version to other users. While it is very seldom that this scenario causes major problems in reality, you may still wish to take steps to further protect your program from "hacking". In any program using RegKey, the weakest link is generally at the point where the program passes control to the RegKey routines. As a result you may want to somehow encrypt (see glossary) or check the validity of this code at run time. A full discussion of such techniques is beyond the scope of this manual. If you wish to add further robustness to the RegKey code itself, you may wish to obtain the source code package (see page 13) to make such modifications. If you are using RegKey with Visual Basic , you should consider checking the validity of the RegKey DLL at run time. For instance, your program could locate the RK30VB.DLL file and calculate a checksum, CRC-32 or other hash value for the file. That value could then be compared with an expected value to determine whether the DLL has been altered. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 42 TROUBLESHOOTING GUIDE ----------------------------------------------------------------------------- This section provides a guide to solving common problems when using the RegKey system. If the suggestions in this section do not help in solving your problem, please feel more than free to get in touch with me. For information on how to reach me, see page 69. PROBLEM KeyGenW complains that CTL3DV2.DLL is not installed POSSIBLE SOLUTION The CTL3DV2.DLL file, included in your RegKey package, must be placed in the Windows system directory (typically C:\WINDOWS\SYSTEM). Ensure that this file DOES NOT also reside in the current default directory, or the directory where KEYGENW.EXE is located. PROBLEM KeyGenW does not list applications that have been previously added POSSIBLE SOLUTION Ensure that the current default directory is the same as it was when KeyGenW was originally run, in order that the same KEYGEN.DAT file can be located. PROBLEM Program using RegKey does not recognize a valid registration key POSSIBLE SOLUTIONS Check that the program is using the validation code that corresponds to the generation code used to create the registration key. Also check that the peRegistered parameter passed to the RegKeyValidate() or RegKeyFileValidate() function is being correctly tested in your program. If file-based registration keys are being used, ensure that the registration key file is placed in the current default directory (depending upon your circumstances, this may be the directory from which you started Windows, the directory from which you started the application or your programming language, or the directory where the application's .EXE file is located. If you are unsure as to what the current default directory is, explicitly pass the location of the registration key file to RegKeyFileValidate(). (i.e., "C:\MYAPP\*.KEY"). Also ensure that only one file with a .KEY extension exists in this directory. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 43 PROBLEM C or C++ program using RegKey will not compile POSSIBLE SOLUTIONS If you receive unexplained errors during the compile phase, ensure that the REGKEY.H file is "#include"ed in your program's source file, and ensure that the correct format for calling the RegKey functions is being used. If you receive unexplained errors during the linking phase, ensure that you are linking with the appropriate RegKey library file for the target environment (DOS or Windows) and memory model that you are using. If you are experiencing problems linking in small, compact or medium memory models, and suspect that the code or data segments may be exceeding 64K in size, try using the large memory model. PROBLEM QuickBASIC program using RegKey will not execute POSSIBLE SOLUTIONS Ensure that the RegKey Quick Library, REGKEYQB.QLB is located in the current directory and that QuickBASIC has loaded this file (specify /LREGKEYQB.QLB on the QB command line). Also ensure that the REGKEY.BI file is included using the $INCLUDE metacommand. Check that you are using the correct syntax for calling the RegKey functions. PROBLEM QuickBASIC program using RegKey will not compile to .EXE file POSSIBLE SOLUTIONS Ensure that the RegKey stand-alone library, REGKEYQB.LIB is located in the correct directory and that QuickBASIC is configured to link your program with this library (specify /LREGKEYQB.QLB on the QB command line). PROBLEM Turbo Pascal program using RegKey will not compile or execute POSSIBLE SOLUTIONS Ensure that you have built the .TPU unit for the version of Turbo Pascal you are using, and named this file RegKeyD.TPU for DOS or RegKeyW.TPU for Windows. Also ensure that your program refers to the RegKeyD / RegKeyW unit in the uses statement. Check that you are using the correct format for calling a RegKey function. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 44 PROBLEM Visual Basic program using RegKey will not run POSSIBLE SOLUTIONS Ensure that the RK30VB.DLL file is installed in the Windows system directory. Also ensure that the REGKEYVB.BAS module is included in the Visual Basic project window for your program. Also check that you are using the correct format for calling the RegKey functions. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 45 ----------------------------------------------------------------------------- PART 4: LANGUAGE-SPECIFIC INFORMATION ----------------------------------------------------------------------------- This portion of the RegKey manual describes how to use the RegKey system with various programming languages, and is divided into the following sections: Using RegKey with C or C++..................................46 Using RegKey with QuickBASIC................................54 Using RegKey with Visual Basic..............................60 Using RegKey with Turbo Pascal..............................61 Using RegKey with Other Languages or Operating Systems......68 Since these sections build on the language-neutral information presented in Part 3 of this manual, you should read Part 3 and have an understanding of the principles of the RegKey system before proceeding to these sections. (Part 3 begins on page 18.) USING THE REGKEY SYSTEM WITH C OR C++ ----------------------------------------------------------------------------- This section describes how to use the RegKey system in programs written with C or C++. Specific information is provided for using RegKey with C and C++ compilers from Microsoft and Borland, including Borland Turbo C, Borland Turbo C++, Borland C++, Microsoft C, Microsoft Quick C, Microsoft C/C++ and Microsoft Visual C++. General information is also provided for using RegKey with other C or C++ compilers. The information provided here is pertinent to DOS, Windows and other operating systems. If you are using a language or compiler that is not specifically discussed in this manual, the information in this section may also be of use to you. The manuals included with many programming languages provide information on how to call C language functions. In these cases, you will need to know the specifics of the C language function prototypes which are described in this section. In order to call the RegKey functions from a C or C++ program, you must: 1. Include the RegKey header file at the beginning of your program's source code file(s), using the #include statement: #include "regkey.h" ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 46 Ensuring that the REGKEY.H file is located in the same directory as your program's source code. Alternatively, you could place the REGKEY.H file in the same directory as your compiler's standard header files. In this case, most C compilers will require you to use angled brackets instead of double quotes in the #include statement, as follows: #include <regkey.h> 2. Link with the appropriate RegKey library file for the platform (DOS or Windows) and memory model you are using. The included library files are as follows: REGKEYSD.LIB DOS, tiny and small memory models REGKEYCD.LIB DOS, compact memory model REGKEYMD.LIB DOS, medium memory model REGKEYLD.LIB DOS, large and huge memory models REGKEYSD.LIB Windows, small memory model REGKEYCD.LIB Windows, compact memory model REGKEYMD.LIB Windows, medium memory model REGKEYLD.LIB Windows, large and huge memory models The actual method for configuring your C or C++ compiler to link with an additional library varies depending upon which compiler you are using. You should consult your compiler's manual for detailed information on how to do this. If you are using the Borland Turbo C IDE, you should create a text file with a .PRJ extension, and list the name of your program's .C source file(s) along with the name of the RegKey library to use in the .PRJ file. If you are using the Borland Turbo C++ or Borland C++ IDE, you should create a project file using the Project|Open menu option, again adding the name of your program's source file(s) along with the name of the RegKey library to use. If you are using the Microsoft Quick C IDE, you should use the Make|Set Program List and Make|Edit Program List menu options to include both your program's .C source file(s) and the appropriate library files. If you are using Microsoft the Visual C++ IDE, you should choose Project|Edit to add the name of the RegKey library to your project. If you are using any of these C or C++ compilers from the command line, you must specify the appropriate link parameters to cause your program to be linked with a RegKey library. The following example C / C++ programs included in the RegKey package illustrate how you can call a RegKey function from within your program: DEMOAPPD.C DOS C version of DemoApp DEMOAPPW.C Windows C version of DemoApp DEMOAPPD.CPP DOS object-oriented C++ version of DemoApp DEMOAPPW.CPP Windows object-oriented C++ version of DemoApp ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 47 When calling either of the registration key validation functions, RegKeyValidate() or RegKeyFileValidate(), the result is returned in an enum of type RKVALID. To declare a variable to hold the result of registration key validation, you would use something similar to the follows: RKVALID registeredMode; The address of this variable is passed to the registration key validation function using the C or C++ address-of operator (&), as follows: RegKeyValidate(szRegString, szRegKey, "KIXE4UB52K", "", 0, ®isteredMode); This variable can have one of two values, RK_UNREGISTERED or RK_REGISTERED. Therefore, at any point in your program where you wish to test whether the program is operating in registered or unregistered mode, you might include an if statement similar to the following: if(registeredMode == RK_REGISTERED) { printf("Registered mode\n"); } else { printf("Unregistered mode\n"); } Below, the calling format for each of the RegKey API functions is documented from the perspective of the C and C++ programming languages: ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 48 ----------------------------------------------------------------------------- LANGUAGE C and C++ FUNCTION RegKeyNewCodeSet() PURPOSE Creates a new generation / validation code set FORMAT RKRETURN RegKeyNewCodeSet( const char FAR *szGenerationCode, char FAR *szValidationCode); RETURNS Type RKRETURN. RK_SUCCESS on success, RK_FAILURE on failure. PARAMS szGenerationCode - INPUT: 10-digit generation code string szValidationCode - OUTPUT: 10-digit validation code string NOTES Generates a registration key validation code corresponding to a generation code. This set of generation and validation codes is unique for each application using RegKey, and determines the unique registration key that corresponds to a particular user's name. The secret generation code is used at registration key generation time, and the corresponding validation code is used within your application when validating a registration key. The validation and generation codes are each represented as a ten-digit strings of numbers and upper-case letters. Hence both parameters should be declared as arrays of characters of at least 11 elements in size. This function is called by KeyGen or your own utility, and is only used once for each application using RegKey. The concepts of code set creation are introduced in the section which begins on page 29. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 49 ----------------------------------------------------------------------------- LANGUAGE C and C++ FUNCTION RegKeyGenerate() PURPOSE Creates a user-entered type registration key FORMAT RKRETURN RegKeyGenerate( const char FAR *szRegString, const char FAR *szGenerationCode, const char FAR *szRandomSeed, char FAR *szRegKey); RETURNS Type RKRETURN. RK_SUCCESS on success, RK_FAILURE on failure. PARAMS szRegString - INPUT: Registration string szGenerationCode - INPUT: Application's generation code string szRandomSeed - INPUT: Random number seed string szRegKey - OUTPUT: 20-digit registration key string NOTES Generates a registration key for a particular user, using the secret generation code corresponding to a particular application (as passed to RegKeyNewCodeSet()). The registration string is usually the name of the registered user, but may also contain other information, such as the version registered or date of expiry. The registration string may be zero to 64K characters in length, and is null-terminated. The registration key is returned as a string of letters and upper-case letters. The string pointed to by szRegKey must be large enough to hold 20 digits, plus a string terminator character. szRandomSeed should contain 10 random numbers and upper- case numbers, which are required during the registration key generation process. This function is called by KeyGen or your own registration key generation utility, each time a registration key is generated for a new user. This function is used for user-entered registration keys; compare with RegKeyFileGenerate(). Concepts of registration key generation are introduced in the section which begins on page 31. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 50 ----------------------------------------------------------------------------- LANGUAGE C and C++ FUNCTION RegKeyValidate() PURPOSE Checks the validity of a user-entered registration key FORMAT RKRETURN RegKeyValidate( const char FAR *szRegString, const char FAR *szRegKey, const char FAR *szValidationCode, const char FAR *szYourName, unsigned long int nYourKey, RKVALID FAR *peRegistered); RETURNS Type RKRETURN. RK_SUCCESS on success, RK_FAILURE on failure. PARAMS szRegString - INPUT: Registration string szRegKey - INPUT: 20-digit registration key string szValidationCode - INPUT: Application's validation code string szYourName - INPUT: Your name (if registered) nYourKey - INPUT: Your key (if registered) peRegistered - OUTPUT: Is key valid NOTES Checks whether a given registration string and registration key combination is valid for a particular application, using the application-specific validation code that was generated by RegKeyNewCodeSet(). The RKVALID pointed to by peRegistered is set to either RK_REGISTERED or RK_UNREGISTERED, indicating whether or not the registration key and registration string are valid. If you have registered RegKey, your own name and RegKey registration key should be passed to this function to disable the RegKey "unregistered" message. This function is called from within your application each time it executes, in order to determine whether it should operate in registered or unregistered mode. This function is used with user- entered registration keys; compare with RegKeyFileValidate(). Concepts of registration key validation are introduced in the section which begins on page 34. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 51 ----------------------------------------------------------------------------- LANGUAGE C and C++ FUNCTION RegKeyFileGenerate() PURPOSE Generates a file-based registration key FORMAT RKRETURN RegKeyFileGenerate( const char FAR *szRegString, const char FAR *szGenerationCode, const char FAR *szRandomSeed, const char FAR *szFileName); RETURNS Type RKRETURN. RK_SUCCESS on success, RK_FAILURE on failure. PARAMS szRegString - INPUT: Registration string szGenerationCode - INPUT: Application's generation code string szRandomSeed - INPUT: Random number seed string szFileName - INPUT: Registration key file name NOTES Generates a file-based registration key for a particular user, using the secret generation code corresponding to a particular application (as passed to RegKeyNewCodeSet()). The registration string is usually the name of the registered user, but may also contain other information, such as the version registered or date of expiry. The registration string may be zero to 64K characters in length, and is null-terminated. A registration key file is generated, using the specified filename, containing the registration string and the resulting registration key. If a file with the specified name already exists, it is overwritten. szRandomSeed should contain 10 random numbers and upper-case letters, which are required during the registration key generation process. This function is called by KeyGen or your own registration key generation utility, each time a registration key is generated for a new user. This function is used for file-based registration keys; compare with RegKeyGenerate(). Concepts of registration key generation are introduced in the section which begins on page 31. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 52 ----------------------------------------------------------------------------- LANGUAGE C and C++ FUNCTION RegKeyFileValidate() PURPOSE Checks the validity of a file-based registration key FORMAT RKRETURN RegKeyFileValidate( const char FAR *szFileName, const char FAR *szValidationCode, const char FAR *szYourName, unsigned long int nYourKey, char FAR *szRegString, unsigned short int cbMaxStringSize, RKVALID FAR *peRegistered); RETURNS Type RKRETURN. RK_SUCCESS on success, RK_FAILURE on failure. PARAMS szFileName - INPUT: Registration key file name szValidationCode - INPUT: App's validation code szYourName - INPUT: Your name (if registered) nYourKey - INPUT: Your key (if registered) szRegString - OUTPUT: Registration string cbMaxStringSize - INPUT: Size of reg. string peRegistered - OUTPUT: Is key valid NOTES Checks whether the specified registration key file is valid for a particular application, using the application-specified validation code that was generated by RegKeyNewCodeSet(). The RKVALID pointed to by peRegistered is set to either RK_REGISTERED or RK_UNREGISTERED, indicating whether or not the registration key and registration string stored in the registration key file are valid. The szFileName parameter may include wildcards. If you have registered RegKey, your own name and RegKey registration key should be passed to this function to disable the RegKey "unregistered" message. This function is called from within your application each time it executes, in order to determine whether it should operate in registered or unregistered mode. This function is used with file- based registration keys; compare with RegKeyValidate(). Concepts of registration key validation are introduced in the section which begins on page 34. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 53 USING THE REGKEY SYSTEM WITH QUICKBASIC ----------------------------------------------------------------------------- This section describes how to use RegKey with programs written with the Microsoft QuickBASIC programming language. RegKey has been tested with Microsoft QuickBASIC version 4.5. Although no testing has been done with other versions, this information would likely also apply to earlier versions of QuickBASIC. In addition, this information may be applicable to using RegKey with Microsoft Visual Basic for DOS. However, RegKey has not been tested with Visual Basic for DOS. For information on using RegKey with Visual Basic for Windows, see page 60. There are three files that form the RegKey interface for QuickBASIC. The REGKEYQB.QLB Quick Library contains a version of the RegKey routines for use within the QuickBASIC development environment (QB.EXE). In order to use RegKey from within QuickBASIC, you must start up QuickBASIC using the command: QB \LREGKEYQB.QLB REGKEYQB.LIB is a stand-alone library corresponding to REGKEYQB.QLB, and is automatically used by QuickBASIC when producing an executable (.EXE) file of your program. The REGKEYQB.BI file provides QuickBASIC with information concerning the routines contained in the REGKEYQB.??? library files, and must be included in any QuickBASIC program that uses RegKey. To do this, the $INCLUDE metacommand is used as follows: ' $INCLUDE: 'regkeyqb.bi' For an example of a QuickBASIC program that uses RegKey, see the DEMOAPPD.BAS program. Below, the calling format for each of the RegKey API functions is documented from the perspective of the BASIC programming language: ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 54 ----------------------------------------------------------------------------- LANGUAGE QuickBASIC and Visual Basic FUNCTION RegKeyNewCodeSet() PURPOSE Creates a new generation / validation code set FORMAT Result% = RegKeyNewCodeSet%(sGenerationCode$, sValidationCode$) RETURNS In QuickBASIC: RKSuccess on success, RKFailure on failure. In Visual Basic: 1 on success, 0 on failure. PARAMS sGenerationCode$ - INPUT: 10-digit generation code string sValidationCode$ - OUTPUT: 10-digit validation code string NOTES Generates a registration key validation code corresponding to a generation code. This set of generation and validation codes is unique for each application using RegKey, and determines the unique registration key that corresponds to a particular user's name. The secret generation code is used at registration key generation time, and the corresponding validation code is used within your application when validating a registration key. The validation and generation codes are each represented as a ten-digit strings of numbers and upper-case letters. This function is called by KeyGen or your own utility, and is only used once for each application using RegKey. The concepts of code set creation are introduced in the section which begins on page 29. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 55 ----------------------------------------------------------------------------- LANGUAGE QuickBASIC and Visual Basic FUNCTION RegKeyGenerate() PURPOSE Creates a user-entered type registration key FORMAT Result% = RegKeyGenerate%(sRegString$, sGenerationCode$, sRandomSeed$, sRegKey$) RETURNS In QuickBASIC: RKSuccess on success, RKFailure on failure. In Visual Basic: 1 on success, 0 on failure. PARAMS sRegString$ - INPUT: Registration string sGenerationCode$ - INPUT: Application's generation code string sRandomSeed$ - INPUT: Random number seed string sRegKey$ - OUTPUT: 20-digit registration key string NOTES Generates a registration key for a particular user, using the secret generation code corresponding to a particular application (as passed to RegKeyNewCodeSet()). The registration string is usually the name of the registered user, but may also contain other information, such as the version registered or date of expiry. The registration string may be zero to 64K characters in length. The registration key is returned as a string of letters and upper-case letters. sRandomSeed$ should contain 10 random numbers and upper- case numbers, which are required during the registration key generation process. This function is called by KeyGen or your own registration key generation utility, each time a registration key is generated for a new user. This function is used for user-entered registration keys; compare with RegKeyFileGenerate(). Concepts of registration key generation are introduced in the section which begins on page 31. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 56 ----------------------------------------------------------------------------- LANGUAGE QuickBASIC and Visual Basic FUNCTION RegKeyValidate() PURPOSE Checks the validity of a user-entered registration key FORMAT Result% = RegKeyValidate%(sRegString$, sRegKey$, sValidationCode$, sYourName$, nYourKey AS LONG, peRegistered AS INTEGER) RETURNS In QuickBASIC: RKSuccess on success, RKFailure on failure. In Visual Basic: 1 on success, 0 on failure. PARAMS sRegString$ - INPUT: Registration string sRegKey$ - INPUT: 20-digit registration key sValidationCode$ - INPUT: Application's validation code sYourName$ - INPUT: Your name (if registered) nYourKey& - INPUT: Your key (if registered) peRegistered% - OUTPUT: Is key valid NOTES Checks whether a given registration string and registration key combination is valid for a particular application, using the application-specific validation code that was generated by RegKeyNewCodeSet(). The integer passed as peRegistered is set to 0 (or RKUnregistered in QuickBASIC) if the registration key is not valid, and is set to 1 (or RKRegistered in QuickBASIC) if the registration key is valid. If you have registered RegKey, your own name and RegKey registration key should be passed to this function to disable the RegKey "unregistered" message. This function is called from within your application each time it executes, in order to determine whether it should operate in registered or unregistered mode. This function is used with user- entered registration keys; compare with RegKeyFileValidate(). Concepts of registration key validation are introduced in the section which begins on page 34. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 57 ----------------------------------------------------------------------------- LANGUAGE QuickBASIC and Visual Basic FUNCTION RegKeyFileGenerate() PURPOSE Generates a file-based registration key FORMAT Result% = RegKeyFileGenerate%(sRegString$, sGenerationCode$, sRandomSeed$, sFileName$) RETURNS In QuickBASIC: RKSuccess on success, RKFailure on failure. In Visual Basic: 1 on success, 0 on failure. PARAMS sRegString$ - INPUT: Registration string sGenerationCode$ - INPUT: Application's generation code string sRandomSeed$ - INPUT: Random number seed string sFileName$ - INPUT: Registration key file name string NOTES Generates a file-based registration key for a particular user, using the secret generation code corresponding to a particular application (as passed to RegKeyNewCodeSet()). The registration string is usually the name of the registered user, but may also contain other information, such as the version registered or date of expiry. A registration key file is generated, using the specified filename, containing the registration string and the resulting registration key. If a file with the specified name already exists, it is overwritten. sRandomSeed$ should contain 10 random numbers and upper-case letters, which are required during the registration key generation process. This function is called by KeyGen or your own registration key generation utility, each time a registration key is generated for a new user. This function is used for file-based registration keys; compare with RegKeyGenerate(). Concepts of registration key generation are introduced in the section which begins on page 31. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 58 ----------------------------------------------------------------------------- LANGUAGE QuickBASIC and Visual Basic FUNCTION RegKeyFileValidate() PURPOSE Checks the validity of a file-based registration key FORMAT Result% = RegKeyFileValidate%(sFileName$, sValidationCode$, sYourName$, nYourKey AS LONG, sRegString$, cbMaxStringSize AS INTEGER, peRegistered AS INTEGER) RETURNS In QuickBASIC: RKSuccess on success, RKFailure on failure. In Visual Basic: 1 on success, 0 on failure. PARAMS sFileName$ - INPUT: Registration key file name string sValidationCode$ - INPUT: App's validation code string sYourName$ - INPUT: Your name (if registered) nYourKey - INPUT: Your key (if registered) sRegString$ - OUTPUT: Registration string cbMaxStringSize% - INPUT: Maximum size of registration string peRegistered& - OUTPUT: Is key valid NOTES Checks whether the specified registration key file is valid for a particular application, using the application-specified validation code that was generated by RegKeyNewCodeSet(). The integer passed as peRegistered is set to 0 (or RKUnregistered in QuickBASIC) if the registration key is not valid, and is set to 1 (or RKRegistered in QuickBASIC) if the registration key is valid. The szFileName parameter may include wildcards. If you have registered RegKey, your own name and RegKey registration key should be passed to this function to disable the RegKey "unregistered" message. The integer cbMaxString size indicates the maximum number if characters that should be placed in the sRegString$ string. With QuickBASIC, this may be any value from 1 to 255. With Visual Basic, this may be any value from 1 to 30,000. This function is called from within your application each time it executes, in order to determine whether it should operate in registered or unregistered mode. This function is used with file- based registration keys; compare with RegKeyValidate(). Concepts of registration key validation are introduced in the section which begins on page 34. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 59 USING THE REGKEY SYSTEM WITH VISUAL BASIC ----------------------------------------------------------------------------- This section describes how to use RegKey in programs written with Microsoft Visual Basic for Windows. For information on using RegKey with Visual Basic for DOS, see page 54. RegKey has been tested with version 2.0 of Visual Basic for Windows. This information should also apply to version 1.0 and 3.0 of the Visual Basic system. The RegKey interface for Visual Basic consists of two components: the REGKEYVB.BAS module that you include in your Visual Basic project, and the RK30VB.DLL file that is used to generate or validate registration keys during your program's execution. To include REGKEYVB.BAS in your program, choose the File|Add File... option from within Visual Basic, and then select the REGKEYVB.BAS file. The REGKEYVB.BAS module will now appear in your program's project window within Visual Basic. You should not normally change the contents of this file, but feel free to refer to it for reference to the RegKey functions. The role of the REGKEYVB.BAS module is to serve as a intermediate layer between your program and the RK30VB.DLL library, ensuring that strings passed to RK30VB.DLL are large enough for it to return any necessary information to you. The RK30VB.DLL file must be present in the Windows system directory (typically C:\WINDOWS\SYSTEM) whenever your program is run, and should be distributed with your program. You may wish to provide an installation utility for your software, which will automatically install the RK30VB.DLL file in the user's Windows system directory. For an example of a Visual Basic program that uses RegKey, see the DemoAppW source code contained in the files DEMOAPPW.BAS and DEMOAPPW.MAK. The calling format for each of the RegKey API functions is documented from the perspective of the BASIC programming language beginning on page 55. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 60 USING THE REGKEY SYSTEM WITH TURBO PASCAL ----------------------------------------------------------------------------- This section describes how to use RegKey in programs written with Turbo Pascal. If you have not already extracted the contents of the TP.ZIP file included in your RegKey package, you should do so now. The RegKey package includes a .TPU unit that is compatible with Turbo Pascal for DOS 7.0. If you are using a different version of Turbo Pascal, you will have to follow the instructions below to build a RegKey unit for your version of Turbo Pascal. If you are using Turbo Pascal 7.0, simply rename the included REGKEYD7.TPU file to REGKEYD.TPU. You can then skip the following instructions for building a RegKey unit. (Please Note - while the necessary files for using RegKey with Turbo Pascal for Windows have been included in the RegKey package, RegKey has not been tested with Turbo Pascal for Windows.) If you are using any version of Turbo Pascal other than Turbo Pascal for DOS 7.0, you will have to first build a .TPU unit for your version of Turbo Pascal. In order to do this, you will need to have the following file (included in the RegKey package) located in the current directory or your Turbo Pascal working directory: FOR DOS: REGKEYD.PAS RKFGEND.OBJ RKFILED.OBJ RKFVALD.OBJ RKGEND.OBJ RKMATHD.OBJ RKNSETD.OBJ RKRD.OBJ RKTPD.OBJ RKVALD.OBJ For Windows: REGKEYW.PAS RKFGENW.OBJ RKFILEW.OBJ RKFVALW.OBJ RKGENW.OBJ RKMATHW.OBJ RKNSETW.OBJ RKRW.OBJ RKTPW.OBJ RKVALW.OBJ You can either build the RegKey unit for the DOS command prompt using the TPC compiler, or from within the TURBO development environment. From the command line, type TPC REGKEYD.PAS to build the REGKEYD.TPU unit. From within the TURBO development ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 61 environment, open the REGKEYD.PAS source file for DOS, or the REGKEYW.PAS source file for Windows. From the Compile menu choose File as a destination, and then choose the "Make" command. Once you have built a .TPU unit for your version of Turbo Pascal, you can either place it in the same directory as your program's .PAS source code files, or you can place it in the Turbo Pascal UNITS directory. To call any of the RegKey functions from within a Turbo Pascal program, you must place a uses clause at the start of your program, and include RegKeyD (for DOS) or RegKeyW (for Windows) in the list of units. For example: program TestAppD; uses RegKeyD, Graph; For an example of a Turbo Pascal program that uses RegKey, see the DEMOAPPD.PAS program that is included in your RegKey package. Below, the calling format for each of the RegKey API functions is documented from the perspective of the BASIC programming language: ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 62 ----------------------------------------------------------------------------- LANGUAGE Turbo Pascal FUNCTION RegKeyNewCodeSet() PURPOSE Creates a new generation / validation code set FORMAT function RegKeyNewCodeSet( sGenerationCode : string; sValidationCode : string) : RKReturn; RETURNS Enumeration type RKReturn. Value of RKSuccess on success, RKFailure on failure. PARAMS sGenerationCode - INPUT: 10-digit generation code string sValidationCode - OUTPUT: 10-digit validation code string NOTES Generates a registration key validation code corresponding to a generation code. This set of generation and validation codes is unique for each application using RegKey, and determines the unique registration key that corresponds to a particular user's name. The secret generation code is used at registration key generation time, and the corresponding validation code is used within your application when validating a registration key. The validation and generation codes are each represented as a ten-digit strings of numbers and upper-case letters. This function is called by KeyGen or your own utility, and is only used once for each application using RegKey. The concepts of code set creation are introduced in the section which begins on page 29. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 63 ----------------------------------------------------------------------------- LANGUAGE Turbo Pascal FUNCTION RegKeyGenerate() PURPOSE Creates a user-entered type registration key FORMAT function RegKeyGenerate( sRegString : string; sGenerationCode : string; sRandomSeed : string; sRegKey : string) : RKReturn; RETURNS Enumeration type RKReturn. Value of RKSuccess on success, RKFailure on failure. PARAMS sRegString - INPUT: Registration string sGenerationCode - INPUT: Application's generation code string sRandomSeed - INPUT: Random number seed string sRegKey - OUTPUT: 20-digit registration key string NOTES Generates a registration key for a particular user, using the secret generation code corresponding to a particular application (as passed to RegKeyNewCodeSet()). The registration string is usually the name of the registered user, but may also contain other information, such as the version registered or date of expiry. The registration key is returned in sRegKey as a string of letters and upper-case letters. The string passed in sRegKey should be at least 20 characters in size. sRandomSeed should contain 10 random numbers and upper-case numbers, which are required during the registration key generation process. This function is called by KeyGen or your own registration key generation utility, each time a registration key is generated for a new user. This function is used for user-entered registration keys; compare with RegKeyFileGenerate(). Concepts of registration key generation are introduced in the section which begins on page 31. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 64 ----------------------------------------------------------------------------- LANGUAGE Turbo Pascal FUNCTION RegKeyValidate() PURPOSE Checks the validity of a user-entered registration key FORMAT function RegKeyValidate( sRegString : string; sRegKey : string; sValidationCode : string; sYourName : string; nYourKey : longint; var peRegistered : RKValid) : RKReturn; RETURNS Enumeration type RKReturn. Value of RKSuccess on success, RKFailure on failure. PARAMS sRegString - INPUT: Registration string sRegKey - INPUT: 20-digit registration key sValidationCode - INPUT: Application's validation code sYourName - INPUT: Your name (if registered) nYourKey - INPUT: Your key (if registered) peRegistered - OUTPUT: Is key valid NOTES Checks whether a given registration string and registration key combination is valid for a particular application, using the application-specific validation code that was generated by RegKeyNewCodeSet(). The parameter peRegistered should be a variable of type RKValid. This variable is set to the value RKRegistered if the registration key is valid, and RKUnregistered if it is not valid. If you have registered RegKey, your own name and RegKey registration key should be passed to this function to disable the RegKey "unregistered" message. This function is called from within your application each time it executes, in order to determine whether it should operate in registered or unregistered mode. This function is used with user- entered registration keys; compare with RegKeyFileValidate(). Concepts of registration key validation are introduced in the section which begins on page 34. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 65 ----------------------------------------------------------------------------- LANGUAGE Turbo Pascal FUNCTION RegKeyFileGenerate() PURPOSE Generates a file-based registration key FORMAT function RegKeyFileGenerate( sRegString : string; sGenerationCode : string; sRandomSeed : string; sFileName : string) : RKReturn; RETURNS Enumeration type RKReturn. Value of RKSuccess on success, RKFailure on failure. PARAMS sRegString - INPUT: Registration string sGenerationCode - INPUT: Application's generation code string sRandomSeed - INPUT: Random number seed string sFileName - INPUT: Registration key file name string NOTES Generates a file-based registration key for a particular user, using the secret generation code corresponding to a particular application (as passed to RegKeyNewCodeSet()). The registration string is usually the name of the registered user, but may also contain other information, such as the version registered or date of expiry. A registration key file is generated, using the specified filename, containing the registration string and the resulting registration key. If a file with the specified name already exists, it is overwritten. sRandomSeed should contain 10 random numbers and upper-case letters, which are required during the registration key generation process. This function is called by KeyGen or your own registration key generation utility, each time a registration key is generated for a new user. This function is used for file-based registration keys; compare with RegKeyGenerate(). Concepts of registration key generation are introduced in the section which begins on page 31. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 66 ----------------------------------------------------------------------------- LANGUAGE Turbo Pascal FUNCTION RegKeyFileValidate() PURPOSE Checks the validity of a file-based registration key FORMAT function RegKeyFileValidate( sFileName : string; sValidationCode : string; sYourName : string; nYourKey : longint; sRegString : string; cbMaxStringSize : byte; var peRegistered : RKValid) : RKReturn; RETURNS Enumeration type RKReturn. Value of RKSuccess on success, RKFailure on failure. PARAMS sFileName - INPUT: Registration key file name string sValidationCode - INPUT: App's validation code string sYourName - INPUT: Your name (if registered) nYourKey - INPUT: Your key (if registered) sRegString - OUTPUT: Registration string cbMaxStringSize - INPUT: Maximum size of registration string peRegistered - OUTPUT: Is key valid NOTES Checks whether the specified registration key file is valid for a particular application, using the application-specified validation code that was generated by RegKeyNewCodeSet(). The parameter peRegistered should be a variable of type RKValid. This variable is set to the value RKRegistered if the registration key is valid, and RKUnregistered if it is not valid. If you have registered RegKey, your own name and RegKey registration key should be passed to this function to disable the RegKey "unregistered" message. The integer cbMaxString size indicates the maximum number if characters that should be placed in the sRegString string, and should be equal to the size of the passed string as declared in Turbo Pascal, or 255 if no size was specified when declaring the string. This function is called from within your application each time it executes, in order to determine whether it should operate in registered or unregistered mode. This function is used with file- based registration keys; compare with RegKeyValidate(). Concepts of registration key validation are introduced in the section which begins on page 34. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 67 USING REGKEY WITH OTHER LANGUAGES OR OPERATING SYSTEMS ----------------------------------------------------------------------------- If you are working with a programming language, compiler or operating system that is not specifically addressed in the above sections, it may still be possible for you to use RegKey. There are three possible options: A.) Calling routines from the included RegKey library files B.) Obtaining the RegKey source code and porting it C.) Obtaining a custom version of RegKey from me Each of these options are described in more detail below: A.) Many PC-based programming languages have the ability to call functions using the C calling conventions, from Intel/Microsoft object format library files. For information on how to do this in the language you are using, see the documentation that is included with your language. This documentation will probably refer to the function names and parameters (known as the function prototype) of the C language functions to be called. The pertinent information on the C functions that form RegKey is described in the section beginning on page 46. B.) As is described on page 13, the RegKey source code is available. RegKey is written in ANSI-compliant C and is designed to be easily ported to other hardware platforms or operating systems. While the source code package does include 80x86 assembly language routines for performing certain tasks such as 96-bit arithmetic, the equivalent C source code for these routines is also included. C.) I may also be willing to port RegKey to another operating system, hardware platform or programming language for you. To do this, I usually require that you (LEGALLY) furnish me with the necessary software and/or hardware to create a custom version of RegKey. If I am able to keep the software / hardware and use it to produce future versions of RegKey for others, I would generally provide you with a free RegKey registration and copy of the source code, but no more. If you wish to discuss this possibility further, please feel free to get in touch with me. For more information how to reach me, see page 69. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 68 ----------------------------------------------------------------------------- PART 5: ADDITIONAL INFORMATION ----------------------------------------------------------------------------- GETTING HELP ----------------------------------------------------------------------------- If you have any questions about RegKey, would like help with a program that your are writing, or have any suggestions for future versions of RegKey, please feel free to get in touch with me. If you are having difficulties with RegKey, the more detailed information you supply (such as source code to the program that is causing the problem, how to duplicate the problem, etc.), the more quickly I will be able to determine the cause of your problem. If you would like to receive the most recent copy of RegKey, you can download it from the RegKey support bulletin board system (phone number below), file request it from the FidoNet address below, or send three dollars ($3) to cover the cost of postage and a diskette to the address listed below. You can get in touch with me by any of the following means: - By conventional mail. My postal address is: Brian Pirie Apt. 1416 - 2201 Riverside Dr. Ottawa, Ontario K1H 8K9 Canada - By electronic mail. My Internet e-mail address is: brian@bpecomm.ocunix.on.ca And my FidoNet netmail address is: 1:243/8 ***SEE NOTE BELOW*** If you have access to an on-line service such as Prodigy or CompuServe, you can also reach me by sending Internet e-mail. While I would like to be able to reply to all FidoNet NetMail messages by CrashMail, I am afraid I can not afford to do this. So, if you choose to send NetMail, please indicate whether you would like me to reply by routed NetMail (this may not work, if routed NetMail is not available in your area), or to place the message on hold for you to poll and pick up. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 69 - By calling the RegKey support bulletin board system. The phone number for the support BBS is: +1 613 526 4466 The BBS supports speeds up to 9600bps, with v.32/v.42bis capabilities. You are given full access to the support BBS on your first call. In addition to being able to reach me through the support BBS, you can also download the newest version of RegKey, and other software that may be of interest to people using RegKey. I try to respond to all correspondences as soon as possible (i.e., within twenty-four hours). However, it is possible that it may take longer to reply to your message, particularly if you are asking a question that requires time for me to get an answer, or if I happen to be away for a few days. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 70 CONTENTS OF PACKAGE ----------------------------------------------------------------------------- The disk / archive in which you received your copy of the RegKey package should include the following files: FILE_ID.DIZ A brief description of RegKey C_CPP.ZIP Contains C/C++ language specific files REGKEYSD.LIB DOS tiny/small memory model RegKey library REGKEYCD.LIB DOS compact memory model RegKey library REGKEYMD.LIB DOS medium memory model RegKey library REGKEYLD.LIB DOS large/huge memory model RegKey library REGKEYSW.LIB Windows small memory model RegKey library REGKEYCW.LIB Windows compact memory model RegKey library REGKEYMW.LIB Windows medium memory model RegKey library REGKEYLW.LIB Windows large/huge memory model RegKey library REGKEY.H C/C++ include file for RegKey DEMOAPPD.C C language DOS version of example program DEMOAPPW.C C language Windows version of example program DEMOAPPD.CPP C++ language DOS version of example program DEMOAPPW.CPP C++ language Windows version of example program TP.ZIP Contains Turbo Pascal specific files REGKEYD.PAS Pascal file for building RegKey TP/DOS unit RKFGEND.OBJ Object files for building RegKey TP/DOS unit RKFILED.OBJ " " RKFVALD.OBJ " " RKGEND.OBJ " " RKMATHD.OBJ " " RKNSETD.OBJ " " RKRD.OBJ " " RKTPD.OBJ " " RKVALD.OBJ " " REGKEYD.PAS Pascal file for building RegKey TP/Windows unit RKFGEND.OBJ Object files for building TP/Windows unit RKFILED.OBJ " " RKFVALD.OBJ " " RKGEND.OBJ " " RKMATHD.OBJ " " RKNSETD.OBJ " " RKRD.OBJ " " RKTPD.OBJ " " RKVALD.OBJ " " REGKEYD7.TPU RegKey Unit for Turbo Pascal 7.0 for DOS DEMOAPPD.PAS Pascal source code for RegKey example program QB.ZIP Contains QuickBASIC specific files REGKEYQB.QLB QuickBASIC Quick Library for RegKey REGKEYQB.LIB QuickBASIC stand-alone library for RegKey REGKEYQB.BI QuickBASIC include file for RegKey ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 71 DEMOAPPD.BAS QuickBASIC version of the example program VB.ZIP Contains Visual Basic specific files RK30VB.DLL RegKey .DLL callable from Visual Basic REGKEYVB.BAS RegKey interface module for Visual Basic DEMOAPPW.BAS Visual Basic version of the example program DEMOAPPW.MAK Visual Basic project file for example program KEYGEN.DAT Data file used by key generation utility KEYGEND.EXE DOS version of key generation utility KEYGENW.EXE Windows version of key generation utility CTL3DV2.DLL Used by Windows version of KeyGen DEMOAPPD.EXE DOS version of the RegKey example program DEMOAPPW.EXE Windows version of the RegKey example program ORDER.FRM Easy to print RegKey order form REGKEY.TXT The RegKey programmer's manual (this file). If you received your copy of RegKey on a diskette, that disk should also contain the utility PKUNZIP.EXE, which is used to extract the contents of the *.ZIP files. If you do not have this utility, or if you are missing any of the other RegKey files, please contact me for a current copy of RegKey. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 72 GLOSSARY ----------------------------------------------------------------------------- API API is an acronym for "Application Program Interface" or "Application Programmer Interface". An API is a well-defined set of related functions or procedures that can be called from an application program written in a programming language such as C, C++, Pascal or BASIC. These functions are used to access a specific feature or set of features from within your program. The RegKey API consists of five functions (RegKeyNewCodeSet(), RegKeyGenerate (), RegKeyValidate(), RegKeyFileGenerate() and RegKeyFileValidate()) which you can use to add registration key capabilities to your programs. Another example of an APIs is the Microsoft Windows API, which provide Windows programs with access to screen display, printing and other features which are managed by Windows. BRAND As an alternative to using registration keys, each copy of a particular application can be "branded" with a particular user's name. In this case, the application's executable file(s) contains the name of the one user who is licensed to use that copy of the software, and that name is usually displayed at program startup. Branding is commonly used in commercial software to discourage illegal copying of the software, as the guilty user's name will appear on every illegal copy. This disadvantage of this approach is that it requires the author or company selling the software to produce a unique copy of the program for each user. CODE SET RegKey uses the term "code set" to refer to a set consisting of "generation code" and a corresponding "validation code". For each application (or each version of the application) using RegKey that requires unique registration keys, the application developer(s) generate a unique "code set" using the utilities included in the RegKey package. The secret "generation code" is required to create the unique registration keys for a particular application. The "validation code" is used within the application itself to test a registration key provided by the user. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 73 ENCRYPTION Encryption is the process of translating information - such as written text or a computer program - into a form that cannot be read by unauthorized individuals. Only by knowing the manner in which some information has been encrypted, can someone decrypt and make use of that information. It is possible to use an encryption algorithm to encrypt portions of a program's executable file(s), in order to make it more difficult for someone to alter the executable file. This can be of use when using RegKey, in order to increase the security of the RegKey mechanism. RegKey does not provide any encryption capabilities itself. Depending upon where you live and what form of encryption you are using, there may be legal issues you wish to consider if your are going to export software using encryption technology to other countries. FILE-BASED REGISTRATION KEYS RegKey supports two types of registration keys - file-base and user-entered. With file-based registration keys, both the registration string (e.g. the user's name) and the corresponding registration key code are stored in a registration key file. When a user becomes registered, they receive a small registration key file that is installed in the program's working directory. When a valid registration key file is present, the program will operate in registered mode. GENERATION CODE RegKey uses the term "generation code" to refer to the numerical key that is used to generate registration keys for a particular application using RegKey. For each different generation code, different registration keys are generated for the same registration string. Without knowing the generation code used by your application, it is infeasible for anyone else to generate registration keys that will work with your application. For this reason, you should take great care to keep your application's generation code a secret. You can use the KeyGen utility included with RegKey to create a new generation code. When a generation code is created, a corresponding "validation code" is also created. It is this validation code that is passed to RegKey by your application when testing the validity of a registration key. It is not usually important to keep the validation code a secret, as knowing it only allows someone to determine whether or not a ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 74 particular registration key / registration string combination is valid for your application. INFEASIBLE The term "infeasible" is used in software protection to describe something that is very difficult - though not impossible - to achieve. For instance, even if someone were able to test one million registration keys per second, it would still take many centuries to discover a RegKey registration key by a trial-and- error method. Since so much time would be required to discover a RegKey registration key by this method, it is said to be infeasible to "guess" a correct registration key. REGISTERED MODE Programs that use registration key systems may operate in either "registered" or "unregistered" mode. In "unregistered" or "demonstration" mode, the software may have certain features disabled, may only operate for a limited period of time, or may display a "please register" message during program operation. When the user pays for the software, they receive a registration key corresponding to their name or other personal information. When this registration key is presented to the application, it will then operate in "registered" mode, eliminating any "unregistered" messages and possibly enabling additional features. REGISTRATION KEY For each user who pays for your software, you use RegKey to generate a unique registration key, based on the information of the registration string (usually the user's name). The resulting registration key is a 96-bit number that is (in all probability) unique for each user that registers your application. This registration key may either be entered into your application by the user, or may be stored in a "registration key file" that is given to the user upon registration. Your application can then use RegKey to determine whether or not the registration key is valid, thus determining whether or not it should operate in "registered mode". RegKey represents the registration key as a 20 digit base 32 number. The registration key returned to you when generating registration keys, and the key presented to RegKey by your application, is represented as a 20 character string of numerals and uppercase letters. Hence, AB7EWBR24LZTUFEY2PLF might be a typical RegKey registration key. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 75 REGISTRATION KEY FILE When file-based registration keys are used, both the registration string (usually the user's name) and the registration key code are stored in a small registration key file. This file usually has a .KEY filename extension. REGISTRATION STRING A unique registration string is associated with each user who registers your software. This registration string is usually just the user or organization's name, but it may also include additional information, such as the registered version or registration expiry date. In any case, the registration string usually consists of information that the user knows prior to registering. When the user pays for your software, you use RegKey to generate a registration key that corresponds to the registration string. When the registration string is presented to your application in conjunction with the registration key, it can use RegKey to test the validity of the registration string / registration key combination, in order to determine whether or not to operate in "registered mode". SHAREWARE A method of marketing computer software, where the author encourages the free distribution of the software. This allows potential users of the software to "test-drive" the application before buying it. In the shareware approach to software marketing, the user is usually required to either stop using the software after a three to four week trial period, or pay to "register" the software with the author. SOFTWARE PROTECTION The term "software protection" is used to describe any mechanism or scheme that is used to prevent or discourage illegal or unauthorized use of computer software. Approaches to software protection include "copy-protection" schemes which attempt to prevent a duplicate copy of the software from being produced, "hardware-key" mechanisms which require a particular hardware device (which is sold with the software) to be present in order to ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 76 use the software, and "registration-key" mechanisms such as is provided by RegKey. USER-ENTERED REGISTRATION KEYS RegKey supports two types of registration keys - file-base and user-entered. With user-entered registration keys, the user manually enters registration string (e.g. the user's name) and the corresponding registration key code into the application or configuration program when they first register. When a valid registration key has been entered for the entered registration string, the program will operate in registered mode. UNREGISTERED MODE See "Registered Mode". VALIDATION CODE RegKey uses the term "validation code" to refer to the numerical key that is used to test the validity of a registration key / registration string combination, during your application's execution. Your application should pass its unique validation code to RegKey when it wishes to test a registration key. You can use the KeyGen utility included with RegKey to create a new validation code / generation code set for a new application (or version). Unlike the generation code that should be kept confidential, it is not usually important to keep the validation code a secret. This is because knowing the validation code only allows someone to determine whether or not a particular registration key /registration string combination is valid for your application. Knowing the validation code does not enable someone to generate false registration keys for your application. ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 77 INDEX ----------------------------------------------------------------------------- - A - - I - API, 29, 31, 34, 73 Introduction, 3, 23 C/C++, 53 QuickBASIC/Visual Basic, 59 - K - Turbo Pascal, 67 Applications of Registration Keys, KeyGen Program, 13, 18, 19, 27, 28, 22 29, 30, 31, 32, 37, 41, 49, 50, Author's address, 69 52, 55, 56, 58, 63, 64, 66, 72, 74, 77 - B - - O - Branding Software, 22, 73 Ordering RegKey - C - Agreement, 17 Filling Order Form, 8 Code Sets, 23, 24, 27, 28, 29, 30, Order Form, 15 37, 38, 49, 55, 63, 73, 77 Overview, 7 Common Problems, 43 Price, 11 CTL3DV2.DLL File, 20, 27, 43, 72 Source Code, 13 Terms, 17 - E - - P - Encryption, 74 Evaluation Terms, 5 Porting RegKey, 13, 68 Expiry Information, 23, 26, 32, 37, Principles of RegKey, 23 38, 39, 41, 50, 52, 56, 58, 64, Printing Manual, 1 66, 76 - Q - - F - QuickBASIC, 3, 19, 36, 44, 46, 54, Features of RegKey, 3 55, 56, 57, 58, 59, 71, 72 File-Base Registration Keys, 74 File-Based Registration Keys, 25, 76 - R - Files, 71 Registered Mode, 21, 36, 40, 75 - G - Registering RegKey. See Ordering Registration Key Expiry, 23, 26, 32, Generating Registration Keys, 31 37, 38, 39, 41, 50, 52, 56, 58, Generation Codes, 4, 23, 29, 30, 31, 64, 66, 76 32, 33, 41, 42, 43, 49, 50, 52, Registration Keys, 21, 23, 75 55, 56, 58, 63, 64, 66, 73, 74, 77 Registration Strings, 23, 25, 26, Getting Help, 43, 69 31, 32, 33, 34, 35, 36, 37, 38, Glossary, 73 39, 42, 50, 51, 52, 53, 56, 57, 58, 59, 64, 65, 66, 67, 74, 75, 76, 77 ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 78 RegKey Files, 71 - T - RegKeyFileGenerate() Function, 33, 50, 52, 56, 58, 64, 66, 73 Table Of Contents, 2, 18, 46 RegKeyFileValidate() Function, 34, Troubleshooting, 43 35, 36, 43, 48, 51, 53, 57, 59, Turbo Pascal, 3, 19, 36, 44, 46, 61, 65, 67, 73 62, 63, 64, 65, 66, 67, 71 RegKeyGenerate() Function, 33, 50, 52, 56, 58, 64, 66, 73 - U - RegKeyNewCodeSet() Function, 29, 49, 50, 51, 52, 53, 55, 56, 57, 58, Unregistered Mode, 21, 36, 40, 77 59, 63, 64, 65, 66, 67, 73 User-Entered Registration Keys, 25, RegKeyValidate() Function, 34, 35, 77 36, 42, 43, 48, 51, 53, 57, 59, 65, 67, 73 - V - - S - Validation Codes, 4, 23, 24, 27, 28, 29, 30, 34, 35, 37, 42, 43, 49, Security, 4, 6, 12, 13, 21, 27, 40, 51, 53, 55, 57, 59, 63, 65, 67, 74 73, 74, 77 Shareware, 21, 22, 76 Visual Basic, 3, 19, 36, 42, 45, 46, Software Protection, 42, 76 54, 55, 56, 57, 58, 59, 60, 72 ----------------------------------------------------------------------------- REGISTRATION KEY SYSTEM 3.00 - PROGRAMMER'S MANUAL PAGE 79