Acquiring the Use License

The AcquirePreLicense SOAP method will obtain a use license on behalf of another person. This is an optional step because a requesting user could obtain their own use license for content. However, obtaining a use license in advance and packaging it inside a requested file allows the user to use the content immediately, without having to connect to a network (providing that the user has rights to the content, and the user's computer has been properly activated).

The following C# example shows how to call the AcquirePreLicense SOAP method.

// Function takes in a signed issuance license and a user ID, 
// and returns an array that consists of the use license, followed 
// byindividual certificates leading back to the root certificate.
// These must be concatenated into a single chain for the end user.
public override string[] AcquireEndUserLicense(
                          string signedPL, 
                          string userId)
{
    // Verify that parameters are valid.
    if (signedPL == null || userId == null)
        throw new ArgumentNullException();

    // Create variables to hold license request parameters 
    // and responsefor the AcquirePreLicenseParams method.
    RmsLicenseProxy.AcquirePreLicenseParams[] _params;
    RmsLicenseProxy.AcquirePreLicenseResponse[] _response;
    string[] licResponse;
    string[] Identities;


    // Set request parameter values. 
    _params = new RmsLicenseProxy.AcquirePreLicenseParams[1];
    _params[0] = new RmsLicenseProxy.AcquirePreLicenseParams();

    // Enter identities of license requesters.
    Identities = new string[1];
    Identities[0] = userId;
    _params[0].LicenseeIdentities = Identities; 

    // Change signed issuance license string into XmlNode object.
    XmlDocument xmld = new XmlDocument();
    xmld.LoadXml(signedPL);
    _params[0].IssuanceLicense = new XmlNode[] {xmld.DocumentElement};

    _params[0].ApplicationData = null;

    // Set parameters on AcquirePreLicense SOAP proxy. 
    m_srvLicense.Url = 
          RMSHost + @"/license.asmx";
    m_srvLicense.VersionDataValue = 
          new RmsLicenseProxy.VersionData();
    m_srvLicense.VersionDataValue.MinimumVersion = 
          DataVersionConstants.MinimumVersion;
    m_srvLicense.VersionDataValue.MaximumVersion = 
          DataVersionConstants.MaximumVersion;
    m_srvLicense.Credentials = 
          CredentialCache.DefaultCredentials;


    // Acquire use license. 
    _response = m_srvLicense.AcquirePreLicense(_params);

    // Response holds number of certificates in the chain, 
    // plus 1 use license. If multiple identies are specified in 
    // the call, you will have multiple licenses and a single chain.
    licResponse = new string[_response[0].CertificateChain.Length + 1];

    // Copy use license. Assume just one.
    licResponse[0] = _response[0].Licenses[0].OuterXml;

    // Convert XmlNode array into a string array and add
    // to the response array.
    string[] responseChain = GetStringChainFromXmlnChain(
                               _response[0].CertificateChain);
    responseChain.CopyTo(licResponse, 1);

    return licResponse;
 }

The string array that is returned by AcquirePreLicense must be changed into an array that a rights management–consuming application can use. In the example, this is done by using the rights management publishing function DRMConstructCertificateChain. This function must be called twice: once to return the size of the variable that is needed to hold the returned chain, and a second time to perform the actual concatenation.

To reformat the values returned in AcquirePreLicenseResponse

1. Convert each AcquirePreLicenseResponse.CertificateChain value into a string array.

2. Convert the corresponding AcquirePreLicenseResponse.Licenses value into a string value.

3. Append the license as an initial element in the certificate chain array.

4. Pass the resulting string array into DRMConstructCertificateChain to create a certificate chain that can be used by a rights management–consuming application to acquire a use license, as shown in the following C# function. // Takes in a string certificate chain, and converts it into // a chain that rights management publishing functions can use. private StringBuilder CreateMsdrmCompatibleChain(string[] LicensorCertChain) { uint chainLen = (uint)LicensorCertChain.Length;
   uint nLenChain = 0; StringBuilder szChain = null;

       Nmc.Check(DRMConstructCertificateChain(
           chainLen,               // Chain length passed in.
           LicensorCertChain,      // Certificate chain array.
           ref nLenChain,          // [out]
                                   // Size of variable needed to hold returned chain.
           szChain ));             // Null on first call.
   
       // Allocate the string builder with the length specified. 
       if (nLenChain > 0)
       {
           szChain = new StringBuilder((int)nLenChain);
       }
   
       // Obtain the certificate chain.
       Nmc.Check(DRMConstructCertificateChain(
           chainLen,
           LicensorCertChain, 
           ref nLenChain, 
           szChain ));
   
       return szChain;
   }
   

This chain can now be added to the file.

See Also

Adding the Use License to the Compound File
Building a Protected Document Library

Send comments about this topic to Microsoft

Build date: 3/13/2008