3.4.4.1 AcquireLicense Operation

  • Article

The AcquireLicense request is used to acquire a UL from the server. A UL is required for a user to access protected content. The UL describes what usage policies apply to the user while accessing a particular protected content file. It also contains the content key encrypted with the user's RAC public key. The UL is the authorization token that allows a user to access protected content.

AcquireLicense message sequence

Figure 8: AcquireLicense message sequence

 <wsdl:operation name="AcquireLicense">
     <wsdl:input message="tns:AcquireLicenseSoapIn" />
     <wsdl:output message="tns:AcquireLicenseSoapOut" />
 </wsdl:operation>

Exceptions Thrown: The AcquireLicense method SHOULD return a fault code when a failure occurs.  Details of the RMS: Client to Server Protocol SOAP Fault Format can be found in section 3.1.4.5.

Exception

Description

Microsoft.DigitalRightsManagement.Licensing.InvalidPersonaCertSignatureException

The account certificate the requestor supplied has been tampered with.

Microsoft.DigitalRightsManagement.Licensing.InvalidPersonaCertTimeException

The account certificate the requestor supplied is currently invalid.

Microsoft.DigitalRightsManagement.Licensing.UnexpectedPersonaCertException

An unexpected error was encountered while validating the account certificate.

Microsoft.DigitalRightsManagement.Licensing.UntrustedPersonaCertException

The account certificate the requestor supplied was not issued by a trusted user domain server.

Microsoft.DigitalRightsManagement.Licensing.NoRightsForRequestedPrincipalException

The PL contains no rights for the requested principal.

Microsoft.DigitalRightsManagement.Licensing.DrmacIsExcludedException

The account certificate has been excluded and is not permitted to submit this request.

Microsoft.DigitalRightsManagement.Licensing.InvalidRightsLabelSignatureException

The publishing license contains an invalid signature.

Microsoft.DigitalRightsManagement.Licensing.IssuanceLicenseIsNotWithinValidTimeRangeException

The publishing license has expired or the time specified is not within the valid time range.

Microsoft.DigitalRightsManagement.Licensing.RightsLabelNoMatchingIssuedPrincipalException

The publishing license has no issued principals corresponding to this server.

Microsoft.RightsManagementServices.ClusterDecommissionedException

A request was received, but the server is in a decommissioned state and cannot honor the request.

Microsoft.DigitalRightsManagement.Cryptography.UnsupportedCryptographicSetException

The given certificate does not contain an acceptable combination of asymmetric key and signature hash algorithms.

In the AcquireLicense operation, the client submits a signed PL chain, a RAC chain, and application data, and requests a UL chain. A properly formed AcquireLicense request MUST contain a signed PL chain, a RAC chain, and application data XML. The application data XML MAY contain a null value by way of an empty XML element. If the client specifies "1.0.0.0" as the MaximumVersion field of the VersionData header, the request MUST contain only one AcquireLicenseParams element in the RequestParams field of the AcquireLicense element.

Upon receiving an AcquireLicense request, the server SHOULD perform signature validation on the PL chain and ensure that it trusts the issuer of the PL. The server MUST know the private key that corresponds to the public key of the issuer of the PL in order to issue a UL. The server SHOULD perform signature validation on the RAC chain and verify that it trusts the RAC.

  • If the RAC chain fails signature validation, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.InvalidPersonaCertSignatureException SOAP fault code.

  • If the RAC chain is expired or not yet valid, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.InvalidPersonaCertTimeException SOAP fault code.

  • If the RAC is signed by an SLC that is not the SLC of one of the elements of the trustedRacIssuers field of ServerState, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.UntrustedPersonaCertException.

  • If the RAC public key is in the racExclusionPolicy set of ServerState, the server SHOULD return the SOAP fault Microsoft.DigitalRightsManagement.Licensing.DrmacIsExcludedException.

  • If the Repository SECURITYLEVEL in the SPC does not meet the minimum required version in the spcExclusionPolicy field of ServerState, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.BlackBoxIsInvalidException SOAP fault.

  • If a Credential-Creation-Time SECURITYLEVEL is present in the RAC and exceeds the ISSUEDTIME of the PL by more than the value of the creationTimeTolerance field of ServerState, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.CredentialCreationTimeException SOAP fault.

  • If any other errors are found validating the RAC chain, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.UnexpectedPersonaCertException SOAP fault.

  • If the federationEnabled field of ServerState is false and the RAC type is "federation" (section 2.2.9.5.4), the server SHOULD reject the request.

  • If the PL chain fails signature validation, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.InvalidRightsLabelSignatureException fault.

  • If the current time is not within the range specified by the VALIDITYTIME of the PL and the serverDecommissioned field of ServerState is false, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.IssuanceLicenseIsNotWithinValidTimeRangeException fault. 

  • If the serverDecommissioned field of ServerState is true, the server SHOULD return a Microsoft.RightsManagementServices.ClusterDecommissionedException fault.

  • If the ApplicationData field of the AcquireLicenseParams element is greater than the maximum size supported by the implementation, the server SHOULD return a Microsoft.DigitalRightsManagement.Utilities.UnspecifiedErrorException fault.<41>

  • If the RAC contains a public key length or hash algorithm that is not allowed in the cryptographic mode indicated by the cryptographicMode attribute of ServerState, the server SHOULD return a Microsoft.DigitalRightsManagement.Cryptography.UnsupportedCryptographicSetException fault.

  • If the cryptographic mode indicated by the cryptographicMode attribute of ServerState is Mode 1 cryptography and the PL contains a public key length or hash algorithm that is not allowed in Mode 1, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.RightsLabelNoMatchingIssuedPrincipalException fault.

If validation succeeds, the server SHOULD service the request. To service the request, the server SHOULD determine whether the PRINCIPAL in the ISSUEDPRINCIPALS of the PL matches the PRINCIPAL in the ISSUEDPRINCIPALS of the SLC in ServerState or the SLC in one of the elements of the trustedLicensingServers set in ServerState. If it matches its own SLC, the keyPair of the ServerState SHOULD be used to service the request. If it matches an SLC of one of the elements of the trustedLicensingServers, the SLC, keyPair, and templates of the matching TrustedLicensingServer SHOULD be used for the purposes of decrypting the PL and evaluating policy. In either case, the SLC and keyPair of the ServerState  SHOULD be used for issuing a UL. If no matching PRINCIPAL was found, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.RightsLabelNoMatchingIssuedPrincipalException fault. The server SHOULD decrypt the usage policy and content key from the PL by using the keyPair of ServerState. The server SHOULD cache the parsed PL for use in subsequent requests with the same PL SIGNATURE element, by adding a new PLCacheEntry element to the plCache field of the ServerState. This PLCacheEntry SHOULD have a plSignature field corresponding to the SIGNATURE of the PL, and a parsedPl field containing an in-memory representation of the PL. If the noRightsCacheEnabled field of the ServerState is set to true, the server SHOULD check whether there is a PLCacheEntry in the plCache field of ServerState for the PL. If so, the server SHOULD check whether the ID type and value from the ID element of the OBJECT of the PRINCIPAL of the ISSUEDPRINCIPALS of the RAC is in the racsWithNoRights field of the PLCacheEntry. If so, the server SHOULD return a Microsoft.DigitalRightsManagement.Licensing.NoRightsForRequestedPrincipalException SOAP fault. The server MUST determine if the user identified by the RAC is allowed to access the content according to the policy in the PL.

The server SHOULD follow any level of indirection in making this determination, such as group memberships, aliases, and so on. (The IsPrincipalMemberOf service is specified in [MS-RMPRS].) If the superUserEnabled field of ServerState is true and the user is a member of the group specified in the superUserGroup field of the ServerState, the user SHOULD receive the OWNER right in the UL that is generated without regard to the rights specified in the PL. If the user is the OWNER specified in the PL, the user SHOULD receive the OWNER right in the UL that is generated without regard to the rights specified in the PL. If the user is not granted any access, the server returns a Microsoft.DigitalRightsManagement.Licensing.NoRightsForRequestedPrincipalException SOAP fault. If the noRightsCacheEnabled field of the ServerState is set to true, the server SHOULD add the ID type and value from the ID of the OBJECT of the PRINCIPAL of the ISSUEDPRINCIPALS of the RAC to the racsWithNoRights field of the PLCacheEntry with a plSignature field matching the SIGNATURE of the PL. If the GUID in the DESCRIPTOR of the ERD of the PL matches the GUID of a Rights Policy Template in either the publishedTemplates field or the archivedTemplates field of the ServerState, the server SHOULD ignore the policy in the PL and instead use the policy from the matching entry in publishedTemplates or archivedTemplates.

If the user is granted some level of access according to the policy, the server SHOULD generate a UL to return to the client. The UL MUST describe the access that has been granted along with any conditions on that access as determined by the policy. The ISSUEDPRINCIPALS element of the UL SHOULD contain a PRINCIPAL element with the same values as the PRINCIPAL element of the ISSUEDPRINCIPALS element of the RAC. If the ERD of the PL contains any POLICYLIST elements, these elements MUST be included in the UL. If the server has any ApplicationExclusionEntry values in the applicationExclusionPolicy field of ServerState, corresponding POLICY elements MUST be added to a POLICYLIST in the UL with type "exclusion". If the server osExclusionEnabled field of ServerState is true, a CONDITION element based on the osExclusionPolicy field of ServerState MUST be added to the CONDITIONLIST in the UL. The UL MUST contain the content key encrypted with the RAC public key. The ISSUER element of the UL MUST contain the public key of the server. The OWNER element of the METADATA of the UL SHOULD be copied verbatim from the OWNER element of the METADATA of the PL. If the distributionpoint-ref field of the PL is present, it SHOULD be copied verbatim to the distributionpoint-ref field of the UL. The body of the UL MUST be signed by the server, and the signature MUST be included in the SIGNATURE element of the UL. The server MUST append its SLC chain to the UL to complete the UL chain. For information about certificate formats, see section 2.2.9.

For a successful request, the server MUST return a UL chain. For an unsuccessful request, the server MUST return a SOAP fault code listed above or a generic SOAP fault code. The client MUST treat all SOAP fault codes the same.

If the client specifies "1.1.0.0" as the MaximumVersion field of the VersionData header, and the server supports version "1.1.0.0", multiple ULs can be retrieved in a single request. In this case, the RequestParams element of the AcquireLicense element can contain more than one AcquireLicenseParams element. The first AcquireLicenseParams element MUST contain a PL. For subsequent AcquireLicenseParams elements, the most recent non-null PL MUST be used. The server SHOULD generate a UL for each AcquireLicenseParams element. The AcquireLicenseResult element of the AcquireLicenseResponse element MUST have one AcquireLicenseResponse value for each AcquireLicenseParams. If an error occurs while the server is processing an individual AcquireLicenseParams element, the CertificateChain element of the AcquireLicenseResponse SHOULD contain an AcquireLicenseException (section 3.4.4.1.3.5) element with the error message in place of a UL.