Implementing License Revocation

Implementing License Revocation

When implementing license revocation, the license issuer must first do the following:

• Develop a client-side application, such as an ActiveX control, based on the Windows Media Format 9.5 SDK. This application is distributed to consumers as part of the content service. This application must include a way to assign a machine ID to each client computer. The IWMLicenseRevocationAgent interface in the Windows Media Format 9.5 SDK provides the methods needed for this application.
• Using the WMRMKeys.GenerateSigningKeys method, generate a public-private key pair for license revocation, which will be used to ensure secure communications between the client and the license issuer. This key pair also ensures that a licensing server can revoke only its own licenses.

To issue licenses that can be revoked

When issuing licenses, the license revocation public key must be added to licenses as an attribute using the WMRMLicGen.Attribute property as follows:

WMRMLicGen.Attribute("LGPUBKEY") = YourLicenseRevocationPublicKey

Although Windows Media Rights Manager 10 SDK is required for license revocation, you can revoke licenses of previous versions if they contain the LBPUBKEY attribute.

You can also add a user ID (UID), which allows you to revoke licenses based on the user:

WMRMLicGen.Attribute("UID") = UserID

The client-side application can use these attributes as well as a key ID as criteria for revoking licenses by including them in the custom data section of the license revocation challenge.

Note   At this time, the only custom data attribute that is supported is UID.

Licenses can be revoked according to one of the following combinations of attributes:

LGPUBKEY

LGPUBKEY and UID

LGPUBKEY and KID

LGPUBKEY, UID, and KID

To generate a license revocation response

1. Use the WMRMLicenseRevocationChallenge object to retrieve the information from the license revocation challenge received from the client-side application.

   First, use the Initialize method to set the challenge information in the object.

   Then, use the following methods to retrieve information:

   • GetMachineId
   • GetTransactionId
   • GetMachinePublicKey
   • GetCustomData

2. Use the WMRMLicenseRevocationResponse object to create the license revocation response.

   First, specify the conditions for the licenses you want to delete by using the following properties:

   • CustomData (This value can only be the user ID.)

   • KeyId

     Note   You can specify only one key ID per license revocation response. If you want to revoke licenses for multiple key IDs, you must generate one response for each key ID.

   Specify the transaction ID by using the TransactionId property.

   Specify the license revocation public key by using the RevocationPublicKey property.

   Sign and generate the license revocation response by using the GenerateSignedResponse method. The license revocation response is signed with the license revocation private key and is encrypted with the client's public key.

The client receives the license revocation response, decrypts it using its own private key, and verifies the signature by using the license revocation public key. Then, the client deletes the licenses that meet the conditions specified in the license revocation response and sends back an acknowledgement.

Example Code

'"""""""""""""""""""""""""""""""""""""""""""""""""""""
' Declare variables.
'"""""""""""""""""""""""""""""""""""""""""""""""""""""
Dim LRChallengeObj       ' WMRMLicenseRevocationChallenge object
Dim LRResponseObj        ' WMRMLicenseRevocationResponse object

Dim LRChallString        ' License revocation challenge string
Dim ClientMachineID      ' Value that identifies the client computer
Dim CustomDataArray      ' Array to hold the custom data
Dim CustomDataItem       ' Counter
Dim UIDValue             ' User ID value
Dim KIDValue             ' Key ID value
Dim ChallTransID         ' Transaction ID in the challenge
Dim ClientPubkey         ' Public key of the client computer
Dim CustomDataString     ' Custom data included by the client plug-in
Dim KeyID                ' Key ID identifying the licenses to revoke
Dim LRPubkey             ' Public key for license revocation
Dim LRPrivkey            ' Private key for license revocation
Dim LRResponseString     ' License revocation response string

'"""""""""""""""""""""""""""""""""""""""""""""""""""""
' Set variables.
'"""""""""""""""""""""""""""""""""""""""""""""""""""""
LRChallString = "<Replace this with a challenge string>"
LRPubkey = "<Replace this with the license revocation public key>"
LRPrivkey = "<Replace this with the license revocation private key>"


'"""""""""""""""""""""""""""""""""""""""""""""""""""""
' Set the license revocation challenge into the 
' WMRMLicenseRevocationChallenge object. Retrieve the client
' computer ID, public key, transaction ID, and custom data.
'"""""""""""""""""""""""""""""""""""""""""""""""""""""
Set LRChallengeObj = Server.CreateObject("WMRMObjs.WMRMLicenseRevocationChallenge")
Call LRChallengeObj.Initialize(LRChallString)
ClientMachineID = LRChallengeObj.GetMachineId
ChallTransID = LRChallengeObj.GetTransactionId
ClientPubkey = LRChallengeObj.GetMachinePublicKey
' B64Decode is a custom function (not shown) to decode the base64-encoded string.
CustomDataString = B64Decode(LRChallengeObj.GetCustomData())

'"""""""""""""""""""""""""""""""""""""""""""""""""""""
' Create the license revocation response. 
'"""""""""""""""""""""""""""""""""""""""""""""""""""""
Set LRResponseObj = Server.CreateObject("WMRMObjs.WMRMLicenseRevocationResponse")

'"""""""""""""""""""""""""""""""""""""""""""""""""""""
' Process your custom data and follow your business logic 
' to determine which licenses to delete. 
' In this example, assume the custom data specified a user ID
' (UID) of 123 and a key ID (KID) of 456; the custom data string
' would be "UID=123;KID=456;"
' So, in this sample, if a user ID is present, set it into
' the CustomData property. 
' If a key ID is present, set it into the KeyId property. 
' If both values are specified, only licenses with both
' values will be revoked.
'"""""""""""""""""""""""""""""""""""""""""""""""""""""
CustomDataArray = Split(CustomDataString, ";")
For Each CustomDataItem in CustomDataArray
    If InStr(CustomDataItem, "UID=") > 0 then      ' Specify a user ID.
        UIDValue = right(CustomDataItem, Len(CustomDataItem)-Len("UID:"))
        LRResponseObj.CustomData = UIDValue
    Elseif InStr(CustomDataItem, "KID=") > 0 then  ' Specify a key ID.
        KIDValue = right(CustomDataItem, Len(CustomDataItem) - Len("KID:"))
        LRResponseObj.KeyId = KIDValue 
    End If
Next

'"""""""""""""""""""""""""""""""""""""""""""""""""""""
' Specify the license revocation public key and the transaction ID.
' Generate the license revocation response.
'"""""""""""""""""""""""""""""""""""""""""""""""""""""
LRResponseObj.RevocationPublicKey = LRPubkey
LRResponseObj.TransactionId = ChallTransID    
LRResponseString = LRResponseObj.GenerateSignedResponse(LRPrivkey, ClientPubkey)

To process the license revocation acknowledgement

Use the WMRMLicenseRevocationAcknowledger object to process the information.

• Use the Acknowledgement property to retrieve the string.
• Use the Verify method with the client's public key to verify the signature.

Example Code

'"""""""""""""""""""""""""""""""""""""""""""""""""""""
' Declare variables.
'"""""""""""""""""""""""""""""""""""""""""""""""""""""
Dim LRAcknowledgeObj     ' WMRMLicenseRevocationAcknowledger object
Dim LRAckString          ' License revocation acknowledgement string
Dim AckTransID           ' Transaction ID in the acknowledgement string
Dim ClientPubkey         ' Public key of the client computer

'"""""""""""""""""""""""""""""""""""""""""""""""""""""
' Process the license revocation acknowledgement.
'"""""""""""""""""""""""""""""""""""""""""""""""""""""
LRAckString = "<Replace this with the license license revocation acknowledgement string>"
Set LRAcknowledgeObj = Server.CreateObject("WMRMObjs.WMRMLicenseRevocationAcknowledger")
LRAcknowledgeObj.Acknowledgement = LRAckString
AckTransID = LRAcknowledgeObj.GetTransactionId()

' Verify the signature on the string. This method fails if the signature is not valid.
' ClientPubkey was already retrieved from the license revocation challenge.
LRAcknowledgeObj.Verify(ClientPubkey)

See Also

• How License Revocation Works
• Revoking Licenses
• WMRMLicenseRevocationAcknowledger Object
• WMRMLicenseRevocationChallenge Object
• WMRMLicenseRevocationResponse Object

© 2007 Microsoft Corporation. All rights reserved.