3.3.4.1 Certify Operation

To access protected content, the user needs a RAC that corresponds to the user's account. The RAC grants the role of a user who can access protected content. It issues an asymmetric encryption key pair and identifies the user account in the RMS system. The client uses the Certify request to acquire a RAC. The client MUST have a valid SPC before calling Certify.

Figure 7: Certify message sequence

 <wsdl:operation name="Certify">
     <wsdl:input message="tns:CertifySoapIn" />
     <wsdl:output message="tns:CertifySoapOut" />
 </wsdl:operation>

Exceptions Thrown: The Certify 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
System.UnauthorizedAccessException	The access is unauthorized.
Microsoft.DigitalRightsManagement.Core.VerifyEmailAddressFailedException	The email address is formatted incorrectly. See [RFC822] for the correct format of an email address.
Microsoft.DigitalRightsManagement.Utilities.ADEntrySearchFailedException	Failed to find an entry in the directory.
Microsoft.DigitalRightsManagement.Core.VerifyMachineCertificateChainFailedException	The machine certificate provided has a certificate chain that is not valid.
Microsoft.DigitalRightsManagement.Licensing.BlackBoxIsInvalidException	The client's RM lockbox has been revoked. The client computer MUST be reactivated to retrieve the latest RM lockbox.
Microsoft.RightsManagementServices.ClusterDecommissionedException	A request was received, but the server is in a decommissioned state and cannot process the request.
Microsoft.DigitalRightsManagement.Cryptography.UnsupportedCryptographicSetException	The given certificate does not contain an acceptable combination of asymmetric key and signature hash algorithms.

The client MUST authenticate to the server. The client SHOULD<37> use NTLM authentication, as described in [MS-NTHT], for Certify requests. If the isAuthenticated field of the RequestContext is false or the authenticationType field of the RequestContext is MWBF when the federationEnabled field of ServerState is set to false, the server SHOULD return a System.UnauthorizedAccessException SOAP fault code. If the authenticationType field of the RequestContext is not MWBF and the authenticatedAccount represents a well-known local account, the server MAY<38> replace authenticatedAccount with a DomainAccount representing the machine account of the server. The SOAP request does not encapsulate the authentication.<39>

In the Certify operation, the client authenticates to the server, submits an SPC chain, identifies a RAC type, and requests a RAC chain. A properly formed Certify request MUST contain a signed SPC chain and a flag for the RAC type. If the server decommissioned flag is set, the server SHOULD return a Microsoft.RightsManagementServices.ClusterDecommissionedException fault.

Upon receiving a Certify request, the server SHOULD validate the follow items:

• The signature of each certificate in the SPC certificate chain.

• The public key of either the first or second certificate that follows the SPC in the SPC chain is present in the trustedSpcCAKeys field of ServerState.

• The Repository SECURITYLEVEL in the SPC meets the minimum required version in the spcExclusionPolicy field of ServerState.

If this validation fails, a Microsoft.DigitalRightsManagement.Core.VerifyMachineCertificateChainFailedException SOAP fault code SHOULD be returned. If the Repository SECURITYLEVEL in the SPC does not meet the minimum required version in the spcExclusionPolicy field of ServerState, the server SHOULD return the Microsoft.DigitalRightsManagement.Licensing.BlackBoxIsInvalidException SOAP fault code. The server SHOULD ignore the values of the following SPC elements: [[- cps -]], [[- type -]] and [[- name -]] of the ISSUER element as described in section 2.2.9.4.2. If the SPC or any certificate in the SPC certificate chain contains public key lengths or hash algorithms that are not allowed in the cryptographic mode indicated by the cryptographicMode attribute of ServerState, the server SHOULD return a Microsoft.DigitalRightsManagement.Cryptography.UnsupportedCryptographicSetException fault.

If validation succeeds, the server SHOULD service the request. To service the request, the server SHOULD generate a new RAC chain. To generate a RAC chain, the server MUST provide a unique asymmetric key pair for the user. The server SHOULD invoke the GetUserKeyPair abstract interface, passing in a string identifying the user. If the authenticationType of the RequestContext is MWBF, the string SHOULD be the emailAddress of the authenticatedAccount of the RequestContext. Otherwise, the string SHOULD be the SID of the authenticatedAccount of the RequestContext. If the return value is null, the server MUST generate a unique asymmetric key pair for the user. If a new key pair is generated, the server SHOULD invoke the SetUserKeyPair abstract interface, passing in a string identifying the user, as described previously, and the generated key pair. The server SHOULD store the RAC if the persistRac field of ServerState is true. The VALIDITYTIME element of the RAC SHOULD be computed using the racValidityTime field of ServerState. If the request is for a temporary certificate, the tempRacValidityTime field of ServerState SHOULD be used. If the request was authenticated using Microsoft Web Browser Federated Sign-On authentication, the federatedRacValidityTime field of ServerState SHOULD be used. To account for clock differences between the clock and the server, the server SHOULD subtract an amount of time equal to the certificateValidityTimeTolerance field of ServerState from the ISSUEDTIME to compute the FROM value of the VALIDITYTIME. If the request is for a persistent RAC, the RACtype of the ISSUEDPRINCIPALS (section 2.2.9.5.4) MUST be a SECURITYLEVEL element with the name "Group-Identity-Credential-Type" and a value of "Persistent". If the request is for a temporary RAC, the RACtype of the ISSUEDPRINCIPALS MUST be a SECURITYLEVEL element with the name "Group-Identity-Credential-Type" and a value of "Temporary".

The server processes the ISSUEDPRINCIPALS element differently, depending on the type of authentication used:

Microsoft Web Browser Federated Sign-On (MWBF) authentication: The userid of the ISSUEDPRINCIPALS MUST be a GUID. This GUID MUST be unique for each authenticated email address. The emailaddress of the ISSUEDPRINCIPALS MUST be the value of the emailAddress field of the authenticatedAccount of the RequestContext. If the email address is not properly formatted, a Microsoft.DigitalRightsManagement.Core.VerifyEmailAddressFailedException SOAP fault code SHOULD be returned by the server. See [RFC822] for the correct format of an email address. The emailalias of the ISSUEDPRINCIPALS SHOULD be populated using the values of the proxyAddresses field of the authenticatedAccount of the RequestContext.

Non-MWBF authentication: The userid of the ISSUEDPRINCIPALS MUST be the SID field of the authenticatedAccount of the RequestContext. The emailaddress of the ISSUEDPRINCIPALS MUST be the value returned by GetEmailAddressForAccount for the authenticatedAccount of the RequestContext. If the email address is not properly formatted, a Microsoft.DigitalRightsManagement.Core.VerifyEmailAddressFailedException SOAP fault code SHOULD be returned by the server. See [RFC822] for the correct format of an email address. If GetEmailAddressForAccount returns NULL, the server SHOULD return a Microsoft.DigitalRightsManagement.Utilities.ADEntrySearchFailedException SOAP fault code. The emailalias of the ISSUEDPRINCIPALS MUST NOT be present when MWBF authentication is not used.

The RAC MUST contain the user's public key in the ISSUEDPRINCIPALS element. The RAC MUST contain the user's private key, encrypted to the SPC public key, in the FEDERATIONPRINCIPALS element. The server MUST include a DISTRIBUTIONPOINT (section 2.2.9.5.3) of type "Activation". The ADDRESS element SHOULD contain the baseUrl of the ServerState followed by "/certification". If the externalCertificationUrl of the ServerState is not null, the server SHOULD include a DISTRIBUTIONPOINT of type "Extranet-Activation". The ADDRESS element SHOULD contain the externalCertificationUrl.  The ISSUER element of the RAC MUST be copied from the ISSUEDPRINCIPALS element of the server's SLC. The SIGNATURE element of the RAC MUST be generated using the server's private key. The server's entire SLC chain MUST be appended to the RAC to form the RAC chain. For more information on the RAC chain, see section 2.2.9.5.

For a successful request, the server MUST return a RAC chain. If the federationEnabled field of ServerState is true and the user is calling the interface for Federated Identity, then a RAC with the type "federation" SHOULD be returned. 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. For information on Certificate formats, see section 2.2.9.