MachineKey.Protect(Byte[], String[]) Method

Definition

Namespace:

System.Web.Security

Assembly:

System.Web.dll

Protects the specified data by encrypting or signing it.

public:
 static cli::array <System::Byte> ^ Protect(cli::array <System::Byte> ^ userData, ... cli::array <System::String ^> ^ purposes);

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

static member Protect : byte[] * string[] -> byte[]

Public Shared Function Protect (userData As Byte(), ParamArray purposes As String()) As Byte()

Parameters

userData

Byte[]

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

purposes

String[]

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

Returns

Byte[]

The ciphertext data.

Exceptions

ArgumentNullException

The userData parameter is null.

ArgumentException

The purposes array contains one or more white-space-only entries.

Remarks

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");  

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);  

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.