diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 078aa2f9df0..6569c39309d 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -9,13 +9,13 @@ ] }, "paket": { - "version": "5.241.2", + "version": "5.245.1", "commands": [ "paket" ] }, "fake-cli": { - "version": "5.18.3", + "version": "5.20.0-alpha.1580", "commands": [ "fake" ] diff --git a/.paket/Paket.Restore.targets b/.paket/Paket.Restore.targets index dfc4aaec7a2..8d37e28bca9 100644 --- a/.paket/Paket.Restore.targets +++ b/.paket/Paket.Restore.targets @@ -27,10 +27,16 @@ $(PaketRootPath)paket.bootstrapper.exe $(PaketToolsPath)paket.bootstrapper.exe $([System.IO.Path]::GetDirectoryName("$(PaketBootStrapperExePath)"))\ - + "$(PaketBootStrapperExePath)" $(MonoPath) --runtime=v4.0.30319 "$(PaketBootStrapperExePath)" + + + + true + true + True @@ -130,7 +136,7 @@ - $([System.Text.RegularExpressions.Regex]::Split(`%(Identity)`, `": "`)[0].Replace(`"`, ``).Replace(` `, ``)) $([System.Text.RegularExpressions.Regex]::Split(`%(Identity)`, `": "`)[1].Replace(`"`, ``).Replace(` `, ``)) @@ -163,7 +169,7 @@ - + diff --git a/Fake.sln b/Fake.sln index 0e5fc1af42a..7224773de1e 100644 --- a/Fake.sln +++ b/Fake.sln @@ -181,8 +181,16 @@ Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Fake.ExpectoSupport", "src\ EndProject Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Fake.Sql.SqlPackage", "src\app\Fake.Sql.SqlPackage\Fake.Sql.SqlPackage.fsproj", "{43B8BB3C-9BE7-466D-BF15-18842AF1A4B8}" EndProject +Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Fake.Tools.SignTool", "src\app\Fake.Tools.SignTool\Fake.Tools.SignTool.fsproj", "{3AC9D697-54FA-44CC-B69D-25BA5B656181}" +EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "TestTools", "TestTools", "{9200793A-8B59-4242-A5C8-F37CE08DE801}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{092B9791-915B-43BC-A2FD-1EA62BF5DF15}" +EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "app", "app", "{0141CA13-3E9C-4DB7-9BAE-0920F5B7A12D}" +EndProject +Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Fake.Core.DependencyManager.Paket", "src\app\Fake.Core.DependencyManager.Paket\Fake.Core.DependencyManager.Paket.fsproj", "{F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -1140,6 +1148,30 @@ Global {43B8BB3C-9BE7-466D-BF15-18842AF1A4B8}.Release|x64.Build.0 = Release|Any CPU {43B8BB3C-9BE7-466D-BF15-18842AF1A4B8}.Release|x86.ActiveCfg = Release|Any CPU {43B8BB3C-9BE7-466D-BF15-18842AF1A4B8}.Release|x86.Build.0 = Release|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Debug|Any CPU.Build.0 = Debug|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Debug|x64.ActiveCfg = Debug|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Debug|x64.Build.0 = Debug|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Debug|x86.ActiveCfg = Debug|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Debug|x86.Build.0 = Debug|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Release|Any CPU.ActiveCfg = Release|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Release|Any CPU.Build.0 = Release|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Release|x64.ActiveCfg = Release|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Release|x64.Build.0 = Release|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Release|x86.ActiveCfg = Release|Any CPU + {3AC9D697-54FA-44CC-B69D-25BA5B656181}.Release|x86.Build.0 = Release|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Debug|Any CPU.Build.0 = Debug|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Debug|x64.ActiveCfg = Debug|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Debug|x64.Build.0 = Debug|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Debug|x86.ActiveCfg = Debug|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Debug|x86.Build.0 = Debug|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Release|Any CPU.ActiveCfg = Release|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Release|Any CPU.Build.0 = Release|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Release|x64.ActiveCfg = Release|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Release|x64.Build.0 = Release|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Release|x86.ActiveCfg = Release|Any CPU + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65}.Release|x86.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -1224,7 +1256,10 @@ Global {664A121E-17A2-453E-BC2E-1C59A67875D2} = {7BFFAE76-DEE9-417A-A79B-6A6644C4553A} {D063FC91-8F84-406D-AA48-9E946B7E4323} = {CCAC5CAB-03C8-4C11-ADBE-A0D05F6A4F18} {43B8BB3C-9BE7-466D-BF15-18842AF1A4B8} = {7BFFAE76-DEE9-417A-A79B-6A6644C4553A} + {3AC9D697-54FA-44CC-B69D-25BA5B656181} = {7BFFAE76-DEE9-417A-A79B-6A6644C4553A} {9200793A-8B59-4242-A5C8-F37CE08DE801} = {CCAC5CAB-03C8-4C11-ADBE-A0D05F6A4F18} + {0141CA13-3E9C-4DB7-9BAE-0920F5B7A12D} = {092B9791-915B-43BC-A2FD-1EA62BF5DF15} + {F4D3249D-F4EC-4B86-BEA8-3F2314ED9B65} = {7BFFAE76-DEE9-417A-A79B-6A6644C4553A} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {058A0C5E-2216-4306-8AFB-0AE28320C26A} diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index d60365b56db..9bbd61b5158 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,6 +1,24 @@ # Release Notes -## 5.19.1 - 2019-02-10 +## 5.20.0 - 2020-05-05 + +* (Minor) BREAKING: Drop support for `net462` and update to `net472`. +* ENHANCEMENT: Keep unreleased changelog section when promote to new version, thanks @vilinski - https://github.com/fsharp/FAKE/pull/2480 +* ENHANCEMENT: Added SignTool for v5, thanks @jhromadik - https://github.com/fsharp/FAKE/pull/2444 +* ENHANCEMENT: Remove old netstandard1.6 dependencies, thanks @teo-tsirpanis - https://github.com/fsharp/FAKE/pull/2493 +* ENHANCEMENT: Add support for running Octo as dotnet tool, thanks @jeremyabbott - https://github.com/fsharp/FAKE/pull/2489 +* ENHANCEMENT: Add support for `--include-symbols` in `dotnet pack`, thanks @devployment - https://github.com/fsharp/FAKE/pull/2508 +* ENHANCEMENT: Add support for default proxy credentials to GitHub (Octokit), thanks @csmager - https://github.com/fsharp/FAKE/pull/2507 +* ENHANCEMENT: `Fake.DotNet.FSFormatting` supports the 4.0 RC release +* ENHANCEMENT: Update paket to support `netcoreapp5.0`, thanks @TheAngryByrd, @fc1943s - https://github.com/fsharp/FAKE/issues/2496 +* BUGFIX: Update FCS, fixes ionide FAKE support (https://github.com/fsharp/FsAutoComplete/issues/561), thanks @baronfel - https://github.com/fsharp/FAKE/pull/2475, https://github.com/fsharp/FAKE/pull/2479, https://github.com/fsharp/FAKE/pull/2481, https://github.com/fsharp/FAKE/pull/2500 +* BUGFIX: Fix Paket.restore references-files, thanks @nilshelmig - https://github.com/fsharp/FAKE/pull/2474 +* BUGFIX: Fix/octo args to string bug, thanks @ids-pfinn - https://github.com/fsharp/FAKE/pull/2469 +* BUGFIX: Fix an AppVeyor environment variable (`APPVEYOR_REPO_COMMIT_MESSAGE_EXTENDED`) returning `null`, thanks @teo-tsirpanis - https://github.com/fsharp/FAKE/pull/2448 +* BUGFIX: Fix potential `FileNotFoundException` when cache is outdated. +* DOCS: Fixed typos and improved docs, thanks @milbrandt, @jzabroski, @objectx - https://github.com/fsharp/FAKE/pull/2492, https://github.com/fsharp/FAKE/pull/2497, https://github.com/fsharp/FAKE/pull/2502 + +## 5.19.1 - 2020-02-10 * ANNOUNCEMENT: `dotnet-fake` cli tool via `DotNetCliToolReference` is now history - https://github.com/fsharp/FAKE/issues/2465 * ENHANCEMENT: Update MSTest.fs for VS 2019, thanks @0x53A - https://github.com/fsharp/FAKE/pull/2450 @@ -200,18 +218,6 @@ * DOCS: Resort TraceSecrets.register indexed parameters - https://github.com/fsharp/FAKE/pull/2254 * DOCS: fix broken links #2241 - https://github.com/fsharp/FAKE/pull/2241 -#### 4.64.18 - 2020-01-30 -* Add Dynamics Business Central 365 support - -#### 4.64.17 - 2019-03-19 -* Add support for MSBuild16 - -#### 4.64.16 - 2019-02-15 -* Add Dynamics NAV FullCompile function - -## 4.64.14 - 2019-01-07 -* Add DynamicsNAV 365 Business Central support - https://github.com/fsharp/FAKE/pull/2224 - ## 5.12.0 - 2019-01-12 * NEW: module `Fake.DotNet.Xdt` - https://github.com/fsharp/FAKE/pull/2218 @@ -521,11 +527,6 @@ * BUGFIX: Fake being unable to compile when `intellisense.fsx` doesn't exist - https://github.com/fsharp/FAKE/issues/1908 * ENHANCEMENT: Some improvements to the target build order algorithm - https://github.com/fsharp/FAKE/pull/1903 -## 4.64.13 - 2019-05-02 - -* Download x86 version of dotnet core on win x86 - https://github.com/SAFE-Stack/SAFE-BookStore/issues/328 - - ## 5.0.0-rc010 - 2018-05-01 * BUGFIX: Some minor issues after last performance release - https://github.com/fsharp/FAKE/pull/1902 @@ -816,7 +817,6 @@ * DOCS: Fix menu on mobile - https://github.com/fsharp/FAKE/pull/1668 * ENHANCEMENT: Add Paket helper to push specific files - https://github.com/fsharp/FAKE/pull/1665 - ## 5.0.0-alpha015 - 2017-08-27 * Update Paket.core @@ -881,22 +881,48 @@ * Fix NuGet key leak if push fails - https://github.com/matthid/FAKE/pull/2 * Coreclr nunit3 params - https://github.com/matthid/FAKE/pull/3 -#### 4.64.11 - 2018-03-09 +## 4.64.18 - 2020-01-30 + +* Add Dynamics Business Central 365 support + +## 4.64.17 - 2019-03-19 + +* Add support for MSBuild16 + +## 4.64.16 - 2019-02-15 + +* Add Dynamics NAV FullCompile function + +## 4.64.14 - 2019-01-07 + +* Add DynamicsNAV 365 Business Central support - https://github.com/fsharp/FAKE/pull/2224 + +## 4.64.13 - 2019-05-02 + +* Download x86 version of dotnet core on win x86 - https://github.com/SAFE-Stack/SAFE-BookStore/issues/328 + +## 4.64.11 - 2018-03-09 + * Added SynchronizeSchemaChanges for DynamicsNAV -#### 4.64.10 - 2018-03-06 +## 4.64.10 - 2018-03-06 + * Added RunCodeunitWithSettings for DynamicsNAV - https://github.com/fsharp/FAKE/pull/1811 -#### 4.64.9 - 2018-03-05 +## 4.64.9 - 2018-03-05 + * CompileWithFilter for DynamicsNAV -#### 4.64.7 - 2018-03-01 +## 4.64.7 - 2018-03-01 + * Allow REST calls without credentials -#### 4.64.6 - 2018-02-21 +## 4.64.6 - 2018-02-21 + * ConvertFileFromWin7ToWin8 reads file line by line ## 4.64.4 - 2018-01-17 + * Support for Dynamics NAV 2018 - https://github.com/fsharp/FAKE/pull/1758 ## 4.64.3 - 2017-12-19 diff --git a/build.fsx b/build.fsx index edf9bd76c90..85378a986d3 100644 --- a/build.fsx +++ b/build.fsx @@ -201,7 +201,7 @@ let restoreTools = let callpaket wd args = restoreTools() - + let res = DotNet.exec (dtntWorkDir wd) "paket" args if not res.OK then failwithf "paket failed to start: %A" res @@ -252,6 +252,7 @@ let dotnetAssemblyInfos = "Fake.BuildServer.Travis", "Integration into Travis buildserver" "Fake.Core.CommandLineParsing", "Core commandline parsing support via docopt like syntax" "Fake.Core.Context", "Core Context Infrastructure" + "Fake.Core.DependencyManager.Paket", "Paket Dependency Manager" "Fake.Core.Environment", "Environment Detection" "Fake.Core.Process", "Starting and managing Processes" "Fake.Core.ReleaseNotes", "Parsing ReleaseNotes" @@ -308,6 +309,7 @@ let dotnetAssemblyInfos = "Fake.Tools.Octo", "Octopus Deploy octo.exe tool helper" "Fake.Tools.Pickles", "Convert Gherkin to HTML" "Fake.Tools.Rsync", "Running Rsync commands" + "Fake.Tools.SignTool", "Running signtool commands" "Fake.Tracing.NAntXml", "NAntXml" "Fake.Windows.Chocolatey", "Running and packaging with Chocolatey" "Fake.Windows.Registry", "CRUD functionality for Windows registry" ] @@ -371,7 +373,7 @@ Target.create "StartBootstrapBuild" (fun _ -> let formatState (state:Octokit.CommitStatus) = sprintf "{ State: %O, Description: %O, TargetUrl: %O }" state.State state.Description state.TargetUrl - let result = + let result = async { let! client = GitHub.createClientWithToken token let mutable whileResult = None @@ -398,7 +400,7 @@ Target.create "StartBootstrapBuild" (fun _ -> do! doWait() match whileResult with | Some r -> return r - | None -> + | None -> // time is up let! combStatus = client.Repository.Status.GetCombined(github_release_user, gitName, sha) |> Async.AwaitTask return @@ -610,14 +612,14 @@ let startWebServer () = if portIsTaken then findPort (port + 1) else port let port = findPort 8083 - + let inline (@@) a b = Suave.WebPart.concatenate a b let mimeTypes = Suave.Writers.defaultMimeTypesMap @@ (function | ".avi" -> Suave.Writers.createMimeType "video/avi" false | ".mp4" -> Suave.Writers.createMimeType "video/mp4" false - | _ -> None) + | _ -> None) let serverConfig = { Suave.Web.defaultConfig with homeFolder = Some (Path.GetFullPath docsDir) @@ -818,7 +820,7 @@ let setBuildEnvVars versionVar isDebianPackaging = Environment.setEnvironVar "PackageProjectUrl" "https://fake.build" Environment.setEnvironVar "PackageRepositoryUrl" "https://github.com/fsharp/Fake" Environment.setEnvironVar "PackageRepositoryType" "git" - Environment.setEnvironVar "PackageLicenseExpression" "Apache-2.0" + Environment.setEnvironVar "PackageLicenseExpression" "Apache-2.0 OR MS-PL" Environment.setEnvironVar "IsDebianPackaging" (if isDebianPackaging then "true" else "false") //Environment.setEnvironVar "IncludeSource" "true" //Environment.setEnvironVar "IncludeSymbols" "false" @@ -829,7 +831,7 @@ Target.create "_DotNetPackage" (fun _ -> let nugetDir = System.IO.Path.GetFullPath nugetDncDir // This lines actually ensures we get the correct version checked in // instead of the one previously bundled with `fake` or `paket` - callpaket "." "restore" // first make paket restire its target file if it feels like it. + callpaket "." "restore" // first make paket restore its target file if it feels like it. Git.CommandHelper.gitCommand "" "checkout .paket/Paket.Restore.targets" // now restore ours restoreTools() diff --git a/global.json b/global.json index 97370580122..18c629a23eb 100644 --- a/global.json +++ b/global.json @@ -1,5 +1,5 @@ { "sdk" : { - "version": "3.1.100" + "version": "3.1.201" } } diff --git a/help/markdown/core-targets.md b/help/markdown/core-targets.md index 7603cca8a91..922e19a28d7 100644 --- a/help/markdown/core-targets.md +++ b/help/markdown/core-targets.md @@ -101,7 +101,7 @@ Target.runOrDefault "Deploy" Now we have the following options: - `fake run build.fsx -t "Build"` --> starts the *Build* target and runs the dependency *Clean* -- `fake run build.fsx -t "Build"` --single-target --> starts only the *Build* target and runs no dependencies +- `fake run build.fsx -t "Build" --single-target` --> starts only the *Build* target and runs no dependencies - `fake run build.fsx -s -t Build` --> starts only the *Build* target and runs no dependencies - `fake run build.fsx` --> starts the Deploy target (and runs the dependencies *Clean* and *Build*) @@ -110,7 +110,7 @@ Now we have the following options: Example: ```fsharp -let args = Target.getArguments() // use this at the top of your script isntead of `Target.initEnvironment()` +let args = Target.getArguments() // use this at the top of your script instead of `Target.initEnvironment()` // So some stuff depending on the args match args with diff --git a/help/markdown/fake-tools-octo.md b/help/markdown/fake-tools-octo.md index 91652825d37..9947807a88a 100644 --- a/help/markdown/fake-tools-octo.md +++ b/help/markdown/fake-tools-octo.md @@ -19,6 +19,13 @@ You will also need to install and configure at least one [Tentacle](http://octop This module is a wrapper around the [Octo.exe](https://octopus.com/docs/api-and-integration/octo.exe-command-line) CLI tool which controls Octopus Deploy API. You'll need the Octo.exe tool itself accessible to your FAKE script. Download it from [here](https://octopus.com/downloads). +This module also supports use via a .NET Core Tool-Manifest. Installation is simple! From the root of your repository run the following + +```bash +dotnet new tool-manifest # if one doesn't already exist +dotnet tool install Octopus.DotNet.Cli +``` + ### Generate an API Key In order to communicate with the Octopus Deploy API you will need an *API key* to authenticate with. @@ -34,6 +41,7 @@ It is a good idea to create an account in Octopus Deploy for your Continuous Int You can define a function defining shared parameters like `ToolPath` or your Octopus Deploy instance details. Then the function can be used in subsequent `Octo` calls. ```fsharp +open Fake.DotNet // needed for ToolType open Fake.Tools let setCommon (ps:Octo.Options) = @@ -42,6 +50,7 @@ let setCommon (ps:Octo.Options) = Server = { ServerUrl = "Your Octopus Server URL" ApiKey = "Your API key" + ToolType = ToolType.CreateLocalTool() // default is ToolType.FullFramework } } ``` diff --git a/help/markdown/fake-tools-signtool.md b/help/markdown/fake-tools-signtool.md new file mode 100644 index 00000000000..ed79696ea74 --- /dev/null +++ b/help/markdown/fake-tools-signtool.md @@ -0,0 +1,351 @@ +# SignTool + +
+
INFO
+

This documentation is for FAKE version 5.0 or later. The old documentation can be found here.

+
+ + +This module is a wrapper around the [signtool.exe](https://docs.microsoft.com/en-gb/windows/win32/seccrypto/signtool) tool, a command-line tool that digitally signs files, verifies signatures in files, or time stamps files. + +The 3 supported functions are: + + - [SignTool.sign: digitally signing files](#Signing) + - [SignTool.timeStamp: time stamping previously signed files](#Time-stamping) + - [SignTool.verify: verify signed files](#Verifying) + +Additional information: + + - [Common options: options common to all supported functions](#Common-options) + - [Certificates: notes and how to get one](#Certificates) + - [SHA1/SHA256: differences and when to use which](#SHA1-SHA256) + +API Reference: + + - [`SignTool`](apidocs/v5/fake-tools-signtool.html): The SignTool tool is a command-line tool that digitally signs files, verifies signatures in files, or time stamps files. + - [`CertificateFromFile`](apidocs/v5/fake-tools-signtool-certificatefromfile.html): Specifies parameters to use when using a certificate from a file. + - [`CertificateFromStore`](apidocs/v5/fake-tools-signtool-certificatefromstore.html): Specifies parameters to use when using a certificate from a certificate store. + - [`SignCertificate`](apidocs/v5/fake-tools-signtool-signcertificate.html): Specifies what type of certificate to use. + - [`SignOptions`](apidocs/v5/fake-tools-signtool-signoptions.html): Sign command options + - [`TimeStampOption`](apidocs/v5/fake-tools-signtool-timestampoption.html): Specifies the URL of the time stamp server and the digest algorithm used by the RFC 3161 time stamp server. + - [`TimeStampOptions`](apidocs/v5/fake-tools-signtool-timestampoptions.html): Timestamp command options + - [`VerifyOptions`](apidocs/v5/fake-tools-signtool-verifyoptions.html): Verify command options + +

+ +## Open namespace + +```fsharp +open Fake.Tools +``` + +

+ +## Signing + +Digitally signing files. + +A [certificate](#Certificates) is needed to do this. + + +### When the certificate is located in a .pfx file + +Only PFX files are supported by signtool.exe. + +```fsharp +// val sign : +// certificate:SignTool.SignCertificate +// -> setOptions:(SignTool.SignOptions -> SignTool.SignOptions) +// -> files:seq +// -> unit +SignTool.sign + (SignTool.SignCertificate.FromFile( + "path/to/certificate-file.pfx", + fun o -> { o with + Password = Some "certificate-password" } ) ) + (fun o -> o) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`CertificateFromFile`](apidocs/v5/fake-tools-signtool-certificatefromfile.html), [`SignOptions`](apidocs/v5/fake-tools-signtool-signoptions.html). + +### When the certificate is located in a certificate store + +All options are optional, and any combination may be used, depending on specific needs. + +If no `StoreName` is specified, the "My" store is opened. + +```fsharp +// val sign : +// certificate:SignTool.SignCertificate +// -> setOptions:(SignTool.SignOptions -> SignTool.SignOptions) +// -> files:seq +// -> unit +SignTool.sign + (SignTool.SignCertificate.FromStore( + fun o -> { o with + AutomaticallySelectCertificate = Some true + SubjectName = Some "subject" + StoreName = Some "My" } ) ) + (fun o -> o) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`CertificateFromStore`](apidocs/v5/fake-tools-signtool-certificatefromstore.html), [`SignOptions`](apidocs/v5/fake-tools-signtool-signoptions.html). + +### Custom signing options + +Use SHA256 ([see SHA1/SHA256](#SHA1-SHA256)) to create file signatures. + +```fsharp +// val sign : +// certificate:SignTool.SignCertificate +// -> setOptions:(SignTool.SignOptions -> SignTool.SignOptions) +// -> files:seq +// -> unit +SignTool.sign + (SignTool.SignCertificate.From..(..)) + (fun o -> { o with + DigestAlgorithm = Some SignTool.DigestAlgorithm.SHA256 } ) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`SignOptions`](apidocs/v5/fake-tools-signtool-signoptions.html). + +### Adding a time stamp + +Time stamp at the same time as signing. + +There is a separate function `signWithTimeStamp` that, compared to `sign`, has 2 additional parameters to set time stamping options. + +If you want to time stamp previously signed files, use the [Time stamping](#Time-stamping) function. + +For more information about time stamping [see Time stamping](#Time-stamping). + +```fsharp +// val signWithTimeStamp : +// certificate:SignTool.SignCertificate +// -> setSignOptions:(SignTool.SignOptions -> SignTool.SignOptions) +// -> serverUrl:string +// -> setTimeStampOptions:(SignTool.TimeStampOption -> SignTool.TimeStampOption) +// -> files:seq +// -> unit +SignTool.signWithTimeStamp + (SignTool.SignCertificate.From..(..)) + (fun o -> o) + "http://timestamp.example-ca.com" + (fun o -> o) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`SignOptions`](apidocs/v5/fake-tools-signtool-signoptions.html), [`TimeStampOption`](apidocs/v5/fake-tools-signtool-timestampoption.html). + +#### Custom time stamp options + +Use SHA256 ([see SHA1/SHA256](#SHA1-SHA256)). + +```fsharp +// val signWithTimeStamp : +// certificate:SignTool.SignCertificate +// -> setSignOptions:(SignTool.SignOptions -> SignTool.SignOptions) +// -> serverUrl:string +// -> setTimeStampOptions:(SignTool.TimeStampOption -> SignTool.TimeStampOption) +// -> files:seq +// -> unit +SignTool.signWithTimeStamp + (SignTool.SignCertificate.From..(..)) + (fun o -> o) + "http://timestamp.example-ca.com" + (fun o -> { o with + Algorithm = Some SignTool.DigestAlgorithm.SHA256 } ) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`SignOptions`](apidocs/v5/fake-tools-signtool-signoptions.html), [`TimeStampOption`](apidocs/v5/fake-tools-signtool-timestampoption.html). + +

+ +## Time stamping + +Time stamping previously signed files. + +When signing a file, the signature is valid only as long as the certificate used to create it is valid. The moment the certificate expires, the signature becomes invalid. +Time stamping is used to extend the validity of the signature. A time stamp proves that the signature was created while the certificate was still valid and effectively extends the signature's validity indefinitely. + + +### Default options + +Time stamp server does not have to be from the same CA as the certificate. + +```fsharp +// val timeStamp : +// serverUrl:string +// -> setOptions:(SignTool.TimeStampOptions -> SignTool.TimeStampOptions) +// -> files:seq +// -> unit +SignTool.timeStamp + "http://timestamp.example-ca.com" + (fun o -> o) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`TimeStampOptions`](apidocs/v5/fake-tools-signtool-timestampoptions.html). + +### Custom options + +Use SHA256 ([see SHA1/SHA256](#SHA1-SHA256)). + +```fsharp +// val timeStamp : +// serverUrl:string +// -> setOptions:(SignTool.TimeStampOptions -> SignTool.TimeStampOptions) +// -> files:seq +// -> unit +SignTool.timeStamp + "http://timestamp.example-ca.com" + (fun o -> { o with + Algorithm = Some SignTool.DigestAlgorithm.SHA256 } ) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`TimeStampOption`](apidocs/v5/fake-tools-signtool-timestampoption.html), [`TimeStampOptions`](apidocs/v5/fake-tools-signtool-timestampoptions.html). + +

+ +## Verifying + +Verify signed files. + +The verify command determines whether the signing certificate was issued by a trusted authority, whether the signing certificate has been revoked, and, optionally, whether the signing certificate is valid for a specific policy. + + +### Default options + +```fsharp +// val verify : +// setOptions:(SignTool.VerifyOptions -> SignTool.VerifyOptions) +// -> files:seq +// -> unit +SignTool.verify + (fun o -> o) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`VerifyOptions`](apidocs/v5/fake-tools-signtool-verifyoptions.html). + + +### Custom options + +```fsharp +// val verify : +// setOptions:(SignTool.VerifyOptions -> SignTool.VerifyOptions) +// -> files:seq +// -> unit +SignTool.verify + (fun o -> + { o with + AllSignatures = Some true + RootSubjectName = Some "root subject" + WarnIfNotTimeStamped = Some true } ) + ["program.exe"; "library.dll"] +``` + +Only a subset of options is shown in the example, see API Reference for all available options: [`VerifyOptions`](apidocs/v5/fake-tools-signtool-verifyoptions.html). + +

+ +## Common options + +All functions share some common options. + + +Tool options - path to signtool.exe, execution timeout, working directory. These options are not set by default. + +```fsharp +// set path to signtool.exe - if you want to use a specific version or you don't have Windows SDKs installed +// by default, an attempt will be made to locate it automatically in 'Program Files (x86)\Windows Kits' +{ o with + ToolPath = Some "path/to/signtool.exe" } +// set the timeout +{ o with + Timeout = Some (TimeSpan.FromMinutes 1.0) } +// set the working directory - uses current directory by default +{ o with + WorkingDir = Some (Directory.GetCurrentDirectory()) } +``` + +Debug - displays debugging information (signtool option: /debug). This option is not set by default. + +```fsharp +// display debugging information (/debug) +{ o with + Debug = Some true } +// do not display debugging information +{ o with + Debug = Some false } +// use default +{ o with + Debug = None } +``` + +Verbosity - output verbosity (signtool options: /q, /v). This option is not set by default. + +```fsharp +// set verbosity to verbose (/v) +{ o with + Verbosity = Some SignTool.Verbosity.Verbose } +// set verbosity to quiet (/q) +{ o with + Verbosity = Some SignTool.Verbosity.Quiet } +// use default +{ o with + Verbosity = None } +``` + +API Reference: [`SignOptions`](apidocs/v5/fake-tools-signtool-signoptions.html), [`TimeStampOptions`](apidocs/v5/fake-tools-signtool-timestampoptions.html), [`VerifyOptions`](apidocs/v5/fake-tools-signtool-verifyoptions.html), [`Verbosity`](apidocs/v5/fake-tools-signtool-verbosity.html). + +

+ +## Certificates + +The SignTool needs a certificate to sign files. + + +### Prod / release + +For production / release purposes a proper publically trusted code signing certificate may be purchased from many CA's. + + +### Dev / test + +For dev and testing purposes a certificate can be created using the [`New-SelfSignedCertificate` PowerShell cmdlet](https://docs.microsoft.com/en-us/powershell/module/pkiclient/new-selfsignedcertificate): +```powershell +New-SelfSignedCertificate -CertStoreLocation cert:\currentuser\my ` +-Subject "CN=My Company, Inc.;O=My Company, Inc.;L=My City;C=SK" ` +-KeyAlgorithm RSA ` +-KeyLength 2048 ` +-Provider "Microsoft Enhanced RSA and AES Cryptographic Provider" ` +-KeyExportPolicy Exportable ` +-KeyUsage DigitalSignature ` +-Type CodeSigningCert +``` +This creates the certificate under "Certificates - Current User" -> "Personal" -> "Certificates" and prints the certificate Thumbprint. The certificate can be used as-is using the [`CertificateFromStore`](#When-the-certificate-is-located-in-a-certificate-store) option. + +If you want to export the certificate to a file, use the [`Export-PfxCertificate` PowerShell cmdlet](https://docs.microsoft.com/en-us/powershell/module/pkiclient/export-pfxcertificate). Replace "{Thumbprint}" with the value from `New-SelfSignedCertificate` output: +```powershell +$certpwd = ConvertTo-SecureString -String "mycertpassword" -Force -AsPlainText +Get-ChildItem -Path cert:\currentuser\my\{Thumbprint} | Export-PfxCertificate -FilePath C:\certificate.pfx -Password $certpwd +``` +Now the certificate can be used with the [`CertificateFromFile`](#When-the-certificate-is-located-in-a-pfx-file) option. + +This certificate should not be used for prod / release purposes as it is self-signed and not trusted. + +

+ +## SHA1/SHA256 + +If the signed binaries are run on Windows 7 or newer, using SHA256 only is fine - this is also the default value for `DigestAlgorithm` (/fd and /td options). + +If the signed binaries are run on Windows older than Windows 7, SHA1 should be used. + +If the signed binaries are run on newer and older versions of Windows, then dual signing is probably the way to go. This means signing all binaries twice - first using SHA1, and then SHA256. Make sure to set `AppendSignature` to true when signing the second time, otherwise the first signature will be replaced. [More information about dual signing](https://support.ksoftware.net/support/solutions/articles/215805-the-truth-about-sha1-sha-256-dual-signing-and-code-signing-certificates-). diff --git a/help/markdown/todo-fluentmigrator.md b/help/markdown/todo-fluentmigrator.md index 2cd47be77bd..ae57bc20944 100644 --- a/help/markdown/todo-fluentmigrator.md +++ b/help/markdown/todo-fluentmigrator.md @@ -2,7 +2,7 @@
INFO
-

This documentation is for FAKE.exe before version 5 (or the non-netcore version). The documentation needs te be updated, please help!

+

This documentation is for FAKE.exe before version 5 (or the non-netcore version). The documentation needs to be updated, please help!

[FluentMigrator](https://github.com/schambers/fluentmigrator/) is a .NET library which helps to version database schema using incremental migrations which are described in C#. diff --git a/help/templates/template.cshtml b/help/templates/template.cshtml index 4fad82982fb..4b07390a37a 100644 --- a/help/templates/template.cshtml +++ b/help/templates/template.cshtml @@ -222,6 +222,7 @@ Pickles Octo Rsync + SignTool