Add docs for the signing manifest

2017-12-22 18:14:23 -08:00 · 2017-12-22 18:14:23 -08:00 · 3714ec2828
--- a/docs/Signing.md
+++ b/docs/Signing.md
@ -0,0 +1,126 @@
+Signing
+=======
+
+KoreBuild supports generating a signing request manfiest. This includes a list of all files that should be signed
+and information about the strongname or certificate that should be used.
+
+## Format
+
+The signing request manifest supports three element types. A minimal example looks like this. See [Elements](#Elements) below for details
+
+```xml
+<SigningRequest>
+  <File Path="MyAssembly.dll" Certificate="MyCert" StrongName="MyStrongName" />
+  <File Path="build/Another.dll" Certificate="MyCert" />
+  <Container Path="MyLib.1.0.0.nupkg" Type="nupkg" Certificate="NuGetCert">
+    <File Path="lib/netstandard2.0/MyLib.dll" Certificate="MyCert" />
+  </Container>
+  <Container Path="MyVSTool.vsix" Type="vsix" Certificate="VsixCert">
+    <File Path="MyVSTool.dll" Certificate="MyCert" />
+    <!-- excluded from signing, but useful if you want to assert all files in a container are accounted for. -->
+    <ExcludedFile Path="NotMyLib.dll" />
+  </Container>
+</SigningRequest>
+```
+
+## Config
+
+### Assemblies
+
+To sign assemblies, set the AssemblySigningCertName and AssemblySigningStrongName property in the \*.csproj.
+
+```xml
+<PropertyGroup>
+  <AssemblySigningCertName>MyCert</AssemblySigningCertName>
+  <AssemblySigningStrongName>PrivateStrongName</AssemblySigningStrongName>
+</PropertyGroup>
+```
+
+This will generate a signing request like this:
+
+```xml
+<SigningRequest>
+  <File Path="MyLib.dll" Certificate="MyCert" StrongName="PrivateStrongName" />
+</SigningRequest>
+```
+
+### NuGet packages
+
+To sign NuGet packages, set the PackageSigningCertName property in the \*.csproj that produces the nupkg.
+
+```xml
+<PropertyGroup>
+  <PackageSigningCertName>NuGetCert</PackageSigningCertName>
+</PropertyGroup>
+```
+
+This will generate a signing request like this:
+
+```xml
+<SigningRequest>
+  <Container Path="MyLib.1.0.0.nupkg" Type="nupkg" Certificate="NuGetCert" />
+</SigningRequest>
+```
+
+### NuGet packages with assemblies
+
+For assemblies that ship in a NuGet package, you can specify multiple properties.
+
+```xml
+<PropertyGroup>
+  <AssemblySigningCertName>MyCert</AssemblySigningCertName>
+  <PackageSigningCertName>NuGetCert</PackageSigningCertName>
+</PropertyGroup>
+```
+
+This will generate a signing request like this:
+
+```xml
+<SigningRequest>
+  <Container Path="MyLib.1.0.0.nupkg" Type="nupkg" Certificate="NuGetCert">
+    <File Path="lib/netstandard2.0/MyLib.dll" Certificate="MyCert" />
+  </Container>
+</SigningRequest>
+```
+
+
+## Elements
+
+#### `SigningRequest`
+
+Root element. No options.
+
+#### `File`
+
+A file to be signed.
+
+**Path** - file path, relative to the file path. If nested in a `<Container>`, is relative to the organization within the container
+
+**Certificate** - the name of the certificate to use
+
+**StrongName** - for assemblies only. This is used to strong name assemblies that were delay signed in public.
+
+#### `Container`
+
+A container is an archive file, installer, or some kind of bundle that can be signed, or that has files that can be signed
+inside it. Nested elements can be added for `<File>` and `<ExcludedFile>`.
+
+**Path** - file path to the container
+
+**Certificate** - the name of the certificate to use
+
+**Type** - The type of the container. Instructs the consumer how to extract the container. Example values:
+
+  - zip
+  - tar.gz
+  - vsix
+  - nupkg
+  - msi
+
+#### `ExcludedFile`
+
+This is useful when you want to exclude files within a container from being signed, but want to assert that
+all files in a container are accounted for.
+
+**Path** - file path to a file to be ignored by the signing tool
+
--- a/files/KoreBuild/modules/solutionbuild/Project.Inspection.targets
+++ b/files/KoreBuild/modules/solutionbuild/Project.Inspection.targets
@ -22,8 +22,8 @@
        <PackageType>$(PackageType)</PackageType>
        <RepositoryRoot>$(RepositoryRoot)</RepositoryRoot>
        <Category>$(PackageArtifactCategory)</Category>
-        <Certificate>$(PackageSigningCert)</Certificate>
-        <ShouldBeSigned Condition="'$(PackageSigningCert)' != '' OR @(SignedPackageFile->Count()) != 0 ">true</ShouldBeSigned>
+        <Certificate>$(PackageSigningCertName)</Certificate>
+        <ShouldBeSigned Condition="'$(PackageSigningCertName)' != '' OR @(SignedPackageFile->Count()) != 0 ">true</ShouldBeSigned>
        <IsContainer>true</IsContainer>
      </ArtifactInfo>

@ -37,8 +37,8 @@
        <PackageType>$(PackageType)</PackageType>
        <RepositoryRoot>$(RepositoryRoot)</RepositoryRoot>
        <Category>$(PackageArtifactCategory)</Category>
-        <Certificate>$(PackageSigningCert)</Certificate>
-        <ShouldBeSigned Condition="'$(PackageSigningCert)' != '' OR @(SignedPackageFile->Count()) != 0 ">true</ShouldBeSigned>
+        <Certificate>$(PackageSigningCertName)</Certificate>
+        <ShouldBeSigned Condition="'$(PackageSigningCertName)' != '' OR @(SignedPackageFile->Count()) != 0 ">true</ShouldBeSigned>
        <IsContainer>true</IsContainer>
      </ArtifactInfo>

@ -92,16 +92,16 @@ Items:
          Condition=" '$(TargetFramework)' != '' "
          DependsOnTargets="BuiltProjectOutputGroup;SatelliteDllsProjectOutputGroup">

-    <ItemGroup Condition=" '$(NuspecFile)' == '' AND '$(IncludeBuildOutput)' != 'false' AND ('$(AssemblySigningCert)' != '' OR '$(AssemblySigningStrongName)' != '') ">
+    <ItemGroup Condition=" '$(NuspecFile)' == '' AND '$(IncludeBuildOutput)' != 'false' AND ('$(AssemblySigningCertName)' != '' OR '$(AssemblySigningStrongName)' != '') ">
      <SignedPackageFile Include="@(BuiltProjectOutputGroupOutput)">
        <PackagePath>$(BuildOutputTargetFolder)/$(TargetFramework)/%(BuiltProjectOutputGroupOutput.FileName)%(BuiltProjectOutputGroupOutput.Extension)</PackagePath>
-        <Certificate>$(AssemblySigningCert)</Certificate>
+        <Certificate>$(AssemblySigningCertName)</Certificate>
        <StrongName>$(AssemblySigningStrongName)</StrongName>
      </SignedPackageFile>

      <SignedPackageFile Include="@(SatelliteDllsProjectOutputGroupOutput)">
        <PackagePath>$(BuildOutputTargetFolder)/$(TargetFramework)/%(SatelliteDllsProjectOutputGroupOutput.FileName)%(SatelliteDllsProjectOutputGroupOutput.Extension)</PackagePath>
-        <Certificate>$(AssemblySigningCert)</Certificate>
+        <Certificate>$(AssemblySigningCertName)</Certificate>
        <StrongName>$(AssemblySigningStrongName)</StrongName>
      </SignedPackageFile>
    </ItemGroup>
--- a/modules/KoreBuild.Tasks/GenerateSignRequests.cs
+++ b/modules/KoreBuild.Tasks/GenerateSignRequests.cs
@ -14,7 +14,7 @@ namespace KoreBuild.Tasks
    /// The items are expected to be files.
    /// </para>
    /// </summary>
-    public class GenerateSignRequests : Microsoft.Build.Utilities.Task
+    public class GenerateSignRequest : Microsoft.Build.Utilities.Task
    {
        /// <summary>
        /// Files or containers of files that should be signed.
--- a/modules/KoreBuild.Tasks/Internal/SignRequestCollectionXmlWriter.cs
+++ b/modules/KoreBuild.Tasks/Internal/SignRequestCollectionXmlWriter.cs
@ -17,7 +17,7 @@ namespace KoreBuild.Tasks
        public SignRequestCollectionXmlWriter(TextWriter output)
        {
            this.output = output;
-            document = new XDocument(new XElement("SignRequests"));
+            document = new XDocument(new XElement("SignRequest"));
        }

        public void Save()
--- a/modules/KoreBuild.Tasks/module.props
+++ b/modules/KoreBuild.Tasks/module.props
@ -14,7 +14,7 @@
  <UsingTask TaskName="KoreBuild.Tasks.GenerateBillOfMaterials" AssemblyFile="$(KoreBuildTasksDll)" />
  <UsingTask TaskName="KoreBuild.Tasks.GenerateDependenciesPropsFile" AssemblyFile="$(KoreBuildTasksDll)" />
  <UsingTask TaskName="KoreBuild.Tasks.GeneratePackageVersionPropsFile" AssemblyFile="$(KoreBuildTasksDll)" />
-  <UsingTask TaskName="KoreBuild.Tasks.GenerateSignRequests" AssemblyFile="$(KoreBuildTasksDll)" />
+  <UsingTask TaskName="KoreBuild.Tasks.GenerateSignRequest" AssemblyFile="$(KoreBuildTasksDll)" />
  <UsingTask TaskName="KoreBuild.Tasks.GetToolsets" AssemblyFile="$(KoreBuildTasksDll)" />
  <UsingTask TaskName="KoreBuild.Tasks.InstallDotNet" AssemblyFile="$(KoreBuildTasksDll)" />
  <UsingTask TaskName="KoreBuild.Tasks.PackNuSpec" AssemblyFile="$(KoreBuildTasksDll)" />
--- a/modules/KoreBuild.Tasks/module.targets
+++ b/modules/KoreBuild.Tasks/module.targets
@ -174,7 +174,7 @@ Generates a manifest that contains signin requests for files.
      <Sign Include="@(ArtifactInfo)" Condition=" '%(ArtifactInfo.ShouldBeSigned)' == 'true' " />
    </ItemGroup>

-    <GenerateSignRequests
+    <GenerateSignRequest
      Requests="@(Sign)"
      Exclusions="@(ExcludeFromSigning)"
      BasePath="$(ArtifactsDir)"
--- a/test/KoreBuild.Tasks.Tests/GenerateSignRequestsTests.cs
+++ b/test/KoreBuild.Tasks.Tests/GenerateSignRequestsTests.cs
@ -12,11 +12,11 @@ using Xunit.Abstractions;

 namespace KoreBuild.Tasks.Tests
 {
-    public class GenerateSignRequestsTests
+    public class GenerateSignRequestTests
    {
        private readonly ITestOutputHelper _output;

-        public GenerateSignRequestsTests(ITestOutputHelper output)
+        public GenerateSignRequestTests(ITestOutputHelper output)
        {
            _output = output;
        }
@ -64,7 +64,7 @@ namespace KoreBuild.Tasks.Tests
                    })
            };

-            var task = new GenerateSignRequests
+            var task = new GenerateSignRequest
            {
                Requests = requests,
                BasePath = AppContext.BaseDirectory,
@ -76,14 +76,14 @@ namespace KoreBuild.Tasks.Tests

            Assert.True(task.Execute(() => new StringWriter(sb)), "Task should pass");

-            var expected = $@"<SignRequests>
+            var expected = $@"<SignRequest>
  <File Path=`build/MyLib.dll` Certificate=`Cert1` />
  <Container Path=`build/MyLib.nupkg` Type=`zip`>
    <ExcludedFile Path=`lib/NotMyLib.dll` />
    <File Path=`lib/netstandard2.0/MyLib.dll` Certificate=`Cert1` StrongName=`Key1` />
  </Container>
  <Container Path=`build/ZZApp.vsix` Type=`vsix` Certificate=`Cert4` />
-</SignRequests>".Replace('`', '"');
+</SignRequest>".Replace('`', '"');
            _output.WriteLine(sb.ToString());

            Assert.Equal(expected, sb.ToString(), ignoreLineEndingDifferences: true, ignoreWhiteSpaceDifferences: true);
--- a/testassets/SimpleRepo/src/Simple.CliTool/Simple.CliTool.csproj
+++ b/testassets/SimpleRepo/src/Simple.CliTool/Simple.CliTool.csproj
@ -6,8 +6,8 @@
    <PackageType>DotnetTool</PackageType>
    <AssemblyName>cowsay</AssemblyName>
    <PackageId>Simple.CliTool</PackageId>
-    <AssemblySigningCert>TestCert</AssemblySigningCert>
-    <PackageSigningCert></PackageSigningCert>
+    <AssemblySigningCertName>TestCert</AssemblySigningCertName>
+    <PackageSigningCertName></PackageSigningCertName>
    <NuspecFile>$(MSBuildProjectName).nuspec</NuspecFile>
  </PropertyGroup>

@ -15,7 +15,7 @@
    <PackageReference Include="Newtonsoft.Json" PrivateAssets="All" Version="$(NewtonsoftJsonPackageVersion)" />

    <!-- Required to specify manually when using nuspec. -->
-    <SignedPackageFile Include="$(TargetPath)" Certificate="$(AssemblySigningCert)" Visible="false">
+    <SignedPackageFile Include="$(TargetPath)" Certificate="$(AssemblySigningCertName)" Visible="false">
      <PackagePath>tools/$(TargetFramework)/any/$(TargetFileName)</PackagePath>
    </SignedPackageFile>

--- a/testassets/SimpleRepo/src/Simple.Lib/Simple.Lib.csproj
+++ b/testassets/SimpleRepo/src/Simple.Lib/Simple.Lib.csproj
@ -2,7 +2,7 @@

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;net461</TargetFrameworks>
-    <AssemblySigningCert>TestCert</AssemblySigningCert>
+    <AssemblySigningCertName>TestCert</AssemblySigningCertName>
  </PropertyGroup>

  <ItemGroup>