Microsoft KB Archive/309408

= How to troubleshoot the Data Protection API (DPAPI) =

Article ID: 309408

Article Last Modified on 12/3/2007

-

APPLIES TO


 * Microsoft Windows Server 2003, Datacenter Edition (32-bit x86)
 * Microsoft Windows Server 2003, Enterprise Edition (32-bit x86)
 * Microsoft Windows Server 2003, Standard Edition (32-bit x86)
 * Microsoft Windows XP Professional
 * Microsoft Windows 2000 Advanced Server
 * Microsoft Windows 2000 Professional Edition
 * Microsoft Windows 2000 Server
 * Microsoft Windows 2000 Datacenter Server
 * Microsoft Windows NT 4.0
 * Microsoft Windows Small Business Server 2003 Premium Edition
 * Microsoft Windows Small Business Server 2003 Standard Edition

-



This article was previously published under Q309408



SUMMARY
The Data Protection API (DPAPI) helps to protect data in Windows 2000 and later operating systems. DPAPI is used to help protect private keys, stored credentials (in Windows XP and later), and other confidential information that the operating system or a program wants to keep confidential.

DPAPI is not responsible for storing the confidential information it protects. It is only responsible for encrypting and decrypting data for programs that call it, such as Windows Credential manager, the Private Key storage mechanism, or any third-party programs that call the CryptProtectData function and the CryptUnprotectData function in Windows 2000, Windows XP, or later.

Note This functionality is different from the functionality that is offered by the Windows protected store (P-store) in Windows NT 4.0. P-store is responsible for protecting and storing confidential information. DPAPI offers no storage capabilities.

This article describes how DPAPI help protect data at a basic level. It also includes information that is related to troubleshooting loss of access to DPAPI protected data in different scenarios.

For more information about how DPAPI works, visit the following Microsoft Web site:

http://msdn2.microsoft.com/en-us/library/ms995355.aspx

This article includes the following topics:
 * What DPAPI Can Protect
 * Example: Certificates and Private Keys
 * How DPAPI Works
 * DPAPI Environmental Considerations
 * DPAPI and Mandatory Profiles
 * DPAPI and Roaming Profiles
 * DPAPI and Password Changes
 * Known Issues
 * You Cannot Access DPAPI Confidential Information with Roaming Profiles in a Windows NT 4.0 Domain
 * You Cannot Access DPAPI Confidential Information After Reinstalling Windows
 * You Cannot Add or Access DPAPI Confidential Information with Mandatory Profiles
 * You Cannot Access DPAPI Confidential Information After Joining or Disjoining a Domain
 * Guidelines and Best Practices



MORE INFORMATION
Important To troubleshoot the loss of DPAPI data, you must gather the following information:
 * How does DPAPI work in your particular security environment including the local workstation version?
 * Is the workstation is joined to a domain?
 * Is the user is a member of the domain?
 * What is the operating system version that is hosting the domain?

Many problems with DPAPI occur when DPAPI is used in a Windows NT 4.0 domain. See the &quot;Known Issues&quot; section later in this article for more information.

DPAPI is used primarily by the security features of the operating system to help protect data on the user's behalf. Additionally, any third-party program can use DPAPI to help securely protect user data.

What DPAPI Can Protect
DPAPI helps protect the following items:
 * Web page credentials (for example, passwords)
 * File share credentials
 * Private keys associated with Encrypting File System (EFS), S/MIME, and other certificates
 * Program data that is protected using the CryptProtectData function

Example: Certificates and Private Keys
This section describes the difference between personal data and confidential information that DPAPI helps protect. The following list describes the placement of data during an import operation of a certificate and it describes the private key that is associated with that certificate to the user's personal store:  The certificate is encoded as a binary large object and stored as a binary value in the following file location:

%Userprofile%\Application Data\Microsoft\SystemCertificates\My\Certificates

 Note that the location of the registry key is in the local user's profile. This placement makes sure that only the logon user has access to their own certificates in typical circumstances. Certificates are not protected by DPAPI by any default Windows mechanisms. An Access Control List (ACL) is used to define who may load the user's hive and who may read the certificates that are stored in the hive. The private key that is associated with the certificate is encrypted by DPAPI and saved (in an encrypted form) in a key container as an individual file in the user's profile in the following folders:  For RSA Keys:

%Userprofile%\Application Data\Microsoft\Crypto\RSA\

 For DSA Keys:

%Userprofile%\Application Data\Microsoft\Crypto\DSA\

</ul> </li></ul>

back to the top

How DPAPI Works
Note The terms and concepts that are described in this section have been simplified for the purposes of clarity in the context of this article. Some level of detail has been omitted. For example, this article discusses a value that is derived from the user's password, but it does not describe the details of the algorithm that is used to derive the value. For a detailed description of how DPAPI works, view the Windows Data Protection white paper. To view this white paper, visit the following Microsoft Web site:

http://msdn2.microsoft.com/en-us/library/ms995355.aspx

DPAPI is a function that is used by programs and various operating system components to help protect data for a user. The operation of DPAPI is not visible to the user. DPAPI helps protect data in the security context of the user who runs the program.

DPAPI helps protect confidential information by using value data derived from a pseudo-random 512-bit number named a master key. Windows Server 2003 domain controllers use a 2048-bit RSA key, but only when the domain is running in domain functional level 2 or Windows Server 2003 mode. Each user account has one or more randomly generated master keys. The number of master keys depends on the age of the user's profile. Master keys are renewed at regular intervals. By default, this value is every 90 days.

Because master keys contain the data that is required to decrypt all the user's confidential information, the master keys must be protected. They are protected using a value that is derived from the user's password. The password is a unique value that only a user knows. Because the master key is actually encrypted using a value that is derived from the user's password, this value is used interchangeably with the user's password in the descriptions presented in this article.

back to the top

DPAPI Environmental Considerations
This section describes the environmental configurations that affect the behavior of DPAPI protection.

DPAPI and Mandatory Profiles
Mandatory profiles are read-only profiles. No updates that are made to the local copy of a mandatory profile are saved. For example, key generation is blocked in a mandatory profile. DPAPI stores the master key in the local copy of a profile and regularly creates new master keys and updates the encryption on the protected confidential information with the new master key.

Because these two conditions are incompatible, programs that depend on DPAPI to help protect confidential information do not work correctly with mandatory profiles. Programs that help protect confidential information with DPAPI that do not work correctly with mandatory profiles include EFS (private keys), Certificates with Private Keys (private keys), and Stored Credentials in Windows XP and later (credentials). Configurations that use these data types or programs are not supported.

back to the top

DPAPI and Roaming Profiles
DPAPI works as expected with roaming profiles for users and computers that are joined to an Active Directory directory service domain. DPAPI data that is stored in the profile acts exactly like any other setting or file that is stored in a roaming profile. Confidential information that the DPAPI helps protect are uploaded to the central profile location during the logoff process and are downloaded from the central profile location when a user logs on.

For DPAPI to work correctly when it uses roaming profiles, the domain user must only be logged on to a single computer in the domain. If the user wants to log on to a different computer that is in the domain, the user must log off the first computer before the user logs on to the second computer. If the user is logged on to multiple computers at the same time, it is likely that DPAPI will not be able to decrypt existing encrypted data correctly.

DPAPI on one computer can decrypt the master key (and the data) on another computer. This functionality is provided by the user's consistent password that is stored and verified by the domain controller. If an unexpected interruption of the typical process occurs, DPAPI can use the process described in the &quot;Password Reset&quot; section later in this article.

There is a current limitation with roaming profiles between Windows XP-based or Windows Server 2003-based computers and Windows 2000-based computers. If keys are generated or imported on a Windows XP-based or Windows Server 2003-based computer and then stored in a roaming profile, DPAPI cannot decrypt these keys on a Windows 2000-based computer if you are logged on with a roaming user profile. However, a Windows XP-based or Windows Server 2003-based computer can decrypt keys that are generated on a Windows 2000-based computer.

back to the top

DPAPI and Password Changes
Users in an enhanced security environment are expected to change their passwords at regular intervals. As a result, DPAPI must be able to maintain the same level of access to the user's protected data after password changes. The following methods are used to change user passwords in a Windows environment:

Password Change
In this method, there is continuity of access to the user's master keys during a password change. The DPAPI is invoked by the Winlogon component during password change operations in an Active Directory domain:
 * DPAPI receives notification from Winlogon during a password change operation.
 * DPAPI decrypts all master keys that were encrypted with the user's old passwords.
 * DPAPI re-encrypts all master keys with the user's new password.

Password Reset (Set)
In this method, an administrator forcibly resets a user password. A password reset is more complex than a password change. Because the administrator is not logged on as the user and does not have access to the user's old password, that old password cannot be used to decrypt the old master key and re-encrypt it with the new password.

In all cases of password resets, if the user's password is changed back to the last password before it was reset, access is restored to master key and, as a result, access is restored to all the confidential information it helps protect. This behavior occurs because master keys are never deleted, even when they cannot be decrypted. However, this may be an unreliable solution because you cannot expect the user to be able to always remember the old password. For example, the user's password may have been reset because the user forgot this password.

The way that DPAPI solves the password reset issue depends on the security environment where the user is authenticated.

Password Reset: Domain Users in a Windows 2000 or Later Domain

When DPAPI is used in an Active Directory domain environment, two copies of the master key are created and updated whenever an operation is performed on the master key. The first copy is protected by the user password as described earlier in this article. The second copy is encrypted with a public key that is associated with the domain controllers in the domain. The private key that is associated with this public key is known to all of the Windows 2000 and later domain controllers. Windows 2000 domain controllers use a symmetric key to encrypt and decrypt the second copy of the master key.

If the user password is reset and the original master key is rendered inaccessible to the user, the user's access to the master key is automatically restored using the backup master key in the following process:
 * The workstation sends the encrypted backup master key to a Windows 2000 or later domain controller over protected RPC.
 * The domain controller uses the private key to decrypt the user's master key.
 * The domain controller returns the unencrypted master key to the workstation.
 * The workstation re-encrypts the master key using the user's new password.

Password Reset: Windows NT 4.0 Domain

Microsoft does not recommend the use of DPAPI-enabled features (for example, EFS or Private Key storage) for users who are in a Windows NT 4.0 domain. See the &quot;Known Issues&quot; section of this article for more information.

After a password reset, a Windows 2000-based client computer restores the user's access to the DPAPI-protected confidential information automatically by using the backup master key in the same way it does if the user is in a workgroup. See the &quot;Password Reset: Windows 2000 Workstation in a Workgroup&quot; section in this article for more information about this procedure and for informational about security risks.

Windows XP in a Windows NT 4.0 domain does not keep a backup copy of the master key. For more information, see the &quot;Known Issues&quot; section in this article

Password Reset: Windows 2000 Workstation in a Workgroup

If you are using DPAPI on a stand-alone computer, two copies of the master key are created and updated whenever an operation is performed on the master key. The first copy is protected by the user password as described earlier in this article. The second copy is encrypted with a confidential value known only to the local computer account.

After a user's password has been forcibly reset and the user logs on with the new password, Windows 2000 automatically decrypts the computer-encrypted copy of the master key and re-encrypts it with the value derived from the new user password. From the user's point of view, the user's access to the confidential information that is protected by DPAPI is completely uninterrupted.

Important This behavior may affect security. Microsoft does not recommend that you use DPAPI in a default configuration like this. Microsoft recommends that you use one of the following methods for Windows 2000 stand-alone computers that contain sensitive data that may be physically compromised: <ul> Upgrade to Windows XP</li> Use SYSKEY mode 2 or 3 on the Windows 2000-based laptop</li> 

For additional information about SYSKEY, click the following article number to view the article in the Microsoft Knowledge Base:

143475 Windows NT System Key Permits Strong Encryption of the SAM

</li></ul>

Password Reset: Windows XP Workstation in a Workgroup

By default, Window XP does not create backup copies of the master key. It does so to help prevent an offline attack of the master key cache. In Windows XP, you can create a password reset disk so that the user may recover their password if they forget it. If you are using Windows XP Service Pack 1 (SP1) or later, you can configure the registry so that Windows keeps a backup copy of the master key.

For additional information about effects of a forcible password change and possible recovery, click the following article number to view the article in the Microsoft Knowledge Base:

290260 EFS, credentials, and private keys from certificates are unavailable after a password is reset

Password Reset Disks

Password reset disks are only available on Windows XP or later-based computers that are joined to workgroups. The password recover disk permits the user to regain access to their account and all the confidential information that is protected by DPAPI in the profile.

For additional information about the password reset disk, click the following article number to view the article in the Microsoft Knowledge Base:

321305 How to log on to Windows XP if you forget your password or your password expires

back to the top

You Cannot Access DPAPI Confidential Information in a Windows NT 4.0 Domain
Important Microsoft does not recommend that you use DPAPI in a Windows NT 4.0 domain environment.

In a Windows NT 4.0 domain, Windows XP does not create a backup copy of the user's master key. This is the default behavior. If you change or reset the password, the user may be denied access to the confidential information that is contained in their profile. Access is only restored when the user changes the password back to the last known good password.

The most frequent causes of problems with DPAPI in a Windows NT 4.0 domain involve password resets or roaming profiles. Problems with roaming profiles occur if the user has recently changed their password. Depending on various factors that may interrupt typical roaming user profile operations, the profile that the user is logged on to may not have been updated with the new password (master key encryption).

To resolve this problem, install a Windows 2000 or Windows Server 2003 domain controller in the user domain. DPAPI automatically finds this domain controller to perform backup and restore operations using the domain controller's DPAPI public/private key pair.

If you are using Windows SP1 and later, you can force DPAPI to make local backups of the master key while you are joined to a Windows NT4 domain. However, Microsoft does not recommend this procedure because it affects the security of the computer where the change is applied.

For additional information, click the following article number to view the article in the Microsoft Knowledge Base:

331333 User cannot gain access to EFS encrypted files after password change or when using a roaming profile

back to the top

You Cannot Access DPAPI Confidential Information After Reinstalling Windows on a Stand-Alone Computer
By design, you cannot access DPAPI confidential information after you install Windows on a stand-alone computer. The instance of the user that was present on the original copy of Windows is destroyed after you re-install the operating system without upgrading. Any new user that is created with the same name has a different security principal in a different security database. The new user does not have access to decrypt the DPAPI confidential information of the original user. The user cannot access their confidential information by using the user master key.

The original copy of Windows helps protect its copy of the master key with confidential data that is known only to that copy of Windows. If you replace the operating system, this confidential data cannot be accessed. The user cannot access their confidential information by using the backup master key.

back to the top

You Cannot Add or Access DPAPI Confidential Information with Mandatory Profiles
By design, Windows 2000 and Windows XP do not allow you to write to the local copy of a mandatory profile because the data is saved after the initial session. As a result, DPAPI cannot store new master keys, update master keys on password change, or add protected data to a mandatory profile.

You Cannot Access DPAPI Confidential Information After Joining or Disjoining a Domain
If you have joined a stand-alone computer to a domain and you have lost access to DPAPI data, you can restore access by logging on as the local user. To log on as a local user on a domain-joined computer, click the local computer's name in the dropdown box in the Logon dialog box, and then enter your local user name and password.

If you have disjoined a computer from a domain, you must rejoin the domain and then log on as the same domain user to regain access to your files.

back to the top

Guidelines and Best Practices

 * Microsoft recommends that you use strong passwords. Use the most difficult complex password you can reliably remember. Note Password filters are currently not supported by DPAPI.
 * Export and back up important certificates and private keys to a safe and secure location.

back to the top

Additional query words: rebuild

Keywords: kbinfo KB309408

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.