Skip to content

Noted Windows-only support for ProtectedData #2465

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 17, 2019
Merged

Noted Windows-only support for ProtectedData #2465

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9759f97
Noted Windows-only support
May 17, 2019
f364d92
Addressed review comment
May 17, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 11 additions & 7 deletions xml/System.Security.Cryptography/ProtectedData.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,17 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This class provides access to the Data Protection API (DPAPI) available in Microsoft Windows 2000 and later operating systems. This is a service that is provided by the operating system and does not require additional libraries. It provides protection using the user or machine credentials to encrypt or decrypt data.

The class consists of two wrappers for the unmanaged DPAPI, <xref:System.Security.Cryptography.ProtectedData.Protect%2A> and <xref:System.Security.Cryptography.ProtectedData.Unprotect%2A>. These two methods can be used to encrypt and decrypt data such as passwords, keys, and connection strings.
## Remarks

This class provides access to the Data Protection API (DPAPI) available in Windows operating systems. This is a service that is provided by the operating system and does not require additional libraries. It provides protection using the user or machine credentials to encrypt or decrypt data.

> [!IMPORTANT]
> Because it depends on DPAPI, the `ProtectedData` class is supported on the Windows platform only. Its use on .NET Core on platforms other than Windows throws a <xref:System.PlatformNotSupportedException>.

If you use these methods during impersonation, you may receive the following error: "Key not valid for use in specified state." This occurs because the DPAPI stores the key data in user profiles. If the profile is not loaded, DPAPI won't be able to perform the decryption. To prevent this error, load the profile of the user you want to impersonate before calling either method. Using DPAPI with impersonation can incur significant complication and requires careful design choices.


The class consists of two wrappers for the unmanaged DPAPI, <xref:System.Security.Cryptography.ProtectedData.Protect%2A> and <xref:System.Security.Cryptography.ProtectedData.Unprotect%2A>. These two methods can be used to encrypt and decrypt data such as passwords, keys, and connection strings.

If you use these methods during impersonation, you may receive the following error: "Key not valid for use in specified state." This occurs because the DPAPI stores the key data in user profiles. If the profile is not loaded, DPAPI won't be able to perform the decryption. To prevent this error, load the profile of the user you want to impersonate before calling either method. Using DPAPI with impersonation can incur significant complication and requires careful design choices.

## Examples
The following example shows how to use data protection.

Expand Down Expand Up @@ -113,6 +115,7 @@
<exception cref="T:System.Security.Cryptography.CryptographicException">The encryption failed.</exception>
<exception cref="T:System.NotSupportedException">The operating system does not support this method.</exception>
<exception cref="T:System.OutOfMemoryException">The system ran out of memory while encrypting the data.</exception>
<exception cref="T:System.PlatformNotSupportedException">.NET Core only: Calls to the <c>Protect</c> method are supported on Windows operating systems only.</exception>
<permission cref="T:System.Security.Permissions.DataProtectionPermission">with the associated <see cref="P:System.Security.Permissions.DataProtectionPermissionAttribute.ProtectData" /> flag for permission to protect data.</permission>
</Docs>
</Member>
Expand Down Expand Up @@ -181,6 +184,7 @@
<exception cref="T:System.Security.Cryptography.CryptographicException">The decryption failed.</exception>
<exception cref="T:System.NotSupportedException">The operating system does not support this method.</exception>
<exception cref="T:System.OutOfMemoryException">Out of memory.</exception>
<exception cref="T:System.PlatformNotSupportedException">.NET Core only: Calls to the <c>Unprotect</c> method are supported on Windows operating systems only.</exception>
<permission cref="T:System.Security.Permissions.DataProtectionPermission">with the associated <see cref="P:System.Security.Permissions.DataProtectionPermissionAttribute.UnprotectData" /> flag for permission to unprotect data.</permission>
</Docs>
</Member>
Expand Down