Make SHA algorithm names more consistent (#11104)

Author: gewarren

xml/Microsoft.Extensions.Compliance.Redaction/HmacRedactor.xml

@@ -24,9 +24,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>
-            A redactor using HMACSHA256 to encode data being redacted.
-            </summary>
+    <summary>Represents a redactor that uses HMAC SHA-256 to encode redacted data.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>

xml/System.CodeDom/CodeChecksumPragma.xml

@@ -47,19 +47,19 @@
   <Docs>
     <summary>Represents a code checksum pragma code entity.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.CodeDom.CodeChecksumPragma> class inherits from <xref:System.CodeDom.CodeDirective> and can be contained in a <xref:System.CodeDom.CodeDirectiveCollection>. <xref:System.CodeDom.CodeChecksumPragma> provides the unique identification of source files, including files that have been generated.  
-  
-   
-  
-## Examples  
- The following code example shows the use of the <xref:System.CodeDom.CodeChecksumPragma> class.  
-  
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+ The <xref:System.CodeDom.CodeChecksumPragma> class inherits from <xref:System.CodeDom.CodeDirective> and can be contained in a <xref:System.CodeDom.CodeDirectiveCollection>. <xref:System.CodeDom.CodeChecksumPragma> provides the unique identification of source files, including files that have been generated.
+
+
+
+## Examples
+ The following code example shows the use of the <xref:System.CodeDom.CodeChecksumPragma> class.
+
  :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet1":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet1":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet1":::
+
  ]]></format>
     </remarks>
   </Docs>
@@ -106,14 +106,14 @@
       <Docs>
         <summary>Initializes a new instance of the <see cref="T:System.CodeDom.CodeChecksumPragma" /> class.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Examples  
- The following code example shows the use of the <xref:System.CodeDom.CodeChecksumPragma.%23ctor%2A> constructor. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Examples
+ The following code example shows the use of the <xref:System.CodeDom.CodeChecksumPragma.%23ctor%2A> constructor. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class.
+
  :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet4":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet4":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet4":::
+
  ]]></format>
         </remarks>
       </Docs>
@@ -159,19 +159,19 @@
         <param name="checksumData">A byte array that contains the checksum data.</param>
         <summary>Initializes a new instance of the <see cref="T:System.CodeDom.CodeChecksumPragma" /> class using a file name, a GUID representing the checksum algorithm, and a byte stream representing the checksum data.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- For more information on the `checksumAlgorithmId` parameter, see the <xref:System.CodeDom.CodeChecksumPragma.ChecksumAlgorithmId%2A> property.  
-  
-   
-  
-## Examples  
- The following code example shows the use of the <xref:System.CodeDom.CodeChecksumPragma.%23ctor%2A> constructor. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ For more information on the `checksumAlgorithmId` parameter, see the <xref:System.CodeDom.CodeChecksumPragma.ChecksumAlgorithmId%2A> property.
+
+
+
+## Examples
+ The following code example shows the use of the <xref:System.CodeDom.CodeChecksumPragma.%23ctor%2A> constructor. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class.
+
  :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet8":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet8":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet8":::
+
  ]]></format>
         </remarks>
       </Docs>
@@ -217,21 +217,22 @@
         <summary>Gets or sets a GUID that identifies the checksum algorithm to use.</summary>
         <value>A <see cref="T:System.Guid" /> that identifies the checksum algorithm to use.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- Algorithms are provided for the MD5 and SHA1 hashes. The GUID value to use for the MD5 hash is {0x406ea660, 0x64cf, 0x4c82, 0xb6, 0xf0, 0x42, 0xd4, 0x81, 0x72, 0xa7, 0x99}. The GUID to use for the SHA1 hash is {0xff1816ec, 0xaa5e, 0x4d10, 0x87, 0xf7, 0x6f, 0x49, 0x63, 0x83, 0x34, 0x60}.  
-  
- The calculation of the checksum is language-specific. That is, the language vendor can use any of the hashing algorithms known to the debugger to calculate the checksum. The use of a GUID for this property provides hash algorithm extensibility.  
-  
- Due to collision problems with SHA1 and MD5, Microsoft recommends a security model based on SHA256 or better.  
-  
-## Examples  
- The following code example shows the setting of the <xref:System.CodeDom.CodeChecksumPragma.ChecksumAlgorithmId%2A> property. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Algorithms are provided for the MD5 and SHA-1 hashes. The GUID value to use for the MD5 hash is {0x406ea660, 0x64cf, 0x4c82, 0xb6, 0xf0, 0x42, 0xd4, 0x81, 0x72, 0xa7, 0x99}. The GUID to use for the SHA-1 hash is {0xff1816ec, 0xaa5e, 0x4d10, 0x87, 0xf7, 0x6f, 0x49, 0x63, 0x83, 0x34, 0x60}.
+
+ The calculation of the checksum is language-specific. That is, the language vendor can use any of the hashing algorithms known to the debugger to calculate the checksum. The use of a GUID for this property provides hash algorithm extensibility.
+
+ Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on SHA-256 or better.
+
+## Examples
+ The following code example shows the setting of the <xref:System.CodeDom.CodeChecksumPragma.ChecksumAlgorithmId%2A> property. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class.
+
  :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet6":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet6":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet6":::
+
  ]]></format>
         </remarks>
       </Docs>
@@ -277,19 +278,19 @@
         <summary>Gets or sets the value of the data for the checksum calculation.</summary>
         <value>A byte array that contains the data for the checksum calculation.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.CodeDom.CodeChecksumPragma.ChecksumData%2A> property contains data from the target file specified by the <xref:System.CodeDom.CodeChecksumPragma.FileName%2A> property.  
-  
-   
-  
-## Examples  
- The following code example shows the setting of the <xref:System.CodeDom.CodeChecksumPragma.ChecksumData%2A> property. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ The <xref:System.CodeDom.CodeChecksumPragma.ChecksumData%2A> property contains data from the target file specified by the <xref:System.CodeDom.CodeChecksumPragma.FileName%2A> property.
+
+
+
+## Examples
+ The following code example shows the setting of the <xref:System.CodeDom.CodeChecksumPragma.ChecksumData%2A> property. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class
+
  :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet7":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet7":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet7":::
+
  ]]></format>
         </remarks>
       </Docs>
@@ -331,19 +332,19 @@
         <summary>Gets or sets the path to the checksum file.</summary>
         <value>The path to the checksum file.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- An example of a <xref:System.CodeDom.CodeChecksumPragma.FileName%2A> property value is "C:\Temp\Test\OuterLinePragma.txt".  
-  
-   
-  
-## Examples  
- The following code example shows the setting of the <xref:System.CodeDom.CodeChecksumPragma.FileName%2A> property. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ An example of a <xref:System.CodeDom.CodeChecksumPragma.FileName%2A> property value is "C:\Temp\Test\OuterLinePragma.txt".
+
+
+
+## Examples
+ The following code example shows the setting of the <xref:System.CodeDom.CodeChecksumPragma.FileName%2A> property. This code example is part of a larger example provided for the <xref:System.CodeDom.CodeChecksumPragma> class
+
  :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet5":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet5":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CodeDom.CodeDirectives/VB/codedirective.vb" id="Snippet5":::
+
  ]]></format>
         </remarks>
       </Docs>

xml/System.Configuration.Assemblies/AssemblyHashAlgorithm.xml

@@ -54,25 +54,25 @@
   <Docs>
     <summary>Specifies all the hash algorithms used for hashing files and for generating the strong name.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- A `hash function``H` is a transformation that takes an input `m` and returns a fixed-size string, which is called the hash value `h` (that is, `h` = `H` (`m`)). Hash functions with just this property have a variety of general computational uses, but when employed in cryptography, the hash functions are usually chosen to have some additional properties.  
-  
- The basic requirements for a cryptographic hash function are:  
-  
--   The input can be of any length.  
-  
--   The output has a fixed length.  
-  
--   `H` (`x)` is relatively easy to compute for any given x.  
-  
--   `H` (`x`) is one-way.  
-  
--   `H` (`x`) is collision-free.  
-  
- The hash value represents concisely the longer message or document from which it was computed; this value is called the message digest. You can think of a message digest as a digital fingerprint of the larger document. Examples of well-known hash functions are MD2 and SHA.  
-  
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+ A `hash function``H` is a transformation that takes an input `m` and returns a fixed-size string, which is called the hash value `h` (that is, `h` = `H` (`m`)). Hash functions with just this property have a variety of general computational uses, but when employed in cryptography, the hash functions are usually chosen to have some additional properties.
+
+ The basic requirements for a cryptographic hash function are:
+
+-   The input can be of any length.
+
+-   The output has a fixed length.
+
+-   `H` (`x)` is relatively easy to compute for any given x.
+
+-   `H` (`x`) is one-way.
+
+-   `H` (`x`) is collision-free.
+
+ The hash value represents concisely the longer message or document from which it was computed; this value is called the message digest. You can think of a message digest as a digital fingerprint of the larger document. Examples of well-known hash functions are MD2 and SHA.
+
  ]]></format>
     </remarks>
   </Docs>
@@ -154,7 +154,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>A mask indicating that there is no hash algorithm. If you specify <see langword="None" /> for a multi-module assembly, the common language runtime defaults to the SHA1 algorithm, since multi-module assemblies need to generate a hash. Due to collision problems with SHA1, Microsoft recommends SHA256.</summary>
+        <summary>A mask indicating that there is no hash algorithm. If you specify <see langword="None" /> for a multi-module assembly, the common language runtime defaults to the SHA-1 algorithm, since multi-module assemblies need to generate a hash. Due to collision problems with SHA-1, Microsoft recommends SHA-256.</summary>
       </Docs>
     </Member>
     <Member MemberName="SHA1">

xml/System.IO.Packaging/PackageDigitalSignatureManager.xml

@@ -273,13 +273,13 @@ This property specifies where the signer's X.509 certificate will be stored when
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- The default hash algorithm for the standard <xref:System.IO.Packaging.PackageDigitalSignatureManager> class is <xref:System.Security.Cryptography.Xml.SignedXml.XmlDsigSHA1Url> (Secure Hash Algorithm version 1.0 (SHA1)).
+ The default hash algorithm for the standard <xref:System.IO.Packaging.PackageDigitalSignatureManager> class is <xref:System.Security.Cryptography.Xml.SignedXml.XmlDsigSHA1Url> (Secure Hash Algorithm version 1.0, or SHA-1).
 
  The <xref:System.IO.Packaging.PackageDigitalSignatureManager.HashAlgorithm%2A> property gets or sets the actual hash algorithm this is used to create and verify signatures.
 
  The <xref:System.IO.Packaging.PackageDigitalSignatureManager.DefaultHashAlgorithm%2A> property is typically used to reset the <xref:System.IO.Packaging.PackageDigitalSignatureManager.HashAlgorithm%2A> property back to default after a temporary change.
 
- Due to collision problems with SHA1, Microsoft recommends a security model based on SHA256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
 
  ]]></format>
         </remarks>
@@ -360,7 +360,7 @@ This property specifies where the signer's X.509 certificate will be stored when
 
  The <xref:System.IO.Packaging.PackageDigitalSignatureManager.HashAlgorithm%2A> property is typically not changed from its default. This property must be changed only if a signature that uses a different known and accessible <xref:System.Security.Cryptography.HashAlgorithm> is encountered. When finished with the signature that uses a different hash algorithm, call <xref:System.IO.Packaging.PackageDigitalSignatureManager.DefaultHashAlgorithm%2A> to reset the <xref:System.IO.Packaging.PackageDigitalSignatureManager.HashAlgorithm%2A> property back to default.
 
- Due to collision problems with SHA1, Microsoft recommends a security model based on SHA256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
 
  ]]></format>
         </remarks>