Can I use Sheriff to protect my application without resorting to C++?
Yes, SlsApi.dll is a standard Windows DLL that can be called by any Windows programming language including Delphi, Visual Basic and VBA. In fact, Sheriff SDK provides ready-to-use templates/classes for Delphi and Visual Basic.
What library and header files will I need to include in my project?
It depends on your programming language. In Sheriff SDK there are three directories under the API directory, namely VC, VB, Delphi & VFP. In general you have to include all of the files from the relevant directory in your project. To distribute your software, you only need to include SlsApi.dll.
What is the best location for the Sheriff DLL (SlsApi.dll)?
It does not matter, usually the DLL is located in the same folder as the application.
What name for the folder for the licence file?
It should be the same name as the Product ID number.
I understand that it is possible to bypass the need for the user to call in for a licence number, using the SLS_License function?
SLS_License is designed for issuing trial/demo licence only. Although it does not stop you from using to issue a full licence, we do recommend that user has to contact you for a proper Licence Key. However, your contact can be made by phone, fax, email or even your web-site (with Sheriff 1.61 and above you can set up a web page that can automatically issue licence keys, though this requires an NT server).
Can there be "soft" and "hard" landings, meaning the user gets a warning when they are approaching their limits of logons?
Yes, how your application behaves when the limit is approaching is decided by your application. By using the API function SLS_GetLicenceInfo you can retrieve the states of the licence, including the usage, at any time.
I've tried to install my protected software and then to change the system clock to extend the time. The Sheriff API detected the time change but now, each call to SLS_GetReference generates an error message : "Invalid System Time" and the software is then locked for eternity. What's happening?
As soon as Sheriff detects any system or licence parameter being tampered with it locks up the licence database to prevent further usage. The way to unlock your licence database is to either change your system clock back to the correct time or delete the licence database files and start it again. Please note that Sheriff allows up to 24 hours time difference between workstations.
I have implemented time metering in my application. What happens if the user tries to cirumvent this by turning back the system clock?
If day/date metering has been implemented and the user puts the clock back more than 24 hours then the error code SLS_E_SYSTEM_TIME will be generated. What action your program takes if this happens is up to you. When the user puts the time forward, the system will work again. However, should the user put the clock forward and then put it back, Sheriff will also consider this to be an attempt to circumvent the metering.
Monitoring the registry in Windows NT shows that upon registering an application registry entries are created pointing to the location of the licence files. Thus if the registry entries and licence files are deleted it appears to be possible to reset any demo version of software and begin the demo period again. Is there any mechanism which will detect this occurrence and provide protection against this action?
Function SLS_IsProductInstalled is provided for this purpose. Before calling SLS_License to issue a demo licence, call SLS_IsProductInstalled to check whether the product has been previously installed. Sheriff Ver 1.1 and above enhance this feature to provide additional protection against re-installing a demo licence.
I have a question about the IsProductInstalled function: Under what conditions does it return false? I want to use it as a test before I use the License function to create a 30-day trial. I have found that it returns true even when I run the demo application on a machine that has never had Sheriff installed on it. Is this a limitation of the demo product key provided?
IsProductInstalled returns as true soon as a Sheriff-protected product has been installed on a PC. To clear it - i.e. to make it return false again - you have to "remove" the product. This can be achieved by running "SlsAdmin" and selecting the "licence|remove" function. Please note that you'll also need to run "SlsGen" to generate a "remove password" in order to remove a licence.
You have indicated that the API function SLS_IsProductInstalled prevents users from installing multiple times on the same PC (or, I assume, same network). Is there, however, a means of preventing multiple installations to other PC's? Is that what is meant when it generates a machine "fingerprint"?
When a Sheriff-protected product is installed on a particular machine it is bound to that machine, which can identified by my means of the machine 'fingerprint' contained in the unique Reference Code that is displayed at the time of installation. Normally, a user will quote their Reference Code to you, the publisher, and you will issue a Licence Key to the user enabling him to run the application according to the terms of the Licence Policy (unlimited use, unit metered etc.). However, because the application is bound to the machine that it is installed on, it cannot be copied from that machine to other machines. It can, however, be installed to other machines provided the correct installation procedure is undertaken (i.e. the publisher issues a unique Licence Key for each of those other machines). So it's up to you to decide how many machines the application is installed on. SLS_IsProductInstalled function is typically used in conjunction with SLS_License. SLS_License will be used only when you wish to issue a trial licence with some limitations - such as limited features or limited life span.
I need to implement a licence remove facility to verify that the user terminated the licence.
SLS_Terminate combined with SLS_VerifyTerminationCode (from the Extended API) should do the trick.
Suppose I have a customer who has already bought a 10 users licence. Now, the customer wants to upgrade the licence to a 20 user licence. Beside using SlsAdmin to terminate the licence, can I terminate the licence inside my program by calling SLS_TERMINATE ? What's the effect of calling SLS_TERMINATE in my program? Do I have to stop the timer object (for heartbeating)? Do I need to run SLS_RELEASE after I run SLS_TERMINATE? (I assume I do not need to because the licence is already terminated.)
Yes, you can call the SLS_Terminate to terminate the licence. After the licence is terminated, the licence files will be completely removed. The correct procedure to terminate a licence should be:
- Call SLS_Release (this is not essential but it is always a good practice to close files before deleting them).
- StopHeartbeat
- CallSLS_Terminate
However, you don't have to terminate an existing licence in order to upgrade it. You can always overwrite it by issuing a new licence. Again, you should release the licence and stop the heartbeat before renewing it.
OnChallenge event: we are not sure when and why the event is issued. We understand it is making sure the data passed between our application and Sheriff has not been tampered with but how do we use it?
As explained in the "ActiveX | Automatic Mode Quick Start | Step 6", OnChallenge event is only fired if you put Sheriff in automatic mode. The purpose of OnChallenge event is to challenge the host application in order to verify whether or not the host application is the software publisher's original. OnChallenge makes sure that only the software publisher can issue a trial licence automatically.
Having looked at the demo source in VB, I don't know why the secrets array has 72 codes, and also where do these come from. The SetSecrets method in the Sheriff class takes this secrets array and then pads out another 56 codes with zero.
The VB demo uses the encrypted Secret Codes, each code is 18 bytes in length and there are four Secret Codes hence 72 bytes in total. However, by design the maximum length allocated for each Secret Code is 32 bytes in order to leave spaces for future expansion. That is why we need to pad 14 bytes to the end of each code.
When I use the GetReference function after the a successful SetLicence, the value has changed. Am I doing something wrong or is this normal?
Nothing is wrong. This is a feature that prevents a Reference Code from being re-used.
What is the justification for OnProductNotLicensed event and what does it mean when is it triggered?
OnProductNotLicensed event is triggered when Sheriff detects that the product is installed but it has not been authorised with a valid licence i.e. there is no valid licence detected on the PC for the product.
What's the difference between SLS_TYPE_REUSABLE_KEY & SLS_TYPE_REUSABLE_REF?
SLS_TYPE_REUSABLE_KEY produces a reusable Licence Key. A reusable Licence Key can be reused on the same machine any number of times as long as the Licence Policy permits this. For example, if the Licence File is deleted by accident the user can simply re-license the machine with the reusable Licence Key without the need to contact the publisher.
SLS_TYPE_REUSABLE_REF makes the Reference Code reusable, which enables the software publisher to save the Reference Code for renewal purposes. If the Reference Code is not reusable, when a user's licence is due for renewal the publisher has to first ask the user for the current Reference Code before issuing a renewal licence. With a reusable Reference Code, the publisher can simply reuse the previous Reference Code to issue a Licence Key without first needing to contact the user.
NB. You would not create a Reusable Key if your product is time/unit metered, since this would enable your user to bypass the protection.
What is the difference between the functions Query Licence Info (SLS_QueryLicenceInfo) and Get Licence Status (SLS_GetStatusCode) and when would you use them? For example, if you wanted to display the current status of the licence to the user (E.g. 10 days left to run), which would you use?
The difference is that QueryLicenceInfo returns the licence properties in non-encrypted format where as GetLicenceStatus returns them encrypted. If you want to display the current status of the licence to the user you need to call QueryLicenceInfo.
I have downloaded the evaluation version and I am having trouble using the unit meter feature. I call SLS_Update with an SLS_UPDATE record with UnitsConsumed set. When I later call SLS_QueryLicenceInfo, the units consumed again equals 0. Any ideas or sample source code? I am very interested in buying such a product.
Units are deducted from the licence only at the time when SLS_Release is called. SLS_Update causes units to be deducted from licence's pool instead of the licence's meter.