371 lines
14 KiB
Markdown
371 lines
14 KiB
Markdown
# <a id="CapyKit_Helpers_SecurityHelper"></a> Class SecurityHelper
|
|
|
|
Namespace: [CapyKit.Helpers](CapyKit.Helpers.md)
|
|
Assembly: CapyKit.dll
|
|
|
|
A class that contains methods for managing secure data processing and cryptography.
|
|
|
|
```csharp
|
|
public class SecurityHelper
|
|
```
|
|
|
|
#### Inheritance
|
|
|
|
[object](https://learn.microsoft.com/dotnet/api/system.object) ←
|
|
[SecurityHelper](CapyKit.Helpers.SecurityHelper.md)
|
|
|
|
#### Inherited Members
|
|
|
|
[object.Equals\(object?\)](https://learn.microsoft.com/dotnet/api/system.object.equals\#system\-object\-equals\(system\-object\)),
|
|
[object.Equals\(object?, object?\)](https://learn.microsoft.com/dotnet/api/system.object.equals\#system\-object\-equals\(system\-object\-system\-object\)),
|
|
[object.GetHashCode\(\)](https://learn.microsoft.com/dotnet/api/system.object.gethashcode),
|
|
[object.GetType\(\)](https://learn.microsoft.com/dotnet/api/system.object.gettype),
|
|
[object.MemberwiseClone\(\)](https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone),
|
|
[object.ReferenceEquals\(object?, object?\)](https://learn.microsoft.com/dotnet/api/system.object.referenceequals),
|
|
[object.ToString\(\)](https://learn.microsoft.com/dotnet/api/system.object.tostring)
|
|
|
|
#### Extension Methods
|
|
|
|
[ObjectExtensions.UpdateProperties<SecurityHelper\>\(SecurityHelper, SecurityHelper\)](CapyKit.Extensions.ObjectExtensions.md\#CapyKit\_Extensions\_ObjectExtensions\_UpdateProperties\_\_1\_\_\_0\_\_\_0\_),
|
|
[ObjectExtensions.UpdateProperties\(object, object\)](CapyKit.Extensions.ObjectExtensions.md\#CapyKit\_Extensions\_ObjectExtensions\_UpdateProperties\_System\_Object\_System\_Object\_)
|
|
|
|
## Methods
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_CompareHashedPassword__1_CapyKit_Password_System_String_System_Byte___System_Object___"></a> CompareHashedPassword<T\>\(Password, string, byte\[\], params object\[\]\)
|
|
|
|
Compares an unencrypted <code class="paramref">password</code> with a stored, encrypted <code class="paramref">existingPassword</code>.
|
|
This method uses the specified password algorithm type <code class="typeparamref">T</code> to retrieve the hashed version
|
|
of the <code class="paramref">password</code> and then compares it with the <code class="paramref">existingPassword</code>.
|
|
|
|
```csharp
|
|
public static bool CompareHashedPassword<T>(Password existingPassword, string password, byte[] salt, params object[] args)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`existingPassword` [Password](CapyKit.Password.md)
|
|
|
|
The existing, encrypted password.
|
|
|
|
`password` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The unencrypted password to be compared.
|
|
|
|
`salt` [byte](https://learn.microsoft.com/dotnet/api/system.byte)\[\]
|
|
|
|
The salt value used in password hashing.
|
|
|
|
`args` [object](https://learn.microsoft.com/dotnet/api/system.object)\[\]
|
|
|
|
Additional arguments required for constructing the password algorithm instance.
|
|
|
|
#### Returns
|
|
|
|
[bool](https://learn.microsoft.com/dotnet/api/system.boolean)
|
|
|
|
<a href="https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool">true</a> if hash comparison succeeds, <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool">false</a> if it fails.
|
|
|
|
#### Type Parameters
|
|
|
|
`T`
|
|
|
|
The type of the password hashing algorithm.
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_CompareHashedPassword_CapyKit_Password_System_String_System_Byte___CapyKit_IPasswordAlgorithm_System_Object___"></a> CompareHashedPassword\(Password, string, byte\[\], IPasswordAlgorithm, params object\[\]\)
|
|
|
|
Compares an unencrypted <code class="paramref">password</code> with a stored, encrypted <code class="paramref">existingPassword</code>.
|
|
This method uses the specified <code class="paramref">algorithm</code> to retrieve the hashed version
|
|
of the <code class="paramref">password</code> and then compares it with the <code class="paramref">existingPassword</code>.
|
|
|
|
```csharp
|
|
public static bool CompareHashedPassword(Password existingPassword, string password, byte[] salt, IPasswordAlgorithm algorithm, params object[] args)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`existingPassword` [Password](CapyKit.Password.md)
|
|
|
|
The existing, encrypted password.
|
|
|
|
`password` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The unencrypted password to be compared.
|
|
|
|
`salt` [byte](https://learn.microsoft.com/dotnet/api/system.byte)\[\]
|
|
|
|
The salt value used in password hashing.
|
|
|
|
`algorithm` [IPasswordAlgorithm](CapyKit.IPasswordAlgorithm.md)
|
|
|
|
The password hashing algorithm.
|
|
|
|
`args` [object](https://learn.microsoft.com/dotnet/api/system.object)\[\]
|
|
|
|
Additional arguments required for constructing the password algorithm instance.
|
|
|
|
#### Returns
|
|
|
|
[bool](https://learn.microsoft.com/dotnet/api/system.boolean)
|
|
|
|
<a href="https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool">true</a> if hash comparison succeeds, <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool">false</a> if it fails.
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_CompareSessionID_System_String_System_String_"></a> CompareSessionID\(string, string\)
|
|
|
|
Compares two session identifiers.
|
|
|
|
```csharp
|
|
public static bool CompareSessionID(string first, string second)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`first` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The first session identifier.
|
|
|
|
`second` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The second session identifier.
|
|
|
|
#### Returns
|
|
|
|
[bool](https://learn.microsoft.com/dotnet/api/system.boolean)
|
|
|
|
<a href="https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool">true</a> if comparison succeeds, <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool">false</a> if not.
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_GetPassword__1_System_String_System_Object___"></a> GetPassword<T\>\(string, params object\[\]\)
|
|
|
|
Retrieves a <xref href="CapyKit.Password" data-throw-if-not-resolved="false"></xref> object using the specified password and generates a random salt value.
|
|
Then it uses that salt to call the overloaded <xref href="CapyKit.Helpers.SecurityHelper.GetPassword%60%601(System.String%2cSystem.Byte%5b%5d%2cSystem.Object%5b%5d)" data-throw-if-not-resolved="false"></xref> method with the given password and
|
|
the generated salt as arguments.
|
|
|
|
```csharp
|
|
public static Password GetPassword<T>(string password, params object[] args)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`password` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The plaintext password to be hashed.
|
|
|
|
`args` [object](https://learn.microsoft.com/dotnet/api/system.object)\[\]
|
|
|
|
Optional constructor arguments for the <xref href="CapyKit.IPasswordAlgorithm" data-throw-if-not-resolved="false"></xref> implementation
|
|
instance.
|
|
|
|
#### Returns
|
|
|
|
[Password](CapyKit.Password.md)
|
|
|
|
A new <xref href="CapyKit.Password" data-throw-if-not-resolved="false"></xref> object with the given password and a randomly generated salt, as well as an
|
|
instance of <code class="typeparamref">T</code> created using any optional constructor arguments provided.
|
|
|
|
#### Type Parameters
|
|
|
|
`T`
|
|
|
|
The type of <xref href="CapyKit.IPasswordAlgorithm" data-throw-if-not-resolved="false"></xref> implementation to use.
|
|
|
|
#### See Also
|
|
|
|
[SecurityHelper](CapyKit.Helpers.SecurityHelper.md).SALT\_SIZE
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_GetPassword__1_System_String_System_Byte___System_Object___"></a> GetPassword<T\>\(string, byte\[\], params object\[\]\)
|
|
|
|
Retrieves a <xref href="CapyKit.Password" data-throw-if-not-resolved="false"></xref> object using the specified password, salt, and optional
|
|
constructor arguments.
|
|
|
|
```csharp
|
|
public static Password GetPassword<T>(string password, byte[] salt, params object[] args) where T : IPasswordAlgorithm
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`password` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The plaintext password to be hashed.
|
|
|
|
`salt` [byte](https://learn.microsoft.com/dotnet/api/system.byte)\[\]
|
|
|
|
A random value used as an additional input to the one-way function that hashes data, a
|
|
password or passphrase. This is used to make each output different for the same input
|
|
thus adding security.
|
|
|
|
`args` [object](https://learn.microsoft.com/dotnet/api/system.object)\[\]
|
|
|
|
Optional constructor arguments for the <xref href="CapyKit.IPasswordAlgorithm" data-throw-if-not-resolved="false"></xref> implementation
|
|
instance.
|
|
|
|
#### Returns
|
|
|
|
[Password](CapyKit.Password.md)
|
|
|
|
A new <xref href="CapyKit.Password" data-throw-if-not-resolved="false"></xref> object with the given password and salt, as well as an instance
|
|
of <code class="typeparamref">T</code> created using the provided constructor arguments.
|
|
|
|
#### Type Parameters
|
|
|
|
`T`
|
|
|
|
The type of <xref href="CapyKit.IPasswordAlgorithm" data-throw-if-not-resolved="false"></xref> implementation to use.
|
|
|
|
#### Remarks
|
|
|
|
This method uses reflection to find a constructor for the specified password algorithm type (<code class="typeparamref">T</code>).
|
|
It emits an error event if a suitable constructor is not found or if there is an error invoking the constructor.
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_GetRandomPassword_System_Int32_CapyKit_Helpers_ValidCharacterCollection___"></a> GetRandomPassword\(int, params ValidCharacterCollection\[\]\)
|
|
|
|
Gets a cryptographically strong random password.
|
|
|
|
```csharp
|
|
public static string GetRandomPassword(int length, params ValidCharacterCollection[] validCharacters)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`length` [int](https://learn.microsoft.com/dotnet/api/system.int32)
|
|
|
|
The length of the password to generate.
|
|
|
|
`validCharacters` [ValidCharacterCollection](CapyKit.Helpers.ValidCharacterCollection.md)\[\]
|
|
|
|
An array of <xref href="CapyKit.Helpers.ValidCharacterCollection" data-throw-if-not-resolved="false"></xref> enumeration values representing the desired
|
|
character sets.
|
|
|
|
#### Returns
|
|
|
|
[string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The password.
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_GetRandomString_System_Int32_"></a> GetRandomString\(int\)
|
|
|
|
A convenience method to generate a random string of the specified length using all character sets.
|
|
|
|
```csharp
|
|
public static string GetRandomString(int length)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`length` [int](https://learn.microsoft.com/dotnet/api/system.int32)
|
|
|
|
The desired length of the generated random string.
|
|
|
|
#### Returns
|
|
|
|
[string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
#### See Also
|
|
|
|
[ValidCharacterCollection](CapyKit.Helpers.ValidCharacterCollection.md),
|
|
[SecurityHelper](CapyKit.Helpers.SecurityHelper.md).[GetRandomString](CapyKit.Helpers.SecurityHelper.md\#CapyKit\_Helpers\_SecurityHelper\_GetRandomString\_System\_Int32\_CapyKit\_Helpers\_ValidCharacterCollection\_\_\_)\([int](https://learn.microsoft.com/dotnet/api/system.int32), params [ValidCharacterCollection](CapyKit.Helpers.ValidCharacterCollection.md)\[\]\)
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_GetRandomString_System_Int32_CapyKit_Helpers_ValidCharacterCollection___"></a> GetRandomString\(int, params ValidCharacterCollection\[\]\)
|
|
|
|
Gets a cryptographically strong random string using the character values found in VALID_CHARACTERS.
|
|
|
|
```csharp
|
|
public static string GetRandomString(int length, params ValidCharacterCollection[] validChars)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`length` [int](https://learn.microsoft.com/dotnet/api/system.int32)
|
|
|
|
The length of the string to create.
|
|
|
|
`validChars` [ValidCharacterCollection](CapyKit.Helpers.ValidCharacterCollection.md)\[\]
|
|
|
|
#### Returns
|
|
|
|
[string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The random string.
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_GetSalt_System_Int32_"></a> GetSalt\(int\)
|
|
|
|
Generates a random byte array that can act as a salt.
|
|
|
|
```csharp
|
|
public static byte[] GetSalt(int length = 32)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`length` [int](https://learn.microsoft.com/dotnet/api/system.int32)
|
|
|
|
(Optional) The desired length of the generated byte array.
|
|
|
|
#### Returns
|
|
|
|
[byte](https://learn.microsoft.com/dotnet/api/system.byte)\[\]
|
|
|
|
An array of byte.
|
|
|
|
#### Remarks
|
|
|
|
A default length of <xref href="CapyKit.Helpers.SecurityHelper.SALT_SIZE" data-throw-if-not-resolved="false"></xref> is provided as a sane default. Larger values can be used for increased
|
|
entropy.
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_Pbkdf2_System_String_System_Byte___"></a> Pbkdf2\(string, byte\[\]\)
|
|
|
|
Generates a new <xref href="CapyKit.Password" data-throw-if-not-resolved="false"></xref> object using the PBKDF2 algorithm with the provided <code class="paramref">password</code>
|
|
and <code class="paramref">salt</code>.
|
|
|
|
```csharp
|
|
public static Password Pbkdf2(string password, byte[] salt)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`password` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The clear text password to be hashed.
|
|
|
|
`salt` [byte](https://learn.microsoft.com/dotnet/api/system.byte)\[\]
|
|
|
|
A random value used to add an additional layer of security to the generated hash.
|
|
|
|
#### Returns
|
|
|
|
[Password](CapyKit.Password.md)
|
|
|
|
A new <xref href="CapyKit.Password" data-throw-if-not-resolved="false"></xref> object containing the hashed password and salt.
|
|
|
|
#### Remarks
|
|
|
|
This method uses the PBKDF2 (Password-Based Key Derivation Function 2) algorithm to generate
|
|
a new password hash. The algorithm iteratively applies a pseudorandom function to the
|
|
password and salt, which increases the security of the resulting hash.
|
|
|
|
### <a id="CapyKit_Helpers_SecurityHelper_Pbkdf2_System_String_"></a> Pbkdf2\(string\)
|
|
|
|
Generates a new <xref href="CapyKit.Password" data-throw-if-not-resolved="false"></xref> object using the PBKDF2 algorithm with the provided <code class="paramref">password</code>.
|
|
This overload of the method generates a random salt value for added security.
|
|
|
|
```csharp
|
|
public static Password Pbkdf2(string password)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`password` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The clear text password to be hashed.
|
|
|
|
#### Returns
|
|
|
|
[Password](CapyKit.Password.md)
|
|
|
|
A new <xref href="CapyKit.Password" data-throw-if-not-resolved="false"></xref> object containing the hashed password and a randomly generated salt.
|
|
|
|
#### Remarks
|
|
|
|
This method uses the PBKDF2 (Password-Based Key Derivation Function 2) algorithm to generate
|
|
a new password hash. The algorithm iteratively applies a pseudorandom function to the
|
|
password and salt, which increases the security of the resulting hash. In this overload,
|
|
a random salt value is generated using <xref href="CapyKit.Helpers.SecurityHelper.GetRandomBytes(System.Int32)" data-throw-if-not-resolved="false"></xref> method.
|
|
|