Activating a Computer Programmatically with AD RMS
Overview
Before a specific computer can be used to encrypt or decrypt content, you must sign it into the Active Directory Rights Management Services (AD RMS) Pre-production or Production certificate hierarchy. This process, called activating a computer, returns a certificate chain. The root of the chain is a Microsoft certification authority (CA) certificate, and the chain ends with a signed machine certificate that uniquely identifies the computer being used. You can use the DRMActivate function to activate a computer. This is an asynchronous function that returns immediately to your application while processing the activation request on another thread. It delivers the result to a callback function that you must create. After you activate the computer, you must also activate the account of the logged-on user to retrieve a rights account certificate that signs the account into the same hierarchy as the computer. For more information, see Activating a User Programmatically with AD RMS. Activating a computer that has already been activated overwrites the machine certificate, thereby requiring that you also renew the rights account certificate. Therefore, you should check the current activation state to avoid inadvertently activating the computer more than once. You can call DRMIsActivated to check the state. Computer activation is performed locally by the AD RMS client. There is no interaction with an AD RMS activation service. The client notifies your callback function when activation is complete and then installs the machine certificate in the appropriate store.
Machine Certificates
An Active Directory Rights Management Services (AD RMS) machine certificate identifies a computer by signing it into the Pre-production or Production certificate hierarchy. Machine certificates are created when a computer is activated. One machine certificate is installed for each user who activates the computer into the hierarchy. Each certificate typically contains the following elements:
- The issuance date and time.
- A certificate type ID and name.
- The name and ID of the issuer.
- The location from which the certificate was retrieved.
- The principal ID, public key, digest and security processor.
- A signature created by using the private key of the AD RMS activation service.
- A certificate chain that contains the server licensor certificate and one or more CA certificates.
The following diagram shows the basic XrML structure of the certificate. For a more complete example, see Machine Certificate XML Example.
- <XrML version="1.2" >
- <BODY >
+ <ISSUEDTIME>
+ <DESCRIPTOR>
+ <ISSUER>
+ <DISTRIBUTIONPOINT>
+ <ISSUEDPRINCIPALS>
</BODY>
<SIGNATURE>
+ <DIGEST>
<ALGORITHM />
<VALUE />
</SIGNATURE>
</XrML>
- <XrML version "1.2"> <!-- server licensor certificate -->
- <XrML version "1.2"> <!-- DRM-CA-Certificate -->
- <XrML version "1.2"> <!-- DRM-CA-Certificate -->
- <XrML version "1.2"> <!-- DRM-CA-Certificate -->
Machine Certificate Store
The machine certificate is named CERT-Machine.drm and is installed in one of the following folders, depending on the Active Directory Rights Management Services (AD RMS) version and on the operating system.
Version Certificate location
AD RMS on Windows Vista and Windows Server 2008 using the client lockbox: %USERPROFILE%\AppData\Local\Microsoft\DRM
AD RMS on Windows Vista and Windows Server 2008 using the server lockbox: %ALLUSERSPROFILE%\Microsoft\DRM\Server\UserSid
RMS client 1.0 SP2 using the client lockbox: %USERPROFILE%\Local Settings\Application Data\Microsoft\DRM
RMS server 1.0 SP2 using the server lockbox: %ALLUSERSPROFILE%\Application Data\Microsoft\DRM\Server\UserSid
Machine Certificate XML Example
The following example shows an XrML machine certificate. To see an actual machine certificate, activate the computer, navigate to the appropriate Machine Certificate Store, and open the CERT-Machine.drm file.
- <XrML version="1.2" >
- <BODY type="LICENSE" version="3.0">
<ISSUEDTIME>2008-03-17T15:49</ISSUEDTIME>
- <DESCRIPTOR>
- <OBJECT type="Machine-Certificate">
<ID type="MS-GUID">
{958E4BE1-6B28-4C3D-9DEC-EA5B36169085}\
</ID>
<NAME>Microsoft Machine-Certificate</NAME>
</OBJECT>
</DESCRIPTOR>
- <ISSUER>
- <OBJECT type="MS-DRM-Desktop-Security-Processor">
<ID type="MS-GUID">
{d250be5b-50f1-48e6-81a5-6003ccf9cb44}
</ID>
<NAME>
Microsoft DRM ISV Desktop Security Processor
Activation Certificate
</NAME>
</OBJECT>
- <PUBLICKEY>
<ALGORITHM>RSA</ALGORITHM>
- <PARAMETER name="public-exponent">
<VALUE encoding="integer32">65537</VALUE>
</PARAMETER>
- <PARAMETER name="modulus">
<VALUE encoding="base64" size="1024">
z9738mlRsvk7jRuUMUMe89JWYVVeF6MwjilbtTFgMyIvU6lbbbOjbgT3
3vzLRA8opv4u6YzK30dlFzzN3UwKX4LqKmUr7kbg0bUtMM3UK0UvfnWX
+ucPVR8K7cRX/g9ZOh+MgNllKfsmQv5nG48w0I0q/cpmDlYrqwBGGAD8
isk=
</VALUE>
</PARAMETER>
</PUBLICKEY>
</ISSUER>
- <DISTRIBUTIONPOINT>
- <OBJECT type="Activation">
<ID type="MS-GUID">
{99F48562-703E-4E7D-9175-DD69C66921B7}
</ID>
<NAME>Microsoft Activation</NAME>
<ADDRESS type="URL">file:///rmactivate.exe</ADDRESS>
</OBJECT>
</DISTRIBUTIONPOINT>
- <ISSUEDPRINCIPALS>
- <PRINCIPAL>
- <OBJECT type="Machine-Unique-Identifier">
<ID type="MS-GUID">
{8a0acfdb-b60f-49bd-a781-f6b41e876219}
</ID>
<NAME>Machine</NAME>
</OBJECT>
- <PUBLICKEY>
<ALGORITHM>RSA</ALGORITHM>
- <PARAMETER name="public-exponent">
<VALUE encoding="integer32">65537</VALUE>
</PARAMETER>
- <PARAMETER name="modulus">
<VALUE encoding="base64" size="1024">
2Q7nZtumLn6yIlt2xYpaNAi8Ffgk0yKOXOZXAJ423SnhkAl9Ge2WOw
adHYTqT9wtX9dc9WTA32MU+4jcTgO4qouMvKHwBF9vXI1v37tY0bqY
KrrCz3QmtDhDSwt8RZvoBVavh2nAggv3XeEA7RWRtG0DVXKjuOnyEN
6iFzEzhbs=
</VALUE>
</PARAMETER>
</PUBLICKEY>
- <DIGEST>
<ALGORITHM>SHA1</ALGORITHM>
- <PARAMETER name="codingtype">
<VALUE encoding="string">surface-coding</VALUE>
</PARAMETER>
<VALUE encoding="base64" size="160">
i8m+LJyoj+3ou1XLohjh+O+V0to=
</VALUE>
</DIGEST>
<SECURITYLEVEL name="Platform" value="2.6.0.6000" />
<SECURITYLEVEL
name="Manufacturer"
value="Microsoft Corporation mcoregen DLL 6.0.5840.16389
(RMS Client v2.0 Desktop Security Processor)" />
<SECURITYLEVEL
name="Repository"
value="Microsoft Corporation Windows RMS Client v2.0
secure repository 6.0.5840.16389" />
</PRINCIPAL>
</ISSUEDPRINCIPALS>
</BODY>
- <SIGNATURE>
- <DIGEST>
<ALGORITHM>SHA1</ALGORITHM>
- <PARAMETER name="codingtype">
<VALUE encoding="string">surface-coding</VALUE>
</PARAMETER>
<VALUE encoding="base64" size="160">
HbcVyJiDVTCu+cymql4BY4BpjUA=
</VALUE>
</DIGEST>
<ALGORITHM>RSA PKCS#1-V1.5</ALGORITHM>
<VALUE encoding="base64" size="1024">
TlPe5eNPl+89wF2prAmgcjs54hnnA/GQzUVds37UaTOlaMvs7CCnNmw+q5ui1q
cFyYWSOpQW9FU4xt3aWn2oJIPfyuwuF2s+eQBxzX3l7PuGiTVTx6I09yK5mgyj
AZDrS407znQzQ4VV9glsda1lhZYYLh8khDgwTVcn5AbjSQY=
</VALUE>
</SIGNATURE>
</XrML>
.
.
. - <XrML version="1.2">
- <XrML version="1.2">