#163 Refactor examples, docs, and improve developer tooling

Refactored example methods to use PascalCase, added XML comments, and improved variable naming for clarity. Standardized key management APIs across AES, DSA, and RSA examples. Enhanced file encryption examples to support arbitrary file types.

Updated documentation with detailed examples, migration guides, and a new `tooling.md` for developer workflows. Improved CI/CD documentation and reusable workflow examples in `CONTRIBUTING.md`.

Added support for special characters in encryption examples and advanced PEM operations. Updated project structure to include a "Docs" project and additional documentation files. Enhanced code readability, consistency, and developer experience.

Author: maythamfahmi

CONTRIBUTING.md

@@ -18,18 +18,18 @@ contributors must follow to avoid common build and packaging failures.
 
 ### Example: Caller (no `runs-on`)
 
-``` yaml
+~~~ yaml
 jobs:
   call-build:
     uses: ./.github/workflows/cd-build-test-pack.yml
     with:
       version: ${{ github.ref_name }}
       configuration: Release
-```
+~~~
 
 ### Example: Reusable Workflow
 
-``` yaml
+~~~ yaml
 on:
   workflow_call:
     inputs:
@@ -48,7 +48,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
       # �
-```
+~~~
 
 ## Versioning and Git Tag Guidelines
 
@@ -78,15 +78,15 @@ jobs:
 
 ### Sanitization Example
 
-``` yaml
+~~~ yaml
 - name: Sanitize version
   id: sanitize
   run: |
     v="${{ inputs.version }}"
     v="${v#v}"
     v="${v#V}"
     echo "sanitized_version=$v" >> "$GITHUB_OUTPUT"
-```
+~~~
 
 Use via: `${{ steps.sanitize.outputs.sanitized_version }}`
 

CryptoNet.Examples/ExampleAes.cs

@@ -12,119 +12,146 @@
 
 namespace CryptoNet.Examples;
 
+/// <summary>
+/// Example usage scenarios for AES symmetric encryption using the CryptoNet library.
+/// Demonstrates generating, saving/loading symmetric keys and encrypting/decrypting
+/// both content and files.
+/// </summary>
 public static class ExampleAes
 {
     private const string ConfidentialDummyData = @"Some Secret Data";
 
-    private static readonly string BaseFolder = AppDomain.CurrentDomain.BaseDirectory;
-    private readonly static string SymmetricKeyFile = Path.Combine(BaseFolder, $"{KeyType.SymmetricKey}.xml");
+    private static readonly string BaseDirectory = AppDomain.CurrentDomain.BaseDirectory;
+    private static readonly string SymmetricKeyFilePath = Path.Combine(BaseDirectory, $"{KeyType.SymmetricKey}.xml");
 
-    public static void Example_1_Encrypt_Decrypt_Content_With_SelfGenerated_SymmetricKey()
+    /// <summary>
+    /// Generate a symmetric key, encrypt and decrypt a string using self-generated key.
+    /// </summary>
+    public static void EncryptDecryptWithSelfGeneratedSymmetricKey()
     {
         ICryptoNetAes cryptoNet = new CryptoNetAes();
-        var key = cryptoNet.GetKey();
+        string key = cryptoNet.GetKey();
 
         ICryptoNet encryptClient = new CryptoNetAes(key);
-        var encrypt = encryptClient.EncryptFromString(ConfidentialDummyData);
+        byte[] encrypted = encryptClient.EncryptFromString(ConfidentialDummyData);
 
         ICryptoNet decryptClient = new CryptoNetAes(key);
-        var decrypt = decryptClient.DecryptToString(encrypt);
+        string decrypted = decryptClient.DecryptToString(encrypted);
 
-        Debug.Assert(ConfidentialDummyData == decrypt);
+        Debug.Assert(ConfidentialDummyData == decrypted);
     }
 
-    public static void Example_2_SelfGenerated_And_Save_SymmetricKey()
+    /// <summary>
+    /// Generate a symmetric key and save it to disk, then load it to decrypt previously encrypted content.
+    /// </summary>
+    public static void GenerateAndSaveSymmetricKey()
     {
         ICryptoNetAes cryptoNet = new CryptoNetAes();
-        var file = new FileInfo(SymmetricKeyFile);
-        cryptoNet.SaveKey(file);
+        FileInfo keyFile = new FileInfo(SymmetricKeyFilePath);
+        cryptoNet.SaveKey(keyFile);
 
-        Debug.Assert(File.Exists(file.FullName));
+        Debug.Assert(File.Exists(keyFile.FullName));
 
-        var encrypt = cryptoNet.EncryptFromString(ConfidentialDummyData);
+        byte[] encrypted = cryptoNet.EncryptFromString(ConfidentialDummyData);
 
-        ICryptoNet cryptoNetKeyImport = new CryptoNetAes(file);
-        var decrypt = cryptoNetKeyImport.DecryptToString(encrypt);
+        ICryptoNet cryptoNetImported = new CryptoNetAes(keyFile);
+        string decrypted = cryptoNetImported.DecryptToString(encrypted);
 
-        Debug.Assert(ConfidentialDummyData == decrypt);
+        Debug.Assert(ConfidentialDummyData == decrypted);
     }
 
-    public static void Example_3_Encrypt_Decrypt_Content_With_Own_SymmetricKey()
+    /// <summary>
+    /// Encrypt and decrypt using a provided raw symmetric key and IV.
+    /// </summary>
+    public static void EncryptDecryptWithProvidedSymmetricKey()
     {
-        var symmetricKey = "12345678901234567890123456789012";
+        string symmetricKey = "12345678901234567890123456789012";
         if (symmetricKey.Length != 32)
         {
-            Console.WriteLine("key should be 32 character long");
+            Console.WriteLine("Key should be 32 characters long");
             Environment.Exit(0);
         }
 
-        var secret = "1234567890123456";
+        string secret = "1234567890123456";
         if (secret.Length != 16)
         {
-            Console.WriteLine("key should be 16 character long");
+            Console.WriteLine("IV should be 16 characters long");
             Environment.Exit(1);
         }
 
-        var key = Encoding.UTF8.GetBytes(symmetricKey);
-        var iv = Encoding.UTF8.GetBytes(secret);
+        byte[] key = Encoding.UTF8.GetBytes(symmetricKey);
+        byte[] iv = Encoding.UTF8.GetBytes(secret);
 
         ICryptoNet encryptClient = new CryptoNetAes(key, iv);
-        var encrypt = encryptClient.EncryptFromString(ConfidentialDummyData);
+        byte[] encrypted = encryptClient.EncryptFromString(ConfidentialDummyData);
 
         ICryptoNet decryptClient = new CryptoNetAes(key, iv);
-        var decrypt = decryptClient.DecryptToString(encrypt);
+        string decrypted = decryptClient.DecryptToString(encrypted);
 
-        Debug.Assert(ConfidentialDummyData == decrypt);
+        Debug.Assert(ConfidentialDummyData == decrypted);
     }
 
-    public static void Example_4_Encrypt_Decrypt_Content_With_Human_Readable_Key_Secret_SymmetricKey()
+    /// <summary>
+    /// Generate a human-readable key/secret pair and use them for encryption/decryption.
+    /// </summary>
+    public static void EncryptDecryptWithHumanReadableKeySecret()
     {
-        var symmetricKey = UniqueKeyGenerator("symmetricKey");
-        var secret = new string(UniqueKeyGenerator("password").Take(16).ToArray());
+        string symmetricKey = GenerateUniqueKey("symmetricKey");
+        string secret = new string(GenerateUniqueKey("password").Take(16).ToArray());
 
-        var key = Encoding.UTF8.GetBytes(symmetricKey);
-        var iv = Encoding.UTF8.GetBytes(secret);
+        byte[] key = Encoding.UTF8.GetBytes(symmetricKey);
+        byte[] iv = Encoding.UTF8.GetBytes(secret);
 
         ICryptoNet encryptClient = new CryptoNetAes(key, iv);
-        var encrypt = encryptClient.EncryptFromString(ConfidentialDummyData);
+        byte[] encrypted = encryptClient.EncryptFromString(ConfidentialDummyData);
 
         ICryptoNet decryptClient = new CryptoNetAes(key, iv);
-        var decrypt = decryptClient.DecryptToString(encrypt);
+        string decrypted = decryptClient.DecryptToString(encrypted);
 
-        Debug.Assert(ConfidentialDummyData == decrypt);
+        Debug.Assert(ConfidentialDummyData == decrypted);
     }
 
-    public static void Example_5_Encrypt_And_Decrypt_File_With_SymmetricKey_Test(string filename)
+    /// <summary>
+    /// Encrypt and decrypt a file using a self-generated symmetric key and verify content equality.
+    /// </summary>
+    /// <param name="filename">Relative path under TestFiles directory to the file to encrypt.</param>
+    public static void EncryptAndDecryptFileWithSymmetricKeyTest(string filename)
     {
         ICryptoNetAes cryptoNet = new CryptoNetAes();
-        var key = cryptoNet.GetKey();
+        string key = cryptoNet.GetKey();
 
-        FileInfo fi = new FileInfo(filename);
+        FileInfo fileInfo = new FileInfo(filename);
 
         ICryptoNet encryptClient = new CryptoNetAes(key);
-        string pdfFilePath = Path.Combine(BaseFolder, filename);
-        byte[] pdfFileBytes = File.ReadAllBytes(pdfFilePath);
-        var encrypt = encryptClient.EncryptFromBytes(pdfFileBytes);
+        string sourceFilePath = Path.Combine(BaseDirectory, filename);
+        byte[] fileBytes = File.ReadAllBytes(sourceFilePath);
+        byte[] encrypted = encryptClient.EncryptFromBytes(fileBytes);
 
         ICryptoNet decryptClient = new CryptoNetAes(key);
-        var decrypt = decryptClient.DecryptToBytes(encrypt);
-        string pdfDecryptedFilePath = $"TestFiles\\{Path.GetFileNameWithoutExtension(fi.Name)}-decrypted.{fi.Extension}";
-        File.WriteAllBytes(pdfDecryptedFilePath, decrypt);
+        byte[] decrypted = decryptClient.DecryptToBytes(encrypted);
+        string decryptedFilePath = $"TestFiles\\{Path.GetFileNameWithoutExtension(fileInfo.Name)}-decrypted{fileInfo.Extension}";
+        File.WriteAllBytes(decryptedFilePath, decrypted);
 
-        var isIdenticalFile = ExtShared.ExtShared.ByteArrayCompare(pdfFileBytes, decrypt);
+        bool isIdenticalFile = ExtShared.ExtShared.ByteArrayCompare(fileBytes, decrypted);
         Debug.Assert(isIdenticalFile);
     }
 
-    public static string UniqueKeyGenerator(string input)
+    /// <summary>
+    /// Create a deterministic unique key string from input using MD5 (example helper).
+    /// </summary>
+    /// <param name="input">Input string to derive the key from.</param>
+    /// <returns>Hexadecimal string representation of MD5 hash.</returns>
+    public static string GenerateUniqueKey(string input)
     {
         byte[] inputBytes = Encoding.ASCII.GetBytes(input);
         byte[] hash = MD5.HashData(inputBytes);
 
         StringBuilder sb = new StringBuilder();
-        foreach (var t in hash)
+        foreach (byte b in hash)
         {
-            sb.Append(t.ToString("X2"));
+            sb.Append(b.ToString("X2"));
         }
+
         return sb.ToString();
     }
 }

CryptoNet.Examples/ExampleDsa.cs

@@ -13,48 +13,57 @@
 
 namespace CryptoNet.Examples;
 
+/// <summary>
+/// Example usage scenarios for DSA operations using the CryptoNet library.
+/// Demonstrates signing, verification and saving/loading DSA keys.
+/// </summary>
 public static class ExampleDsa
 {
     private const string ConfidentialDummyData = @"Some Secret Data";
-    private static readonly string BaseFolder = AppDomain.CurrentDomain.BaseDirectory;
+    private static readonly string BaseDirectory = AppDomain.CurrentDomain.BaseDirectory;
 
-    internal static readonly string PrivateKeyFile = Path.Combine(BaseFolder, "privateKey");
-    internal static readonly string PublicKeyFile = Path.Combine(BaseFolder, "publicKey.pub");
+    internal static readonly string PrivateKeyFilePath = Path.Combine(BaseDirectory, "privateKey");
+    internal static readonly string PublicKeyFilePath = Path.Combine(BaseDirectory, "publicKey.pub");
 
-    public static void Example_1_Sign_Validate_Content_With_SelfGenerated_AsymmetricKey()
+    /// <summary>
+    /// Demonstrates signing content with a self-generated DSA key and validating the signature.
+    /// </summary>
+    public static void SignAndValidateWithSelfGeneratedKey()
     {
         ICryptoNetDsa client = new CryptoNetDsa();
-        var privateKey = client.GetKey(true);
+        string privateKeyXml = client.GetKey(true);
 
-        ICryptoNetDsa signatureClient = new CryptoNetDsa(privateKey);
-        var signature = signatureClient.CreateSignature(ConfidentialDummyData);
+        ICryptoNetDsa signatureClient = new CryptoNetDsa(privateKeyXml);
+        byte[] signature = signatureClient.CreateSignature(ConfidentialDummyData);
 
-        ICryptoNetDsa verifyClient = new CryptoNetDsa(privateKey);
-        var confidentialAsBytes = ExtShared.ExtShared.StringToBytes(ConfidentialDummyData);
+        ICryptoNetDsa verifyClient = new CryptoNetDsa(privateKeyXml);
+        byte[] contentBytes = ExtShared.ExtShared.StringToBytes(ConfidentialDummyData);
 
-        bool isVerified = verifyClient.IsContentVerified(confidentialAsBytes, signature);
+        bool isVerified = verifyClient.IsContentVerified(contentBytes, signature);
 
         Debug.Assert(isVerified == true);
     }
 
-    public static void Example_2_SelfGenerated_And_Save_AsymmetricKey()
+    /// <summary>
+    /// Demonstrates generating DSA key pair, saving them to files, and verifying signatures using loaded keys.
+    /// </summary>
+    public static void GenerateAndSaveDsaKeyPair()
     {
         ICryptoNetDsa cryptoNet = new CryptoNetDsa();
 
-        cryptoNet.SaveKey(new FileInfo(PrivateKeyFile), true);
-        cryptoNet.SaveKey(new FileInfo(PublicKeyFile), false);
+        cryptoNet.SaveKey(new FileInfo(PrivateKeyFilePath), true);
+        cryptoNet.SaveKey(new FileInfo(PublicKeyFilePath), false);
 
-        Debug.Assert(File.Exists(new FileInfo(PrivateKeyFile).FullName));
-        Debug.Assert(File.Exists(new FileInfo(PublicKeyFile).FullName));
+        Debug.Assert(File.Exists(new FileInfo(PrivateKeyFilePath).FullName));
+        Debug.Assert(File.Exists(new FileInfo(PublicKeyFilePath).FullName));
 
-        ICryptoNetDsa dsaWithPrivateKey = new CryptoNetDsa(new FileInfo(PrivateKeyFile));
-        var signature = dsaWithPrivateKey.CreateSignature(ConfidentialDummyData);
+        ICryptoNetDsa dsaWithPrivateKey = new CryptoNetDsa(new FileInfo(PrivateKeyFilePath));
+        byte[] signature = dsaWithPrivateKey.CreateSignature(ConfidentialDummyData);
 
-        ICryptoNetDsa dsaWithPublicKey = new CryptoNetDsa(new FileInfo(PublicKeyFile));
-        var confidentialAsBytes = ExtShared.ExtShared.StringToBytes(ConfidentialDummyData);
-        var isVerified = dsaWithPublicKey.IsContentVerified(confidentialAsBytes, signature);
+        ICryptoNetDsa dsaWithPublicKey = new CryptoNetDsa(new FileInfo(PublicKeyFilePath));
+        byte[] confidentialBytes = ExtShared.ExtShared.StringToBytes(ConfidentialDummyData);
+        bool isVerified = dsaWithPublicKey.IsContentVerified(confidentialBytes, signature);
 
         Debug.Assert(isVerified == true);
     }
-    
 }