wagesj45/CapyKit
wagesj45/CapyKit
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity

Generate API docs as markdown

Browse source
This commit is contained in:
Jordan Wages 2026-07-07 01:56:58 -05:00
commit 85e90f7bd5
120 changed files with 14227 additions and 76482 deletions
Download patch file Download diff file Expand all files Collapse all files

371
Docs/api/CapyKit.Helpers.SecurityHelper.md Normal file
View file

@ -0,0 +1,371 @@
# <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.