mirror of https://github.com/lianthony/NT4.0
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
546 lines
13 KiB
546 lines
13 KiB
/*++ BUILD Version: 0001 // Increment this if a change has global effects
|
|
|
|
Copyright (c) 1994, 1995 Microsoft Corporation.
|
|
All rights reserved.
|
|
|
|
MODULE NAME:
|
|
|
|
license.h
|
|
|
|
ABSTRACT:
|
|
|
|
License APIs to support MSLSP32.DLL, the Microsoft LSAPI-compliant
|
|
license service provider.
|
|
|
|
CREATED:
|
|
|
|
1995-08-31 Jeff Parham (jeffparh)
|
|
|
|
REVISION HISTORY:
|
|
|
|
--*/
|
|
|
|
#ifndef LSAPI_LICENSE_H
|
|
#define LSAPI_LICENSE_H
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
// MACROS //
|
|
//////////////
|
|
|
|
// minimum length of product identifiers guaranteed to be unique
|
|
// (defined in the LSAPI spec)
|
|
#define LS_PUBLISHER_UNIQUE_SUBSTR_LENGTH ( 32 )
|
|
#define LS_PRODUCT_UNIQUE_SUBSTR_LENGTH ( 32 )
|
|
#define LS_VERSION_UNIQUE_SUBSTR_LENGTH ( 12 )
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
// TYPE DEFINITIONS //
|
|
////////////////////////
|
|
|
|
typedef LS_VOID * LS_LICENSE_HANDLE;
|
|
|
|
// units associated with a license
|
|
typedef struct _LS_LICENSE_UNITS
|
|
{
|
|
LS_ULONG lsulTotalUnits;
|
|
LS_ULONG lsulMaximumDesiredUnits;
|
|
} LS_LICENSE_UNITS;
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
// PROTOTYPES //
|
|
//////////////////
|
|
|
|
LS_STATUS_CODE
|
|
LicenseListCreate( LS_VOID );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Initializes the license list.
|
|
|
|
Arguments:
|
|
|
|
None.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
LS_SYSTEM_INIT_FAILED
|
|
Could not initialize the license list.
|
|
--*/
|
|
|
|
LS_VOID
|
|
LicenseListDestroy( LS_VOID );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Destroys the license list (the antithesis to LicenseListCreate).
|
|
|
|
Arguments:
|
|
|
|
None.
|
|
|
|
Return Value:
|
|
|
|
None.
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseListLock( LS_VOID );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Locks the license list such that no other threads (of this or any other
|
|
process) may make any changes to license information until
|
|
LicenseListUnlock() is called.
|
|
|
|
Arguments:
|
|
|
|
None.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
LS_SYSTEM_ERROR
|
|
A system error occurred while trying to obtain the lock.
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseListUnlock( LS_VOID );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Unlocks the license list such that other threads may make changes to
|
|
license information.
|
|
|
|
Arguments:
|
|
|
|
None.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
LS_SYSTEM_ERROR
|
|
An unexpected system error occurred.
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseUnitsReserve( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_ULONG lsulUnitsReserved,
|
|
LS_ULONG * plsulUnitsGranted );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Attempts to reserve enough license units to satisfy the given
|
|
license requirement. Note that LS_SUCCESS is returned as long as no
|
|
unexpected errors are encountered, even though the units requested may
|
|
not have been granted.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to reserve units.
|
|
lsulUnitsReserved (LS_ULONG)
|
|
Number of units the application wishes to reserve.
|
|
plsulUnitsGrantedNone (LS_ULONG *)
|
|
On return, holds the number of units actually granted. This value
|
|
should be between 0 and the number of units reserved, inclusive.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
As many units as required (or as many as was possible, perhaps none)
|
|
have been granted.
|
|
LS_BAD_HANDLE
|
|
The given license handle is invalid.
|
|
other
|
|
error return from LicenseListLock(), LicenseUnitsGet(), or
|
|
LicenseUnitsSet()
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseOpen( LS_STR * PublisherName,
|
|
LS_STR * ProductName,
|
|
LS_STR * Version,
|
|
LS_STR * pszUserName,
|
|
LS_LICENSE_HANDLE * plslhLicenseHandle );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Open a handle to the given license to be used in subsequent License API
|
|
calls.
|
|
|
|
A license need not exist for this routine to succeed.
|
|
|
|
If the return value is LS_SUCCESS, the handle must eventually be
|
|
LicenseClose()'d.
|
|
|
|
Arguments:
|
|
|
|
PublisherName (LS_STR *)
|
|
Name of the publisher for which to open a license.
|
|
ProductName (LS_STR *)
|
|
Name of the product for which to open a license.
|
|
Version (LS_STR *)
|
|
Version of the product for which to open a license.
|
|
pszUserName (LS_STR *)
|
|
User name for which to open a license. A NULL value indicates that the
|
|
license should be opened for the username corresponding to the current
|
|
thread.
|
|
plslhLicenseHandle (LS_LICENSE_HANDLE *)
|
|
On return, and if LS_SUCCESS is returned, holds the opened handle.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Handle successfully opened. The handle must eventually be closed
|
|
with LicenseClose().
|
|
LS_RESOURCES_UNAVAILABLE
|
|
Memory could not be allocated.
|
|
other
|
|
error return from LicenseReload() or LicenseKeyNameDerive()
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseClose( LS_LICENSE_HANDLE lslhLicenseHandle );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Releases a license instance previously allocated via a successful
|
|
LicenseOpen().
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License to release.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseUnitsGet( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_LICENSE_UNITS * plsluLicenseUnits );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Retrieve the purchased, currently leased, and maximum desired units for
|
|
the given license.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to obtain units.
|
|
plsluLicenseUnits (LS_LICENSE_UNITS *)
|
|
On return, and if return value is LS_SUCCESS, holds the units for this
|
|
license.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
other
|
|
Error return from LicenseListLock() or LicenseReload().
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseUnitsSet( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_LICENSE_UNITS * plsluLicenseUnits );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Set the purchased, currently leased, and maximum desired units for
|
|
the given license.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to set units.
|
|
plsluLicenseUnits (LS_LICENSE_UNITS *)
|
|
Values for the individual unit tallies.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
LS_SYSTEM_ERROR
|
|
An unexpected system error occurred accessing the registry.
|
|
other
|
|
Error return from LicenseListLock() or LicenseReload().
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseChallengeVerify( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_CHALLDATA * plscdSent,
|
|
LS_STR * pszFormat,
|
|
... );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Verify the signature for the given data.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to verify the challenge.
|
|
plscdSent (LS_CHALLDATA *)
|
|
The signature given by the application.
|
|
pszFormat (LS_STR *)
|
|
Format of the parameters which comprise the data signed. The
|
|
format is comprised solely of "%u" or "%s" entries, corresponding to
|
|
unsigned 32-bit values and string values, resp.
|
|
...
|
|
Parameters for pszFormat.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
LS_BAD_ARG
|
|
The signature is invalid.
|
|
other
|
|
Error return from LicenseChallengeCompute().
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseChallengeSign( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_CHALLDATA * plscdChallData,
|
|
LS_STR * pszFormat,
|
|
... );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Sign the given data. A signature is optionally given and verified by both
|
|
the application and LSAPI using the license secrets to help protect against
|
|
spoofing.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to verify the challenge.
|
|
plscdChallData (LS_CHALLDATA *)
|
|
On return, holds the computed signature.
|
|
pszFormat (LS_STR *)
|
|
Format of the parameters which comprise the data to be signed. The
|
|
format is comprised solely of "%u" or "%s" entries, corresponding to
|
|
unsigned 32-bit values and string values, resp.
|
|
...
|
|
Parameters for pszFormat.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
other
|
|
Error return from LicenseChallengeCompute().
|
|
|
|
--*/
|
|
|
|
BOOL
|
|
LicenseUnitsExist( LS_LICENSE_HANDLE lslhLicenseHandle );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Check if any units have been purchased for the given license.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License to check.
|
|
|
|
Return Value:
|
|
|
|
(BOOL)
|
|
TRUE
|
|
At least one unit has been purchased for the given license.
|
|
FALSE
|
|
An error occurred in the lookup operation, or no units exist for
|
|
this license.
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseUnitsConsume( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_ULONG lsulUnitsConsumed );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Consume the given number of units of the specified license. These units
|
|
are permanently removed from the license system.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to consume the units.
|
|
lsulUnitsConsumed (LS_ULONG)
|
|
Number of units to consume.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
other
|
|
Error return from LicenseListLock(), LicenseUnitsGet(), or
|
|
LicenseUnitsSet().
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseSecretSet( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_ULONG lsulSecretIndex,
|
|
LS_ULONG lsulSecret );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Set the secret at the given index for the specified license.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to set the secret.
|
|
lsulSecretIndex (LS_ULONG)
|
|
Index of the secret to set. Secrets are normally in the range
|
|
1 to 4, though any index is acceptable.
|
|
lsulSecret (LS_ULONG)
|
|
Value to which to set the secret.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
LS_SYSTEM_ERROR
|
|
An unexpected system error occurred.
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseTypeSet( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_LICENSE_TYPE lsltLicenseType );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Set the license type (e.g., per seat, per user) for the given license.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to change type.
|
|
lsltLicenseType (LS_LICENSE_TYPE)
|
|
Type to which to change the license. Valid values are
|
|
LS_LICENSE_TYPE_NODE (per seat) and LS_LICENSE_TYPE_USER (per user).
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
LS_SYSTEM_ERROR
|
|
An unexpected error occurred accessing the registry.
|
|
other
|
|
Error return from LicenseListLock() or LicenseListReload().
|
|
--*/
|
|
|
|
LS_STATUS_CODE
|
|
LicenseTypeGet( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_LICENSE_TYPE * plsltLicenseType );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Get the license type (e.g., per seat, per user) for the given license.
|
|
The type returned is the current type saved in the registry, which may
|
|
be different from the type reflected in memory.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to change type.
|
|
plsltLicenseType (LS_LICENSE_TYPE *)
|
|
On return, the type of the license as reflected in the current
|
|
registry settings. Valid values are LS_LICENSE_TYPE_NODE (per seat)
|
|
and LS_LICENSE_TYPE_USER (per user).
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
other
|
|
Error return from LicenseListLock().
|
|
|
|
--*/
|
|
|
|
LS_STATUS_CODE LicenseNameGet( LS_LICENSE_HANDLE lslhLicenseHandle,
|
|
LS_STR * pszPublisherName,
|
|
LS_STR * pszProductName,
|
|
LS_STR * pszVersion );
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
Get the product name, publisher name, and version string associated
|
|
with a given license.
|
|
|
|
Arguments:
|
|
|
|
lslhLicenseHandle (LS_LICENSE_HANDLE)
|
|
License for which to return the associated strings.
|
|
pszPublisherName (LS_STR *)
|
|
pszProductName (LS_STR *)
|
|
pszVersion (LS_STR *)
|
|
On return, hold the product name, publisher name, and key name (resp.)
|
|
associated with this license. Each buffer must be at least
|
|
1 + LS_*_UNIQUE_SUBSTR_LENGTH long, where * is PUBLISHER, PRODUCT, or
|
|
VERSION, as appropriate.
|
|
|
|
Return Value:
|
|
|
|
(LS_STATUS_CODE)
|
|
LS_SUCCESS
|
|
Success.
|
|
LS_BAD_HANDLE
|
|
The given handle is invalid.
|
|
|
|
--*/
|
|
|
|
#endif // LSAPI_LICENSE_H
|