Add/update documentation for the X509Certificates namespace. (#3669)

* Add/update documentation for the X509Certificates namespace.

* Remove redundant tag close.

* Apply suggestions from code review

Co-Authored-By: Carlos Sanchez Lopez <[email protected]>

* Apply suggestions from code review

Co-Authored-By: Carlos Sanchez Lopez <[email protected]>

* Apply suggestions from code review

Co-Authored-By: Genevieve Warren <[email protected]>

Author: 2 people

xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml

@@ -1665,6 +1665,11 @@
         <summary>Returns the hash value for the X.509v3 certificate that is computed by using the specified cryptographic hash algorithm.</summary>
         <returns>A byte array that contains the hash value for the X.509 certificate.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentException">
+          <paramref name="hashAlgorithm" />.<see cref="P:System.Security.Cryptography.HashAlgorithmName.Name" /> is <see langword="null" /> or an empty string.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">
+          <paramref name="hashAlgorithm" /> is not a known hash algorithm.</exception>
+        <altmember cref="M:System.Security.Cryptography.X509Certificates.X509Certificate.TryGetCertHash(System.Security.Cryptography.HashAlgorithmName,System.Span{System.Byte},System.Int32@)" />
       </Docs>
     </Member>
     <MemberGroup MemberName="GetCertHashString">
@@ -1751,6 +1756,10 @@
         <summary>Returns a hexadecimal string containing the hash value for the X.509v3 certificate computed using the specified cryptographic hash algorithm.</summary>
         <returns>The hexadecimal string representation of the X.509 certificate hash value.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentException">
+          <paramref name="hashAlgorithm" />.<see cref="P:System.Security.Cryptography.HashAlgorithmName.Name" /> is <see langword="null" /> or an empty string.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">
+          <paramref name="hashAlgorithm" /> is not a known hash algorithm.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetEffectiveDateString">
@@ -2320,6 +2329,8 @@
         <returns>The public key for the X.509 certificate as an array of bytes.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
+## Remarks
+This value corresponds to the contents of the `subjectPublicKey` field of the SubjectPublicKeyInfo data within the certificate.
   
 ## Examples  
  The following example uses the <xref:System.Security.Cryptography.X509Certificates.X509Certificate.GetPublicKey%2A> method to return a certificate's public key as an array of bytes and displays it to the console.  
@@ -2368,6 +2379,8 @@
         <returns>The public key for the X.509 certificate as a hexadecimal string.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
+## Remarks
+This value corresponds to the contents of the `subjectPublicKey` field of the SubjectPublicKeyInfo data within the certificate.
   
 ## Examples  
  The following example uses the <xref:System.Security.Cryptography.X509Certificates.X509Certificate.GetPublicKeyString%2A> method to return a certificate's public key as a string and displays it to the console.  
@@ -2420,6 +2433,8 @@
         <returns>A byte array containing the X.509 certificate data.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
+## Remarks
+The output of this method is equivalent to the output of the <xref:System.Security.Cryptography.X509Certificates.X509Certificate.Export%2A> method with an output encoding of <xref:System.Security.Cryptography.X509Certificates.X509ContentType.Cert?displayProperty=nameWithType>.
   
 ## Examples  
  The following example uses the <xref:System.Security.Cryptography.X509Certificates.X509Certificate.GetRawCertData%2A> method to return a certificate's raw data as an array of bytes and displays it to the console.  
@@ -2702,6 +2717,7 @@
         <permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This class cannot be used by partially trusted or transparent code.</permission>
         <permission cref="F:System.Security.Permissions.SecurityAction.InheritanceDemand">for full trust for inheritors. This member cannot be inherited by partially trusted code.</permission>
         <permission cref="T:System.Security.Permissions.KeyContainerPermission">for permission to create a key container. Security action: <see cref="F:System.Security.Permissions.SecurityAction.Demand" />. Associated enumeration: <see cref="F:System.Security.Permissions.KeyContainerPermissionFlags.Create" /></permission>
+        <exception cref="T:System.PlatformNotSupportedException">.NET Core only: In all cases.</exception>  
       </Docs>
     </Member>
     <Member MemberName="Import">
@@ -2764,6 +2780,7 @@
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">The <paramref name="fileName" /> parameter is <see langword="null" />.</exception>
+        <exception cref="T:System.PlatformNotSupportedException">.NET Core only: In all cases.</exception>  
         <permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This class cannot be used by partially trusted or transparent code.</permission>
         <permission cref="F:System.Security.Permissions.SecurityAction.InheritanceDemand">for full trust for inheritors. This member cannot be inherited by partially trusted code.</permission>
         <permission cref="T:System.Security.Permissions.FileIOPermission">for permission to read the file described by the <paramref name="fileName" /> parameter. Security action: <see cref="F:System.Security.Permissions.SecurityAction.Demand" />. Associated enumeration: <see cref="F:System.Security.Permissions.EnvironmentPermissionAccess.Read" /></permission>
@@ -2831,6 +2848,7 @@
  -or-  
 
  The length of the <paramref name="rawData" /> parameter is 0.</exception>
+        <exception cref="T:System.PlatformNotSupportedException">.NET Core only: In all cases.</exception>  
         <permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This class cannot be used by partially trusted or transparent code.</permission>
         <permission cref="F:System.Security.Permissions.SecurityAction.InheritanceDemand">for full trust for inheritors. This member cannot be inherited by partially trusted code.</permission>
         <permission cref="T:System.Security.Permissions.KeyContainerPermission">for permission to create a key container. Security action: <see cref="F:System.Security.Permissions.SecurityAction.Demand" />. Associated enumeration: <see cref="F:System.Security.Permissions.KeyContainerPermissionFlags.Create" /></permission>
@@ -2895,6 +2913,7 @@
  -or-  
 
  The length of the <paramref name="rawData" /> parameter is 0.</exception>
+        <exception cref="T:System.PlatformNotSupportedException">.NET Core only: In all cases.</exception>  
         <permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This class cannot be used by partially trusted or transparent code.</permission>
         <permission cref="F:System.Security.Permissions.SecurityAction.InheritanceDemand">for full trust for inheritors. This member cannot be inherited by partially trusted code.</permission>
         <permission cref="T:System.Security.Permissions.KeyContainerPermission">for permission to create a key container. Security action: <see cref="F:System.Security.Permissions.SecurityAction.Demand" />. Associated enumeration: <see cref="F:System.Security.Permissions.KeyContainerPermissionFlags.Create" /></permission>
@@ -2957,6 +2976,7 @@
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">The <paramref name="fileName" /> parameter is <see langword="null" />.</exception>
+        <exception cref="T:System.PlatformNotSupportedException">.NET Core only: In all cases.</exception>  
         <permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This class cannot be used by partially trusted or transparent code.</permission>
         <permission cref="F:System.Security.Permissions.SecurityAction.InheritanceDemand">for full trust for inheritors. This member cannot be inherited by partially trusted code.</permission>
         <permission cref="T:System.Security.Permissions.FileIOPermission">for permission to read the file described by the <paramref name="fileName" /> parameter. Security action: <see cref="F:System.Security.Permissions.SecurityAction.Demand" />. Associated enumeration: <see cref="F:System.Security.Permissions.EnvironmentPermissionAccess.Read" /></permission>
@@ -3020,6 +3040,7 @@
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">The <paramref name="fileName" /> parameter is <see langword="null" />.</exception>
+        <exception cref="T:System.PlatformNotSupportedException">.NET Core only: In all cases.</exception>  
         <permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This class cannot be used by partially trusted or transparent code.</permission>
         <permission cref="F:System.Security.Permissions.SecurityAction.InheritanceDemand">for full trust for inheritors. This member cannot be inherited by partially trusted code.</permission>
         <permission cref="T:System.Security.Permissions.FileIOPermission">for permission to read the file described by the <paramref name="fileName" /> parameter. Security action: <see cref="F:System.Security.Permissions.SecurityAction.Demand" />. Associated enumeration: <see cref="F:System.Security.Permissions.EnvironmentPermissionAccess.Read" /></permission>
@@ -3198,6 +3219,7 @@
         <param name="sender">The source of the deserialization event.</param>
         <summary>Implements the <see cref="T:System.Runtime.Serialization.ISerializable" /> interface and is called back by the deserialization event when deserialization is complete.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.PlatformNotSupportedException">.NET Core only: In all cases.</exception>  
       </Docs>
     </Member>
     <Member MemberName="System.Runtime.Serialization.ISerializable.GetObjectData">
@@ -3244,6 +3266,7 @@
         <param name="context">The destination context of the serialization.</param>
         <summary>Gets serialization information with all the data needed to recreate an instance of the current <see cref="T:System.Security.Cryptography.X509Certificates.X509Certificate" /> object.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.PlatformNotSupportedException">.NET Core only: In all cases.</exception>  
         <permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.</permission>
       </Docs>
     </Member>
@@ -3394,12 +3417,18 @@
         <Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
       </Parameters>
       <Docs>
-        <param name="hashAlgorithm">To be added.</param>
-        <param name="destination">To be added.</param>
-        <param name="bytesWritten">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="hashAlgorithm">The algorithm to use for the thumbprint.</param>
+        <param name="destination">The buffer to receive the certificate thumbprint.</param>
+        <param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
+        <summary>Attempts to produce a "thumbprint" for the certificate by hashing the encoded representation of the certificate with the specified hash algorithm.</summary>
+        <returns>
+          <see langword="true"/> if <paramref name="destination"/> is long enough to receive the hash value; otherwise, <see langword="false"/>.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentException">
+          <paramref name="hashAlgorithm" />.<see cref="P:System.Security.Cryptography.HashAlgorithmName.Name" /> is <see langword="null" /> or an empty string.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">
+          <paramref name="hashAlgorithm" /> is not a known hash algorithm.</exception>
+        <altmember cref="M:System.Security.Cryptography.X509Certificates.X509Certificate.GetCertHash(System.Security.Cryptography.HashAlgorithmName)" />
       </Docs>
     </Member>
   </Members>

xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml

@@ -934,11 +934,26 @@
         <Parameter Name="password" Type="System.String" Index="1" FrameworkAlternate="xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="contentType">To be added.</param>
-        <param name="password">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="contentType">One of the <see cref="T:System.Security.Cryptography.X509Certificates.X509ContentType" /> values that describes how to format the output data.</param>
+        <param name="password">The password required to access the X.509 certificate data.</param>
+        <summary>Exports the current <see cref="T:System.Security.Cryptography.X509Certificates.X509Certificate" /> object to a byte array in a format described by one of the <see cref="T:System.Security.Cryptography.X509Certificates.X509ContentType" /> values, and using the specified password.</summary>
+        <returns>An array of bytes that represents the current <see cref="T:System.Security.Cryptography.X509Certificates.X509Certificate" /> object.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ The `contentType` parameter accepts only the following values of the <xref:System.Security.Cryptography.X509Certificates.X509ContentType> enumeration: <xref:System.Security.Cryptography.X509Certificates.X509ContentType.Cert>, <xref:System.Security.Cryptography.X509Certificates.X509ContentType.SerializedCert>, and <xref:System.Security.Cryptography.X509Certificates.X509ContentType.Pkcs12>.  Passing any other value causes a <xref:System.Security.Cryptography.CryptographicException> to be thrown.  
+  
+> [!IMPORTANT]
+> Never hard code a password within your source code.  Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) tool, a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe.  
+  
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">A value other than <see cref="F:System.Security.Cryptography.X509Certificates.X509ContentType.Cert" />, <see cref="F:System.Security.Cryptography.X509Certificates.X509ContentType.SerializedCert" />, or <see cref="F:System.Security.Cryptography.X509Certificates.X509ContentType.Pkcs12" /> was passed to the <paramref name="contentType" /> parameter.  
+  
+ -or-  
+  
+ The certificate could not be exported.</exception>
       </Docs>
     </Member>
     <Member MemberName="Extensions">