Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
242 lines (213 sloc) 17.2 KB
<Type Name="MachineKey" FullName="System.Web.Security.MachineKey">
<TypeSignature Language="C#" Value="public static class MachineKey" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi abstract sealed beforefieldinit MachineKey extends System.Object" />
<TypeSignature Language="DocId" Value="T:System.Web.Security.MachineKey" />
<TypeSignature Language="VB.NET" Value="Public Class MachineKey" />
<TypeSignature Language="C++ CLI" Value="public ref class MachineKey abstract sealed" />
<TypeSignature Language="F#" Value="type MachineKey = class" />
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Base>
<BaseTypeName>System.Object</BaseTypeName>
</Base>
<Interfaces />
<Docs>
<summary>Provides a way to encrypt or hash data (or both) by using the same algorithms and key values that are used for ASP.NET forms authentication and view state.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Web.Security.MachineKey> class provides methods that expose the hashing and encryption logic that ASP.NET provides. For information about which encryption and hashing algorithms ASP.NET uses, and the key values that it uses with them, see [machineKey Element (ASP.NET Settings Schema)](https://msdn.microsoft.com/library/4b5699a9-bc21-4c4a-85f1-8b3b8ebd2d46).
> [!WARNING]
> The <xref:System.Web.Security.MachineKey> APIs should only be used in an ASP.NET app. Behavior of the MachineKey APIs outside the context of an ASP.NET application is undefined
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The data to encrypt, hash, decrypt, or validate does not exist</exception>
</Docs>
<Members>
<Member MemberName="Decode">
<MemberSignature Language="C#" Value="public static byte[] Decode (string encodedData, System.Web.Security.MachineKeyProtection protectionOption);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig unsigned int8[] Decode(string encodedData, valuetype System.Web.Security.MachineKeyProtection protectionOption) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Web.Security.MachineKey.Decode(System.String,System.Web.Security.MachineKeyProtection)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Decode (encodedData As String, protectionOption As MachineKeyProtection) As Byte()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static cli::array &lt;System::Byte&gt; ^ Decode(System::String ^ encodedData, System::Web::Security::MachineKeyProtection protectionOption);" />
<MemberSignature Language="F#" Value="static member Decode : string * System.Web.Security.MachineKeyProtection -&gt; byte[]" Usage="System.Web.Security.MachineKey.Decode (encodedData, protectionOption)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8">
<AttributeName>System.Obsolete("This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the Protect and Unprotect methods instead.")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Byte[]</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="encodedData" Type="System.String" />
<Parameter Name="protectionOption" Type="System.Web.Security.MachineKeyProtection" />
</Parameters>
<Docs>
<param name="encodedData">The encrypted data to decrypt and/or validate.</param>
<param name="protectionOption">Indicates whether the <paramref name="encodedData" /> parameter should be encrypted and/or hashed.</param>
<summary>Decodes and/or validates data that has been encrypted or provided with a hash-based message authentication code (HMAC).</summary>
<returns>A <see cref="T:System.Byte" /> array that represents the decrypted data.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
For information about which encryption and hashing algorithms ASP.NET uses to decrypt and validate the data that is passed in, see [machineKey Element (ASP.NET Settings Schema)](https://msdn.microsoft.com/library/4b5699a9-bc21-4c4a-85f1-8b3b8ebd2d46).
## Examples
For a code example, see the <xref:System.Web.Security.MachineKey> class overview.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Encode">
<MemberSignature Language="C#" Value="public static string Encode (byte[] data, System.Web.Security.MachineKeyProtection protectionOption);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig string Encode(unsigned int8[] data, valuetype System.Web.Security.MachineKeyProtection protectionOption) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Web.Security.MachineKey.Encode(System.Byte[],System.Web.Security.MachineKeyProtection)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Encode (data As Byte(), protectionOption As MachineKeyProtection) As String" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::String ^ Encode(cli::array &lt;System::Byte&gt; ^ data, System::Web::Security::MachineKeyProtection protectionOption);" />
<MemberSignature Language="F#" Value="static member Encode : byte[] * System.Web.Security.MachineKeyProtection -&gt; string" Usage="System.Web.Security.MachineKey.Encode (data, protectionOption)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8">
<AttributeName>System.Obsolete("This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the Protect and Unprotect methods instead.")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="data" Type="System.Byte[]" />
<Parameter Name="protectionOption" Type="System.Web.Security.MachineKeyProtection" />
</Parameters>
<Docs>
<param name="data">The data to encrypt.</param>
<param name="protectionOption">Indicates whether the <paramref name="data" /> parameter should be encrypted and/or hashed.</param>
<summary>Encrypts data and/or appends a hash-based message authentication code (HMAC).</summary>
<returns>The encrypted value, the input value with an HMAC appended, or the result of encrypting the input value with an HMAC appended.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
For information about which encryption and hashing algorithms ASP.NET uses to decrypt and validate the data that is passed in, see [machineKey Element (ASP.NET Settings Schema)](https://msdn.microsoft.com/library/4b5699a9-bc21-4c4a-85f1-8b3b8ebd2d46).
## Examples
For a code example, see the <xref:System.Web.Security.MachineKey> class overview.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Protect">
<MemberSignature Language="C#" Value="public static byte[] Protect (byte[] userData, params string[] purposes);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig unsigned int8[] Protect(unsigned int8[] userData, string[] purposes) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Web.Security.MachineKey.Protect(System.Byte[],System.String[])" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Protect (userData As Byte(), ParamArray purposes As String()) As Byte()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static cli::array &lt;System::Byte&gt; ^ Protect(cli::array &lt;System::Byte&gt; ^ userData, ... cli::array &lt;System::String ^&gt; ^ purposes);" />
<MemberSignature Language="F#" Value="static member Protect : byte[] * string[] -&gt; byte[]" Usage="System.Web.Security.MachineKey.Protect (userData, purposes)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Byte[]</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="userData" Type="System.Byte[]" Index="0" FrameworkAlternate="netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="purposes" Type="System.String[]" Index="1" FrameworkAlternate="netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8">
<Attributes>
<Attribute>
<AttributeName>System.ParamArray</AttributeName>
</Attribute>
</Attributes>
</Parameter>
</Parameters>
<Docs>
<param name="userData">The data to protect. This data is passed as plaintext.</param>
<param name="purposes">A list of purposes for the data. If this value is specified, the same list must be passed to the <see cref="M:System.Web.Security.MachineKey.Unprotect(System.Byte[],System.String[])" /> method in order to decipher the returned ciphertext.</param>
<summary>Protects the specified data by encrypting or signing it.</summary>
<returns>The ciphertext data.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This method supersedes the <xref:System.Web.Security.MachineKey.Encode%2A> method, which requires the caller to specify whether the plaintext data should be encrypted, signed, or both. The <xref:System.Web.Security.MachineKey.Protect%2A> method performs the appropriate operation and securely protects the data. Ciphertext data produced by this method can only be deciphered by the <xref:System.Web.Security.MachineKey.Unprotect%2A> 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 <xref:System.Web.Security.MachineKey.Protect%2A> method and feed it as input to another subsystem's <xref:System.Web.Security.MachineKey.Unprotect%2A> 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:
```csharp
MachineKey.Protect(..., "Authentication token");
MachineKey.Unprotect(..., "Authentication token");
```
```vb
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:
```csharp
MachineKey.Protect(..., "Private message", "Recipient: " + username);
MachineKey.Unprotect(..., "Private message", "Recipient: " + username);
```
```vb
MachineKey.Protect(..., "Private message", "Recipient: " + username)
MachineKey.Unprotect(..., "Private message", "Recipient: " + username)
```
When the <xref:System.Web.Security.MachineKey.Unprotect%2A> method is called, the value that is provided for the `purposes` parameter must be the same value that was provided to the <xref:System.Web.Security.MachineKey.Protect%2A> method. Otherwise the operation will fail with a <xref:System.Security.Cryptography.CryptographicException> exception.
The configuration settings that are required for the <xref:System.Web.Configuration.MachineKeyCompatibilityMode.Framework45?displayProperty=nameWithType> option are required for this method even if the <xref:System.Web.Configuration.MachineKeySection.CompatibilityMode%2A?displayProperty=nameWithType> property is not set to the <xref:System.Web.Configuration.MachineKeyCompatibilityMode.Framework45> option.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="userData" /> parameter is null.</exception>
<exception cref="T:System.ArgumentException">The purposes array contains one or more white-space-only entries.</exception>
</Docs>
</Member>
<Member MemberName="Unprotect">
<MemberSignature Language="C#" Value="public static byte[] Unprotect (byte[] protectedData, params string[] purposes);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig unsigned int8[] Unprotect(unsigned int8[] protectedData, string[] purposes) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Web.Security.MachineKey.Unprotect(System.Byte[],System.String[])" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Unprotect (protectedData As Byte(), ParamArray purposes As String()) As Byte()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static cli::array &lt;System::Byte&gt; ^ Unprotect(cli::array &lt;System::Byte&gt; ^ protectedData, ... cli::array &lt;System::String ^&gt; ^ purposes);" />
<MemberSignature Language="F#" Value="static member Unprotect : byte[] * string[] -&gt; byte[]" Usage="System.Web.Security.MachineKey.Unprotect (protectedData, purposes)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Byte[]</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="protectedData" Type="System.Byte[]" Index="0" FrameworkAlternate="netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="purposes" Type="System.String[]" Index="1" FrameworkAlternate="netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8">
<Attributes>
<Attribute>
<AttributeName>System.ParamArray</AttributeName>
</Attribute>
</Attributes>
</Parameter>
</Parameters>
<Docs>
<param name="protectedData">The ciphertext data to unprotect.</param>
<param name="purposes">A list of purposes that describe what the data is meant for. This must be the same value that was passed to the <see cref="M:System.Web.Security.MachineKey.Protect(System.Byte[],System.String[])" /> method when the data was protected.</param>
<summary>Unprotects the specified data, which was protected by the <see cref="M:System.Web.Security.MachineKey.Protect(System.Byte[],System.String[])" /> method.</summary>
<returns>The plaintext data.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
For information about this method, see the <xref:System.Web.Security.MachineKey.Protect%2A> method.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="protectedData" /> parameter is null.</exception>
<exception cref="T:System.ArgumentException">The purposes array contains one or more white-space-only entries.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">Possible causes include the following:
- The protected data was tampered with.
- The value of the <paramref name="purposes" /> parameter is not the same as the value that was specified when the data was protected.
- The application is deployed to more than one server and is using auto-generated encryption keys.</exception>
</Docs>
</Member>
</Members>
</Type>
You can’t perform that action at this time.