Add Authenticode signing support for PowerShell modules

PowerShellBuild/IB.tasks.ps1

@@ -3,26 +3,26 @@ Set-Variable -Name PSBPreference -Option ReadOnly -Scope Script -Value (. ([IO.P
 $__DefaultBuildDependencies = $PSBPreference.Build.Dependencies
 
 # Synopsis: Initialize build environment variables
-task Init {
+Task Init {
     Initialize-PSBuild -UseBuildHelpers -BuildEnvironment $PSBPreference
 }
 
 # Synopsis: Clears module output directory
-task Clean Init, {
+Task Clean Init, {
     Clear-PSBuildOutputFolder -Path $PSBPreference.Build.ModuleOutDir
 }
 
 # Synopsis: Builds module based on source directory
-task StageFiles Clean, {
+Task StageFiles Clean, {
     $buildParams = @{
-        Path                = $PSBPreference.General.SrcRootDir
-        ModuleName          = $PSBPreference.General.ModuleName
-        DestinationPath     = $PSBPreference.Build.ModuleOutDir
-        Exclude             = $PSBPreference.Build.Exclude
-        Compile             = $PSBPreference.Build.CompileModule
-        CompileDirectories  = $PSBPreference.Build.CompileDirectories
-        CopyDirectories     = $PSBPreference.Build.CopyDirectories
-        Culture             = $PSBPreference.Help.DefaultLocale
+        Path               = $PSBPreference.General.SrcRootDir
+        ModuleName         = $PSBPreference.General.ModuleName
+        DestinationPath    = $PSBPreference.Build.ModuleOutDir
+        Exclude            = $PSBPreference.Build.Exclude
+        Compile            = $PSBPreference.Build.CompileModule
+        CompileDirectories = $PSBPreference.Build.CompileDirectories
+        CopyDirectories    = $PSBPreference.Build.CopyDirectories
+        Culture            = $PSBPreference.Help.DefaultLocale
     }
 
     if ($PSBPreference.Help.ConvertReadMeToAboutHelp) {
@@ -59,7 +59,7 @@ $analyzePreReqs = {
 }
 
 # Synopsis: Execute PSScriptAnalyzer tests
-task Analyze -If (. $analyzePreReqs) Build,{
+Task Analyze -If (. $analyzePreReqs) Build, {
     $analyzeParams = @{
         Path              = $PSBPreference.Build.ModuleOutDir
         SeverityThreshold = $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel
@@ -86,7 +86,7 @@ $pesterPreReqs = {
 }
 
 # Synopsis: Execute Pester tests
-task Pester -If (. $pesterPreReqs) Build,{
+Task Pester -If (. $pesterPreReqs) Build, {
     $pesterParams = @{
         Path                         = $PSBPreference.Test.RootDir
         ModuleName                   = $PSBPreference.General.ModuleName
@@ -117,7 +117,7 @@ $genMarkdownPreReqs = {
 }
 
 # Synopsis: Generates PlatyPS markdown files from module help
-task GenerateMarkdown -if (. $genMarkdownPreReqs) StageFiles,{
+Task GenerateMarkdown -if (. $genMarkdownPreReqs) StageFiles, {
     $buildMDParams = @{
         ModulePath            = $PSBPreference.Build.ModuleOutDir
         ModuleName            = $PSBPreference.General.ModuleName
@@ -141,7 +141,7 @@ $genHelpFilesPreReqs = {
 }
 
 # Synopsis: Generates MAML-based help from PlatyPS markdown files
-task GenerateMAML -if (. $genHelpFilesPreReqs) GenerateMarkdown, {
+Task GenerateMAML -if (. $genHelpFilesPreReqs) GenerateMarkdown, {
     Build-PSBuildMAMLHelp -Path $PSBPreference.Docs.RootDir -DestinationPath $PSBPreference.Build.ModuleOutDir
 }
 
@@ -155,7 +155,7 @@ $genUpdatableHelpPreReqs = {
 }
 
 # Synopsis: Create updatable help .cab file based on PlatyPS markdown help
-task GenerateUpdatableHelp -if (. $genUpdatableHelpPreReqs) BuildHelp, {
+Task GenerateUpdatableHelp -if (. $genUpdatableHelpPreReqs) BuildHelp, {
     Build-PSBuildUpdatableHelp -DocsPath $PSBPreference.Docs.RootDir -OutputPath $PSBPreference.Help.UpdatableHelpOutDir
 }
 
@@ -184,17 +184,149 @@ Task Publish Test, {
 #region Summary Tasks
 
 # Synopsis: Builds help documentation
-task BuildHelp GenerateMarkdown,GenerateMAML
+Task BuildHelp GenerateMarkdown, GenerateMAML
 
 Task Build {
     if ([String]$PSBPreference.Build.Dependencies -ne [String]$__DefaultBuildDependencies) {
         throw [NotSupportedException]'You cannot use $PSBPreference.Build.Dependencies with Invoke-Build. Please instead redefine the build task or your default task to include your dependencies. Example: Task . Dependency1,Dependency2,Build,Test or Task Build Dependency1,Dependency2,StageFiles'
     }
-},StageFiles,BuildHelp
+}, StageFiles, BuildHelp
 
 # Synopsis: Execute Pester and ScriptAnalyzer tests
-task Test Analyze,Pester
+Task Test Analyze, Pester
 
-task . Build,Test
+Task . Build, Test
+
+# Synopsis: Signs module files (*.psd1, *.psm1, *.ps1) with an Authenticode signature
+Task SignModule -If {
+    if (-not $PSBPreference.Sign.Enabled) {
+        Write-Warning 'Module signing is not enabled.'
+        return $false
+    }
+    if (-not (Get-Command -Name 'Set-AuthenticodeSignature' -ErrorAction Ignore)) {
+        Write-Warning 'Set-AuthenticodeSignature is not available. Module signing requires Windows.'
+        return $false
+    }
+    $true
+} Build, {
+    $certParams = @{
+        CertificateSource         = $PSBPreference.Sign.CertificateSource
+        CertStoreLocation         = $PSBPreference.Sign.CertStoreLocation
+        CertificateEnvVar         = $PSBPreference.Sign.CertificateEnvVar
+        CertificatePasswordEnvVar = $PSBPreference.Sign.CertificatePasswordEnvVar
+    }
+    if ($PSBPreference.Sign.Thumbprint) {
+        $certParams.Thumbprint = $PSBPreference.Sign.Thumbprint
+    }
+    if ($PSBPreference.Sign.PfxFilePath) {
+        $certParams.PfxFilePath = $PSBPreference.Sign.PfxFilePath
+    }
+    if ($PSBPreference.Sign.PfxFilePassword) {
+        $certParams.PfxFilePassword = $PSBPreference.Sign.PfxFilePassword
+    }
+
+    $certificate = if ($PSBPreference.Sign.Certificate) {
+        $PSBPreference.Sign.Certificate
+    } else {
+        Get-PSBuildCertificate @certParams
+    }
+
+    if ($null -eq $certificate) {
+        throw $LocalizedData.NoCertificateFound
+    }
+
+    $signingParams = @{
+        Path            = $PSBPreference.Build.ModuleOutDir
+        Certificate     = $certificate
+        TimestampServer = $PSBPreference.Sign.TimestampServer
+        HashAlgorithm   = $PSBPreference.Sign.HashAlgorithm
+        Include         = $PSBPreference.Sign.FilesToSign
+    }
+    Invoke-PSBuildModuleSigning @signingParams
+}
+
+# Synopsis: Creates a Windows catalog (.cat) file for the built module
+Task BuildCatalog -If {
+    if (-not ($PSBPreference.Sign.Enabled -and $PSBPreference.Sign.Catalog.Enabled)) {
+        Write-Warning 'Catalog generation is not enabled.'
+        return $false
+    }
+    if (-not (Get-Command -Name 'New-FileCatalog' -ErrorAction Ignore)) {
+        Write-Warning 'New-FileCatalog is not available. Catalog generation requires Windows.'
+        return $false
+    }
+    $true
+} SignModule, {
+    $catalogFileName = if ($PSBPreference.Sign.Catalog.FileName) {
+        $PSBPreference.Sign.Catalog.FileName
+    } else {
+        "$($PSBPreference.General.ModuleName).cat"
+    }
+    $catalogFilePath = Join-Path -Path $PSBPreference.Build.ModuleOutDir -ChildPath $catalogFileName
+
+    $catalogParams = @{
+        ModulePath      = $PSBPreference.Build.ModuleOutDir
+        CatalogFilePath = $catalogFilePath
+        CatalogVersion  = $PSBPreference.Sign.Catalog.Version
+    }
+    New-PSBuildFileCatalog @catalogParams
+}
+
+# Synopsis: Signs the module catalog (.cat) file with an Authenticode signature
+Task SignCatalog -If {
+    if (-not ($PSBPreference.Sign.Enabled -and $PSBPreference.Sign.Catalog.Enabled)) {
+        Write-Warning 'Catalog signing is not enabled.'
+        return $false
+    }
+    if (-not (Get-Command -Name 'Set-AuthenticodeSignature' -ErrorAction Ignore)) {
+        Write-Warning 'Set-AuthenticodeSignature is not available. Catalog signing requires Windows.'
+        return $false
+    }
+    $true
+} BuildCatalog, {
+    $certParams = @{
+        CertificateSource         = $PSBPreference.Sign.CertificateSource
+        CertStoreLocation         = $PSBPreference.Sign.CertStoreLocation
+        CertificateEnvVar         = $PSBPreference.Sign.CertificateEnvVar
+        CertificatePasswordEnvVar = $PSBPreference.Sign.CertificatePasswordEnvVar
+    }
+    if ($PSBPreference.Sign.Thumbprint) {
+        $certParams.Thumbprint = $PSBPreference.Sign.Thumbprint
+    }
+    if ($PSBPreference.Sign.PfxFilePath) {
+        $certParams.PfxFilePath = $PSBPreference.Sign.PfxFilePath
+    }
+    if ($PSBPreference.Sign.PfxFilePassword) {
+        $certParams.PfxFilePassword = $PSBPreference.Sign.PfxFilePassword
+    }
+
+    $certificate = if ($PSBPreference.Sign.Certificate) {
+        $PSBPreference.Sign.Certificate
+    } else {
+        Get-PSBuildCertificate @certParams
+    }
+
+    if ($null -eq $certificate) {
+        throw $LocalizedData.NoCertificateFound
+    }
+
+    $catalogFileName = if ($PSBPreference.Sign.Catalog.FileName) {
+        $PSBPreference.Sign.Catalog.FileName
+    } else {
+        "$($PSBPreference.General.ModuleName).cat"
+    }
+
+    $signingParams = @{
+        Path            = $PSBPreference.Build.ModuleOutDir
+        Certificate     = $certificate
+        TimestampServer = $PSBPreference.Sign.TimestampServer
+        HashAlgorithm   = $PSBPreference.Sign.HashAlgorithm
+        Include         = @($catalogFileName)
+    }
+    Invoke-PSBuildModuleSigning @signingParams
+}
+
+# Synopsis: Signs module files and catalog (meta task)
+Task Sign SignModule, SignCatalog
 
 #endregion Summary Tasks

PowerShellBuild/PowerShellBuild.psd1

@@ -19,7 +19,10 @@
         'Build-PSBuildModule'
         'Build-PSBuildUpdatableHelp'
         'Clear-PSBuildOutputFolder'
+        'Get-PSBuildCertificate'
         'Initialize-PSBuild'
+        'Invoke-PSBuildModuleSigning'
+        'New-PSBuildFileCatalog'
         'Publish-PSBuildModule'
         'Test-PSBuildPester'
         'Test-PSBuildScriptAnalysis'