From ab4ea34d468c889053b732fcff0b5d659cff7dfb Mon Sep 17 00:00:00 2001
From: Jeremy Barton <jbarton@microsoft.com>
Date: Fri, 2 Aug 2019 16:49:56 -0700
Subject: [PATCH 1/3] Document Pkcs12SafeContents

---
 .../Pkcs12SafeContents.xml                    | 236 +++++++++++++-----
 1 file changed, 179 insertions(+), 57 deletions(-)

diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
index 334d9dec6a9..2276dd23b0b 100644
--- a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
+++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
@@ -15,7 +15,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Represents a PKCS#12 SafeContents value. This class cannot be inherited.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -33,7 +33,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents"/> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -57,10 +57,14 @@
         <Parameter Name="certificate" Type="System.Security.Cryptography.X509Certificates.X509Certificate2" />
       </Parameters>
       <Docs>
-        <param name="certificate">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="certificate">The certificate to add.</param>
+        <summary>Adds a certificate to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12CertBag"/> and returns the newly created bag instance.</summary>
+        <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="certificate"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="certificate"/> parameter is in an invalid state.</exception>
+        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
       </Docs>
     </Member>
     <Member MemberName="AddKeyUnencrypted">
@@ -83,10 +87,16 @@
         <Parameter Name="key" Type="System.Security.Cryptography.AsymmetricAlgorithm" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="key">The asymmetric private key to add.</param>
+        <summary>Adds an asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12KeyBag"/> and returns the newly created bag instance.</summary>
+        <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
+        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportPkcs8PrivateKey()" />
       </Docs>
     </Member>
     <Member MemberName="AddNestedContents">
@@ -109,10 +119,22 @@
         <Parameter Name="safeContents" Type="System.Security.Cryptography.Pkcs.Pkcs12SafeContents" />
       </Parameters>
       <Docs>
-        <param name="safeContents">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="safeContents">The nested contents to add to the SafeContents.</param>
+        <summary>Adds a nested SafeContents to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12SafeContentsBag"/> and returns the newly created bag instance.</summary>
+        <returns>The bag instance which was added to the SafeContents.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+
+ This method processes the contents of the `safeContents` parameter into a new read-only instance.
+ Any modifications to the value passed as the `safeContents` parameter after this method is called will have no effect on this instance.
+  
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="safeContents"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.ArgumentException">The <paramref name="safeContents"/> parameter is encrypted.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
       </Docs>
     </Member>
     <Member MemberName="AddSafeBag">
@@ -135,9 +157,18 @@
         <Parameter Name="safeBag" Type="System.Security.Cryptography.Pkcs.Pkcs12SafeBag" />
       </Parameters>
       <Docs>
-        <param name="safeBag">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="safeBag">The SafeBag value to add.</param>
+        <summary>Adds a SafeBag to the SafeContents.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ Unlike the other methods that add a SafeBag to the SafeContents, this method adds the bag "live" and further modifications to the input parameter are reflected in the final encoded output.
+  
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="safeBag"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
       </Docs>
     </Member>
     <Member MemberName="AddSecret">
@@ -163,9 +194,12 @@
       <Docs>
         <param name="secretType">To be added.</param>
         <param name="secretValue">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Adds an ASN.1 BER-encoded value with a specified type identifier to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12SecretBag"/> and returns the newly created bag instance.</summary>
+        <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="secretType"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="secretValue"/> parameter does not represent a single ASN.1 BER-encoded value.</exception>
       </Docs>
     </Member>
     <Member MemberName="AddShroudedKey">
@@ -189,12 +223,18 @@
         <Parameter Name="pbeParameters" Type="System.Security.Cryptography.PbeParameters" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="passwordBytes">To be added.</param>
-        <param name="pbeParameters">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="key">The asymmetric private key to add.</param>
+        <param name="passwordBytes">The bytes to use as a password when encrypting the key material.</param>
+        <param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
+        <summary>Adds an encrypted asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from a byte-based password in an array and returns the newly created bag instance.</summary>
+        <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
+        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey(System.ReadOnlySpan{System.Byte}, System.Security.Cryptography.PbeParameters)" />
       </Docs>
     </Member>
     <Member MemberName="AddShroudedKey">
@@ -218,12 +258,18 @@
         <Parameter Name="pbeParameters" Type="System.Security.Cryptography.PbeParameters" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="passwordBytes">To be added.</param>
-        <param name="pbeParameters">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="key">The asymmetric private key to add.</param>
+        <param name="passwordBytes">The bytes to use as a password when encrypting the key material.</param>
+        <param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
+        <summary>Adds an encrypted asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from a byte-based password in a span and returns the newly created bag instance.</summary>
+        <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
+        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey(System.ReadOnlySpan{System.Byte}, System.Security.Cryptography.PbeParameters)" />
       </Docs>
     </Member>
     <Member MemberName="AddShroudedKey">
@@ -247,12 +293,18 @@
         <Parameter Name="pbeParameters" Type="System.Security.Cryptography.PbeParameters" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="password">To be added.</param>
-        <param name="pbeParameters">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="key">The asymmetric private key to add.</param>
+        <param name="password">The password to use when encrypting the key material.</param>
+        <param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
+        <summary>Adds an encrypted asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from a char-based password in a span and returns the newly created bag instance.</summary>
+        <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
+        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey(System.ReadOnlySpan{System.Char}, System.Security.Cryptography.PbeParameters)" />
       </Docs>
     </Member>
     <Member MemberName="AddShroudedKey">
@@ -276,12 +328,18 @@
         <Parameter Name="pbeParameters" Type="System.Security.Cryptography.PbeParameters" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="password">To be added.</param>
-        <param name="pbeParameters">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="key">The asymmetric private key to add.</param>
+        <param name="password">The password to use when encrypting the key material.</param>
+        <param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
+        <summary>Adds an encrypted asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from a char-based password in a string and returns the newly created bag instance.</summary>
+        <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
+        <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
+        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey(System.ReadOnlySpan{System.Char}, System.Security.Cryptography.PbeParameters)" />
       </Docs>
     </Member>
     <Member MemberName="ConfidentialityMode">
@@ -301,8 +359,8 @@
         <ReturnType>System.Security.Cryptography.Pkcs.Pkcs12ConfidentialityMode</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets a value that indicates the type of encryption applied to the contents.</summary>
+        <value>One of the enumeration values that indicates the type of encryption applied to the contents. The default value is <see cref="F:System.Security.Cryptography.Pkcs.Pkcs12ConfidentialityMode.None"/>.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -326,9 +384,23 @@
         <Parameter Name="passwordBytes" Type="System.Byte[]" />
       </Parameters>
       <Docs>
-        <param name="passwordBytes">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="passwordBytes">The bytes to use as a password for decrypting the encrypted contents.</param>
+        <summary>Decrypts the contents of this SafeContents value using a byte-based password from an array.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by the encrypted contents.
+ This enables compatibility with other systems which use a text encoding other than UTF-8 when processing passwords with PBKDF2 (Password-Based Key Derivation Function 2).
+
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.InvalidOperationException">The <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.ConfidentialityMode"/> property is not <see cref="F:System.Security.Cryptography.Pkcs.Pkcs12ConfidentialityMode.Password"/>.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
+
+-or-
+
+The contents were not successfully decrypted.</exception>
       </Docs>
     </Member>
     <Member MemberName="Decrypt">
@@ -351,9 +423,23 @@
         <Parameter Name="passwordBytes" Type="System.ReadOnlySpan&lt;System.Byte&gt;" />
       </Parameters>
       <Docs>
-        <param name="passwordBytes">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="passwordBytes">The bytes to use as a password for decrypting the encrypted contents.</param>
+        <summary>Decrypts the contents of this SafeContents value using a byte-based password from a span.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by the encrypted contents.
+ This enables compatibility with other systems which use a text encoding other than UTF-8 when processing passwords with PBKDF2 (Password-Based Key Derivation Function 2).
+
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.InvalidOperationException">The <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.ConfidentialityMode"/> property is not <see cref="F:System.Security.Cryptography.Pkcs.Pkcs12ConfidentialityMode.Password"/>.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
+
+-or-
+
+The contents were not successfully decrypted.</exception>
       </Docs>
     </Member>
     <Member MemberName="Decrypt">
@@ -376,9 +462,22 @@
         <Parameter Name="password" Type="System.ReadOnlySpan&lt;System.Char&gt;" />
       </Parameters>
       <Docs>
-        <param name="password">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="password">The password to use for decrypting the encrypted contents.</param>
+        <summary>Decrypts the contents of this SafeContents value using a char-based password from a span.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ When the encrypted contents indicate an algorithm that uses PBKDF1 (Password-Based Key Derivation Function 1) or PBKDF2 (Password-Based Key Derivation Function 2), the password is converted to bytes via the UTF-8 encoding.
+
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.InvalidOperationException">The <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.ConfidentialityMode"/> property is not <see cref="F:System.Security.Cryptography.Pkcs.Pkcs12ConfidentialityMode.Password"/>.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
+
+-or-
+
+The contents were not successfully decrypted.</exception>
       </Docs>
     </Member>
     <Member MemberName="Decrypt">
@@ -401,9 +500,22 @@
         <Parameter Name="password" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="password">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="password">The password to use for decrypting the encrypted contents.</param>
+        <summary>Decrypts the contents of this SafeContents value using a char-based password from a string.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ When the encrypted contents indicate an algorithm that uses PBKDF1 (Password-Based Key Derivation Function 1) or PBKDF2 (Password-Based Key Derivation Function 2), the password is converted to bytes via the UTF-8 encoding.
+
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.InvalidOperationException">The <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.ConfidentialityMode"/> property is not <see cref="F:System.Security.Cryptography.Pkcs.Pkcs12ConfidentialityMode.Password"/>.</exception>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
+
+-or-
+
+The contents were not successfully decrypted.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetBags">
@@ -424,9 +536,11 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Gets an enumerable representation of the SafeBag values contained within the SafeContents.</summary>
+        <returns>An enumerable representation of the SafeBag values contained within the SafeContents.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperatinException">The contents are encrypted.</exception>
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.ConfidentialityMode"/>
       </Docs>
     </Member>
     <Member MemberName="IsReadOnly">
@@ -446,10 +560,18 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets a value that indicates whether this instance in a read-only state.</summary>
+        <value><see langword="true"/> if this value is in a read-only state; otherwise, <see langword="false"/>. The default value is <see langword="false"/>.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+
+A <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeContents> is read-only when the value is created to represent previously encoded values, such as from <xref:System.Security.Cryptography.Pkcs.Pkcs12Info.Decode%2A> or the encoding operation internal to <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddNestedContents%2A>.
+
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
\ No newline at end of file
+</Type>

From db4ff18ef99b0ccc68709c9f717d4c7492b41848 Mon Sep 17 00:00:00 2001
From: Jeremy Barton <jbarton@microsoft.com>
Date: Fri, 2 Aug 2019 17:54:22 -0700
Subject: [PATCH 2/3] Fix bad namespace references

---
 .../Pkcs12SafeContents.xml                    | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
index 2276dd23b0b..81c44652c11 100644
--- a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
+++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
@@ -33,7 +33,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents"/> class.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12SafeContents"/> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -64,7 +64,7 @@
         <exception cref="T:System.ArgumentNullException">The <paramref name="certificate"/> parameter is <see langword="null"/>.</exception>
         <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="certificate"/> parameter is in an invalid state.</exception>
-        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.IsReadOnly" />
       </Docs>
     </Member>
     <Member MemberName="AddKeyUnencrypted">
@@ -94,8 +94,8 @@
         <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
         <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
-        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
-        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddShroudedKey" />
         <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportPkcs8PrivateKey()" />
       </Docs>
     </Member>
@@ -232,8 +232,8 @@
         <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
         <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
-        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
-        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddShroudedKey" />
         <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey(System.ReadOnlySpan{System.Byte}, System.Security.Cryptography.PbeParameters)" />
       </Docs>
     </Member>
@@ -267,8 +267,8 @@
         <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
         <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
-        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
-        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddShroudedKey" />
         <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey(System.ReadOnlySpan{System.Byte}, System.Security.Cryptography.PbeParameters)" />
       </Docs>
     </Member>
@@ -302,8 +302,8 @@
         <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
         <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
-        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
-        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddShroudedKey" />
         <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey(System.ReadOnlySpan{System.Char}, System.Security.Cryptography.PbeParameters)" />
       </Docs>
     </Member>
@@ -337,8 +337,8 @@
         <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
         <exception cref="T:System.InvalidOperationException">This instance is read-only.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key export failed.</exception>
-        <altmember cref="P:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.IsReadOnly" />
-        <altmember cref="Overload:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.AddShroudedKey" />
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.IsReadOnly" />
+        <altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddShroudedKey" />
         <altmember cref="M:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey(System.ReadOnlySpan{System.Char}, System.Security.Cryptography.PbeParameters)" />
       </Docs>
     </Member>

From 5c13f9d6bcfe729245356cd0d3aca721ae72e6c9 Mon Sep 17 00:00:00 2001
From: Jeremy Barton <jbarton@microsoft.com>
Date: Mon, 5 Aug 2019 08:53:56 -0700
Subject: [PATCH 3/3] Apply suggestions from code review

Co-Authored-By: Ron Petrusha <ronpet@microsoft.com>
---
 .../Pkcs12SafeContents.xml                         | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
index 81c44652c11..e3f5e7eb7cb 100644
--- a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
+++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml
@@ -192,8 +192,8 @@
         <Parameter Name="secretValue" Type="System.ReadOnlyMemory&lt;System.Byte&gt;" />
       </Parameters>
       <Docs>
-        <param name="secretType">To be added.</param>
-        <param name="secretValue">To be added.</param>
+         <param name="secretType">The Object Identifier (OID) which identifies the data type of the secret value.</param>
+         <param name="secretValue">The BER-encoded value representing the secret to add.</param>
         <summary>Adds an ASN.1 BER-encoded value with a specified type identifier to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12SecretBag"/> and returns the newly created bag instance.</summary>
         <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
@@ -296,7 +296,7 @@
         <param name="key">The asymmetric private key to add.</param>
         <param name="password">The password to use when encrypting the key material.</param>
         <param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
-        <summary>Adds an encrypted asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from a char-based password in a span and returns the newly created bag instance.</summary>
+        <summary>Adds an encrypted asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from a character-based password in a span and returns the newly created bag instance.</summary>
         <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
@@ -331,7 +331,7 @@
         <param name="key">The asymmetric private key to add.</param>
         <param name="password">The password to use when encrypting the key material.</param>
         <param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
-        <summary>Adds an encrypted asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from a char-based password in a string and returns the newly created bag instance.</summary>
+        <summary>Adds an encrypted asymmetric private key to the SafeContents via a new <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from a character-based password in a string and returns the newly created bag instance.</summary>
         <returns>The bag instance which was added to the SafeContents.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">The <paramref name="key"/> parameter is <see langword="null"/>.</exception>
@@ -463,7 +463,7 @@ The contents were not successfully decrypted.</exception>
       </Parameters>
       <Docs>
         <param name="password">The password to use for decrypting the encrypted contents.</param>
-        <summary>Decrypts the contents of this SafeContents value using a char-based password from a span.</summary>
+        <summary>Decrypts the contents of this SafeContents value using a character-based password from a span.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
@@ -501,7 +501,7 @@ The contents were not successfully decrypted.</exception>
       </Parameters>
       <Docs>
         <param name="password">The password to use for decrypting the encrypted contents.</param>
-        <summary>Decrypts the contents of this SafeContents value using a char-based password from a string.</summary>
+        <summary>Decrypts the contents of this SafeContents value using a character-based password from a string.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
@@ -539,7 +539,7 @@ The contents were not successfully decrypted.</exception>
         <summary>Gets an enumerable representation of the SafeBag values contained within the SafeContents.</summary>
         <returns>An enumerable representation of the SafeBag values contained within the SafeContents.</returns>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.InvalidOperatinException">The contents are encrypted.</exception>
+        <exception cref="T:System.InvalidOperationException">The contents are encrypted.</exception>
         <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.ConfidentialityMode"/>
       </Docs>
     </Member>