Merge pull request #20 from selfmadecode/dev_raphael_aes

feat: add code comments for encryption aes decryption and include code clean up for better maintainability

Author: selfmadecode

SafeCrypt.csproj

@@ -4,4 +4,8 @@
     <TargetFramework>netstandard2.0</TargetFramework>
   </PropertyGroup>
 
+  <ItemGroup>
+    <PackageReference Include="System.ComponentModel.Annotations" Version="5.0.0" />
+  </ItemGroup>
+
 </Project>

src/Encryption/AesEncryption/BaseAesEncryption.cs

@@ -1,28 +1,52 @@
-using System;
+using SafeCrypt.src.Encryption.AesEncryption.Models;
+using System;
 using System.IO;
 using System.Security.Cryptography;
 
 namespace SafeCrypt.src.Encrypt.AesEncryption
 {
     public class BaseAesEncryption
     {
-        // Method to encrypt data using AES algorithm
-        public virtual byte[] EncryptAES(byte[] data, byte[] key, byte[] iv)
+        /// <summary>
+        /// Encrypts the provided data using the Advanced Encryption Standard (AES) algorithm.
+        /// </summary>
+        /// <param name="param.Data">The data to be encrypted.</param>
+        /// <param name="param.SecretKey">The secret key used for encryption.</param>
+        /// <param name="param.IV">The initialization vector used for encryption.</param>
+        /// <returns>The encrypted data as a byte array.</returns>
+        /// <remarks>
+        /// The method uses the AES algorithm to encrypt the input data with the provided key and initialization vector.
+        /// </remarks>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown if the input data, key, or initialization vector is null.
+        /// </exception>
+        /// <exception cref="Exception">
+        /// Thrown for general encryption-related exceptions.
+        /// </exception>
+        public virtual byte[] EncryptAES(ByteEncryptionParameters param)
         {
             try
             {
+                // Create an instance of the AES algorithm
                 using (Aes aes = Aes.Create())
                 {
-                    aes.Key = key;
-                    aes.IV = iv;
+                    // Set the key and initialization vector
+                    aes.Key = param.SecretKey;
+                    aes.IV = param.IV;
+                    // Create an encryptor using the key and initialization vector
                     ICryptoTransform encryptor = aes.CreateEncryptor(aes.Key, aes.IV);
+
+                    // Use a MemoryStream to store the encrypted data
                     using (MemoryStream memoryStream = new MemoryStream())
                     {
+                        // Use a CryptoStream to perform the encryption
                         using (CryptoStream cryptoStream = new CryptoStream(memoryStream, encryptor, CryptoStreamMode.Write))
                         {
-                            cryptoStream.Write(data, 0, data.Length);
+                            // Write the data to be encrypted to the CryptoStream
+                            cryptoStream.Write(param.Data, 0, param.Data.Length);
                             cryptoStream.FlushFinalBlock();
 
+                            // Return the encrypted data as a byte array
                             return memoryStream.ToArray();
                         }
                     }
@@ -34,20 +58,41 @@ public virtual byte[] EncryptAES(byte[] data, byte[] key, byte[] iv)
             }
         }
 
-        // Method to decrypt data using AES algorithm
+        /// <summary>
+        /// Decrypts the provided encrypted data using the Advanced Encryption Standard (AES) algorithm.
+        /// </summary>
+        /// <param name="encryptedData">The data to be decrypted.</param>
+        /// <param name="key">The secret key used for decryption.</param>
+        /// <param name="iv">The initialization vector used for decryption.</param>
+        /// <returns>The decrypted data as a byte array.</returns>
+        /// <remarks>
+        /// The method uses the AES algorithm to decrypt the input encrypted data with the provided key and initialization vector.
+        /// </remarks>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown if the input encrypted data, key, or initialization vector is null.
+        /// </exception>
         public static byte[] DecryptAES(byte[] encryptedData, byte[] key, byte[] iv)
         {
+            // Create an instance of the AES algorithm
             using (Aes aes = Aes.Create())
             {
+                // Set the key and initialization vector
                 aes.Key = key;
                 aes.IV = iv;
+
+                // Create a decryptor using the key and initialization vector
                 ICryptoTransform decryptor = aes.CreateDecryptor(aes.Key, aes.IV);
+
+                // Use a MemoryStream to read the encrypted data
                 using (MemoryStream memoryStream = new MemoryStream(encryptedData))
                 {
+                    // Use a CryptoStream to perform the decryption
                     using (CryptoStream cryptoStream = new CryptoStream(memoryStream, decryptor, CryptoStreamMode.Read))
                     {
+                        // Use a MemoryStream to store the decrypted data
                         using (MemoryStream decryptedStream = new MemoryStream())
                         {
+                            // Copy the decrypted data from the CryptoStream to the MemoryStream
                             cryptoStream.CopyTo(decryptedStream);
                             return decryptedStream.ToArray();
                         }
@@ -56,10 +101,22 @@ public static byte[] DecryptAES(byte[] encryptedData, byte[] key, byte[] iv)
             }
         }
 
-        // Method to generate a random byte array of given length
-        // Used to get the IV
-        // Generate a random 16-byte IV for AES in CBC mode
-        public static byte[] GenerateRandomBytes(int length)
+        
+        /// <summary>
+        /// Generates an array of random bytes using a cryptographically secure random number generator.
+        /// </summary>
+        /// <param name="length">The length of the byte array to generate.</param>
+        /// <returns>An array of random bytes or the IV key</returns>
+        /// <remarks>
+        /// The method uses a cryptographically secure random number generator (RNGCryptoServiceProvider) to generate
+        /// a byte array with the specified length, providing a high level of randomness suitable for cryptographic use.
+        /// </remarks>
+        /// <param name="length">The desired length of the generated byte array.</param>
+        /// <returns>An array of random bytes with the specified length.</returns>
+        /// <exception cref="ArgumentException">
+        /// Thrown if the specified length is less than or equal to zero.
+        /// </exception>
+        public static byte[] GenerateRandomIVKeyAsBytes(int length)
         {
             byte[] randomBytes = new byte[length];
             using (RNGCryptoServiceProvider rng = new RNGCryptoServiceProvider())

src/Encryption/AesEncryption/Decrypting.cs

@@ -1,8 +1,6 @@
 using SafeCrypt.src.Encrypt.AesEncryption;
 using SafeCrypt.src.Helpers;
 using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace SafeCrypt.src.Encryption.AesEncryption
 {

src/Encryption/AesEncryption/Encrypting.cs

@@ -1,42 +1,87 @@
 using System;
 using System.Text;
-using System.Security.Cryptography;
 using SafeCrypt.src.Helpers;
 using SafeCrypt.src.Encryption.AesEncryption.Models;
 
 namespace SafeCrypt.src.Encrypt.AesEncryption
 {
     public class Encrypting : BaseAesEncryption
     {
-        public byte[] Encrypt(byte[] data, byte[] secretKey, byte[] iv)
-            => EncryptAES(data, secretKey, iv);
+        /// <summary>
+        /// Encrypts the provided data using the specified secret key and initialization vector (IV).
+        /// </summary>
+        /// <param name="parameters">The encryption parameters.</param>
+        /// <returns>The encrypted data as a byte array.</returns>
+        /// <remarks>
+        /// This method serves as a wrapper around the underlying AES encryption logic provided by the
+        /// <see cref="EncryptAES"/> method. It simplifies the encryption process by exposing a more
+        /// user-friendly interface, accepting data, secret key, and initialization vector as parameters.
+        /// </remarks>
+        /// <param name="data">The data to be encrypted.</param>
+        /// <param name="secretKey">The secret key used for encryption.</param>
+        /// <param name="iv">The initialization vector used for encryption.</param>
+        /// <returns>The encrypted data as a byte array.</returns>
+        public byte[] Encrypt(ByteEncryptionParameters param)
+        {
+            Validators.ValidateNotNull(param);
+
+            // Delegate the encryption to the underlying AES encryption method
+            return EncryptAES(param);
+        }
 
 
-        public byte[] Encrypt(string data, string secretKey, string iv)
+        public byte[] Encrypt(StringEncryptionParameters param)
         {
-            NullChecks(data, secretKey, iv);
+            Validators.ValidateNotNull(param);
 
-            var aesKey = secretKey.ConvertKeysToBytes();
-            var aesIv = iv.ConvertKeysToBytes();
+            var byteEncryptionParameters = new ByteEncryptionParameters
+            {
+                SecretKey = param.SecretKey.ConvertKeysToBytes(),
+                IV = param.IV.ConvertKeysToBytes(),
+                Data = param.Data.HexadecimalStringToByteArray()
+            };
 
-            var aesData = data.HexadecimalStringToByteArray();
-            return EncryptAES(aesData, aesKey, aesIv);
+            return EncryptAES(byteEncryptionParameters);
         }
 
-       
-
-        public AesEncryptionData Encrypt(string data, string secretKey)
+        /// <summary>
+        /// Encrypts the provided string data using the Advanced Encryption Standard (AES) algorithm.
+        /// </summary>
+        /// <param name="data">The string data to be encrypted.</param>
+        /// <param name="secretKey">The secret key used for encryption.</param>
+        /// <returns>An <see cref="AesEncrypted"/> object containing the encrypted data and initialization vector (IV).</returns>
+        /// <remarks>
+        /// This method encrypts the input string data using the specified secret key and a randomly generated initialization
+        /// vector (IV) for AES encryption in Cipher Block Chaining (CBC) mode. The resulting encrypted data and IV are encapsulated
+        /// in an <see cref="AesEncrypted"/> object, which is then returned.
+        /// </remarks>
+        /// <param name="data">The string data to be encrypted.</param>
+        /// <param name="secretKey">The secret key used for encryption.</param>
+        /// <returns>An <see cref="AesEncrypted"/> object containing the encrypted data and initialization vector (IV).</returns>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown if the input data or secret key is null.
+        /// </exception>
+        public EncryptionData Encrypt(string data, string secretKey)
         {
             NullChecks(data, secretKey);
 
-            var aesIv = GenerateRandomBytes(16);
+            // Generate a random 16-byte IV for AES in CBC mode
+            var aesIv = GenerateRandomIVKeyAsBytes(16);
 
-            var aesKey = Encoding.UTF8.GetBytes(secretKey);
-            var aesData = data.HexadecimalStringToByteArray();
+            //var aesKey = Encoding.UTF8.GetBytes(secretKey);
+            //var aesData = data.HexadecimalStringToByteArray();
 
-            var response = EncryptAES(aesData, aesKey, aesIv);
+            var byteEncryptionParameters = new ByteEncryptionParameters
+            {
+                SecretKey = Encoding.UTF8.GetBytes(secretKey),
+                IV = aesIv,
+                Data = data.HexadecimalStringToByteArray()
+            };
 
-            var responseData = new AesEncryptionData
+            //var response = EncryptAES(aesData, aesKey, aesIv);
+            var response = EncryptAES(byteEncryptionParameters);
+
+            var responseData = new EncryptionData
             {
                 Data = response,
                 Iv = aesIv
@@ -45,43 +90,90 @@ public AesEncryptionData Encrypt(string data, string secretKey)
             return responseData;
         }
 
-        public string EncryptByteToHexString(byte[] data, byte[] secretKey, byte[] iv)
+        /// <summary>
+        /// Encrypts the provided byte data using the Advanced Encryption Standard (AES) algorithm
+        /// and returns the encrypted data as a hexadecimal string.
+        /// </summary>
+        /// <param name="param">The parameters containing the byte data, secret key, and initialization vector (IV).</param>
+        /// <returns>The encrypted data represented as a hexadecimal string.</returns>
+        /// <remarks>
+        /// This method encrypts the input byte data using the specified secret key and initialization vector (IV)
+        /// using the AES algorithm. The resulting encrypted data is then converted to a hexadecimal string before being
+        /// returned. The encryption parameters are encapsulated in a <see cref="ByteEncryptionParameters"/> object.
+        /// </remarks>
+        /// <param name="param">The parameters containing the byte data, secret key, and initialization vector (IV).</param>
+        /// <returns>The encrypted data represented as a hexadecimal string.</returns>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown if the input parameters or byte data is null.
+        /// </exception>
+        public string EncryptByteToHexString(ByteEncryptionParameters param)
         {
-            var cipherText = EncryptAES(data, secretKey, iv);
+            Validators.ValidateNotNull(param);
+
+            var cipherText = EncryptAES(param);
 
+            // Convert the encrypted data to a hexadecimal string
             return cipherText.ByteArrayToHexString();
         }
 
-        public string EncryptByteToBase64String(byte[] data, byte[] secretKey, byte[] iv)
+        /// <summary>
+        /// Encrypts the provided byte data using the Advanced Encryption Standard (AES) algorithm
+        /// and returns the encrypted data as a Base64-encoded string.
+        /// </summary>
+        /// <param name="param">The parameters containing the byte data, secret key, and initialization vector (IV).</param>
+        /// <returns>The encrypted data represented as a Base64-encoded string.</returns>
+        /// <remarks>
+        /// This method encrypts the input byte data using the specified secret key and initialization vector (IV)
+        /// using the AES algorithm. The resulting encrypted data is then converted to a Base64-encoded string before
+        /// being returned. The encryption parameters are encapsulated in a <see cref="ByteEncryptionParameters"/> object.
+        /// </remarks>
+        /// <param name="param">The parameters containing the byte data, secret key, and initialization vector (IV).</param>
+        /// <returns>The encrypted data represented as a Base64-encoded string.</returns>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown if the input parameters or byte data is null.
+        /// </exception>
+        public string EncryptByteToBase64String(ByteEncryptionParameters param)
         {
-            var cipherText = EncryptAES(data, secretKey, iv);
+            Validators.ValidateNotNull(param);
+
+            var cipherText = EncryptAES(param);
 
             return Convert.ToBase64String(cipherText);
         }
 
-        public string EncryptByteToString(byte[] data, byte[] secretKey, byte[] iv)
+        /// <summary>
+        /// Encrypts the provided byte data using the Advanced Encryption Standard (AES) algorithm
+        /// and returns the encrypted data as a string using UTF-8 encoding.
+        /// </summary>
+        /// <param name="param">The parameters containing the byte data, secret key, and initialization vector (IV).</param>
+        /// <returns>The encrypted data represented as a string using UTF-8 encoding.</returns>
+        /// <remarks>
+        /// This method encrypts the input byte data using the specified secret key and initialization vector (IV)
+        /// using the AES algorithm. The resulting encrypted data is then converted to a string using UTF-8
+        /// encoding before being returned. The encryption parameters are encapsulated in a <see cref="ByteEncryptionParameters"/> object.
+        /// </remarks>
+        /// <param name="param">The parameters containing the byte data, secret key, and initialization vector (IV).</param>
+        /// <returns>The encrypted data represented as a string using UTF-8 encoding.</returns>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown if the input parameters or byte data is null.
+        /// </exception>
+        public string EncryptByteToString(ByteEncryptionParameters param)
         {
-            var cipherText = EncryptAES(data, secretKey, iv);
+            Validators.ValidateNotNull(param);
+
+            var cipherText = EncryptAES(param);
 
             return cipherText.BytesToString();
         }
+                    
 
-        // needs methods that would accept aes mode
-        //public byte[] AesEncrypt(byte[] data, byte[] key, byte[] iv, ReturnType returnType)
-        //{
-
-        //}     
-
-        private void NullChecks(string data, string secretKey, string iv = "")
+        private void NullChecks(string data, string secretKey)
         {
             if (data == null || data.Length <= 0)
                 throw new ArgumentNullException(nameof(data));
 
             if (secretKey == null || secretKey.Length <= 0)
                 throw new ArgumentNullException(nameof(secretKey));
-
-            if (iv == null || iv.Length <= 0)
-                throw new ArgumentNullException(nameof(iv));
         }
     }
 

src/Encryption/AesEncryption/Models/AesEncryptionData.cs

@@ -0,0 +1,22 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace SafeCrypt.src.Encryption.AesEncryption.Models
+{
+    /// <summary>
+    /// Represents the data and initialization vector (IV) used in encryption.
+    /// </summary>
+    public class EncryptionData
+    {
+        /// <summary>
+        /// Gets or sets the data to be encrypted.
+        /// </summary>
+        public byte[] Data { get; set; }
+
+        /// <summary>
+        /// Gets or sets the initialization vector (IV) used for encryption.
+        /// </summary>
+        public byte[] Iv { get; set; }
+    }
+}