Skip to content

Commit bfe0b4d

Browse files
microsoftshawarmamicrosoftshawarma
committed
adding how to and overview page
1 parent 2a5d218 commit bfe0b4d

File tree

7 files changed

+185
-281
lines changed

7 files changed

+185
-281
lines changed

‎articles/trusted-signing/how-to-signing-integrations.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: Implement signing integrations with Trusted Signing #Required; page title is displayed in search results. Include the brand.
3+
description: Learn how to set up signing integrations with Trusted Signing. #Required; article description that is displayed in search results.
4+
author: microsoftshawarma #Required; your GitHub user alias, with correct capitalization.
5+
ms.author: rakiasegev #Required; microsoft alias of author; optional team alias.
6+
ms.service: azure-code-signing #Required; service per approved list. slug assigned by ACOM.
7+
ms.topic: how-to #Required; leave this attribute/value as-is.
8+
ms.date: 03/21/2024 #Required; mm/dd/yyyy format.
9+
ms.custom: template-how-to-pattern #Required; leave this attribute/value as-is.
10+
---
11+
12+
Trusted Signing currently supports the following signing integrations:
13+
• SignTool
14+
• GitHub Action
15+
• ADO Task
16+
• PowerShell for Authenticode
17+
• Azure PowerShell - App Control for Business CI Policy
18+
We constantly work to support more signing integrations and will update the above list if/when more are available.
19+
20+
This article explains how to set up each of the above Trusted Signing signing integrations.
21+
22+
23+
## Set up SignTool with Trusted Signing
24+
This section explains how to set up SignTool to use with Trusted Signing. For more detailed signing with SignTool, check out [Tutorial Public Trust](tutorial.md).
25+
26+
Prerequisites:
27+
• A Trusted Signing account, Identity Validation, and Certificate Profile.
28+
• Ensure there are proper individual or group role assignments for signing (“Trusted Signing Certificate Profile Signer” role).
29+
30+
Overview of steps:
31+
1. [Download and install SignTool.](#download-and-install-signtool)
32+
2. [Download and install the .NET 6 Runtime.](#download-and-install-.net-6.0-runtime)
33+
3. [Download and install the Trusted Signing Dlib Package.](download-and-install-trusted-signing-dlib-package)
34+
4. [Create JSON file to provide your Trusted Signing account and Certificate Profile.](#create-json-file)
35+
5. [Invoke SignTool.exe to sign a file.](invoke-signtool-to-sign-a-file)
36+
37+
### Download and install SignTool
38+
Trusted Signing requires the use of SignTool.exe to sign files on Windows, specifically the version of SignTool.exe from the Windows 10 SDK 10.0.19041 or higher. You can install the full Windows 10 SDK via the Visual Studio Installer or [download and install it separately](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk/).
39+
40+
41+
To download and install SignTool:
42+
43+
1. Download the latest version of SignTool + Windows Build Tools NuGet at: [Microsft.Windows.SDK.BuildTools](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools/)
44+
2. Install SignTool from Windows SDK (min version: 10.0.2261.755)
45+
46+
Another option is to use the latest nuget.exe to download and extract the latest SDK Build Tools NuGet package by completing the following steps (PowerShell):
47+
48+
1. Download nuget.exe by running the following download command:
49+
50+
```
51+
Invoke-WebRequest -Uri https://dist.nuget.org/win-x86-commandline/latest/nuget.exe -OutFile .\nuget.exe
52+
```
53+
54+
2. Install nuget.exe by running the following install command:
55+
```
56+
.\nuget.exe install Microsoft.Windows.SDK.BuildTools -Version 10.0.20348.19
57+
```
58+
59+
### Download and install .NET 6.0 Runtime
60+
The components that SignTool.exe uses to interface with Trusted Signing require the installation of the [.NET 6.0 Runtime](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) You only need the core .NET 6.0 Runtime. Make sure you install the correct platform runtime depending on which version of SignTool.exe you intend to run (or simply install both). For example:
61+
62+
* For x64 SignTool.exe: [Download Download .NET 6.0 Runtime - Windows x64 Installer](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-6.0.9-windows-x64-installer)
63+
* For x86 SignTool.exe: [Download Download .NET 6.0 Runtime - Windows x86 Installer](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-6.0.9-windows-x86-installer)
64+
65+
### Download and install Trusted Signing Dlib package
66+
Complete these steps to download and install the Trusted Signing Dlib package (.ZIP):
67+
1. Download the [Trusted Signing Dlib package](https://www.nuget.org/packages/Azure.CodeSigning.Client).
68+
69+
2. Extract the Trusted Signing Dlib zip content and install it onto your signing node in a directory of your choice. You’re required to install it onto the node you’ll be signing files from with SignTool.exe.
70+
71+
### Create JSON file
72+
To sign using Trusted Signing, you need to provide the details of your Trusted Signing Account and Certificate Profile that were created as part of the prerequisites. You provide this information on a JSON file by completing these steps:
73+
1. Create a new JSON file (for example `metadata.json`).
74+
2. Add the specific values for your Trusted Signing Account and Certificate Profile to the JSON file. For more information, see the metadata.sample.json file that’s included in the Trusted Signing Dlib package or refer to the following example:
75+
```
76+
{
77+
  "Endpoint": "<Code Signing Account Endpoint>",
78+
  "CodeSigningAccountName": "<Code Signing Account Name>",
79+
  "CertificateProfileName": "<Certificate Profile Name>",
80+
  "CorrelationId": "<Optional CorrelationId*>"
81+
}
82+
```
83+
84+
* The `"Endpoint"` URI value must have a URI that aligns to the region your Trusted Signing Account and Certificate Profile were created in during the setup of these resources. The table shows regions and their corresponding URI.
85+
86+
| Region | Region Class Fields | Endpoint URI value |
87+
|--------------|-----------|------------|
88+
| East US | EastUS | https://eus.codesigning.azure.net |
89+
| West US | WestUS | https://wus.codesigning.azure.net |
90+
| West Central US | WestCentralUS | https://wcus.codesigning.azure.net/ |
91+
| West US 2 | WestUS2 | https://wus2.codesigning.azure.net/ |
92+
| North Europe | NorthEurope | https://neu.codesigning.azure.net |
93+
| West Europe | WestEurope | https://weu.codesigning.azure.net |
94+
95+
* The optional `"CorrelationId"` field is an opaque string value that you can provide to correlate sign requests with your own workflows such as build identifiers or machine names.
96+
97+
### Invoke SignTool to sign a file
98+
Complete the following steps to invoke SignTool to sign a file for you:
99+
1. Make a note of where your SDK Build Tools, extracted Azure.CodeSigning.Dlib, and metadata.json file are located (from the previous steps above).
100+
101+
2. Replace the placeholders in the following path with the specific values you noted in step 1.
102+
103+
```
104+
& "<Path to SDK bin folder>\x64\signtool.exe" sign /v /debug /fd SHA256 /tr "http://timestamp.acs.microsoft.com" /td SHA256 /dlib "<Path to Azure Code Signing Dlib bin folder>\x64\Azure.CodeSigning.Dlib.dll" /dmdf "<Path to Metadata file>\metadata.json" <File to sign>
105+
```
106+
* Both x86 and x64 versions of SignTool.exe are provided as part of the Windows SDK - ensure you reference the corresponding version of Azure.CodeSigning.Dlib.dll. The above example is for the x64 version of SignTool.exe.
107+
* You must make sure you use the recommended Windows SDK version in the dependencies listed at the beginning of this article. Otherwise our dlib won’t work.
108+
109+
Trusted Signing certificates have a 3-day validity, so timestamping is critical for continued successful validation of a signature beyond that 3-day validity period. Trusted Signing recommends the use of Trusted Signing’s Microsoft Public RSA Time Stamping Authority: http://timestamp.acs.microsoft.com/.
110+
111+
## Use other signing integrations with Trusted Signing
112+
This section explains how to set up other not [SignTool](#setup-signtool-with-trusted-signing) signing integrations with Trusting Signing.
113+
114+
* GitHub Action – To use the GitHub action for Trusted Signing, visit [Azure Code Signing · Actions · GitHub Marketplace](https://github.com/marketplace/actions/azure-code-signing) and follow the instructions to set up and use GitHub action.
115+
116+
* ADO Task – To use the Trusted Signing AzureDevOps task, visit [Azure Code Signing - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=VisualStudioClient.AzureCodeSigning) and follow the instructions for setup.
117+
118+
* PowerShell for Authenticode – To use PowerShell for Trusted Signing, visit [PowerShell Gallery | AzureCodeSigning 0.2.15](https://www.powershellgallery.com/packages/AzureCodeSigning/0.2.15) to install the PowerShell module.
119+
120+
* Azure PowerShell – App Control for Business CI Policy - App Control for Windows [link to CI policy signing tutorial].
121+
122+
* Trusted Signing SDK – To create your own signing integration our [Trusted Signing SDK](https://www.nuget.org/packages/Azure.CodeSigning.Sdk) is publicly available.

‎articles/trusted-signing/how-to.md

Lines changed: 0 additions & 69 deletions
This file was deleted.

‎articles/trusted-signing/media/trusted-signing-rbac-roles.png

74.6 KB
Loading

‎articles/trusted-signing/media/trusted-signing-resource-structure-overview.png

53.2 KB
Loading

‎articles/trusted-signing/overview.md

Lines changed: 26 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,42 @@
11
---
2-
title: Trusted Signing overview #Required; page title is displayed in search results. Include the brand.
3-
description: Learn how to sign with Trusted Signing #Required; article description that is displayed in search results.
2+
title: What is Trusted Signing? #Required; page title is displayed in search results. Include the brand.
3+
description: Learn about the Trusted Signing service. #Required; article description that is displayed in search results.
44
author: microsoftshawarma #Required; your GitHub user alias, with correct capitalization.
55
ms.author: rakiasegev #Required; microsoft alias of author; optional team alias.
66
ms.topic: overview #Required; leave this attribute/value as-is.
77
ms.service: azure-code-signing
8-
ms.date: 01/05/2024 #Required; mm/dd/yyyy format.
8+
ms.date: 03/21/2024 #Required; mm/dd/yyyy format.
99
ms.custom: template-overview #Required; leave this attribute/value as-is.
1010
---
1111

1212
# What is Trusted Signing?
13+
Signing is often difficult to do – from obtaining certificates, to securing them, and operationalizing a secure way to integrate with build pipelines.
1314

14-
<!-- 2. Introductory paragraph ----------------------------------------------------------
15+
Trusted Signing (formerly Azure Code Signing) is a Microsoft fully managed end-to-end signing solution that simplifies the process and empowers 3rd party developers to easily build and distribute applications. This is part of Microsoft’s commitment to an open, inclusive, and secure ecosystem.
1516

16-
Required: The introductory paragraph helps customers quickly determine whether an article is
17-
relevant. Describe in customer-friendly terms what the service is and does, and why the customer
18-
should care. Keep it short for the intro. You can go into more detail later in the article. Many
19-
services add artwork or videos below the introduction.
17+
## Features
2018

21-
-->
19+
* Simplifies the signing process with an intuitive experience in Azure
20+
* Zero-touch certificate lifecycle management that is FIPS 140-2 Level 3 compliant.
21+
* Integrations into leading developer toolsets.
22+
* Supports Public Trust, Test, Private Trust, and CI policy signing scenarios.
23+
* Timestamping service.
24+
* Content confidential signing – meaning digest signing that is fast and reliable – your file never leaves your endpoint.
2225

26+
## Resource structure
27+
Here’s a high-level overview of the service’s resource structure:
2328

24-
<!---Avoid notes, tips, and important boxes. Readers tend to skip over them. Better to put that info
25-
directly into the article text.
29+
![Diagram of Azure Code Signing resource group and cert profiles.](./media/trusted-signing-resource-structure-overview.png)
2630

27-
--->
31+
* You create a resource group within a subscription. You then create a Trusted Signing account within the resource group.
32+
* Two resources within an account:
33+
* Identity validation
34+
* Certificate profile
35+
* Two types of accounts (depending on the SKU you choose):
36+
* Basic
37+
* Premium
2838

29-
<!-- 3. Article body ------------------------------------------------------------ Required: After
30-
the intro, you can develop your overview by discussing the features that answer the "Why should I
31-
care" question with a bit more depth. Be sure to call out any basic requirements and dependencies,
32-
as well as limitations or overhead. Don't catalog every feature, and some may only need to be
33-
mentioned as available, without any discussion.
34-
35-
-->
36-
37-
38-
<!-- Top tasks ------------------------------------------------------------------------------
39-
40-
Suggested: An effective way to structure you overview article is to create an H2 for the top
41-
customer tasks you identified during the [planning process](../contribute/content-dev-plan.md) and
42-
describe how the product/service helps customers with that task.
43-
44-
Create a new H2 for each task you list.
45-
46-
--->
47-
48-
## \<Top task\>
49-
50-
<!-- 5. Next steps ------------------------------------------------------------------------
51-
52-
Required: In Overview articles, provide at least one next step and no more than three. Next steps in
53-
overview articles will often link to a quickstart. Use regular links; do not use a blue box link.
54-
What you link to will depend on what is really a next step for the customer. Do not use a "More info
55-
section" or a "Resources section" or a "See also section".
56-
57-
--->
39+
## Next steps
40+
* [Learn more about the Trusted Signing resource structure.](concept.md)
41+
* [Learn more about the signing integrations.](how-to-signing-integrations.md)
42+
* [Get started with Trusted Signing.](quickstart.md)

‎articles/trusted-signing/tutorial-assign-roles.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Assign roles in Trusted Signing #Required; page title displayed in search results. Include the word "tutorial". Include the brand.
3+
description: Tutorial on assigning roles in the Trusted Signing service. #Required; article description that is displayed in search results. Include the word "tutorial".
4+
author: microsoftshawarma #Required; your GitHub user alias, with correct capitalization.
5+
ms.author: rakiasegev #Required; microsoft alias of author; optional team alias.
6+
ms.service: azure-code-signing #Required; service per approved list. slug assigned by ACOM.
7+
ms.topic: tutorial #Required; leave this attribute/value as-is.
8+
ms.date: 03/21/2023 #Required; mm/dd/yyyy format.
9+
---
10+
11+
The Trusting Signing service has a few Trusted Signing specific roles (in addition to the standard Azure roles). Use [Azure role-based access control (RBAC)](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview) to assign user and group roles for the Trusted Signing specific roles. In this tutorial, you review the different Trusted Signing supported roles and assign roles to your Trusted Signing account on the Azure portal.
12+
13+
## Supported roles with Trusting Signing
14+
The following table lists the roles that Trusted Signing supports, including what each role can access within the service’s resources.
15+
16+
| Role | Manage/View Account | Manage Cert Profiles | Sign w/ Cert Profile | View Signing History | Manage Role Assignment | Manage Identity Validation |
17+
|--------------|----------|------------|--------------|-----------|------------|-------------|
18+
| Trusted Signing Identity Verifier| | | | | | x|
19+
| Trusted Signing Certificate Profile Signer | | | x | x| | |
20+
| Owner | x |x | | | x | |
21+
| Contributor | x |x | | | | |
22+
| Reader | x | | | | | |
23+
| User Access Admin | | | | |x | |
24+
25+
The Identity Verified role specifically is needed to manage Identity Validation requests, which can only be done via Azure portal not AzCli. The Signer role is needed to successfully sign with Trusted Signing.
26+
27+
## Assign roles in Trusting Signing
28+
Complete the following steps to assign roles in Trusted Signing.
29+
1. Navigate to your Trusted Signing account on the Azure portal and select the **Access Control (IAM)** tab in the left menu.
30+
2. Select on the **Roles** tab and search "Trusted Signing". You can see in the screenshot below the two custom roles.
31+
![Screenshot of Azure portal UI with the Trusted Signing custom RBAC roles.](./media/trusted-signing-rbac-roles.png)
32+
33+
3. To assign these roles, select on the **Add** drop down and select **Add role assignment**. Follow the [Assign roles in Azure](https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal?tabs=current) guide to assign the relevant roles to your identities.
34+
35+
## Related content
36+
* [What is Azure role-based access control (RBAC)?](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview)
37+
* [Trusted Signing Quickstart](quickstart.md)

0 commit comments

Comments
 (0)