deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-21 13:23:36 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

update to cert pinning

Browse Source
This commit is contained in:
Paolo Matarazzo
2023-05-24 17:41:35 -04:00
parent 4c53363dcf
commit c445889dd3
1 changed files with 69 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
windows/security/identity-protection/enterprise-certificate-pinning.md
View File

@ -1,24 +1,24 @@
--- ---
title: Enterprise Certificate Pinning title: Enterprise certificate pinning
description: Enterprise certificate pinning is a Windows feature for remembering; or pinning a root issuing certificate authority, or end entity certificate to a given domain name. description: Enterprise certificate pinning is a Windows feature for remembering, or pinning, a root issuing certificate authority, or end-entity certificate to a domain name.
ms.topic: conceptual ms.topic: conceptual
ms.date: 07/27/2017 ms.date: 05/24/2023
--- ---
# Enterprise Certificate Pinning # Enterprise certificate pinning overview
Enterprise certificate pinning is a Windows feature for remembering, or pinning a root issuing certificate authority or end entity certificate to a given domain name. Enterprise certificate pinning is a Windows feature for remembering (pinning), a root issuing certificate authority, or end-entity certificate, to a domain name.\
Enterprise certificate pinning helps reduce man-in-the-middle attacks by enabling you to protect your internal domain names from chaining to unwanted certificates or to fraudulently issued certificates. Enterprise certificate pinning helps reducing man-in-the-middle attacks, by protecting internal domain names from chaining to unwanted or fraudulently issued certificates.
> [!NOTE] > [!NOTE]
> External domain names, where the certificate issued to these domains is issued by a public certificate authority, are not ideal for enterprise certificate pinning. > External domain names, where the certificate issued to these domains is issued by a public certificate authority, are not ideal for enterprise certificate pinning.
Windows Certificate APIs (CertVerifyCertificateChainPolicy and WinVerifyTrust) are updated to check if the site's chain that authenticates servers matches a restricted set of certificates. Windows Certificate APIs (*CertVerifyCertificateChainPolicy* and *WinVerifyTrust*) are updated to check if the site's chain that authenticates servers matches a restricted set of certificates.\
These restrictions are encapsulated in a Pin Rules Certificate Trust List (CTL) that is configured and deployed to Windows 10 computers. The restrictions are encapsulated in a *Pin Rules Certificate Trust List (CTL)* that is configured and deployed to Windows devices.\
Any site certificate that triggers a name mismatch causes Windows to write an event to the CAPI2 event log and prevents the user from navigating to the web site using Microsoft Edge or Internet Explorer. Any site certificates that trigger a name mismatch causes Windows to write an event to the *CAPI2 event log*, and prevents the user from browsing the web site.
> [!NOTE] > [!NOTE]
> Enterprise Certificate Pinning feature triggering doesn't cause clients other than Microsoft Edge or Internet Explorer to block the connection. > Enterprise Certificate Pinning feature triggering doesn't cause clients other than Microsoft Edge to block the connection.
## Deployment ## Deployment
@ -27,14 +27,14 @@ To deploy enterprise certificate pinning, you need to:
- Create a well-formatted certificate pinning rule XML file - Create a well-formatted certificate pinning rule XML file
- Create a pin rules certificate trust list file from the XML file - Create a pin rules certificate trust list file from the XML file
- Apply the pin rules certificate trust list file to a reference administrative computer - Apply the pin rules certificate trust list file to a reference administrative computer
- Deploy the registry configuration on the reference computer using Group Policy Management Console (GPMC), which is included in the [Remote Server Administration Tools (RSAT)](https://www.microsoft.com/download/details.aspx?id=45520). - Deploy the registry configuration on the reference computer via group policy
### Create a Pin Rules XML file ### Create a pin rules XML file
The XML-based pin rules file consists of a sequence of PinRule elements. The XML-based pin rules file consists of a sequence of PinRule elements.
Each PinRule element contains a sequence of one or more Site elements and a sequence of zero or more Certificate elements. Each PinRule element contains a sequence of one or more Site elements and a sequence of zero or more Certificate elements.
```code ```xml
<PinRules ListIdentifier="PinRulesExample" Duration="P28D"> <PinRules ListIdentifier="PinRulesExample" Duration="P28D">
<PinRule Name="AllCertificateAttributes" Error="None" Log="true"> <PinRule Name="AllCertificateAttributes" Error="None" Log="true">
@ -58,18 +58,18 @@ Each PinRule element contains a sequence of one or more Site elements and a sequ
</PinRules> </PinRules>
``` ```
#### PinRules Element #### PinRules element
The PinRules element can have the following attributes. The PinRules element can have the following attributes.
For help with formatting Pin Rules, see [Representing a Date in XML](#representing-a-date-in-xml) or [Representing a Duration in XML](#representing-a-duration-in-xml). For help with formatting Pin Rules, see [Representing a Date in XML](#representing-a-date-in-xml) or [Representing a Duration in XML](#representing-a-duration-in-xml).
| Attribute | Description | Required | | Attribute | Description | Required |
|-----------|-------------|----------| |-----------|-------------|----------|
| **Duration** or **NextUpdate** | Specifies when the Pin Rules will expire. Either is required. **NextUpdate** takes precedence if both are specified. <br> **Duration**, represented as an XML TimeSpan data type, doesn't allow years and months. You represent the **NextUpdate** attribute as an XML DateTime data type in UTC. | **Required?** Yes. At least one is required. | | **Duration** or **NextUpdate** | Specifies when the Pin Rules expires. Either is required. **NextUpdate** takes precedence if both are specified. <br> **Duration**, represented as an XML TimeSpan data type, doesn't allow years and months. You represent the **NextUpdate** attribute as an XML DateTime data type in UTC. | **Required?** Yes. At least one is required. |
| **LogDuration** or **LogEndDate** | Configures auditing only to extend beyond the expiration of enforcing the Pin Rules. <br> **LogEndDate**, represented as an XML DateTime data type in UTC, takes precedence if both are specified. <br> You represent **LogDuration** as an XML TimeSpan data type, which doesn't allow years and months. <br> If `none of the attributes are specified, auditing expiration uses **Duration** or **NextUpdate** attributes. | No. | | **LogDuration** or **LogEndDate** | Configures auditing only to extend beyond the expiration of enforcing the Pin Rules. <br> **LogEndDate**, represented as an XML DateTime data type in UTC, takes precedence if both are specified. <br> You represent **LogDuration** as an XML TimeSpan data type, which doesn't allow years and months. <br> If `none of the attributes are specified, auditing expiration uses **Duration** or **NextUpdate** attributes. | No. |
| **ListIdentifier** | Provides a friendly name for the list of pin rules. Windows doesn't use this attribute for certificate pinning enforcement; however, it's included when the pin rules are converted to a certificate trust list (CTL). | No. | | **ListIdentifier** | Provides a friendly name for the list of pin rules. Windows doesn't use this attribute for certificate pinning enforcement; however, it's included when the pin rules are converted to a certificate trust list (CTL). | No. |
#### PinRule Element #### PinRule element
The **PinRule** element can have the following attributes. The **PinRule** element can have the following attributes.
@ -99,12 +99,12 @@ The **Site** element can have the following attributes.
| **Domain** | Contains the DNS name to be matched for this pin rule. When creating the certificate trust list, the parser normalizes the input name string value as follows: <br>- If the DNS name has a leading "*", it's removed. <br>- Non-ASCII DNS name is converted to ASCII Puny Code. <br>- Upper case ASCII characters are converted to lower case. <br>If the normalized name has a leading ".", then wildcard left-hand label matching is enabled. For example, ".xyz.com" would match "abc.xyz.com". | Yes.| | **Domain** | Contains the DNS name to be matched for this pin rule. When creating the certificate trust list, the parser normalizes the input name string value as follows: <br>- If the DNS name has a leading "*", it's removed. <br>- Non-ASCII DNS name is converted to ASCII Puny Code. <br>- Upper case ASCII characters are converted to lower case. <br>If the normalized name has a leading ".", then wildcard left-hand label matching is enabled. For example, ".xyz.com" would match "abc.xyz.com". | Yes.|
| **AllSubdomains** | By default, wildcard left-hand label matching is restricted to a single left-hand label. This attribute can be set to "true" to enable wildcard matching of all of the left-hand labels.<br>For example, setting this attribute would also match "123.abc.xyz.com" for the ".xyz.com" domain value.| No.| | **AllSubdomains** | By default, wildcard left-hand label matching is restricted to a single left-hand label. This attribute can be set to "true" to enable wildcard matching of all of the left-hand labels.<br>For example, setting this attribute would also match "123.abc.xyz.com" for the ".xyz.com" domain value.| No.|
### Create a Pin Rules Certificate Trust List ### Create a pin rules certificate trust list
The command line utility, **Certutil.exe**, includes the **generatePinRulesCTL** argument to parse the XML file and generate the encoded certificate trust list (CTL) that you add to your reference Windows 10 version 1703 computer and subsequently deploy. The command line utility, *Certutil.exe*, includes the *generatePinRulesCTL* argument to parse the XML file and generate the encoded certificate trust list (CTL) that you add to your reference Windows 10 version 1703 computer and subsequently deploy.
The usage syntax is: The usage syntax is:
```code ```cmd
CertUtil [Options] -generatePinRulesCTL XMLFile CTLFile [SSTFile] CertUtil [Options] -generatePinRulesCTL XMLFile CTLFile [SSTFile]
Generate Pin Rules CTL Generate Pin Rules CTL
XMLFile -- input XML file to be parsed. XMLFile -- input XML file to be parsed.
@ -118,25 +118,25 @@ Options:
-v -- Verbose operation -v -- Verbose operation
``` ```
The same certificate(s) can occur in multiple **PinRule** elements. - The same certificate(s) can occur in multiple **PinRule** elements
The same domain can occur in multiple **PinRule** elements. - The same domain can occur in multiple **PinRule** elements
Certutil coalesces these in the resultant pin rules certificate trust list. - Certutil coalesces these in the resultant pin rules certificate trust list
- Certutil.exe doesn't strictly enforce the XML schema definition
Certutil.exe doesn't strictly enforce the XML schema definition. Certutil performs the following to enable other tools to add/consume their own specific elements and attributes:
It does perform the following to enable other tools to add/consume their own specific elements and attributes:
- Skips elements before and after the **PinRules** element. - Skips elements before and after the **PinRules** element
- Skips any element not matching **Certificate** or **Site** within the **PinRules** element. - Skips any element not matching **Certificate** or **Site** within the **PinRules** element
- Skips any attributes not matching the above names for each element type. - Skips any attributes not matching the above names for each element type
Use the **certutil** command with the **generatePinRulesCTL** argument along with your XML file that contains your certificate pinning rules. Use the *certutil* command with the *generatePinRulesCTL* argument along with your XML file that contains your certificate pinning rules.
Lastly, provide the name of an output file that will include your certificate pinning rules in the form of a certificate trust list. Lastly, provide the name of an output file that will include your certificate pinning rules in the form of a certificate trust list.
```code ```cmd
certutil -generatePinRulesCTL certPinRules.xml pinrules.stl certutil -generatePinRulesCTL certPinRules.xml pinrules.stl
``` ```
### Applying Certificate Pinning Rules to a Reference Computer ### Apply certificate pinning rules to a reference computer
Now that your certificate pinning rules are in the certificate trust list format, you need to apply the settings to a reference computer as a prerequisite to deploying the setting to your enterprise. Now that your certificate pinning rules are in the certificate trust list format, you need to apply the settings to a reference computer as a prerequisite to deploying the setting to your enterprise.
To simplify the deployment configuration, it's best to apply your certificate pinning rules to a computer that has the Group Policy Management Console (GPMC) included in the Remote Server Administration Tools (RSAT). To simplify the deployment configuration, it's best to apply your certificate pinning rules to a computer that has the Group Policy Management Console (GPMC) included in the Remote Server Administration Tools (RSAT).
@ -163,7 +163,7 @@ Certutil writes the binary information to the following registration location:
![Registry binary information.](images/enterprise-pinning-registry-binary-information.png) ![Registry binary information.](images/enterprise-pinning-registry-binary-information.png)
### Deploying Enterprise Pin Rule Settings using Group Policy ### Deploy enterprise pin rule settings using group policy
You've successfully created a certificate pinning rules XML file. You've successfully created a certificate pinning rules XML file.
From the XML file you've created a certificate pinning trust list file, and you've applied the contents of that file to your reference computer from which you can run the Group Policy Management Console. From the XML file you've created a certificate pinning trust list file, and you've applied the contents of that file to your reference computer from which you can run the Group Policy Management Console.
@ -171,29 +171,29 @@ Now you need to configure a Group Policy object to include the applied certifica
Sign-in to the reference computer using domain administrator equivalent credentials. Sign-in to the reference computer using domain administrator equivalent credentials.
1. Start the **Group Policy Management Console** (gpmc.msc) 1. Start the **Group Policy Management Console** (gpmc.msc)
2. In the navigation pane, expand the forest node and then expand the domain node. 1. In the navigation pane, expand the forest node and then expand the domain node
3. Expand the node that contains your Active Directory's domain name 1. Expand the node that contains your Active Directory's domain name
4. Select the **Group Policy objects** node. Right-click the **Group Policy objects** node and click **New**. 1. Select the **Group Policy objects** node. Right-click the **Group Policy objects** node and select **New**
5. In the **New GPO** dialog box, type _Enterprise Certificate Pinning Rules_ in the **Name** text box and click **OK**. 1. In the **New GPO** dialog box, type _Enterprise Certificate Pinning Rules_ in the **Name** text box and select **OK**
6. In the content pane, right-click the **Enterprise Certificate Pinning Rules** Group Policy object and click **Edit**. 1. In the content pane, right-click the **Enterprise Certificate Pinning Rules** Group Policy object and select **Edit**
7. In the **Group Policy Management Editor**, in the navigation pane, expand the **Preferences** node under **Computer Configuration**. Expand **Windows Settings**. 1. In the **Group Policy Management Editor**, in the navigation pane, expand the **Preferences** node under **Computer Configuration**. Expand **Windows Settings**
8. Right-click the **Registry** node and click **New**. 1. Right-click the **Registry** node and select **New**
9. In the **New Registry Properties** dialog box, select **Update** from the **Action** list. Select **HKEY_LOCAL_MACHINE** from the **Hive** list. 1. In the **New Registry Properties** dialog box, select **Update** from the **Action** list. Select **HKEY_LOCAL_MACHINE** from the **Hive** list
10. For the **Key Path**, click **…** to launch the **Registry Item Browser**. Navigate to the following registry key and select the **PinRules** registry value name: 1. For the **Key Path**, select **…** to launch the **Registry Item Browser**. Navigate to the following registry key and select the **PinRules** registry value name:
HKLM\SOFTWARE\Microsoft\Cryptography\OID\EncodingType0\CertDllCreateCertificateChainEngine\Config `HKLM\SOFTWARE\Microsoft\Cryptography\OID\EncodingType0\CertDllCreateCertificateChainEngine\Config`
Click **Select** to close the **Registry Item Browser**. Click **Select** to close the **Registry Item Browser**.
11. The **Key Path** should contain the selected registry key. The **Value name** configuration should contain the registry value name **_PinRules_**. **Value type** should read **_REG\_BINARY_** and **Value data** should contain a long series of numbers from 0-9 and letters ranging from A-F (hexadecimal). Click **OK** to save your settings and close the dialog box. 1. The **Key Path** should contain the selected registry key. The **Value name** configuration should contain the registry value name **_PinRules_**. **Value type** should read **_REG\_BINARY_** and **Value data** should contain a long series of numbers from 0-9 and letters ranging from A-F (hexadecimal). Select **OK** to save your settings and close the dialog box.
![PinRules Properties.](images/enterprise-certificate-pinning-pinrules-properties.png) ![PinRules Properties.](images/enterprise-certificate-pinning-pinrules-properties.png)
12. Close the **Group Policy Management Editor** to save your settings. 1. Close the **Group Policy Management Editor** to save your settings.
13. Link the **Enterprise Certificate Pinning Rules** Group Policy object to apply to computers that run Windows 10, version 1703 in your enterprise. When these domain-joined computers apply Group Policy, the registry information configured in the Group Policy object is applied to the computer. 1. Link the **Enterprise Certificate Pinning Rules** Group Policy object to apply to computers that run Windows 10, version 1703 in your enterprise. When these domain-joined computers apply Group Policy, the registry information configured in the Group Policy object is applied to the computer.
## Additional Pin Rules Logging ## Additional pin rules logging
To assist in constructing certificate pinning rules, you can configure the **PinRulesLogDir** setting under the certificate chain configuration registry key to include a parent directory to log pin rules. To assist in constructing certificate pinning rules, you can configure the **PinRulesLogDir** setting under the certificate chain configuration registry key to include a parent directory to log pin rules.
@ -204,7 +204,7 @@ To assist in constructing certificate pinning rules, you can configure the **Pin
| Value | The Parent directory where Windows should write the additional pin rule logs | | Value | The Parent directory where Windows should write the additional pin rule logs |
| Data type | REG_SZ | | Data type | REG_SZ |
### Permission for the Pin Rule Log Folder ### Permission for the pin rule log folder
The folder in which Windows writes the additional pin rule logs must have permissions so that all users and applications have full access. The folder in which Windows writes the additional pin rule logs must have permissions so that all users and applications have full access.
You can run the following commands from an elevated command prompt to achieve the proper permissions. You can run the following commands from an elevated command prompt to achieve the proper permissions.
@ -221,11 +221,11 @@ icacls %PinRulesLogDir% /inheritance:e /setintegritylevel (OI)(CI)L
Whenever an application verifies a TLS/SSL certificate chain that contains a server name matching a DNS name in the server certificate, Windows writes a .p7b file consisting of all the certificates in the server's chain to one of three child folders: Whenever an application verifies a TLS/SSL certificate chain that contains a server name matching a DNS name in the server certificate, Windows writes a .p7b file consisting of all the certificates in the server's chain to one of three child folders:
- AdminPinRules - AdminPinRules
Matched a site in the enterprise certificate pinning rules. Matched a site in the enterprise certificate pinning rules.
- AutoUpdatePinRules - AutoUpdatePinRules
Matched a site in the certificate pinning rules managed by Microsoft. Matched a site in the certificate pinning rules managed by Microsoft.
- NoPinRules - NoPinRules
Didn't match any site in the certificate pin rules. Didn't match any site in the certificate pin rules.
The output file name consists of the leading eight ASCII hex digits of the root's SHA1 thumbprint followed by the server name. The output file name consists of the leading eight ASCII hex digits of the root's SHA1 thumbprint followed by the server name.
For example: For example:
@ -236,7 +236,7 @@ For example:
If there's either an enterprise certificate pin rule or a Microsoft certificate pin rule mismatch, then Windows writes the .p7b file to the **MismatchPinRules** child folder. If there's either an enterprise certificate pin rule or a Microsoft certificate pin rule mismatch, then Windows writes the .p7b file to the **MismatchPinRules** child folder.
If the pin rules have expired, then Windows writes the .p7b to the **ExpiredPinRules** child folder. If the pin rules have expired, then Windows writes the .p7b to the **ExpiredPinRules** child folder.
## Representing a Date in XML ## Represent a date in XML
Many attributes within the pin rules xml file are dates. Many attributes within the pin rules xml file are dates.
These dates must be properly formatted and represented in UTC. These dates must be properly formatted and represented in UTC.
@ -253,13 +253,13 @@ However, be certain to append the uppercase "Z" to the end of the XML date strin
2015-05-11T07:00:00Z 2015-05-11T07:00:00Z
``` ```
## Converting an XML Date ## Convert an XML date
You can also use Windows PowerShell to validate and convert an XML date into a human readable date to validate it's the correct date. You can also use Windows PowerShell to validate and convert an XML date into a human readable date to validate it's the correct date.
![Converting an XML date.](images/enterprise-certificate-pinning-converting-an-xml-date.png) ![Converting an XML date.](images/enterprise-certificate-pinning-converting-an-xml-date.png)
## Representing a Duration in XML ## Represent a duration in XML
Some elements may be configured to use a duration rather than a date. Some elements may be configured to use a duration rather than a date.
You must represent the duration as an XML timespan data type. You must represent the duration as an XML timespan data type.
@ -267,15 +267,15 @@ You can use Windows PowerShell to properly format and validate durations (timesp
![Representing a duration.](images/enterprise-certificate-pinning-representing-a-duration.png) ![Representing a duration.](images/enterprise-certificate-pinning-representing-a-duration.png)
## Converting an XML Duration ## Convert an XML duration
You can convert an XML formatted timespan into a timespan variable that you can read. You can convert an XML formatted timespan into a timespan variable that you can read.
![Converting an XML duration.](images/enterprise-certificate-pinning-converting-a-duration.png) ![Converting an XML duration.](images/enterprise-certificate-pinning-converting-a-duration.png)
## Certificate Trust List XML Schema Definition (XSD) ## Certificate trust list XML schema definition (XSD)
```code ```xml
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="PinRules"> <xs:element name="PinRules">
<xs:complexType> <xs:complexType>
@ -329,12 +329,3 @@ You can convert an XML formatted timespan into a timespan variable that you can
</xs:element> </xs:element>
</xs:schema> </xs:schema>
``` ```