Data​Protection​Provider Data​Protection​Provider Data​Protection​Provider Class

Definition

Represents a cryptographic provider that can be used to asynchronously encrypt and decrypt static data or a data stream.

public sealed class DataProtectionProvider : IDataProtectionProviderpublic sealed class DataProtectionProvider : IDataProtectionProviderPublic NotInheritable Class DataProtectionProvider Implements IDataProtectionProvider
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

You can use the class to protect data to any of the following:

  • You can use a security descriptor (SID) or a security descriptor definition language (SDDL) string to protect data to an Active Directory (AD) security principal such as an AD group. Any member of the group can decrypt the data.
  • You can protect data to the local user or computer account.
  • You can protect data to the credentials (password) used during logon to a website.

For security descriptors and SDDL strings, you must set the enterprise authentication capability in the manifest. The enterprise authentication capability is restricted to Windows Store app built with company accounts, and is subject to additional onboarding validation. You should avoid the enterprise authentication capability unless it is absolutely necessary. For more information, see Registering for a developer account. For example, the following SID and SDDL providers require the enterprise authentication capability:

  • "SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812"
  • "SDDL=O:S-1-5-5-0-290724G:SYD:(A;;CCDC;;;S-1-5-5-0-290724)(A;;DC;;;WD)"

These providers do not require the enterprise authentication capability:

  • "LOCAL=user"
  • "LOCAL=machine"
  • "WEBCREDENTIALS=MyPasswordName"
  • "WEBCREDENTIALS=MyPasswordName,myweb.com"

Examples

The following sample shows how to protect static data.


using Windows.Security.Cryptography;
using Windows.Security.Cryptography.DataProtection;
using Windows.Storage.Streams;
using System.Threading.Tasks;

namespace SampleProtectAsync
{
    sealed partial class StaticDataProtectionApp : Application
    {
        public StaticDataProtectionApp()
        {
            // Initialize the application.
            this.InitializeComponent();

            // Protect data asynchronously.
            this.Protect();
        }

        public async void Protect()
        {
            // Initialize function arguments.
            String strMsg = "This is a message to be protected.";
            String strDescriptor = "LOCAL=user";
            BinaryStringEncoding encoding = BinaryStringEncoding.Utf8;

            // Protect a message to the local user.
            IBuffer buffProtected = await this.SampleProtectAsync(
                strMsg,
                strDescriptor,
                encoding);

            // Decrypt the previously protected message.
            String strDecrypted = await this.SampleUnprotectData(
                buffProtected,
                encoding);
        }

        public async Task<IBuffer> SampleProtectAsync(
            String strMsg,
            String strDescriptor,
            BinaryStringEncoding encoding)
        {
            // Create a DataProtectionProvider object for the specified descriptor.
            DataProtectionProvider Provider = new DataProtectionProvider(strDescriptor);

            // Encode the plaintext input message to a buffer.
            encoding = BinaryStringEncoding.Utf8;
            IBuffer buffMsg = CryptographicBuffer.ConvertStringToBinary(strMsg, encoding);

            // Encrypt the message.
            IBuffer buffProtected = await Provider.ProtectAsync(buffMsg);

            // Execution of the SampleProtectAsync function resumes here
            // after the awaited task (Provider.ProtectAsync) completes.
            return buffProtected;
        }

        public async Task<String> SampleUnprotectData(
            IBuffer buffProtected,
            BinaryStringEncoding encoding)
        {
            // Create a DataProtectionProvider object.
            DataProtectionProvider Provider = new DataProtectionProvider();

            // Decrypt the protected message specified on input.
            IBuffer buffUnprotected = await Provider.UnprotectAsync(buffProtected);

            // Execution of the SampleUnprotectData method resumes here
            // after the awaited task (Provider.UnprotectAsync) completes
            // Convert the unprotected message from an IBuffer object to a string.
            String strClearText = CryptographicBuffer.ConvertBinaryToString(encoding, buffUnprotected);

            // Return the plaintext string.
            return strClearText;
        }
    }
}

using Windows.Security.Cryptography;
using Windows.Security.Cryptography.DataProtection;
using Windows.Storage.Streams;
using System.Threading.Tasks;

namespace SampleProtectStreamAsync
{

    sealed partial class StreamDataProtectionApp : Application
    {
        public StreamDataProtectionApp()
        {
            // Initialize the application.
            this.InitializeComponent();

            // Protect a stream synchronously
            this.ProtectData();
         }

        public async void ProtectData()
        {
            // Initialize function arguments.
            String strDescriptor = "LOCAL=user";
            String strLoremIpsum = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse elementum "
                + "ullamcorper eros, vitae gravida nunc consequat sollicitudin. Vivamus lacinia, "
                + "diam a molestie porttitor, sapien neque volutpat est, non suscipit leo dolor "
                + "sit amet nisl. Praesent tincidunt tincidunt quam ut pharetra. Sed tincidunt "
                + "sit amet nisl. Praesent tincidunt tincidunt quam ut pharetra. Sed tincidunt "
                + "porttitor massa, at convallis dolor dictum suscipit. Nullam vitae lectus in "
                + "lorem scelerisque convallis sed scelerisque orci. Praesent sed ligula vel erat "
                + "eleifend tempus. Nullam dignissim aliquet mauris a aliquet. Nulla augue justo, "
                + "posuere a consectetur ut, suscipit et sem. Proin eu libero ut felis tincidunt "
                + "interdum. Curabitur vulputate eros nec sapien elementum ut dapibus eros "
                + "dapibus. Suspendisse quis dui dolor, non imperdiet leo. In consequat, odio nec "
                + "aliquam tincidunt, magna enim ultrices massa, ac pharetra est urna at arcu. "
                + "Nunc suscipit, velit non interdum suscipit, lectus lectus auctor tortor, quis "
                + "ultrices orci felis in dolor. Etiam congue pretium libero eu vestibulum. "
                + "Mauris bibendum erat eleifend nibh consequat eu pharetra metus convallis. "
                + "Morbi sem eros, venenatis vel vestibulum consequat, hendrerit rhoncus purus.";
            BinaryStringEncoding encoding = BinaryStringEncoding.Utf16BE;

            // Encrypt the data as a stream.
            IBuffer buffProtected = await this.SampleDataProtectionStream(
                strDescriptor,
                strLoremIpsum,
                encoding);

            // Decrypt a data stream.
            String strUnprotected = await this.SampleDataUnprotectStream(
                buffProtected,
                encoding);
        }

        public async Task<IBuffer> SampleDataProtectionStream(
            String descriptor,
            String strMsg,
            BinaryStringEncoding encoding)
        {
            // Create a DataProtectionProvider object for the specified descriptor.
            DataProtectionProvider Provider = new DataProtectionProvider(descriptor);

            // Convert the input string to a buffer.
            IBuffer buffMsg = CryptographicBuffer.ConvertStringToBinary(strMsg, encoding);

            // Create a random access stream to contain the plaintext message.
            InMemoryRandomAccessStream inputData = new InMemoryRandomAccessStream();

            // Create a random access stream to contain the encrypted message.
            InMemoryRandomAccessStream protectedData = new InMemoryRandomAccessStream();

            // Retrieve an IOutputStream object and fill it with the input (plaintext) data.
            IOutputStream outputStream = inputData.GetOutputStreamAt(0);
            DataWriter writer = new DataWriter(outputStream);
            writer.WriteBuffer(buffMsg);
            await writer.StoreAsync();
            await outputStream.FlushAsync();

            // Retrieve an IInputStream object from which you can read the input data.
            IInputStream source = inputData.GetInputStreamAt(0);

            // Retrieve an IOutputStream object and fill it with encrypted data.
            IOutputStream dest = protectedData.GetOutputStreamAt(0);
            await Provider.ProtectStreamAsync(source, dest);
            await dest.FlushAsync();

            //Verify that the protected data does not match the original
            DataReader reader1 = new DataReader(inputData.GetInputStreamAt(0));
            DataReader reader2 = new DataReader(protectedData.GetInputStreamAt(0));
            await reader1.LoadAsync((uint)inputData.Size);
            await reader2.LoadAsync((uint)protectedData.Size);
            IBuffer buffOriginalData = reader1.ReadBuffer((uint)inputData.Size);
            IBuffer buffProtectedData = reader2.ReadBuffer((uint)protectedData.Size);

            if (CryptographicBuffer.Compare(buffOriginalData, buffProtectedData))
            {
                throw new Exception("ProtectStreamAsync returned unprotected data");
            }

            // Return the encrypted data.
            return buffProtectedData;
        }

        public async Task<String> SampleDataUnprotectStream(
            IBuffer buffProtected,
            BinaryStringEncoding encoding)
        {
            // Create a DataProtectionProvider object.
            DataProtectionProvider Provider = new DataProtectionProvider();

            // Create a random access stream to contain the encrypted message.
            InMemoryRandomAccessStream inputData = new InMemoryRandomAccessStream();

            // Create a random access stream to contain the decrypted data.
            InMemoryRandomAccessStream unprotectedData = new InMemoryRandomAccessStream();

            // Retrieve an IOutputStream object and fill it with the input (encrypted) data.
            IOutputStream outputStream = inputData.GetOutputStreamAt(0);
            DataWriter writer = new DataWriter(outputStream);
            writer.WriteBuffer(buffProtected);
            await writer.StoreAsync();
            await outputStream.FlushAsync();

            // Retrieve an IInputStream object from which you can read the input (encrypted) data.
            IInputStream source = inputData.GetInputStreamAt(0);

            // Retrieve an IOutputStream object and fill it with decrypted data.
            IOutputStream dest = unprotectedData.GetOutputStreamAt(0);
            await Provider.UnprotectStreamAsync(source, dest);
            await dest.FlushAsync();

            // Write the decrypted data to an IBuffer object.
            DataReader reader2 = new DataReader(unprotectedData.GetInputStreamAt(0));
            await reader2.LoadAsync((uint)unprotectedData.Size);
            IBuffer buffUnprotectedData = reader2.ReadBuffer((uint)unprotectedData.Size);

            // Convert the IBuffer object to a string using the same encoding that was
            // used previously to conver the plaintext string (before encryption) to an
            // IBuffer object.
            String strUnprotected = CryptographicBuffer.ConvertBinaryToString(encoding, buffUnprotectedData);

            // Return the decrypted data.
            return strUnprotected;
        }
    }
}

Constructors

DataProtectionProvider() DataProtectionProvider() DataProtectionProvider()

Constructor used for decryption operations. Use this constructor before calling the UnprotectAsync or UnprotectStreamAsync methods.

public DataProtectionProvider()public DataProtectionProvider()Public Sub New()
Attributes

Remarks

Use this constructor before starting a decryption operation. Do not use this constructor before starting an encryption operation. Use the @Windows.Security.Cryptography.DataProtection.DataProtectionProvider.#ctor(System.String)?text=DataProtectionProvider(String) method instead.

For security descriptors and SDDL strings, you must set the enterprise authentication capability in the manifest. The enterprise authentication capability is restricted to Windows Store app built with company accounts, and is subject to additional onboarding validation. You should avoid the enterprise authentication capability unless it is absolutely necessary. For more information, see Registering for a developer account. For example, the following SID and SDDL providers require the enterprise authentication capability:

  • "SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812"
  • "SDDL=O:S-1-5-5-0-290724G:SYD:(A;;CCDC;;;S-1-5-5-0-290724)(A;;DC;;;WD)"

These providers do not require the enterprise authentication capability:

  • "LOCAL=user"
  • "LOCAL=machine"
  • "WEBCREDENTIALS=MyPasswordName"
  • "WEBCREDENTIALS=MyPasswordName,myweb.com"

DataProtectionProvider(String) DataProtectionProvider(String) DataProtectionProvider(String)

Constructor used for encryption operations. Use this constructor before calling the ProtectAsync or ProtectStreamAsync methods.

public DataProtectionProvider(String protectionDescriptor)public DataProtectionProvider(String protectionDescriptor)Public Sub New(protectionDescriptor As String)
Parameters
protectionDescriptor
System.String System.String System.String

Contains the protection descriptor that determines the entity to which the data will be encrypted. For more information, see Remarks.

Attributes

Remarks

Do not use this constructor before starting a decryption operation. You must use the @Windows.Security.Cryptography.DataProtection.DataProtectionProvider.#ctor?text=DataProtectionProvider() constructor instead.

For security descriptors and SDDL strings, you must set the enterprise authentication capability in the manifest. The enterprise authentication capability is restricted to apps built with company accounts, and is subject to additional onboarding validation. You should avoid the enterprise authentication capability unless it is absolutely necessary. For example, the following SID and SDDL providers require the enterprise authentication capability:

  • "SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812"
  • "SDDL=O:S-1-5-5-0-290724G:SYD:(A;;CCDC;;;S-1-5-5-0-290724)(A;;DC;;;WD)"

These providers do not require the enterprise authentication capability on either platform:

  • "LOCAL=user"
  • "LOCAL=machine"

These providers do not require the enterprise authentication capability on Windows:

  • "WEBCREDENTIALS=MyPasswordName"
  • "WEBCREDENTIALS=MyPasswordName,myweb.com"

Methods

ProtectAsync(IBuffer) ProtectAsync(IBuffer) ProtectAsync(IBuffer)

Asynchronously protects static data.

public IAsyncOperation<IBuffer> ProtectAsync(IBuffer data)public IAsyncOperation<IBuffer> ProtectAsync(IBuffer data)Public Function ProtectAsync(data As IBuffer) As IAsyncOperation( Of IBuffer )
Parameters
data
IBuffer IBuffer IBuffer

Data to protect.

Returns

Represents an asynchronous operation.

Attributes

Remarks

You must call the @Windows.Security.Cryptography.DataProtection.DataProtectionProvider.#ctor(System.String)?text=DataProtectionProvider(String) constructor before calling this method.

For security descriptors and SDDL strings, you must set the enterprise authentication capability in the manifest. The enterprise authentication capability is restricted to Windows Store app built with company accounts, and is subject to additional onboarding validation. You should avoid the enterprise authentication capability unless it is absolutely necessary. For more information, see Registering for a developer account. For example, the following SID and SDDL providers require the enterprise authentication capability:

  • "SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812"
  • "SDDL=O:S-1-5-5-0-290724G:SYD:(A;;CCDC;;;S-1-5-5-0-290724)(A;;DC;;;WD)"

These providers do not require the enterprise authentication capability:

  • "LOCAL=user"
  • "LOCAL=machine"
  • "WEBCREDENTIALS=MyPasswordName"
  • "WEBCREDENTIALS=MyPasswordName,myweb.com"

ProtectStreamAsync(IInputStream, IOutputStream) ProtectStreamAsync(IInputStream, IOutputStream) ProtectStreamAsync(IInputStream, IOutputStream)

Asynchronously protects a data stream.

public IAsyncAction ProtectStreamAsync(IInputStream src, IOutputStream dest)public IAsyncAction ProtectStreamAsync(IInputStream src, IOutputStream dest)Public Function ProtectStreamAsync(src As IInputStream, dest As IOutputStream) As IAsyncAction
Parameters
src
IInputStream IInputStream IInputStream

Stream to be protected.

dest
IOutputStream IOutputStream IOutputStream

Protected stream.

Returns

Represents an asynchronous action.

Attributes

Remarks

You must call the @Windows.Security.Cryptography.DataProtection.DataProtectionProvider.#ctor(System.String)?text=DataProtectionProvider(String) constructor before calling this method.

For security descriptors and SDDL strings, you must set the enterprise authentication capability in the manifest. The enterprise authentication capability is restricted to Windows Store app built with company accounts, and is subject to additional onboarding validation. You should avoid the enterprise authentication capability unless it is absolutely necessary. For more information, see Registering for a developer account. For example, the following SID and SDDL providers require the enterprise authentication capability:

  • "SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812"
  • "SDDL=O:S-1-5-5-0-290724G:SYD:(A;;CCDC;;;S-1-5-5-0-290724)(A;;DC;;;WD)"

These providers do not require the enterprise authentication capability:

  • "LOCAL=user"
  • "LOCAL=machine"
  • "WEBCREDENTIALS=MyPasswordName"
  • "WEBCREDENTIALS=MyPasswordName,myweb.com"

UnprotectAsync(IBuffer) UnprotectAsync(IBuffer) UnprotectAsync(IBuffer)

Asynchronously decrypts static data.

public IAsyncOperation<IBuffer> UnprotectAsync(IBuffer data)public IAsyncOperation<IBuffer> UnprotectAsync(IBuffer data)Public Function UnprotectAsync(data As IBuffer) As IAsyncOperation( Of IBuffer )
Parameters
data
IBuffer IBuffer IBuffer

Data to decrypt.

Returns

Represents an asynchronous operation.

Attributes

Remarks

You must call the @Windows.Security.Cryptography.DataProtection.DataProtectionProvider.#ctor?text=DataProtectionProvider() constructor before calling this method.

For security descriptors and SDDL strings, you must set the enterprise authentication capability in the manifest. The enterprise authentication capability is restricted to Windows Store app built with company accounts, and is subject to additional onboarding validation. You should avoid the enterprise authentication capability unless it is absolutely necessary. For more information, see Registering for a developer account. For example, the following SID and SDDL providers require the enterprise authentication capability:

  • "SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812"
  • "SDDL=O:S-1-5-5-0-290724G:SYD:(A;;CCDC;;;S-1-5-5-0-290724)(A;;DC;;;WD)"

These providers do not require the enterprise authentication capability:

  • "LOCAL=user"
  • "LOCAL=machine"
  • "WEBCREDENTIALS=MyPasswordName"
  • "WEBCREDENTIALS=MyPasswordName,myweb.com"

UnprotectStreamAsync(IInputStream, IOutputStream) UnprotectStreamAsync(IInputStream, IOutputStream) UnprotectStreamAsync(IInputStream, IOutputStream)

Asynchronously decrypts a data stream.

public IAsyncAction UnprotectStreamAsync(IInputStream src, IOutputStream dest)public IAsyncAction UnprotectStreamAsync(IInputStream src, IOutputStream dest)Public Function UnprotectStreamAsync(src As IInputStream, dest As IOutputStream) As IAsyncAction
Parameters
src
IInputStream IInputStream IInputStream

Stream to decrypt.

dest
IOutputStream IOutputStream IOutputStream

Decrypted stream.

Returns

Represents an asynchronous action.

Attributes

Remarks

You must call the @Windows.Security.Cryptography.DataProtection.DataProtectionProvider.#ctor?text=DataProtectionProvider() constructor before calling this method.

For security descriptors and SDDL strings, you must set the enterprise authentication capability in the manifest. The enterprise authentication capability is restricted to Windows Store app built with company accounts, and is subject to additional onboarding validation. You should avoid the enterprise authentication capability unless it is absolutely necessary. For more information, see Registering for a developer account. For example, the following SID and SDDL providers require the enterprise authentication capability:

  • "SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812"
  • "SDDL=O:S-1-5-5-0-290724G:SYD:(A;;CCDC;;;S-1-5-5-0-290724)(A;;DC;;;WD)"

These providers do not require the enterprise authentication capability:

  • "LOCAL=user"
  • "LOCAL=machine"
  • "WEBCREDENTIALS=MyPasswordName"
  • "WEBCREDENTIALS=MyPasswordName,myweb.com"