Microsoft Windows

Under the Microsoft Windows environment, each license system service provider is implemented as a Dynamic Link Library (DLL). Applications access the License Service API interface through the license manager DLL (lSAPI.dll). This DLL, implemented by Microsoft, is responsible for coalescing the installed license service providers. It is not a license provider in and of itself.

Each service provider implements the functions exactly as described in this specification, and contains the same entry points and calling conventions (along with their associated ordinal values) as the LSAPIxx.DLL (where xx = 16 or 32 depending on platform). For the enumeration function, each provider simply responds with a single entry which identifies itself. The License Manager DLL will collate the responses from each of the service providers and present the results to the client application. Configuration information dictates the default ordering of the license systems for the particular client.

The indirection through the License Manager DLL should not have a significant performance hit. Furthermore, applications will be infrequently accessing the DLL. However, if the provider DLLs are located on a network server rather than on the client workstation, a small penalty may result due to the remote access.

License system provider DLLs:

must provide the same entry points and parameters as defined for the Windows License Manager DLL.

should be small (code and data size) and very efficient (fast). Perform as much work as possible at the server side.

should not perform challenge authentication within the provider. Rather, the challenge should always be performed within the license server system. The challenge serves as an end-to-end authentication that the license server system indeed knows the secret(s) contained on the license itself.

Microsoft Windows 3.x

Applications will access the providers indirectly through the LSAPI16.DLL, which will be supplied with Microsoft Windows, and with license systems. The LSAPI16.DLL is usually placed into the Windows directory (e.g., \windows), but also may be anywhere as long as it appears in the search path (as defined by the path environment variable).

The calling convention used in the License Manager DLL is FAR PASCAL. Refer to the Microsoft Windows 3.x Software Development Kit for further information on writing DLLs.

In the Windows directory (or anywhere along the path), there is an initialization file (lSAPI.ini) which contains the following sections and parameters:

Section Name

Parameter

Description

[Settings]

Order=

This defines the default order in which license system providers are queried for a particular license. An order of "2 1 3 4" indicates that Provider2 is to be queried first, Provider1 second, etc. Note that each number is separated by a space.

If a number appears here that does not match a provider, the number is skipped. Likewise, if any providers are listed which do not appear in this list, they will be queried after the listed providers. These providers will be queried in the order in which they appear in the [Providers] section.

[Providers]

ProviderN=

One entry for each license system provider installed on the client. Each license system must place a line with a unique value for N. The line contains the full pathname to the DLL, a semicolon (;), the interface specification version number provided in the DLL (for now, all are 1.00); another semicolon followed by a brief text description of the particular license system. The entire line must not exceed 255 characters.

[Vendor]

vendor-specific

Each License system vendor optionally may include limited information in the LSAPI.INI file by placing information under their unique Vendor name.


For future compatibility, applications and license system vendors should read and write the LSAPI.INI file using the Windows GetPrivateProfileString() and SetPrivateProfileString() API calls. In no case should this file be directly accessed. In order to locate the LSAPI.INI file, the installation process should first search the Windows directory, followed by all of the directories specified in the PATH environment variable.

The following is a sample LSAPI.INI file of a system with four license service providers:

[Settings]

Order=2 1 3 4

[Providers]

Provider1=C:\WINDOWS\SITELOCK.DLL;1.00;Brightwork SiteLock

Provider2=C:\DSLA\DSLA.DLL;1.00;Digital Software Licensing System

Provider4=C:\WINDOWS\NETLS.DLL;1.00;HP/Gradient NetLS

Provider3=C:\FLEXLM\FLEXLM.DLL;1.00;Highland Flexible License Mgr

Microsoft Windows NT™ and beyond

Applications will access the providers indirectly through the LSAPI32.DLL, which will be supplied with Microsoft Windows, and with license systems. The LSAPI32.DLL is usually placed into the Windows NT 3.1 directory (e.g., winnt\system32), but also may be anywhere as long as it appears in the search path (as defined by the path system environment variable).

The license service provider configuration information will be kept in the NT System Registry. The configuration information which applies to the whole system be placed under the \HKEY_LOCAL_MACHINE, while information that is specific to one user should be stored under that user's profile and accessed via \HKEY_CURRENT_USER. The information in the Registry should be structured in the same way as the information in the LSAPI.INI file. There should be a "LSAPI" sub-key under the \HKEY_LOCAL_MACHINE\SOFTWARE and \HKEY_CURRENT_USER\SOFTWARE sub-keys. "LSAPI" should have two default sub-keys called "SETTINGS"" and "PROVIDERS" and a sub-key for each license service provider. There should be a value under "SETTINGS" called "ORDER", which should be a string with the order information. There should be values under "PROVIDERS" with names of the form PROVIDERx", where "x" is an integer ID for that provider.

A sample follows:

\HKEY_CURRENT_USER\SOFTWARE\LSAPI\SETTINGS\ORDER=2 1 3 4

\HKEY_CURRENT_USER\SOFTWARE\LSAPI\PROVIDERS\Provider1=C:\WINDOWS\...

\HKEY_CURRENT_USER\SOFTWARE\LSAPI\PROVIDERS\Provider2=C:\WINDOWS\...

\HKEY_CURRENT_USER\SOFTWARE\LSAPI\PROVIDERS\Provider3=C:\WINDOWS\...

\HKEY_CURRENT_USER\SOFTWARE\LSAPI\PROVIDERS\Provider4=C:\WINDOWS\...

SubKeys of \HKEY_CURRENT_USER\ SOFTWARE\LSAPI

Description

SETTINGS\ORDER

This defines the default order in which license system providers are queried for a particular license. An order of "2 1 3 4" indicates that Provider2 is to be queried first, Provider1 second, etc. Note that each number is separated by a space.

If any providers are listed which do not appear in this list, they will be queried after the listed providers. These providers will be queried in the order in which they appear in the PROVIDERS\ section.

PROVIDERS\ProviderN

One entry for each license system provider installed on the client. Each license system must create a key with a unique value for N. The value is set to the full pathname to the DLL, a semicolon (;), the interface specification version number provided in the DLL (for now, all are 1.00); another semicolon followed by a brief text description of the particular license system. The entire line must not exceed 512 characters.

Vendor-Name\...

Vendors that wish to use the registration database for private configuration information may create a key: \HKEY_CURRENT_USER\SOFTWARE\LSAPI\Vendor-Name where the name is a unique trademark name. Below that, the vendor may create keys of its own choosing. At this time, it is recommended that provider developers limit the amount of private configuration information stored into the registry.


Contact Microsoft's Developer Relations Group at (425) 882-8080 for further information.