feat: support hardware intrinsics (#159)

* feat: ShuffleState and QuarterRound AVX2 and SSE3 and AdvSIMD

* chore: copilot feedback

* test: improve coverage

* chore: remove coverage dependency on build cake

* feat: add dotnet 10 and merge coverage from all platforms

* fix: wycheproof tests

* feat: improvements to code coverage for windows

* fix: exclude unused AVX2 256-bit methods

* feat: some minor improvements

* feat:  proper SSE2 and AdvSIMD optimizations for Poly1305

* chore: security improvements

* chore: fix azure devops publish

Author: daviddesmet

.github/workflows/ci.yml

@@ -71,7 +71,9 @@ jobs:
       uses: actions/upload-artifact@v4
       with:
         name: ${{matrix.os}}
-        path: ${{env.BUILD_ARTIFACT_PATH}}
+        path: |
+          ${{env.BUILD_ARTIFACT_PATH}}
+          !${{env.BUILD_ARTIFACT_PATH}}/**/In/**/*
 
   coverage:
     name: 'Process Coverage'
@@ -80,25 +82,30 @@ jobs:
     steps:
     - name: 'Checkout'
       uses: actions/checkout@v4
-    - name: 'Download Artifact'
+    - name: 'Download All Artifacts'
       uses: actions/download-artifact@v4
       with:
-        name: 'ubuntu-latest'
+        path: ./artifacts
+        pattern: '*-latest'
+        merge-multiple: false
     - name: 'Install .NET SDK'
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: | 
           6.0.x
           8.0.x
           9.0.x
+          10.0.x
     - name: 'Install ReportGenerator'
       run: dotnet tool install -g dotnet-reportgenerator-globaltool
-    - name: 'Generate Coverage Report'
-      run: reportgenerator -reports:./TestResults/**/coverage.cobertura.xml -targetdir:${{env.BUILD_ARTIFACT_PATH}}/TestResults/Coverage/Reports "-reporttypes:HtmlInline;HTMLChart;Cobertura"
+    - name: 'List Coverage Files'
+      run: find ./artifacts -name "coverage.cobertura.xml" -type f
+    - name: 'Generate Merged Coverage Report'
+      run: reportgenerator -reports:"./artifacts/**/coverage.cobertura.xml" -targetdir:${{env.BUILD_ARTIFACT_PATH}}/TestResults/Coverage/Reports "-reporttypes:HtmlInline;HTMLChart;Cobertura"
     - name: 'Upload Coverage'
       uses: codecov/codecov-action@v4
       with:
-        file: Cobertura.xml
+        file: ${{env.BUILD_ARTIFACT_PATH}}/TestResults/Coverage/Reports/Cobertura.xml
         fail_ci_if_error: false
         token: ${{ secrets.CODECOV_TOKEN }}
     - name: 'Publish Coverage Report'

NaCl.Core.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio 15
-VisualStudioVersion = 15.0.27428.2002
+# Visual Studio Version 18
+VisualStudioVersion = 18.0.11205.157 d18.0
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "NaCl.Core", "src\NaCl.Core\NaCl.Core.csproj", "{5B711EBA-6E41-429F-A2AC-719C4441B663}"
 EndProject
@@ -11,8 +11,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "NaCl.Core.Benchmarks", "tes
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{28EF1FB3-A057-4C17-A3B2-B9370B234F81}"
 	ProjectSection(SolutionItems) = preProject
-		CodeCoverage.runsettings = CodeCoverage.runsettings
 		build.cake = build.cake
+		.github\workflows\ci.yml = .github\workflows\ci.yml
+		CodeCoverage.runsettings = CodeCoverage.runsettings
 		dotnet-tools.json = dotnet-tools.json
 		global.json = global.json
 		LICENSE = LICENSE

README.md

@@ -48,8 +48,8 @@ Daily NuGet builds of the project are also available in the [Azure Artifacts](ht
 #### Symmetric Key Encryption
 
 ```csharp
-// Create the primitive
-var aead = new ChaCha20Poly1305(key);
+// Create the primitive (implements IDisposable for secure key cleanup)
+using var aead = new ChaCha20Poly1305(key);
 
 // Use the primitive to encrypt a plaintext
 aead.Encrypt(nonce, plaintext, ciphertext, tag, aad);
@@ -58,6 +58,8 @@ aead.Encrypt(nonce, plaintext, ciphertext, tag, aad);
 aead.Decrypt(nonce, ciphertext, tag, plaintext, aad);
 ```
 
+> **Note:** All cipher classes (`ChaCha20`, `XChaCha20`, `Salsa20`, `XSalsa20`, `ChaCha20Poly1305`, `XChaCha20Poly1305`) implement `IDisposable`. Call `Dispose()` or use `using` statements to securely zero the key from memory when done.
+
 #### MAC (Message Authentication Code)
 
 ```csharp
@@ -77,6 +79,19 @@ Poly1305.VerifyMac(key, data, tag);
 - Includes the mandatory RFC [test vectors](https://github.com/daviddesmet/NaCl.Core/tree/master/test/NaCl.Core.Tests).
 - [Project Wycheproof](https://github.com/google/wycheproof) by members of Google Security Team, for testing against known attacks (when applicable).
 
+## Performance
+
+Refer to the [benchmarks](https://github.com/daviddesmet/NaCl.Core/tree/master/test/NaCl.Core.Benchmarks) for performance numbers.
+
+Run the benchmarks using:
+```bash
+dotnet run -c Release --framework net9.0
+```
+
+```bash
+dotnet run -c Release --framework net9.0 --filter "*ChaCha20IntrinsicsBenchmark*"
+```
+
 ## Learn More
 
 [![License](https://img.shields.io/github/license/daviddesmet/NaCl.Core.svg)](https://github.com/daviddesmet/NaCl.Core/blob/master/LICENSE)

azure-pipelines.yml

@@ -58,18 +58,19 @@ jobs:
   # The steps to run to execute the build.
   steps:
   - task: UseDotNet@2
-    displayName: 'Use .NET SDK 9.0'
+    displayName: 'Use .NET SDK 10.0'
     inputs:
       packageType: 'sdk'
-      version: '9.0.x'
+      version: '10.0.x'
+      includePreviewVersions: true
       installationPath: $(Agent.ToolsDirectory)/dotnet
   - task: DotNetCoreCLI@2
     displayName: 'Build Project in $(BuildConfiguration) mode'
     inputs:
       command: 'build'
       projects: '**/NaCl.Core.csproj'
       arguments: '-c $(BuildConfiguration)'
-  - script: dotnet test -f net9.0 test/NaCl.Core.Tests --logger trx /p:CollectCoverage=true /p:CoverletOutput=$(Build.SourcesDirectory)/TestResults/ /p:CoverletOutputFormat=cobertura /p:Exclude='[NaCl.Core.Tests]*'
+  - script: dotnet test -f net10.0 test/NaCl.Core.Tests --logger trx /p:CollectCoverage=true /p:CoverletOutput=$(Build.SourcesDirectory)/TestResults/ /p:CoverletOutputFormat=cobertura /p:Exclude='[NaCl.Core.Tests]*'
     displayName: 'Unit testing'
     enabled: false
   - task: DotNetCoreCLI@2
@@ -79,14 +80,14 @@ jobs:
       projects: '**/NaCl.Core.Tests.csproj'
       arguments: '/p:CollectCoverage=true /p:CoverletOutputFormat=cobertura /p:Include="[NaCl.*]*" /p:Exclude="[*Tests]*"'
     enabled: false
-  - task: reportgenerator@4
+  - task: reportgenerator@5
     displayName: 'Generate Coverage Report'
     inputs:
       reports: '$(Build.SourcesDirectory)/**/coverage.cobertura.xml'
       targetdir: '$(Build.ArtifactStagingDirectory)/TestResults/'
       reporttypes: 'HtmlInline_AzurePipelines_Dark;Cobertura;Badges'
     enabled: false
-  - script: dotnet test -f net9.0 test/NaCl.Core.Tests --logger trx
+  - script: dotnet test -f net10.0 test/NaCl.Core.Tests --logger trx
     displayName: 'Run Unit Tests'
   - task: PublishTestResults@2
     displayName: 'Publish Test Results'
@@ -108,7 +109,7 @@ jobs:
     displayName: 'Publish Library'
     inputs:
       command: 'publish'
-      arguments: '-c $(BuildConfiguration) -f net9.0 -o $(Build.ArtifactStagingDirectory) --no-restore'
+      arguments: '-c $(BuildConfiguration) -f net10.0 -o $(Build.ArtifactStagingDirectory) --no-restore'
       projects: src/NaCl.Core/NaCl.Core.csproj
       publishWebProjects: false
       modifyOutputPath: true
@@ -132,16 +133,17 @@ jobs:
     BuildConfiguration: 'release'
   steps:
   - task: UseDotNet@2
-    displayName: 'Use .NET SDK 9.0'
+    displayName: 'Use .NET SDK 10.0'
     inputs:
       packageType: 'sdk'
-      version: '9.0.x'
+      version: '10.0.x'
+      includePreviewVersions: true
       installationPath: $(Agent.ToolsDirectory)/dotnet
   - script: dotnet restore
     displayName: 'Restore Project'
   - script: dotnet build -c $(BuildConfiguration) --no-restore
     displayName: 'Build Project in $(BuildConfiguration) mode'
-  - script: dotnet test -f net9.0 test/NaCl.Core.Tests --logger trx
+  - script: dotnet test -f net10.0 test/NaCl.Core.Tests --logger trx
     displayName: 'Run Unit Tests'
   - task: PublishTestResults@2
     displayName: 'Publish Test Results'
@@ -164,10 +166,11 @@ jobs:
     displayName: 'Authenticate with Azure Artifacts'
     condition: ne(variables['Build.Reason'], 'PullRequest')
   - task: UseDotNet@2
-    displayName: 'Use .NET SDK 9.0'
+    displayName: 'Use .NET SDK 10.0'
     inputs:
       packageType: 'sdk'
-      version: '9.0.x'
+      version: '10.0.x'
+      includePreviewVersions: true
   - task: DotNetCoreCLI@2
     displayName: 'Build Project in $(BuildConfiguration) mode'
     inputs:
@@ -206,11 +209,13 @@ jobs:
       packagesToPush: '$(Build.ArtifactStagingDirectory)/**/*.nupkg;!$(Build.ArtifactStagingDirectory)/**/*.symbols.nupkg'
       nuGetFeedType: 'internal'
       publishVstsFeed: 'ffbd9fd0-ffca-4040-8576-0fa5065bd6d9/b465c74e-3671-458e-996f-8bbf45f957bc'
+      allowPackageConflicts: true
+    continueOnError: true
   - task: DotNetCoreCLI@2
     displayName: 'Publish Library'
     inputs:
       command: 'publish'
-      arguments: '-c $(BuildConfiguration) -f net9.0 -o $(Build.ArtifactStagingDirectory) --no-restore'
+      arguments: '-c $(BuildConfiguration) -f net10.0 -o $(Build.ArtifactStagingDirectory) --no-restore'
       projects: src/NaCl.Core/NaCl.Core.csproj
       publishWebProjects: false
     enabled: false

build.cake

@@ -42,23 +42,57 @@ Task("Test")
     {
         Information($"Preparing {project.GetFilename()} for test");
 
-        DotNetTest(
-            project.ToString(),
-            new DotNetTestSettings()
+        var settings = new DotNetTestSettings()
+        {
+            Blame = true,
+            Collectors = new string[] { "XPlat Code Coverage" },
+            Configuration = configuration,
+            Loggers = new string[]
             {
-                Blame = true,
-                Collectors = new string[] { "XPlat Code Coverage" },
-                Configuration = configuration,
-                Loggers = new string[]
-                {
-                    $"trx;LogFileName={project.GetFilenameWithoutExtension()}.trx",
-                    $"html;LogFileName={project.GetFilenameWithoutExtension()}.html",
-                },
-                NoBuild = true,
-                NoRestore = true,
-                ResultsDirectory = $"{artifactsDirectory}/TestResults",
-                Settings = "CodeCoverage.runsettings"
-            });
+                $"trx;LogFileName={project.GetFilenameWithoutExtension()}.trx",
+                $"html;LogFileName={project.GetFilenameWithoutExtension()}.html",
+            },
+            NoBuild = true,
+            NoRestore = true,
+            ResultsDirectory = $"{artifactsDirectory}/TestResults",
+            Settings = "CodeCoverage.runsettings"
+        };
+
+        // Platform-specific intrinsics testing
+        if (IsRunningOnUnix())
+        {
+            // ARM/Mac testing with AdvSIMD
+            settings.EnvironmentVariables["COMPlus_EnableAdvSimd"] = "1";
+            settings.ResultsDirectory = $"{artifactsDirectory}/TestResults/AdvSimd";
+            Information($"Running default {project.GetFilename()} test with ARM AdvSIMD enabled");
+            DotNetTest(project.ToString(), settings);
+
+            settings.EnvironmentVariables["COMPlus_EnableAdvSimd"] = "0";
+            settings.ResultsDirectory = $"{artifactsDirectory}/TestResults/Scalar";
+            Information($"Running {project.GetFilename()} test with ARM AdvSIMD disabled (scalar only)");
+            DotNetTest(project.ToString(), settings);
+        }
+        else
+        {
+            // x86/x64 testing with AVX2/SSE3
+            settings.EnvironmentVariables["COMPlus_EnableAVX2"] = "1";
+            settings.EnvironmentVariables["COMPlus_EnableSSE3"] = "1";
+            settings.ResultsDirectory = $"{artifactsDirectory}/TestResults/Avx2";
+            Information($"Running default {project.GetFilename()} test with SSE3 and AVX2 enabled");
+            DotNetTest(project.ToString(), settings);
+
+            settings.EnvironmentVariables["COMPlus_EnableAVX2"] = "0";
+            settings.EnvironmentVariables["COMPlus_EnableSSE3"] = "1";
+            settings.ResultsDirectory = $"{artifactsDirectory}/TestResults/Sse3";
+            Information($"Running {project.GetFilename()} test with SSE3 enabled and AVX2 disabled");
+            DotNetTest(project.ToString(), settings);
+
+            settings.EnvironmentVariables["COMPlus_EnableAVX2"] = "0";
+            settings.EnvironmentVariables["COMPlus_EnableSSE3"] = "0";
+            settings.ResultsDirectory = $"{artifactsDirectory}/TestResults/Scalar";
+            Information($"Running {project.GetFilename()} test with SSE3 and AVX2 disabled");
+            DotNetTest(project.ToString(), settings);
+        }
     });
 
 Task("CoverageReport")
@@ -72,7 +106,7 @@ Task("CoverageReport")
                             ArgumentCustomization = args => args.Append("-reporttypes:HtmlInline;HTMLChart;Cobertura")
                         });
     });
-        
+
 Task("Pack")
     .Description("Creates the NuGet packages and outputs them to the artifacts directory.")
     .Does(() =>

global.json

@@ -1,6 +1,6 @@
 {
   "sdk": {
-    "version": "9.0.101",
+    "version": "10.0.100",
     "rollForward": "latestFeature"
   }
 }