Using the Key Utility Object to Generate Key Information

  • Article

The Key Utility object is an add-on tool designed to provide additional content-processing and licensing features for Microsoft® Windows Media™ Rights Manager. The standard way to process content (such as media files) is by using Windows Media™ Packager and an SQL database to create packaged copies, and to use the Windows Media Rights Manager Web site to issue licenses. However, you may be using Windows Media Rights Manager in other ways, such as to package media files in batches or to integrate Windows Media Rights Manager with third-party applications. In this case, you can use the Protect tool (a command-line tool included with Windows Media Rights Manager) to package media files, and use the Key Utility object to generate the key and the key ID parameters.

This article is intended for developers who want to build tools, such as for batch processing, for Windows Media Rights Manager. To use the Key Utility object, the developer must be familiar with a language that supports COM, such as Microsoft® Visual Basic®, Microsoft® Visual C++®, and Microsoft® Visual Basic® Scripting Edition (VBScript).

This article contains information about the way keys are used and encoded, the methods in the IKeys interface, and where to go for additional information, as follows:

  • Introducing the Key Utility object

  • Using the IKeys interface

  • Additional information

On This Page

Introducing the Key Utility object Introducing the Key Utility object
Understanding how keys are used Understanding how keys are used
Using the IKeys interface Using the IKeys interface
Additional information Additional information

Introducing the Key Utility object

The Key Utility object is a COM object with one interface, IKeys, that supports seven methods. GetKey, the most important method, is used to generate the key and key ID required to encrypt and package media files.

By using this object and the Protect tool (Protect.exe), you can package a media file (such as a song or video) and distribute it on the Internet. When a consumer downloads and tries to play this unlicensed media file, the player opens the consumer's default Web browser to the license acquisition URL specified in the media file so that the consumer can acquire a license. Therefore, it is important to use the Protect tool correctly and in the same way as used by Windows Media Rights Manager.

Understanding how keys are used

Before you use the Key Utility object, it is important to understand how Windows Media Rights Manager manages and uses keys.

The following diagram shows how keys are generated for media files and their licenses. For each media file, Windows Media Packager generates a key using a license key seed (a secret value shared by Windows Media Packager and Windows Media™ License Service), and then encrypts the media file.

Each key is associated with a key ID. Windows Media Packager uses a globally unique identifier (GUID) as the key ID. However, because GUIDs are binary, they cannot be passed easily as a parameter for an executable file. So, the GUID used by Windows Media Packager is base64-encoded to generate the key ID that is placed in the content header. Each time a media file is encrypted, Windows Media Packager converts the GUID into the corresponding string, and stores this value in the database as key_guid.

To play a media file, the consumer is required to have a license that contains the same key as the media file. When the media file is played, the player sends this key ID to Windows Media License Service as part of the challenge string (the license request). With this key ID and the license key seed, Windows Media License Service can generate a license with the same key. For each license transaction, Windows Media License Service stores the encoded key ID in the database as key_id.

Figure 1: How keys are generated for media files and their licenses

Encoding schemes

Windows Media Rights Manager uses two types of encoding schemes: base64 and DRM. Base64 is a standard encoding scheme that uses the characters a-z, A-Z, 0-9, and / + =. DRM encoding is a simple variation of base64 encoding where the slash mark (/) is replaced with an asterisk (*), and the plus sign (+) is replaced with an exclamation point (!). In addition, DRM decoding works on base64-encoded strings.

Windows Media Packager uses base64 encoding, but all other components of Windows Media Rights Manager use DRM encoding and DRM decoding. The primary reason for using DRM encoding is that base64-encoded strings cannot be passed as parameters in a URL because the plus sign (+) and slash mark (/) can be interpreted.

Keyutil.dll

To use the Key Utility object, you need Keyutil.dll, which can be used with any language that supports COM. Copy this file to the Windows Media Rights Manager \bin directory. Then register it by typing regsvr32 keyutil.dll at the command prompt from that directory.

This sample file is only available from the TechNet CD product.

Using the IKeys interface

IKeys is the only interface supported by the Key Utility object:

  • Program ID: keyutil.keys

  • Class ID: {D8D08345-C796-11D2-8B0D-00C04F79EC75}

  • IKeys interface ID: (D8D08344-C796-11D2-8B0D-00C04F79EC75)

The IKeys interface supports the following seven methods:

  • Base64Decode

  • Base64Encode

  • DRMDecode

  • DRMEncode

  • GetKey

  • GuidStringToKid

  • KidToGuidString

IKeys::Base64Decode

The Base64Decode method decodes a given string. The length of the string is inferred from the length of the string in bstrCode.

Syntax

HRESULT Base64Decode(
[in] BSTR bstrCode, 
[out, retval] BSTR *pbstrPlain
);

Parameters

bstrCode

Specifies the string to be decoded.

*pbstrPlain

Pointer to the resulting decoded string.

Return values

If this method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Error code

Meaning

DISP_E_TYPEMISMATCH

The method failed.

E_FAIL

The method failed.

Example

set keyObj = CreateObject("keyutil.keys")
strEnc = "YWI="
strPlain = keyObj.Base64Decode(strEnc)
MsgBox ( strPlain )

Remarks

In the preceding example, the output will be the decoded string "ab".

IKeys::Base64Encode

The Base64Encode method encodes plain text into a base64-encoded string. The length of the plain text is inferred from the length of the string.

Syntax

HRESULT Base64Encode(
[in] BSTR bstrPlain, 
[out, retval] BSTR *pbstrCode
);

Parameters

bstrPlain

Specifies the plain text to encode.

*pbstrCode

Pointer to the resulting base64-encoded string.

Return values

If this method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Error code

Meaning

DISP_E_TYPEMISMATCH

The method failed.

E_FAIL

The method failed.

Example

set keyObj = CreateObject("keyutil.keys")
strPlain = "ab"
strEnc = keyObj.Base64Encode(strPlain)
MsgBox ( strEnc )

Remarks

In the preceding example, the output will be the encoded string "YWI=".

IKeys::DRMDecode

The DRMDecode method decodes a given string. The length of the string is inferred from the length of the string in bstrCode.

Syntax

HRESULT DRMDecode(
[in] BSTR bstrCode, 
[out, retval] BSTR *pbstrPlain
);

Parameters

bstrCode

Specifies the string to be decoded.

*pbstrPlain

Pointer to the resulting decoded string.

Return values

If this method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Error code

Meaning

DISP_E_TYPEMISMATCH

The method failed.

E_FAIL

The method failed.

Example

set keyObj = CreateObject("keyutil.keys")
strEnc = "YWI="
strPlain = keyObj.DRMDecode(strEnc)
MsgBox ( strPlain )

Remarks

In the preceding example, the output will be the decoded string "ab".

IKeys::DRMEncode

The DRMEncode method encodes plain text into a DRM-encoded string. The length of the plain text is inferred from the length of the string.

Syntax

HRESULT DRMEncode(
[in] BSTR bstrPlain, 
[out, retval] BSTR *pbstrCode
);

Parameters

bstrPlain

Specifies the plain text to encode.

*pbstrCode

Pointer to the resulting DRM-encoded string.

Return values

If this method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Error code

Meaning

DISP_E_TYPEMISMATCH

The method failed.

E_FAIL

The method failed.

Example

set keyObj = CreateObject("keyutil.keys")
strPlain = "ab"
strEnc = keyObj.DRMEncode(strPlain)
MsgBox ( strEnc )

Remarks

In the preceding example, the output will be the encoded string "YWI=".

IKeys::GetKey

The GetKey method generates the key and key ID, which are necessary to encrypt and package media files. The key is used to encrypt media files. The key ID is placed in the header of the content.

Syntax

HRESULT GetKey(
[in] BSTR bstrSeed, 
[in, out] VARIANT *pvarKID, 
[in, out] VARIANT *pvarKey
);

Parameters

bstrSeed

Specifies the license key seed, which is the secret value used for generating keys. This string can contain any characters, but the length must be between 6 and 50.

pvarKID

Pointer to the key ID used with the Protect tool (Protect.exe).

pvarKey

Pointer to the key parameter used with the Protect tool (Protect.exe).

Return values

If this method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Error code

Meaning

DISP_E_TYPEMISMATCH

The method failed.

E_FAIL

The method failed.

Example

set keyObj = CreateObject("keyutil.keys")
strSeed = "gXaSVJLA73KYFcxdXX5cqG8PHeZ1WyAshI9FLzZX"
strKid = null
call keyObj.GetKey(strSeed, strKid, strKey)
MsgBox ( strKid )
MsgBox ( strKey )
'Generate the same key again using the KID that was generated above.
call keyObj.GetKey(strSeed, strKid, strKey)

Remarks

Windows Media Packager shares the bstrSeed string with the Windows Media License Service. Windows Media Packager uses this string to generate a key to encrypt and package the content; Windows Media License Service uses this string to generate a license with the same key to unlock the content. This is a plain string and is not encoded.

The pvarKID string is placed in the content header and is usually a base64- or DRM-encoded string, but encoding is not required. The length of this string must not exceed 24 characters (the length of a base64-encoded GUID). This parameter is input/output type. If the value of this string is not null and not empty, it is used as the key ID instead of generating a new one. If the value is null, a random key ID is generated by this method. To be compatible with the key ID generated by Windows Media Packager, this string is base64-encoded.

The pvarKey string must be a base64- or DRM-encoded string that represents the key (usually a binary string). The length of this string is 7 bytes, so it is 12 bytes long when encoded, because the key size is limited to 56 bits due to export restrictions. This parameter is output only.

IKeys::GuidStringToKid

The GuidStringToKid method converts a key ID given in GUID string form into encoded GUID form (KID).

Syntax

HRESULT GuidStringToKid(
[in] BSTR bstrGuid, 
[out,retval] BSTR *pbstrKid
);

Parameters

bstrGuid

Specifies the key_guid string to convert.

*pbstrKid

Pointer to the resulting key ID in encoded form (the KID).

Return values

If this method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Error code

Meaning

DISP_E_TYPEMISMATCH

The method failed.

E_FAIL

The method failed.

Example

set keyObj = CreateObject("keyutil.keys")
strGuid = "{63ED5F91-12E5-11D3-8B3A-00C04F79EC75}"
strKid = keyObj.GuidStringToKid(strGuid)
MsgBox ( strKid )

Remarks

In the preceding example, the output will be "kV/tY+US0xGLOgDAT3nsdQ==".

The SQL database used by Windows Media Rights Manager stores key IDs in more than one table:

  • In the drm_copy_state table, the key ID is stored in GUID string form as key_guid.

  • In the drm_licenses_issued table, the key ID is stored in encoded form as key_id.

For example, with the License Server object, you can reissue licenses for a key ID other than the one in the challenge string received from the consumer. For this operation, you must use the Set method for the License Server object on the key ID, which must be in the encoded form. Before calling the Set method, if you know the key_guid string for the media file for which you want to issue the license from drm_copy_state table, then you can convert to the encoded form by using this method.

IKeys::KidToGuidString

The KidToGuidString method converts an encoded key ID (KID) to GUID string form (key_guid), which is the reverse operation of GuidStringToKid.

Syntax

HRESULT KidToGuidString(
[in] BSTR bstrKid, 
[out,retval] BSTR *pbstrGuid
);

Parameters

bstrKid

Specifies the encoded GUID (KID) to convert.

*pbstrGuid

Pointer to the resulting key_guid string.

Return values

If this method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Error code

Meaning

DISP_E_TYPEMISMATCH

The method failed.

E_FAIL

The method failed.

Example

set keyObj = CreateObject("keyutil.keys")
strKid = "kV/tY+US0xGLOgDAT3nsdQ=="
strGuid = keyObj.KidToGuidString(strKid)
MsgBox ( strGuid )

Remarks

In the preceding example, the output will be the GUID string "{63ED5F91-12E5-11D3-8B3A-00C04F79EC75}".

When a license is issued by Windows Media License Service using the IssueLicense method of the License Server object, it is possible to determine the key ID (key_id or KID) for which the license was issued using the Get method. Then, the KidToGuidString method can be used to convert the key ID to the string form (key_guid) so that you can compare this value to entries in the drm_copy_state table. You can then identify the content_id for which the license was issued.

Even though content_guid is passed with the license acquisition URL, finding the content_id is a more secure method of identifying the media file—consumers can tamper with content_guid (for example, they can edit the URL in the address bar of the Web browser), but they cannot tamper with the key ID. Several different media files can share a key_guid (meaning that the items are part of a key group), but you can combine it with the content_guid passed in the URL to uniquely identify the media file. Use the drm_content table to retrieve the content_guid for a given content_id.

Additional information

To learn more about Windows Media Rights Manager, see Windows Media Rights Manager Help. Windows Media Rights Manager is available for download from the Windows Media Technologies page at the Microsoft Web site ( https://www.microsoft.com/windows/windowsmedia/ ).

Related articles: