LS_CHALLDATA

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LS_CHALLDATA structure is passed in the LS_CHALLENGE structure. The LS_CHALLDATA structure passes the challenge from the application to the license system, and passes the response from the license system back to the application.

typedef struct _LS_CHALLDATA { 
    LS_ULONG SecretIndex; 
    LS_ULONG Random; 
    LS_MSG_DIGEST MsgDigest; 
} LS_CHALLDATA; 
 

Members

SecretIndex
Specifies the index of the secret value to be challenged. Note: The secret index is 1-based, so the first secret must have an index of 1.
Random
Specifies a random 32-bit value.
MsgDigest
Structure that contains the message digest that is computed by the MD4 Message-Digest Algorithm from RSA Data Security, Inc.

Remarks

In the basic challenge protocol, the application must choose the index of the secret to be challenged, and it must generate a random number. It must then compute a message digest using the MD4 Message-Digest Algorithm. The input to the algorithm is formed by concatenating the input parameters to the function being called, the random number, the index of the secret to be challenged, and the actual secret value. The first input parameter should be the name of the license service function being called, either LSRequest or LSUpdate. All parameters should be in the order specified in the prototypes for those functions, and you should exclude the values of the Challenge and LicenseHandle parameters. Copy string parameters without null terminators. The application then passes the algorithm output to the license system.

The license system authenticates the message digest and computes a new message digest consisting of the input parameters to the license service function, the output parameters, the random number, the index of the secret to be challenged, and the actual secret value. The last output parameter should be the returned status. This new message digest is passed back to the application, which, in turn, authenticates it. All parameters should be in the order specified in the prototypes for the LSRequest or LSUpdate function, and you should exclude the values of the Challenge and LicenseHandle parameters. Note that the actual secret value never passes between the application and the license system in plain text.

If the function h(x) is the algorithm that, given input x, returns the output of the MD4 Message-Digest Algorithm, then the following briefly illustrates the basic protocol.

The application passes the LS_CHALLDATA structure to the license system:

R, X, h(in + R + X + SX)

The license system passes a new LS_MSG_DIGEST to the application:

h(in + out + R + X + SX)

where R is the random number, X is the index of the secret to be challenged, in is a byte stream that encodes the input parameters, S indicates a secret, SX is the actual secret value, out is a byte stream that encodes the output parameters, and + denotes concatenation.

This data format can be invalid if the Protocol specified in the LS_CHALLENGE structure is not LS_BASIC_PROTOCOL. Other protocols may define their own LS_CHALLDATA format.

QuickInfo

  Windows NT: Requires version 3.51 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in lsapi.h.

See Also

License Service Application Programming Interface Overview, LSAPI Structures, LS_CHALLENGE, LS_MSG_DIGEST