Certificate Service, Certificate Store and Hashing Facilities

.config/dotnet-tools.json

@@ -15,6 +15,13 @@
         "husky"
       ],
       "rollForward": false
+    },
+    "dotnet-certificate-tool": {
+      "version": "2.0.9",
+      "commands": [
+        "certificate-tool"
+      ],
+      "rollForward": false
     }
   }
 }

.github/workflows/dotnet-publish-abstractions.yml

@@ -38,16 +38,36 @@ jobs:
       shell: powershell
 
     - name: Restore Dependencies
-      run: dotnet restore ${{ env.PROJECT_PATH }} --configfile nuget.config
+      run: >
+        dotnet restore ${{ env.PROJECT_PATH }}
+        --configfile nuget.config
 
     - name: Build Project
-      run: dotnet build ${{ env.PROJECT_PATH }} --nologo --no-restore --configuration Release
+      run: >
+        dotnet build ${{ env.PROJECT_PATH }}
+        --configuration Release
+        --no-restore
+        --nologo
 
     - name: Pack Project
-      run: dotnet pack ${{ env.PROJECT_PATH }} --nologo --no-restore --no-build --configuration Release --output ${{ env.RELEASE_DIRECTORY }}
+      run: >
+        dotnet pack ${{ env.PROJECT_PATH }}
+        --configuration Release
+        --output ${{ env.RELEASE_DIRECTORY }}
+        --no-restore
+        --no-build
+        --nologo
 
     - name: Deploy Package to GitHub
-      run: dotnet nuget push '${{ env.RELEASE_DIRECTORY }}\*.nupkg' --skip-duplicate --api-key ${{ secrets.GH_AUTH_TOKEN_PUSH }} --source ${{ env.GITHUB_SOURCE }}
+      run: >
+        dotnet nuget push '${{ env.RELEASE_DIRECTORY }}\*.nupkg'
+        --api-key ${{ secrets.GH_AUTH_TOKEN_PUSH }}
+        --source ${{ env.GITHUB_SOURCE }}
+        --skip-duplicate
 
     - name: Deploy Package to NuGet
-      run: dotnet nuget push '${{ env.RELEASE_DIRECTORY }}\*.nupkg' --skip-duplicate --api-key ${{ secrets.NUGET_AUTH_TOKEN_PUSH }} --source ${{ env.NUGET_SOURCE }}
+      run: >
+        dotnet nuget push '${{ env.RELEASE_DIRECTORY }}\*.nupkg'
+        --api-key ${{ secrets.NUGET_AUTH_TOKEN_PUSH }}
+        --source ${{ env.NUGET_SOURCE }}
+        --skip-duplicate

.github/workflows/dotnet-publish-core.yml

@@ -38,16 +38,36 @@ jobs:
       shell: powershell
 
     - name: Restore Dependencies
-      run: dotnet restore ${{ env.PROJECT_PATH }} --configfile nuget.config
+      run: >
+        dotnet restore ${{ env.PROJECT_PATH }}
+        --configfile nuget.config
 
     - name: Build Project
-      run: dotnet build ${{ env.PROJECT_PATH }} --nologo --no-restore --configuration Release
+      run: >
+        dotnet build ${{ env.PROJECT_PATH }}
+        --configuration Release
+        --no-restore
+        --nologo
 
     - name: Pack Project
-      run: dotnet pack ${{ env.PROJECT_PATH }} --nologo --no-restore --no-build --configuration Release --output ${{ env.RELEASE_DIRECTORY }}
+      run: >
+        dotnet pack ${{ env.PROJECT_PATH }}
+        --configuration Release
+        --output ${{ env.RELEASE_DIRECTORY }}
+        --no-restore
+        --no-build
+        --nologo
 
     - name: Deploy Package to GitHub
-      run: dotnet nuget push '${{ env.RELEASE_DIRECTORY }}\*.nupkg' --skip-duplicate --api-key ${{ secrets.GH_AUTH_TOKEN_PUSH }} --source ${{ env.GITHUB_SOURCE }}
+      run: >
+        dotnet nuget push '${{ env.RELEASE_DIRECTORY }}\*.nupkg'
+        --api-key ${{ secrets.GH_AUTH_TOKEN_PUSH }}
+        --source ${{ env.GITHUB_SOURCE }}
+        --skip-duplicate
 
     - name: Deploy Package to NuGet
-      run: dotnet nuget push '${{ env.RELEASE_DIRECTORY }}\*.nupkg' --skip-duplicate --api-key ${{ secrets.NUGET_AUTH_TOKEN_PUSH }} --source ${{ env.NUGET_SOURCE }}
+      run: >
+        dotnet nuget push '${{ env.RELEASE_DIRECTORY }}\*.nupkg'
+        --api-key ${{ secrets.NUGET_AUTH_TOKEN_PUSH }}
+        --source ${{ env.NUGET_SOURCE }}
+        --skip-duplicate

.github/workflows/dotnet-tests.yml

@@ -28,8 +28,54 @@ jobs:
     - name: Restore Dependencies
       run: dotnet restore
 
-    - name: Build
-      run: dotnet build --no-restore
+    - name: Restore Dotnet Tools
+      run: dotnet tool restore
 
-    - name: Test
-      run: dotnet test --no-build --verbosity normal
+    - name: Build Project
+      run: >
+        dotnet build ./AdvancedSystems.Security
+        --configuration Release
+        --no-restore
+        /warnAsError
+
+    - name: Import AdvancedSystems Certificate Authority
+      run: >
+        dotnet certificate-tool add --file ./development/AdvancedSystems-CA.pfx
+        --store-name My
+        --store-location CurrentUser
+        --password '${{ secrets.ADV_CA_SECRET }}'
+
+    - name: Import Password Certificate (Windows)
+      if: runner.os == 'Windows'
+      run: |
+        $AppSettings = Get-Content '.\AdvancedSystems.Security.Tests\appsettings.json' -Raw | ConvertFrom-Json
+        $Name = $AppSettings.CertificateStore.Name
+        $Location = $AppSettings.CertificateStore.Location
+        Import-Certificate -FilePath .\development\AdvancedSystems-PasswordCertificate.pem -CertStoreLocation "Cert:\$Location\$Name"
+      shell: powershell
+
+    - name: Import Password Certificate (Ubuntu)
+      if: runner.os == 'Linux'
+      run: |
+        appSettings='./AdvancedSystems.Security.Tests/appsettings.json'
+        name=$(jq -r '.CertificateStore.Name' $appSettings)
+        location=$(jq -r '.CertificateStore.Location' $appSettings)
+        dotnet certificate-tool add --file ./development/AdvancedSystems-PasswordCertificate.pem --store-name $name --store-location $location
+
+    - name: Import Password Certificate (MacOS)
+      if: runner.os == 'macOS'
+      run: |
+        appSettings='./AdvancedSystems.Security.Tests/appsettings.json'
+        name=$(jq -r '.CertificateStore.Name' $appSettings)
+        location=$(jq -r '.CertificateStore.Location' $appSettings)
+        dotnet certificate-tool add --file ./development/AdvancedSystems-PasswordCertificate.pem --store-name $name --store-location $location
+
+    - name: Configure DotNet User Secrets
+      run: |
+        dotnet user-secrets set CertificatePassword '${{ secrets.ADV_CA_SECRET }}' --project ./AdvancedSystems.Security.Tests
+
+    - name: Run Unit Tests
+      run: >
+        dotnet test ./AdvancedSystems.Security.Tests
+        --configuration Release
+        --verbosity normal

.husky/task-runner.json

@@ -23,7 +23,10 @@
          "command": "dotnet",
          "args": [
             "build",
-            "/warnaserror"
+            "./AdvancedSystems.Security",
+            "--configuration",
+            "Release",
+            "/warnAsError"
          ]
       },
       {
@@ -32,7 +35,11 @@
          "command": "dotnet",
          "args": [
             "test",
-            "--nologo"
+            "./AdvancedSystems.Security.Tests",
+            "--configuration",
+            "Release",
+            "--verbosity",
+            "minimal"
          ]
       }
    ]

AdvancedSystems.Security.Abstractions/HashFunction.cs

@@ -0,0 +1,17 @@
+namespace AdvancedSystems.Security.Abstractions;
+
+/// <summary>
+///     Identifies a mathematical function that maps a string of arbitrary length
+///     (up to a pre-determined maximum size) to a fixed-length string.
+/// </summary>
+public enum HashFunction
+{
+    MD5 = 0,
+    SHA1 = 1,
+    SHA256 = 2,
+    SHA384 = 3,
+    SHA512 = 4,
+    SHA3_256 = 5,
+    SHA3_384 = 6,
+    SHA3_512 = 7,
+}

AdvancedSystems.Security.Abstractions/ICertificateService.cs

@@ -1,45 +1,172 @@
-using System.Security.Cryptography.X509Certificates;
-
-using AdvancedSystems.Security.Abstractions.Exceptions;
+using System.Collections.Generic;
+using System.Security.Cryptography.X509Certificates;
 
 namespace AdvancedSystems.Security.Abstractions;
 
 /// <summary>
-///      Defines a service for managing and retrieving X.509 certificates. 
+///      Defines a contract for managing and retrieving X.509 certificates. 
 /// </summary>
+/// <remarks>
+///     See also: <seealso href="https://datatracker.ietf.org/doc/rfc5280/"/>.
+/// </remarks>
+/// <seealso cref="ICertificateStore"/>
 public interface ICertificateService
 {
     #region Methods
 
     /// <summary>
-    ///     Retrieves an X.509 certificate from the specified store using the provided
-    ///     <paramref name="thumbprint"/>.
+    ///     Adds a certificate to a certificate store.
     /// </summary>
-    /// <param name="thumbprint">
-    ///     The thumbprint of the certificate to locate.
+    /// <param name="storeService">
+    ///     The name of the keyed <seealso cref="ICertificateStore"/> service to use.
+    /// </param>
+    /// <param name="certificate">
+    ///     The certificate to add.
+    /// </param>
+    /// <returns>
+    ///     Returns <see langword="true"/> if the <paramref name="certificate"/> was added
+    ///     successfully to the certificate store, else <see langword="false"/>.
+    /// </returns>
+    bool AddCertificate(string storeService, X509Certificate2 certificate);
+
+    /// <summary>
+    ///     <inheritdoc cref="TryImportPemCertificate(string, string, string, string, out X509Certificate2?)" path="/summary"/>
+    /// </summary>
+    /// <param name="storeService">
+    ///     <inheritdoc cref="TryImportPemCertificate(string, string, string, string, out X509Certificate2?)" path="/param[@name='storeService']"/>
+    /// </param>
+    /// <param name="certificatePath">
+    ///     <inheritdoc cref="TryImportPemCertificate(string, string, string, string, out X509Certificate2?)" path="/param[@name='certificatePath']"/>
+    /// </param>
+    /// <param name="privateKeyPath">
+    ///     <inheritdoc cref="TryImportPemCertificate(string, string, string, string, out X509Certificate2?)" path="/param[@name='privateKeyPath']"/>
+    /// </param>
+    /// <param name="certificate">
+    ///     <inheritdoc cref="TryImportPemCertificate(string, string, string, string, out X509Certificate2?)" path="/param[@name='certificate']"/>
+    /// </param>
+    /// <returns>
+    ///     <inheritdoc cref="TryImportPemCertificate(string, string, string, string, out X509Certificate2?)" path="/returns"/>
+    /// </returns>
+    /// <remarks>
+    ///     <inheritdoc cref="TryImportPemCertificate(string, string, string, string, out X509Certificate2?)" path="/remarks"/>
+    /// </remarks>
+    bool TryImportPemCertificate(string storeService, string certificatePath, string privateKeyPath, out X509Certificate2? certificate);
+
+    /// <summary>
+    ///     Tries to import a PEM certificate file into a certificate store.
+    /// </summary>
+    /// <param name="storeService">
+    ///     The name of the keyed <seealso cref="ICertificateStore"/> service to use.
+    /// </param>
+    /// <param name="certificatePath">
+    ///     The file path to the PEM certificate.
+    /// </param>
+    /// <param name="privateKeyPath">
+    ///      The file path to the PKCS#8 (encrypted) private key associated with the specified certificate.
+    /// </param>
+    /// <param name="password">
+    ///     The password required to decrypt the private key (if specified).
+    /// </param>
+    /// <param name="certificate">
+    ///     An output parameter that will contain the imported <see cref="X509Certificate2"/> instance if the operation succeeds;
+    ///     otherwise, it will be <see langword="null"/>.
+    /// </param>
+    /// <returns>
+    ///     <see langword="true"/> if the certificate was imported to the certificate store successfully, else <see langword="false"/>.
+    /// </returns>
+    /// <remarks>
+    ///     See also: <seealso href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail"/>.
+    /// </remarks>
+    bool TryImportPemCertificate(string storeService, string certificatePath, string privateKeyPath, string password, out X509Certificate2? certificate);
+
+    /// <summary>
+    ///     <inheritdoc cref="TryImportPfxCertificate(string, string, string, out X509Certificate2?)" path="/summary"/>
+    /// </summary>
+    /// <param name="storeService">
+    ///     <inheritdoc cref="TryImportPfxCertificate(string, string, string, out X509Certificate2?)" path="/param[@name='storeService']"/>
     /// </param>
-    /// <param name="storeName">
-    ///     The certificate store from which to retrieve the certificate.
+    /// <param name="certificatePath">
+    ///     <inheritdoc cref="TryImportPfxCertificate(string, string, string, out X509Certificate2?)" path="/param[@name='certificatePath']"/>
     /// </param>
-    /// <param name="storeLocation">
-    ///     The location of the certificate store, such as <see cref="StoreLocation.CurrentUser"/>
-    ///     or <see cref="StoreLocation.LocalMachine"/>.
+    /// <param name="certificate">
+    ///     <inheritdoc cref="TryImportPfxCertificate(string, string, string, out X509Certificate2?)" path="/param[@name='certificate']"/>
     /// </param>
     /// <returns>
-    ///     The <see cref="X509Certificate2"/> object if the certificate is found, else <c>null</c>.
+    ///     <inheritdoc cref="TryImportPfxCertificate(string, string, string, out X509Certificate2?)" path="/returns"/>
     /// </returns>
-    /// <exception cref="CertificateNotFoundException">
-    ///     Thrown when no certificate with the specified thumbprint is found in the store.
-    /// </exception>
-    X509Certificate2? GetStoreCertificate(string thumbprint, StoreName storeName, StoreLocation storeLocation);
+    /// <remarks>
+    ///     <inheritdoc cref="TryImportPfxCertificate(string, string, string, out X509Certificate2?)" path="/remarks"/>
+    /// </remarks>
+    bool TryImportPfxCertificate(string storeService, string certificatePath, out X509Certificate2? certificate);
 
     /// <summary>
-    ///      Retrieves an application-configured X.509 certificate.
+    ///     Tries to import a PFX certificate file into a certificate store.
     /// </summary>
+    /// <param name="storeService">
+    ///     The name of the keyed <seealso cref="ICertificateStore"/> service to use.
+    /// </param>
+    /// <param name="certificatePath">
+    ///      The file path to the PFX certificate file that needs to be imported.
+    /// </param>
+    /// <param name="password">
+    ///     The password required to access the PFX file's private key.
+    /// </param>
+    /// <param name="certificate">
+    ///     An output parameter that will contain the imported <see cref="X509Certificate2"/> instance if the operation succeeds;
+    ///     otherwise, it will be <see langword="null"/>.
+    /// </param>
+    /// <returns>
+    ///     <see langword="true"/> if the certificate was imported to the certificate store successfully, else <see langword="false"/>.
+    /// </returns>
+    /// <remarks>
+    ///     See also: <seealso href="https://en.wikipedia.org/wiki/PKCS_12"/>.
+    /// </remarks>
+    bool TryImportPfxCertificate(string storeService, string certificatePath, string password, out X509Certificate2? certificate);
+
+    /// <summary>
+    ///     Retrieves all certificates from the certificate store.
+    /// </summary>
+    /// <param name="storeService">
+    ///     The name of the keyed <seealso cref="ICertificateStore"/> service to use.
+    /// </param>
+    /// <returns>
+    ///     Returns a collection of <seealso cref="X509Certificate2"/> certificates. 
+    /// </returns>
+    IEnumerable<X509Certificate2> GetCertificate(string storeService);
+
+    /// <summary>
+    ///     Retrieves a certificate from the certificate store by using the <paramref name="thumbprint"/>.
+    /// </summary>
+    /// <param name="storeService">
+    ///     The name of the keyed <seealso cref="ICertificateStore"/> service to use.
+    /// </param>
+    /// <param name="thumbprint">
+    ///     The string representing the thumbprint of the certificate to retrieve.
+    /// </param>
+    /// <param name="validOnly">
+    ///     <see langword="true"/> to allow only valid certificates to be returned from the search;
+    ///     otherwise, <see langword="false"/>.
+    /// </param>
+    /// <returns>
+    ///     A <seealso cref="X509Certificate2"/> object if a certificate in the certificate store
+    ///     matches the search criteria, else <see langword="null"/>.
+    /// </returns>
+    X509Certificate2? GetCertificate(string storeService, string thumbprint, bool validOnly = true);
+
+    /// <summary>
+    ///     Removes a certificate from the certificate store by using the <paramref name="thumbprint"/>.
+    /// </summary>
+    /// <param name="storeService">
+    ///     The name of the keyed <seealso cref="ICertificateStore"/> service to use.
+    /// </param>
+    /// <param name="thumbprint">
+    ///     The string representing the thumbprint of the certificate to remove.
+    /// </param>
     /// <returns>
-    ///     The <see cref="X509Certificate2"/> object if the certificate is found, else <c>null</c>.
+    ///     Returns <see langword="true"/> if a certificate with the specified <paramref name="thumbprint"/>
+    ///     was removed from the certificate store, else <see langword="false"/>.
     /// </returns>
-    X509Certificate2? GetConfiguredCertificate();
+    bool RemoveCertificate(string storeService, string thumbprint);
 
     #endregion
 }