deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-05-14 14:27:22 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge pull request #800 from Justinha/vsts11339947

Browse Source 
fixed table formatting
This commit is contained in:
Elizabeth Ross 2017-05-30 20:45:13 -07:00 committed by GitHub
commit c169818633
1 changed files with 23 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
windows/access-protection/enterprise-certificate-pinning.md
View File

@ -71,141 +71,41 @@ Each PinRule element contains a sequence of one or more Site elements and a sequ
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).
- **Duration** or **NextUpdate** | Attribute | Description | Required |
|-----------|-------------|----------|
Specifies when the Pin Rules will expire. | **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, does not allow years and months. You represent the **NextUpdate** attribute as a XML DateTime data type in UTC. | **Required?** Yes. At least one is required. |
Either 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 does not allow years and months. <br> If neither attribute is specified, auditing expiration uses **Duration** or **NextUpdate** attributes. | No. |
**NextUpdate** takes precedence if both are specified. | **ListIdentifier** | Provides a friendly name for the list of pin rules. Windows does not use this attribute for certificate pinning enforcement, however it is included when the pin rules are converted to a certificate trust list (CTL). | No. |
**Duration**, represented as an XML TimeSpan data type, does not allow years and months.
You represent the **NextUpdate** attribute as a 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.
**LogEndDate**, represented as an XML DateTime data type in UTC, takes precedence if both are specified.
You represent **LogDuration** as an XML TimeSpan data type, which does not allow years and months.
If neither attribute is specified, auditing expiration uses **Duration** or **NextUpdate** attributes.
**Required?** No.
- **ListIdentifier**
Provides a friendly name for the list of pin rules.
Windows does not use this attribute for certificate pinning enforcement, however it is included when the pin rules are converted to a certificate trust list (CTL).
**Required?** No.
#### PinRule Element #### PinRule Element
The **PinRule** element can have the following attributes: The **PinRule** element can have the following attributes.
- **Name** | Attribute | Description | Required |
|-----------|-------------|----------|
Uniquely identifies the **PinRule**. | **Name** | Uniquely identifies the **PinRule**. Windows uses this attribute to identify the element for a parsing error or for verbose output. The attribute is not included in the generated certificate trust list (CTL). | Yes.|
Windows uses this attribute to identify the element for a parsing error or for verbose output. | **Error** | Describes the action Windows performs when it encounters a PIN mismatch. You can choose from the following string values: <br>- **Revoked** - Windows reports the certificate protecting the site as if it was revoked. This typically prevents the user from accessing the site. <br>- **InvalidName** - Windows reports the certificate protecting the site as if the name on the certificate does not match the name of the site. This typically results in prompting the user before accessing the site. <br>- **None** - The default value. No error is returned. You can use this setting to audit the pin rules without introducing any user friction. | No. |
The attribute is not included in the generated certificate trust list (CTL). | **Log** | A Boolean value represent as string that equals **true** or **false**. By default, logging is enabled (**true**). | No. |
**Required?** Yes.
- **Error**
Describes the action Windows performs when it encounters a PIN mismatch.
You can choose from the following string values:
- **Revoked** - Windows reports the certificate protecting the site as if it was revoked. This typically prevents the user from accessing the site.
- **InvalidName** - Windows reports the certificate protecting the site as if the name on the certificate does not match the name of the site. This typically results in prompting the user before accessing the site.
- **None** - The default value. No error is returned. You can use this setting to audit the pin rules without introducing any user friction.
**Required?** No.
- **Log**
A Boolean value represent as string that equals **true** or **false**.
By default, logging is enabled (**true**).
**Required?** No.
#### Certificate element #### Certificate element
The **Certificate** element can have the following attributes: The **Certificate** element can have the following attributes.
- **File** | Attribute | Description | Required |
|-----------|-------------|----------|
Path to a file containing one or more certificates. | **File** | Path to a file containing one or more certificates. Where the certificate(s) can be encoded as: <br>- single certificate <br>- p7b <br>- sst <br> These files can also be Base64 formatted. All **Site** elements included in the same **PinRule** element can match any of these certificates. | Yes (File, Directory or Base64 must be present). |
Where the certificate(s) can be encoded as: | **Directory** | Path to a directory containing one or more of the above certificate files. Skips any files not containing any certificates. | Yes (File, Directory or Base64 must be present). |
- single certificate | **Base64** | Base64 encoded certificate(s). Where the certificate(s) can be encoded as: <br>- single certificate <br>- p7b <br> - sst <br> This allows the certificates to be included in the XML file without a file directory dependency. <br> Note: <br> You can use **certutil -encode** to convert a .cer file into base64. You can then use Notepad to copy and paste the base64 encoded certificate into the pin rule. | Yes (File, Directory or Base64 must be present). |
- p7b | **EndDate** | Enables you to configure an expiration date for when the certificate is no longer valid in the pin rule. <br>If you are in the process of switching to a new root or CA, you can set the **EndDate** to allow matching of this element’s certificates.<br> If the current time is past the **EndDate**, then, when creating the certificate trust list (CTL), the parser outputs a warning message and exclude the certificate(s) from the Pin Rule in the generated CTL.<br> For help with formatting Pin Rules, see [Representing a Date in XML](#representing-a-date-in-xml).| No.|
- sst.
These files can also be Base64 formatted.
All **Site** elements included in the same **PinRule** element can match any of these certificates.
**Required?** Yes (File, Directory or Base64 must be present).
- **Directory**
Path to a directory containing one or more of the above certificate files.
Skips any files not containing any certificates.
**Required?** Yes (File, Directory or Base64 must be present).
- **Base64**
Base64 encoded certificate(s).
Where the certificate(s) can be encoded as:
- single certificate
- p7b
- sst.
This allows the certificates to be included in the XML file without a file directory dependency.
> [!Note]
> You can use **certutil -encode** to a .cer file into base64. You can then use Notepad to copy and paste the base64 encoded certificate into the pin rule.
**Required?** Yes (File, Directory or Base64 must be present).
- **EndDate**
Enables you to configure an expiration date for when the certificate is no longer valid in the pin rule.
If you are in the process of switching to a new root or CA, you can set the **EndDate** to allow matching of this element’s certificates.
If the current time is past the **EndDate**, then, when creating the certificate trust list (CTL), the parser outputs a warning message and exclude the certificate(s) from the Pin Rule in the generated CTL.
For help with formatting Pin Rules, see [Representing a Date in XML](#representing-a-date-in-xml).
**Required?** No.
#### Site element #### Site element
The **Site** element can have the following attributes: The **Site** element can have the following attributes.
- **Domain** | Attribute | Description | Required |
|-----------|-------------|----------|
Contains the DNS name to be matched for this pin rule. | **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 is removed. <br>- Non-ASCII DNS name are 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.|
When creating the certificate trust list, the parser normalizes the input name string value as follows: | **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.|
- If the DNS name has a leading "*" it is removed.
- Non-ASCII DNS name are converted to ASCII Puny Code.
- Upper case ASCII characters are converted to lower case.
If the normalized name has a leading ".", then, wildcard left hand label matching is enabled.
For example, ".xyz.com" would match "abc.xyz.com".
**Required?** 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.
For example, setting this attribute would also match "123.abc.xyz.com" for the ".xyz.com" domain value.
**Required?** No.
### Create a Pin Rules Certificate Trust List ### Create a Pin Rules Certificate Trust List
@ -302,10 +202,6 @@ Sign-in to the reference computer using domain administrator equivalent credenti
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.
```code
HKLM\SOFTWARE\Microsoft\Cryptography\OID\EncodingType0\CertDllCreateCertificateChainEngine\Config
```
| Name | Value | | Name | Value |
|------|-------| |------|-------|
| Key | HKLM\SOFTWARE\Microsoft\Cryptography\OID\EncodingType0\CertDllCreateCertificateChainEngine\Config | | Key | HKLM\SOFTWARE\Microsoft\Cryptography\OID\EncodingType0\CertDllCreateCertificateChainEngine\Config |