Export (0) Print
Expand All

DataProtector Class

.NET Framework 4.5

Provides the base class for data protectors.

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

'Declaration
Public MustInherit Class DataProtector

The DataProtector type exposes the following members.

  NameDescription
Protected methodDataProtectorCreates a new instance of the DataProtector class by using the provided application name, primary purpose, and specific purposes.
Top

  NameDescription
Protected propertyApplicationNameGets the name of the application.
Protected propertyPrependHashedPurposeToPlaintextSpecifies whether the hash is prepended to the text array before encryption.
Protected propertyPrimaryPurposeGets the primary purpose for the protected data.
Protected propertySpecificPurposesGets the specific purposes for the protected data.
Top

  NameDescription
Public methodStatic memberCreateCreates an instance of a data protector implementation by using the specified class name of the data protector, the application name, the primary purpose, and the specific purposes.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Protected methodGetHashedPurposeCreates a hash of the property values specified by the constructor.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodIsReprotectRequiredDetermines if re-encryption is required for the specified encrypted data.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodProtectProtects the specified user data.
Protected methodProviderProtectSpecifies the delegate method in the derived class that the Protect method in the base class calls back into.
Protected methodProviderUnprotectSpecifies the delegate method in the derived class that the Unprotect method in the base class calls back into.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodUnprotectUnprotects the specified protected data.
Top

This class protects stored data from viewing and tampering. The access to the protected data is obtained by creating an instance of this class and using the exact purpose strings that were used to protect the data. The caller does not need a key to either protect or unprotect the data. The key is provided by the encryption algorithm.

Derived classes must override the ProviderProtect and Unprotect methods, which the DataProtector base class calls back into. They must also override the IsReprotectRequired method, which can always return true with a potential small loss of efficiency when applications refresh their database of stored cipher text. Derived classes should provide a constructor that calls the base class constructor, which sets the ApplicationName, SpecificPurposes, and PrimaryPurpose properties.

The following example demonstrates how to create a data protector that uses a protection class with an option for extra entropy. By default, the DataProtector class prepends the hash of the purpose properties to the data to be encrypted. You can turn that functionality off and use the hashed purpose as extra entropy when calling a data protector with an extra entropy option.

Imports System
Imports System.Security
Imports System.Security.Cryptography
Imports System.Security.Permissions



Public NotInheritable Class MyDataProtector
    Inherits DataProtector

    Public Property Scope() As DataProtectionScope
        Get 
            Return Scope
        End Get 
        Set(value As DataProtectionScope)
        End Set 
    End Property ' This implementation gets the HashedPurpose from the base class and passes it as OptionalEntropy to ProtectedData.
    ' The default for DataProtector is to prepend the hash to the plain text, but because we are using the hash  
    ' as OptionalEntropy there is no need to prepend it. 

    Protected Overrides ReadOnly Property PrependHashedPurposeToPlaintext() As Boolean 
        Get 
            Return False 
        End Get 
    End Property 

    ' To allow a service to hand out instances of a DataProtector we demand unrestricted DataProtectionPermission  
    ' in the constructor, but Assert the permission when ProviderProtect is called.  This is similar to FileStream 
    ' where access is checked at time of creation, not time of use.
    <SecuritySafeCritical(), DataProtectionPermission(SecurityAction.Assert, ProtectData:=True)> _
    Protected Overrides Function ProviderProtect(ByVal userData() As Byte) As Byte()
        ' Delegate to ProtectedData 
        Return ProtectedData.Protect(userData, GetHashedPurpose(), Scope)

    End Function 'ProviderProtect

    ' To allow a service to hand out instances of a DataProtector we demand unrestricted DataProtectionPermission  
    ' in the constructor, but Assert the permission when ProviderUnProtect is called.  This is similar to FileStream 
    ' where access is checked at time of creation, not time of use.
    <SecuritySafeCritical(), DataProtectionPermission(SecurityAction.Assert, UnprotectData:=True)> _
    Protected Overrides Function ProviderUnprotect(ByVal encryptedData() As Byte) As Byte()
        ' Delegate to ProtectedData 
        Return ProtectedData.Unprotect(encryptedData, GetHashedPurpose(), Scope)

    End Function 'ProviderUnprotect

    Public Overrides Function IsReprotectRequired(ByVal encryptedData() As Byte) As Boolean 
        ' For now, this cannot be determined, so always return true; 
        Return True 

    End Function 'IsReprotectRequired

    ' Public constructor 
    ' The Demand for DataProtectionPermission is in the constructor because we Assert this permission  
    ' in the ProviderProtect/ProviderUnprotect methods. 
    <DataProtectionPermission(SecurityAction.Demand, Unrestricted:=True), SecuritySafeCritical()> _
    Public Sub New(ByVal appName As String, ByVal primaryPurpose As String, ParamArray specificPurpose() As String)
        MyBase.New(appName, primaryPurpose, specificPurpose)

    End Sub 'New 
End Class 'MyDataProtector

The following example demonstrates a simple data protector that uses the PrependHashedPurposeToPlaintext functionality of the DataProtector class.

Imports System
Imports System.Security
Imports System.Security.Permissions
Imports System.Security.Cryptography



Public NotInheritable Class MemoryProtector
    Inherits DataProtector

    Public Property Scope() As MemoryProtectionScope
        Get 
            Return Scope
        End Get 
        Set(value As MemoryProtectionScope)
        End Set 
    End Property 

    Protected Overrides ReadOnly Property PrependHashedPurposeToPlaintext() As Boolean 
        Get 
            ' Signal the DataProtector to prepend the hash of the purpose to the data. 
            Return True 
        End Get 
    End Property 

    ' To allow a service to hand out instances of a DataProtector we demand unrestricted DataProtectionPermission  
    ' in the constructor, but Assert the permission when ProviderProtect is called.  This is similar to FileStream 
    ' where access is checked at time of creation, not time of use.
    <SecuritySafeCritical(), DataProtectionPermission(SecurityAction.Assert, ProtectData:=True)> _
    Protected Overrides Function ProviderProtect(ByVal userData() As Byte) As Byte()

        ' Delegate to ProtectedData
        ProtectedMemory.Protect(userData, Scope)
        Return userData

    End Function 'ProviderProtect

    ' To allow a service to hand out instances of a DataProtector we demand unrestricted DataProtectionPermission  
    ' in the constructor, but Assert the permission when ProviderUnprotect is called..  This is similar to FileStream 
    ' where access is checked at time of creation, not time of use.
    <SecuritySafeCritical(), DataProtectionPermission(SecurityAction.Assert, UnprotectData:=True)> _
    Protected Overrides Function ProviderUnprotect(ByVal encryptedData() As Byte) As Byte()

        ProtectedMemory.Unprotect(encryptedData, Scope)
        Return encryptedData

    End Function 'ProviderUnprotect

    Public Overrides Function IsReprotectRequired(ByVal encryptedData() As Byte) As Boolean 
        ' For now, this cannot be determined so always return true. 
        Return True 

    End Function 'IsReprotectRequired

    ' Public constructor 
    ' The Demand for DataProtectionPermission is in the constructor because we Assert this permission  
    ' in the ProviderProtect/ProviderUnprotect methods. 
    <DataProtectionPermission(SecurityAction.Demand, Unrestricted:=True), SecuritySafeCritical()> _
    Public Sub New(ByVal appName As String, ByVal primaryPurpose As String, ParamArray specificPurpose() As String)
        MyBase.New(appName, primaryPurpose, specificPurpose)

    End Sub 'New 
End Class 'MemoryProtector

.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.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft