Merge pull request #2487 from carlossanlop/security

Port System.Security source comments to Docs

Author: Ron Petrusha

xml/System.Security.Claims/Claim.xml

@@ -40,7 +40,15 @@
         <param name="certificateType">The Object Identifier (OID) for the certificate type.</param>
         <param name="encodedCertificate">The encoded certificate value.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12CertBag" /> class using the specified certificate type and encoding.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+No validation is done to ensure that the `encodedCertificate` value is correct for the indicated `certificateType`.
+
+Note that for X.509 public-key certificates, the correct encoding for a CertBag value is to wrap the DER-encoded certificate in an OCTET STRING.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodedCertificate">
@@ -134,4 +142,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Security.Claims/ClaimsIdentity.xml

@@ -43,7 +43,17 @@
       <Docs>
         <summary>Gets a Signed Cryptographic Message Syntax (CMS) representation of the RFC3161 timestamp token.</summary>
         <returns>The <see cref="T:System.Security.Cryptography.Pkcs.SignedCms" /> representation of the <see cref="T:System.Security.Cryptography.Pkcs.Rfc3161TimestampToken" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+Successive calls to this method return the same object.
+
+The <xref:System.Security.Cryptography.Pkcs.SignedCms> class is mutable, but changes to that object are not reflected in the <xref:System.Security.Cryptography.Pkcs.Rfc3161TimestampToken> object that produced it.
+
+The value from calling <xref:System.Security.Cryptography.Pkcs.SignedCms.Encode?displayProperty=nameWithType> can be interpreted again as an <xref:System.Security.Cryptography.Pkcs.Rfc3161TimestampToken> via another call to <xref:System.Security.Cryptography.Pkcs.Rfc3161TimestampToken.TryDecode(System.ReadOnlyMemory{System.Byte},System.Security.Cryptography.Pkcs.Rfc3161TimestampToken@,System.Int32@)?displayProperty=nameWithType>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="TokenInfo">
@@ -230,4 +240,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Security.Claims/ClaimsPrincipal.xml

@@ -24,8 +24,8 @@
   <Docs>
     <summary>Represents the &lt;<see langword="RSAKeyValue" />&gt; element of an XML signature.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
+      <format type="text/markdown"><![CDATA[
+
 ## Remarks  
  The <xref:System.Security.Cryptography.Xml.RSAKeyValue> class represents the `<RSAKeyValue>` element of an XML signature defined by the XML digital signature specification. The `<RSAKeyValue>` element is the subelement of the `<KeyInfo>` element (represented by the <xref:System.Security.Cryptography.Xml.KeyInfo> class) that describes an <xref:System.Security.Cryptography.RSA> public key. The `<RSAKeyValue>` element contains the public key that corresponds to the private key used to digitally sign a document. A recipient of the document uses the public key to validate the XML signature.  
   
@@ -48,9 +48,9 @@
   
  [!code-cpp[System.Security.Cryptography.XML-XMLDsigDetached#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/CPP/xmldsigdetach.cpp#1)]
  [!code-csharp[System.Security.Cryptography.XML-XMLDsigDetached#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/CS/xmldsigdetach.cs#1)]
- [!code-vb[System.Security.Cryptography.XML-XMLDsigDetached#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb#1)]  
-  
- ]]></format>
+ [!code-vb[System.Security.Cryptography.XML-XMLDsigDetached#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb#1)]
+
+          ]]></format>
     </remarks>
   </Docs>
   <Members>
@@ -86,12 +86,12 @@
       <Docs>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Xml.RSAKeyValue" /> class with a new randomly generated <see cref="T:System.Security.Cryptography.RSA" /> public key.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
+          <format type="text/markdown"><![CDATA[
+
 ## Remarks  
- This constructor creates a new instance of the default implementation of <xref:System.Security.Cryptography.RSA> to hold the public key.  
-  
- ]]></format>
+ This constructor creates a new instance of the default implementation of <xref:System.Security.Cryptography.RSA> to hold the public key.
+
+          ]]></format>
         </remarks>
       </Docs>
     </Member>
@@ -122,8 +122,8 @@
         <param name="key">The instance of an implementation of <see cref="T:System.Security.Cryptography.RSA" /> that holds the public key.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Xml.RSAKeyValue" /> class with the specified <see cref="T:System.Security.Cryptography.RSA" /> public key.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
+          <format type="text/markdown"><![CDATA[
+
 ## Examples  
  The following code example demonstrates how to generate and verify an enveloped XML signature using the <xref:System.Security.Cryptography.Xml.RSAKeyValue> object.  
   
@@ -135,9 +135,9 @@
   
  [!code-cpp[System.Security.Cryptography.XML-XMLDsigDetached#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/CPP/xmldsigdetach.cpp#1)]
  [!code-csharp[System.Security.Cryptography.XML-XMLDsigDetached#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/CS/xmldsigdetach.cs#1)]
- [!code-vb[System.Security.Cryptography.XML-XMLDsigDetached#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb#1)]  
-  
- ]]></format>
+ [!code-vb[System.Security.Cryptography.XML-XMLDsigDetached#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb#1)]
+
+          ]]></format>
         </remarks>
       </Docs>
     </Member>
@@ -168,7 +168,13 @@
       <Docs>
         <summary>Returns the XML representation of the <see cref="T:System.Security.Cryptography.RSA" /> key clause.</summary>
         <returns>The XML representation of the <see cref="T:System.Security.Cryptography.RSA" /> key clause.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+Based upon [The RSAKeyValue Element](https://www.w3.org/TR/2002/REC-xmldsig-core-20020212/#sec-RSAKeyValue) in the W3C Recommendation [XML Signature Syntax and Processing Version 1.0](https://www.w3.org/TR/2002/REC-xmldsig-core-20020212).
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Key">
@@ -198,14 +204,14 @@
         <summary>Gets or sets the instance of <see cref="T:System.Security.Cryptography.RSA" /> that holds the public key.</summary>
         <value>The instance of <see cref="T:System.Security.Cryptography.RSA" /> that holds the public key.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
+          <format type="text/markdown"><![CDATA[
+
 ## Remarks  
  The <xref:System.Security.Cryptography.Xml.RSAKeyValue.Key%2A> property represents the public key to add to an XML digital signature using the `<Modulus>` subelement and the `<Exponent>` subelement of the `<RSAKeyValue>` element.  
   
- For more information about XML digital signatures, see the W3C specification at www.w3.org/TR/xmldsig-core/.  
-  
- ]]></format>
+ For more information about XML digital signatures, see the W3C specification at www.w3.org/TR/xmldsig-core/.
+
+          ]]></format>
         </remarks>
       </Docs>
     </Member>
@@ -238,10 +244,16 @@
       <Docs>
         <param name="value">The XML element from which to load the <see cref="T:System.Security.Cryptography.RSA" /> key clause.</param>
         <summary>Loads an <see cref="T:System.Security.Cryptography.RSA" /> key clause from an XML element.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+Based upon [The RSAKeyValue Element](https://www.w3.org/TR/2002/REC-xmldsig-core-20020212/#sec-RSAKeyValue) in the W3C Recommendation [XML Signature Syntax and Processing Version 1.0](https://www.w3.org/TR/2002/REC-xmldsig-core-20020212).
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">The <paramref name="value" /> parameter is <see langword="null" />.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="value" /> parameter is not a valid <see cref="T:System.Security.Cryptography.RSA" /> key clause XML element.</exception>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>