Skip to content

Commit 1c10ddf

Browse files
selfmadecodeselfmadecode
committed
add Aes readme doc
1 parent c069d94 commit 1c10ddf

1 file changed

Lines changed: 177 additions & 0 deletions

File tree

‎doc/Aes.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
what is secret, what is the length
2+
what is IV, what is the lenght, IV as base 64, IV as hex
3+
how to generate default IV with the package
4+
5+
6+
# SafeCrypt AES Encryption and Decryption
7+
8+
## Overview
9+
10+
The SafeCrypt library provides a simple and secure implementation of the Advanced Encryption Standard (AES) algorithm for
11+
encryption and decryption in C#.
12+
This document guides you through the basic steps to use AES encryption and decryption methods.
13+
14+
## Table of Contents
15+
16+
- [Usage](#usage)
17+
- [EncryptToHexStringAsync method](#encryptToHexStringAsync-method)
18+
- [Encrypting Data](#encrypting-data)
19+
- [Decrypting Data](#decrypting-data)
20+
- [EncryptToBase64StringAsync method](#encryptToBase64StringAsync-method)
21+
- [Example](#example)
22+
- [EncryptionData Object](#encryptiondata-object)
23+
- [Cipher Modes](#cipher-modes)
24+
- [Contributing](#contributing)
25+
26+
## Usage
27+
28+
### EncryptToHexStringAsync method
29+
30+
#### Encrypting Data
31+
32+
To encrypt data using the AES algorithm in this library, you first need to decide which method you want to use.
33+
The `EncryptToHexStringAsync` method returns a hexadecimal string, while `EncryptToBase64StringAsync` returns a Base64 string.
34+
Follow the steps below to use `EncryptToHexStringAsync`:
35+
36+
1. **Generate an IV Key:** Use the `KeyGenerators.GenerateHexadecimalIVKey()` method to create an Initialization Vector (IV) key. The IV is crucial for secure encryption.
37+
38+
2. **Generate a Secret Key:** Call `KeyGenerators.GenerateAesSecretKey(128)` to generate a secret key with the desired bit size. Supported bit sizes are 128, 192, or 256. Any other value will result in an exception.
39+
40+
3. **Create an EncryptionParameters Model:** Construct an `EncryptionParameters` model, providing the data to be encrypted, IV, and secret key.
41+
42+
4. **Call EncryptToHexStringAsync:** Invoke the `Aes.EncryptToHexStringAsync` method with the `EncryptionParameters` model to encrypt the data. Check for errors in the `Errors` property of the returned `EncryptionData` object.
43+
44+
#### Decrypting Data
45+
46+
To decrypt data encrypted with AES, follow these steps:
47+
48+
1. **Create a DecryptionParameters Model:** Build a `DecryptionParameters` model, providing the encrypted data, IV, and secret key used during encryption.
49+
50+
2. **Call DecryptFromHexStringAsync:** Use the `Aes.DecryptFromHexStringAsync` method with the `DecryptionParameters` model to decrypt the data. Ensure that the provided IV and secret key match those used during encryption.
51+
52+
53+
54+
### EncryptToBase64StringAsync method
55+
To use the EncryptToBase64StringAsync method for encryption, follow these steps:
56+
57+
Generate an Initialization Vector (IV) using the KeyGenerators.GenerateBase64IVKey() method.
58+
Generate a secret key by calling the KeyGenerators.GenerateAesSecretKey(256) method. The parameter for this method accepts the following values: 128, 192, 256. Any value aside from these throws an exception with the message "Invalid key size. Supported sizes are 128, 192, or 256 bits."
59+
To encrypt the data, provide the EncryptionParameters model to the EncryptToBase64StringAsync method, along with an optional cipher mode. The cipher mode defaults to CBC if not specified.
60+
61+
62+
## Example
63+
64+
```csharp
65+
using SafeCrypt.AES;
66+
using SafeCrypt.Helpers;
67+
using SafeCrypt.Models;
68+
69+
// Using the EncryptToHexStringAsync and DecryptFromHexStringAsync methods
70+
71+
var aesIv = KeyGenerators.GenerateHexadecimalIVKey();
72+
var secret = KeyGenerators.GenerateAesSecretKey(256);
73+
74+
var dataToEncrypt = "Hello World";
75+
76+
var data = new EncryptionParameters
77+
{
78+
Data = dataToEncrypt,
79+
IV = aesIv,
80+
SecretKey = secret
81+
};
82+
83+
Console.WriteLine($"Hex Encryption Started");
84+
85+
Console.WriteLine();
86+
Console.WriteLine();
87+
88+
var encryptionResult = await Aes.EncryptToHexStringAsync(data);
89+
90+
if (encryptionResult.Errors.Count > 0)
91+
{
92+
// List errors here
93+
}
94+
95+
Console.WriteLine($"Hex Encrypted data: {encryptionResult.EncryptedData}");
96+
Console.WriteLine($"IV key: {encryptionResult.Iv}");
97+
Console.WriteLine($"Secret key: {encryptionResult.SecretKey}");
98+
99+
Console.WriteLine();
100+
Console.WriteLine();
101+
102+
Console.WriteLine($"Hex Decryption Started");
103+
104+
// Perform decryption using the same IV and secret
105+
var decryptionResult = await Aes.DecryptFromHexStringAsync(new DecryptionParameters
106+
{
107+
Data = encryptionResult.EncryptedData,
108+
IV = aesIv,
109+
SecretKey = secret
110+
});
111+
112+
Console.WriteLine($"Hex Decrypted data: {decryptionResult.DecryptedData}");
113+
Console.WriteLine($"IV key: {decryptionResult.Iv}");
114+
Console.WriteLine($"Secret key: {decryptionResult.SecretKey}");
115+
116+
117+
// Using the EncryptToBase64StringAsync and DecryptFromBase64StringAsync methods
118+
119+
var base64AesIv = KeyGenerators.GenerateBase64IVKey();
120+
121+
var base64dataToEncrypt = new EncryptionParameters
122+
{
123+
Data = dataToEncrypt,
124+
IV = base64AesIv,
125+
SecretKey = secret
126+
};
127+
128+
Console.WriteLine();
129+
Console.WriteLine();
130+
131+
132+
Console.WriteLine($"Base64 Encryption Started");
133+
134+
Console.WriteLine();
135+
Console.WriteLine();
136+
137+
var encryptedResult = await Aes.EncryptToBase64StringAsync(base64dataToEncrypt);
138+
Console.WriteLine($"Base64 Encrypted data: {encryptedResult.EncryptedData}");
139+
Console.WriteLine($"IV key: {encryptedResult.Iv}");
140+
Console.WriteLine($"Secret key: {encryptedResult.SecretKey}");
141+
142+
143+
Console.WriteLine();
144+
Console.WriteLine();
145+
146+
Console.WriteLine($"Base64 Decryption Started");
147+
148+
var decryptionResponse = await Aes.DecryptFromBase64StringAsync(new DecryptionParameters
149+
{
150+
Data = encryptedResult.EncryptedData,
151+
IV = base64AesIv,
152+
SecretKey = secret
153+
});
154+
155+
Console.WriteLine($"Base64 Decrypted data: {decryptionResponse.DecryptedData}");
156+
Console.WriteLine($"IV key: {decryptionResponse.Iv}");
157+
Console.WriteLine($"Secret key: {decryptionResponse.SecretKey}");
158+
```
159+
160+
## EncryptionData Object
161+
162+
The Encryption methods returns an `EncryptionData` object with the following properties:
163+
164+
- `EncryptedData`: Holds the encrypted data as a hexadecimal string.
165+
- `Iv`: The Initialization Vector used for encryption.
166+
- `SecretKey`: The secret key used for encryption.
167+
- `HasError`: If an error occurs during encryption, this property is set to true.
168+
- `Errors`: A list of all errors that occurred during encryption.
169+
170+
## Cipher Modes
171+
172+
By default, the methods uses Cipher Block Chaining (CBC) mode for both encryption and decryption.
173+
If you change the mode during encryption, provide the same mode during decryption.
174+
175+
## Contributing
176+
177+
Contributions to the SafeCrypt library are welcome! Follow the contribution guidelines and feel free to open issues or submit pull requests.

0 commit comments

Comments
 (0)