Export (0) Print
Expand All

MachineKey.Protect Method

.NET Framework 4.5

Protects the specified data by encrypting or signing it.

Namespace:  System.Web.Security
Assembly:  System.Web (in System.Web.dll)

public static byte[] Protect(
	byte[] userData,
	params string[] purposes
)

Parameters

userData
Type: System.Byte[]

The data to protect. This data is passed as plaintext.

purposes
Type: System.String[]

A list of purposes for the data. If this value is specified, the same list must be passed to the Unprotect method in order to decipher the returned ciphertext.

Return Value

Type: System.Byte[]
The ciphertext data.

ExceptionCondition
ArgumentNullException

The userData parameter is null.

ArgumentException

The purposes array contains one or more whitespace-only entries.

This method supersedes the Encode method, which requires the caller to specify whether the plaintext data should be encrypted, signed, or both. The Protect method performs the appropriate operation and securely protects the data. Ciphertext data produced by this method can only be deciphered by the Unprotect method.

The purposes parameter is an optional list of reasons that can lock the ciphertext to a specific purpose. This parameter lets you isolate cryptographic operations performed by different subsystems within an application. A malicious client should not be able to get the result of one subsystem's Protect method and feed it as input to another subsystem's Unprotect method, which could compromise application security. The purposes parameter helps ensure that protected data can only be used by the component that originally generated it. Applications should make sure that each subsystem uses a unique purposes list.

For example, to protect or unprotect an authentication token, you could call the method using code like the following example:

MachineKey.Protect(..., "Authentication token");
MachineKey.Unprotect(..., "Authentication token");

Applications can dynamically generate the purposes parameter. In that case, prefix user-supplied values with a fixed value (like "Username: " + username) to minimize the risk of a malicious client crafting input that matches a token that is used by some other part of the system. Any dynamically-generated strings should come after fixed strings. For example, to protect or unprotect a private message that is tied to a specific user, use code like the following example:

MachineKey.Protect(..., "Private message", "Recipient: " + username);
MachineKey.Unprotect(..., "Private message", "Recipient: " + username);

When the Unprotect method is called, the value that is provided for the purposes parameter must be the same value that was provided to the Protect method. Otherwise the operation will fail with a CryptographicException exception.

The configuration settings that are required for the MachineKeyCompatibilityMode.Framework45 option are required for this method even if the MachineKeySection.CompatibilityMode property is not set to the Framework45 option.

.NET Framework

Supported in: 4.5

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft