Add a SecretProvider that can be used for Docker Secrets

docs/preview/features/secret-store/provider/docker-secrets.md

@@ -0,0 +1,90 @@
+---
+title: "Docker Secrets secret provider"
+layout: default
+---
+
+# Docker Secrets secret provider
+This provider allows you to work with Docker secrets. When using Docker secrets in Docker Swarm, the secrets are injected in the Docker container as files.  
+The Docker secrets secret provider provides access to those secrets via the secret store.
+
+This secret provider offers functionality which is equivalent to the _KeyPerFile_ Configuration Provider, but instead of adding the secrets to the Configuration, this secret provider allows access to the Docker Secrets via the _ISecretProvider_ interface.
+
+## Installation
+Adding secrets from the User Secrets manager into the secret store requires following package:
+
+```shell
+PM > Install-Package Arcus.Security.Providers.DockerSecrets
+```
+
+## Configuration
+After installing the package, the addtional extensions becomes available when building the secret store.
+
+```csharp
+public class Program
+{
+    public static void Main(string[] args)
+    {
+        CreateHostBuilder(args).Build().Run();
+    }
+
+    public static IHostBuilder CreateHostBuilder(string[] args)
+    {    
+        return Host.CreateDefaultBuilder(args)
+                   .ConfigureSecretStore((context, config, builder) =>
+                    {
+                        // Adds the secrets that exist in the "/run/secrets" directory to the ISecretStore
+                        // Docker secrets are by default mounted into the /run/secrets directory
+                        // when using Linux containers on Docker Swarm.
+                        builder.AddDockerSecrets(directoryPath: "/run/secrets");
+                    })
+                    .ConfigureWebHostDefaults(webBuilder => webBuilder.UseStartup<Startup>());
+    }
+}
+```
+
+## Retrieving secrets
+
+Suppose you have the following docker-compose file:
+
+```yaml
+version: '3.8'
+services:
+  person-api:
+    image: person-api:latest
+    ports:
+        - 5555:80
+    secrets:
+        - ConnectionStrings__PersonDatabase
+
+secrets:
+  ConnectionStrings__PersonDatabase:
+    external: true
+```
+
+After adding the Docker Secrets secret provider to the secret store, the Docker secrets can simply be retrieved by calling the appropriate methods on the `ISecretProvider`:
+
+```csharp
+public class PersonController
+{
+    private readonly ISecretProvider _secrets;
+
+    public PersonController(ISecretProvider secrets)
+    {
+        _secrets = secrets;
+    }
+
+    [HttpGet]
+    public async Task GetPerson(Guid personId)
+    {
+        string connectionstring = await _secrets.GetRawSecretAsync("ConnectionStrings:PersonDatabase")
+
+        using (var connection = new SqlDbConnection(connectionstring))
+        {
+            var person = new PersonRepository(connection).GetPersonById(personId);
+            return Ok(new { Id = person.Id, Name = person.Name });
+        }
+    }
+}
+```
+
+[&larr; back](/)

docs/preview/index.md

@@ -23,7 +23,8 @@ PM > Install-Package Arcus.Security.Providers.AzureKeyVault
   - Providers
     - [Azure Key Vault](features/secret-store/provider/key-vault)
     - [Configuration](features/secret-store/provider/configuration)
-    - [Environment variables](features/secret-store/provider/environment-variables)
+    - [Docker secrets](features/secret-store/provider/docker-secrets)
+    - [Environment variables](features/secret-store/provider/environment-variables)    
     - [HashiCorp Vault](features/secret-store/provider/hashicorp-vault)
     - [User Secrets](features/secret-store/provider/user-secrets)
   - [Creating your own secret provider](features/secret-store/create-new-secret-provider)

src/Arcus.Security.Providers.DockerSecrets/Arcus.Security.Providers.DockerSecrets.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>netstandard2.0</TargetFrameworks>
+    <Authors>Arcus</Authors>
+    <Description>Provides support for Docker Secrets</Description>
+    <Copyright>Copyright (c) Arcus</Copyright>
+    <PackageLicenseUrl>https://github.com/arcus-azure/arcus.security/blob/master/LICENSE</PackageLicenseUrl>
+    <PackageProjectUrl>https://github.com/arcus-azure/arcus.security</PackageProjectUrl>
+    <PackageIconUrl>https://raw.githubusercontent.com/arcus-azure/arcus/master/media/arcus.png</PackageIconUrl>
+    <RepositoryUrl>https://github.com/arcus-azure/arcus.security</RepositoryUrl>
+    <RepositoryType>Git</RepositoryType>
+    <PackageTags>Docker;Docker secrets;Docker Secrets Manager;Key Per File;Security</PackageTags>
+    <AssemblyName>Arcus.Security.Providers.DockerSecrets</AssemblyName>
+    <RootNamespace>Arcus.Security.Providers.DockerSecrets</RootNamespace>
+    <PackageId>Arcus.Security.Providers.DockerSecrets</PackageId>
+    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Arcus.Security.Core\Arcus.Security.Core.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration.KeyPerFile" Version="3.1.7" />
+  </ItemGroup>
+
+</Project>

src/Arcus.Security.Providers.DockerSecrets/DockerSecretsSecretProvider.cs

@@ -0,0 +1,90 @@
+using Arcus.Security.Core;
+using GuardNet;
+using Microsoft.Extensions.Configuration.KeyPerFile;
+using System;
+using System.IO;
+using System.Threading.Tasks;
+using Microsoft.Extensions.FileProviders;
+
+namespace Arcus.Security.Providers.DockerSecrets
+{
+    /// <summary>
+    /// Represents an <see cref="ISecretProvider" /> that provides access to the Docker secrets mounted into the Docker container as files.
+    /// </summary>
+    public class DockerSecretsSecretProvider : ISecretProvider
+    {
+        private readonly KeyPerFileConfigurationProvider _provider;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DockerSecretsSecretProvider"/> class.
+        /// </summary>
+        /// <param name="secretsDirectoryPath">The path inside the docker container where the secrets are located.</param>
+        /// <exception cref="ArgumentException">Thrown when the <paramref name="secretsDirectoryPath"/> is blank.</exception>
+        public DockerSecretsSecretProvider(string secretsDirectoryPath)
+        {
+            Guard.NotNullOrWhitespace(secretsDirectoryPath, nameof(secretsDirectoryPath));
+
+            if (!Path.IsPathRooted(secretsDirectoryPath))
+            {
+                throw new ArgumentException($"The {nameof(secretsDirectoryPath)} must be an absolute path", nameof(secretsDirectoryPath));
+            }
+
+            if (!Directory.Exists(secretsDirectoryPath))
+            {
+                throw new DirectoryNotFoundException($"The directory {secretsDirectoryPath} which is configured as secretsDirectoryPath does not exist.");
+            }
+
+            KeyPerFileConfigurationSource configuration = new KeyPerFileConfigurationSource
+            {
+                FileProvider = new PhysicalFileProvider(secretsDirectoryPath),
+                Optional = false
+            };
+
+            var provider = new KeyPerFileConfigurationProvider(configuration);
+            provider.Load();
+
+            _provider = provider;
+        }
+
+        /// <summary>
+        /// Retrieves the secret value, based on the given name
+        /// </summary>
+        /// <param name="secretName">The name of the secret key</param>
+        /// <returns>Returns the secret key.</returns>
+        /// <exception cref="ArgumentException">The <paramref name="secretName"/> must not be empty</exception>
+        /// <exception cref="ArgumentNullException">The <paramref name="secretName"/> must not be null</exception>
+        /// <exception cref="SecretNotFoundException">The secret was not found, using the given name</exception>
+        public Task<string> GetRawSecretAsync(string secretName)
+        {
+            Guard.NotNullOrWhitespace(secretName, nameof(secretName), "Requires a non-blank secret name to retrieve a Docker secret");
+
+            if (_provider.TryGet(secretName, out string value))
+            {
+                return Task.FromResult(value);
+            }
+
+            return Task.FromResult<string>(null);
+        }
+
+        /// <summary>
+        /// Retrieves the secret value, based on the given name
+        /// </summary>
+        /// <param name="secretName">The name of the secret key</param>
+        /// <returns>Returns a <see cref="Secret"/> that contains the secret key</returns>
+        /// <exception cref="ArgumentException">The <paramref name="secretName"/> must not be empty</exception>
+        /// <exception cref="ArgumentNullException">The <paramref name="secretName"/> must not be null</exception>
+        /// <exception cref="SecretNotFoundException">The secret was not found, using the given name</exception>
+        public async Task<Secret> GetSecretAsync(string secretName)
+        {
+            Guard.NotNullOrWhitespace(secretName, nameof(secretName), "Requires a non-blank secret name to retrieve a Docker secret");
+
+            string secretValue = await GetRawSecretAsync(secretName);
+            if (secretValue == null)
+            {
+                return null;
+            }
+
+            return new Secret(secretValue);
+        }
+    }
+}

src/Arcus.Security.Providers.DockerSecrets/SecretStoreBuilderExtensions.cs

@@ -0,0 +1,31 @@
+using System;
+using Arcus.Security.Providers.DockerSecrets;
+using GuardNet;
+using Microsoft.Extensions.Configuration.KeyPerFile;
+using Microsoft.Extensions.FileProviders;
+
+// ReSharper disable once CheckNamespace
+namespace Microsoft.Extensions.Hosting
+{
+    /// <summary>
+    /// Extensions on the <see cref="SecretStoreBuilder" /> to easily provide access to Docker secrets in the secret store.
+    /// </summary>
+    public static class SecretStoreBuilderExtensions
+    {
+        /// <summary>
+        /// Adds Docker secrets (mounted as files in the Docker container) to the secret store.
+        /// </summary>
+        /// <param name="builder">The builder to add the Docker secrets provider to.</param>
+        /// <param name="directoryPath">The path inside the container where the Docker secrets are located.</param>
+        /// <param name="mutateSecretName">The optional function to mutate the secret name before looking it up.</param>
+        /// <exception cref="ArgumentNullException">Thrown when the <paramref name="builder"/> is <c>null</c></exception>
+        /// <exception cref="ArgumentException">Throw when the <paramref name="directoryPath"/> is blank</exception>
+        public static SecretStoreBuilder AddDockerSecrets(this SecretStoreBuilder builder, string directoryPath, Func<string, string> mutateSecretName = null)
+        {
+            Guard.NotNull(builder, nameof(builder), "Requires a secret store builder to add the Docker secrets to");
+            Guard.NotNullOrWhitespace(directoryPath, nameof(directoryPath), "Requires a non-blank directory path to locate the Docker secrets");
+
+            return builder.AddProvider(new DockerSecretsSecretProvider(directoryPath), mutateSecretName);
+        }
+    }
+}

src/Arcus.Security.Tests.Integration/Arcus.Security.Tests.Integration.csproj

@@ -26,6 +26,7 @@
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\Arcus.Security.Providers.AzureKeyVault\Arcus.Security.Providers.AzureKeyVault.csproj" />
+    <ProjectReference Include="..\Arcus.Security.Providers.DockerSecrets\Arcus.Security.Providers.DockerSecrets.csproj" />
     <ProjectReference Include="..\Arcus.Security.Providers.HashiCorp\Arcus.Security.Providers.HashiCorp.csproj" />
     <ProjectReference Include="..\Arcus.Security.Providers.UserSecrets\Arcus.Security.Providers.UserSecrets.csproj" />
     <ProjectReference Include="..\Arcus.Security.Tests.Core\Arcus.Security.Tests.Core.csproj" />

src/Arcus.Security.Tests.Integration/DockerSecrets/DockerSecretsProviderTests.cs

@@ -0,0 +1,22 @@
+using Arcus.Security.Providers.DockerSecrets;
+using System;
+using System.IO;
+using Xunit;
+
+namespace Arcus.Security.Tests.Integration.DockerSecrets
+{
+    public class DockerSecretsProviderTests
+    {
+        [Fact]
+        public void Instantiate_WithNonExistingSecretLocation_Throws()
+        {
+            Assert.Throws<DirectoryNotFoundException>(() => new DockerSecretsSecretProvider("/foo/bar"));
+        }
+
+        [Fact]
+        public void Instantiate_WithRelativePath_Throws()
+        {
+            Assert.Throws<ArgumentException>(() => new DockerSecretsSecretProvider("./foo"));
+        }
+    }
+}

src/Arcus.Security.Tests.Integration/DockerSecrets/SecretStoreBuilderExtensionTests.cs

@@ -0,0 +1,86 @@
+using Arcus.Security.Core;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using System;
+using System.IO;
+using System.Threading.Tasks;
+using Arcus.Security.Providers.DockerSecrets;
+using Xunit;
+using Xunit.Abstractions;
+
+namespace Arcus.Security.Tests.Integration.DockerSecrets
+{
+    public class SecretStoreBuilderExtensionTests : IntegrationTest, IDisposable
+    {
+        private readonly string _secretLocation = Path.Combine(Path.GetTempPath(), "dockersecretstests");
+
+        public SecretStoreBuilderExtensionTests(ITestOutputHelper testOutput) : base(testOutput)
+        {
+            Directory.CreateDirectory(_secretLocation);
+        }
+
+        [Fact]
+        public async Task AddDockerSecrets_WithPath_ResolvesSecret()
+        {
+            // Arrange
+            var expectedValue = Guid.NewGuid().ToString();
+            var secretKey = "MySuperSecret";
+            await SetSecretAsync(secretKey, expectedValue);
+
+            var hostBuilder = new HostBuilder();
+
+            // Act
+            hostBuilder.ConfigureSecretStore((config, stores) => stores.AddDockerSecrets(_secretLocation));
+
+            // Assert
+            IHost host = hostBuilder.Build();
+            var secretProvider = host.Services.GetRequiredService<ISecretProvider>();
+
+            string actualValue = await secretProvider.GetRawSecretAsync(secretKey);
+            Assert.Equal(expectedValue, actualValue);
+        }
+
+        [Fact]
+        public async Task DockerSecretsProvider_ReturnsNull_WhenSecretNotFound()
+        {
+            var provider = new DockerSecretsSecretProvider(_secretLocation);
+            await SetSecretAsync("MyExistingSecret", "foo");
+
+            var secret = await provider.GetRawSecretAsync("MyNonExistingSecret");
+
+            Assert.Null(secret);
+        }
+
+        [Fact]
+        public async Task DockerSecrets_HierarchicalKeys_AreSupported()
+        {
+            // Arrange
+            var expectedValue = Guid.NewGuid().ToString();
+            var secretKey = "ConnectionStrings__PersonDb";
+            await SetSecretAsync(secretKey, expectedValue);
+
+            var hostBuilder = new HostBuilder();
+
+            // Act
+            hostBuilder.ConfigureSecretStore((config, stores) => stores.AddDockerSecrets(_secretLocation));
+
+            // Assert
+            IHost host = hostBuilder.Build();
+            var secretProvider = host.Services.GetRequiredService<ISecretProvider>();
+
+            string actualValue = await secretProvider.GetRawSecretAsync("ConnectionStrings:PersonDb");
+            Assert.Equal(expectedValue, actualValue);
+        }
+
+        private async Task SetSecretAsync(string secretKey, string secretValue)
+        {
+            await File.WriteAllTextAsync(Path.Combine(_secretLocation, secretKey), secretValue);
+        }
+
+        /// <summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.</summary>
+        public void Dispose()
+        {
+            Directory.Delete(_secretLocation, true);
+        }
+    }
+}