Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit da3b415

Browse files
bartonjscarlossanlop
bartonjs
authored and
carlossanlop
committed
Add missing documentation for SymmetricAlgorithm types (dotnet#3469)
* Add missing documentation for SymmetricAlgorithm types * Add missing closing tags * Add more missing closing tags
1 parent d2e9568 commit da3b415

File tree

7 files changed

+270
-81
lines changed

7 files changed

+270
-81
lines changed

‎xml/System.Security.Cryptography/Aes.xml

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -228,9 +228,15 @@
228228
<ReturnType>System.Security.Cryptography.KeySizes[]</ReturnType>
229229
</ReturnValue>
230230
<Docs>
231-
<summary>To be added.</summary>
232-
<value>To be added.</value>
233-
<remarks>To be added.</remarks>
231+
<summary>Gets the block sizes, in bits, that are supported by the symmetric algorithm.</summary>
232+
<value>An array that contains the block sizes supported by the algorithm.</value>
233+
<remarks>
234+
<format type="text/markdown"><![CDATA[
235+
236+
## Remarks
237+
For AES, the only legal block size is 128 bits.
238+
]]></format>
239+
</remarks>
234240
</Docs>
235241
</Member>
236242
<Member MemberName="LegalKeySizes">
@@ -260,9 +266,15 @@
260266
<ReturnType>System.Security.Cryptography.KeySizes[]</ReturnType>
261267
</ReturnValue>
262268
<Docs>
263-
<summary>To be added.</summary>
264-
<value>To be added.</value>
265-
<remarks>To be added.</remarks>
269+
<summary>Gets the key sizes, in bits, that are supported by the symmetric algorithm.</summary>
270+
<value>An array that contains the key sizes supported by the algorithm.</value>
271+
<remarks>
272+
<format type="text/markdown"><![CDATA[
273+
274+
## Remarks
275+
For AES, the legal key sizes are 128, 192, and 256 bits.
276+
]]></format>
277+
</remarks>
266278
</Docs>
267279
</Member>
268280
</Members>

‎xml/System.Security.Cryptography/AesCryptoServiceProvider.xml

Lines changed: 73 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -105,9 +105,17 @@
105105
<ReturnType>System.Int32</ReturnType>
106106
</ReturnValue>
107107
<Docs>
108-
<summary>To be added.</summary>
109-
<value>To be added.</value>
110-
<remarks>To be added.</remarks>
108+
<summary>Gets or sets the block size, in bits, of the cryptographic operation.</summary>
109+
<value>The block size, in bits.</value>
110+
<remarks>
111+
<format type="text/markdown"><![CDATA[
112+
113+
## Remarks
114+
The block size is the basic unit of data that can be encrypted or decrypted in one operation. Messages longer than the block size are handled as successive blocks; messages shorter than the block size must be padded with extra bits to reach the size of a block. Valid block sizes are determined by the symmetric algorithm used.
115+
116+
]]></format>
117+
</remarks>
118+
<exception cref="T:System.Security.Cryptography.CryptographicException">The block size is invalid.</exception>
111119
</Docs>
112120
</Member>
113121
<MemberGroup MemberName="CreateDecryptor">
@@ -400,8 +408,9 @@
400408
<Parameter Name="disposing" Type="System.Boolean" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinmac-3.0" />
401409
</Parameters>
402410
<Docs>
403-
<param name="disposing">To be added.</param>
404-
<summary>To be added.</summary>
411+
<param name="disposing">
412+
<see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
413+
<summary>Releases the unmanaged resources used by the <see cref="T:System.Security.Cryptography.AesCryptoServiceProvider" /> and optionally releases the managed resources.</summary>
405414
<remarks>To be added.</remarks>
406415
</Docs>
407416
</Member>
@@ -431,9 +440,10 @@
431440
<ReturnType>System.Int32</ReturnType>
432441
</ReturnValue>
433442
<Docs>
434-
<summary>To be added.</summary>
435-
<value>To be added.</value>
443+
<summary>Gets or sets the feedback size, in bits, of the cryptographic operation for the Cipher Feedback (CFB) and Output Feedback (OFB) cipher modes.</summary>
444+
<value>The feedback size in bits.</value>
436445
<remarks>To be added.</remarks>
446+
<exception cref="T:System.Security.Cryptography.CryptographicException">The feedback size is larger than the block size.</exception>
437447
</Docs>
438448
</Member>
439449
<Member MemberName="GenerateIV">
@@ -546,9 +556,22 @@
546556
<ReturnType>System.Byte[]</ReturnType>
547557
</ReturnValue>
548558
<Docs>
549-
<summary>To be added.</summary>
550-
<value>To be added.</value>
551-
<remarks>To be added.</remarks>
559+
<summary>Gets or sets the initialization vector (<see cref="P:System.Security.Cryptography.SymmetricAlgorithm.IV" />) for the symmetric algorithm.</summary>
560+
<value>The initialization vector.</value>
561+
<remarks>
562+
<format type="text/markdown"><![CDATA[
563+
564+
## Remarks
565+
The <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property is automatically set to a new random value whenever you create a new instance of one of the <xref:System.Security.Cryptography.SymmetricAlgorithm> classes or when you manually call the <xref:System.Security.Cryptography.SymmetricAlgorithm.GenerateIV%2A> method. The size of the <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property must be the same as the <xref:System.Security.Cryptography.SymmetricAlgorithm.BlockSize%2A> property divided by 8.
566+
567+
The classes that derive from the <xref:System.Security.Cryptography.SymmetricAlgorithm> class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the <xref:System.Security.Cryptography.SymmetricAlgorithm> classes, you must set the <xref:System.Security.Cryptography.SymmetricAlgorithm.Key%2A> property and <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property to the same values that were used for encryption.
568+
569+
For a given secret key *k*, a simple block cipher that does not use an initialization vector will encrypt the same input block of plain text into the same output block of cipher text. If you have duplicate blocks within your plain text stream, you will have duplicate blocks within your cipher text stream. If unauthorized users know anything about the structure of a block of your plain text, they can use that information to decipher the known cipher text block and possibly recover your key. To combat this problem, information from the previous block is mixed into the process of encrypting the next block. Thus, the output of two identical plain text blocks is different. Because this technique uses the previous block to encrypt the next block, an initialization vector is needed to encrypt the first block of data.
570+
571+
]]></format>
572+
</remarks>
573+
<exception cref="T:System.ArgumentNullException">An attempt was made to set the initialization vector to <see langword="null" />.</exception>
574+
<exception cref="T:System.Security.Cryptography.CryptographicException">An attempt was made to set the initialization vector to an invalid size.</exception>
552575
</Docs>
553576
</Member>
554577
<Member MemberName="Key">
@@ -674,9 +697,15 @@
674697
<ReturnType>System.Security.Cryptography.KeySizes[]</ReturnType>
675698
</ReturnValue>
676699
<Docs>
677-
<summary>To be added.</summary>
678-
<value>To be added.</value>
679-
<remarks>To be added.</remarks>
700+
<summary>Gets the block sizes, in bits, that are supported by the symmetric algorithm.</summary>
701+
<value>An array that contains the block sizes supported by the algorithm.</value>
702+
<remarks>
703+
<format type="text/markdown"><![CDATA[
704+
705+
## Remarks
706+
For AES, the only legal block size is 128 bits.
707+
]]></format>
708+
</remarks>
680709
</Docs>
681710
</Member>
682711
<Member MemberName="LegalKeySizes">
@@ -703,9 +732,15 @@
703732
<ReturnType>System.Security.Cryptography.KeySizes[]</ReturnType>
704733
</ReturnValue>
705734
<Docs>
706-
<summary>To be added.</summary>
707-
<value>To be added.</value>
708-
<remarks>To be added.</remarks>
735+
<summary>Gets the key sizes, in bits, that are supported by the symmetric algorithm.</summary>
736+
<value>An array that contains the key sizes supported by the algorithm.</value>
737+
<remarks>
738+
<format type="text/markdown"><![CDATA[
739+
740+
## Remarks
741+
For AES, the legal key sizes are 128, 192, and 256 bits.
742+
]]></format>
743+
</remarks>
709744
</Docs>
710745
</Member>
711746
<Member MemberName="Mode">
@@ -734,9 +769,17 @@
734769
<ReturnType>System.Security.Cryptography.CipherMode</ReturnType>
735770
</ReturnValue>
736771
<Docs>
737-
<summary>To be added.</summary>
738-
<value>To be added.</value>
739-
<remarks>To be added.</remarks>
772+
<summary>Gets or sets the mode for operation of the symmetric algorithm.</summary>
773+
<value>The mode for operation of the symmetric algorithm. The default is <see cref="F:System.Security.Cryptography.CipherMode.CBC" />.</value>
774+
<remarks>
775+
<format type="text/markdown"><![CDATA[
776+
777+
## Remarks
778+
See <xref:System.Security.Cryptography.CipherMode> enumeration for a description of specific modes.
779+
780+
]]></format>
781+
</remarks>
782+
<exception cref="T:System.Security.Cryptography.CryptographicException">The cipher mode is not one of the <see cref="T:System.Security.Cryptography.CipherMode" /> values.</exception>
740783
</Docs>
741784
</Member>
742785
<Member MemberName="Padding">
@@ -765,9 +808,17 @@
765808
<ReturnType>System.Security.Cryptography.PaddingMode</ReturnType>
766809
</ReturnValue>
767810
<Docs>
768-
<summary>To be added.</summary>
769-
<value>To be added.</value>
770-
<remarks>To be added.</remarks>
811+
<summary>Gets or sets the padding mode used in the symmetric algorithm.</summary>
812+
<value>The padding mode used in the symmetric algorithm. The default is <see cref="F:System.Security.Cryptography.PaddingMode.PKCS7" />.</value>
813+
<remarks>
814+
<format type="text/markdown"><![CDATA[
815+
816+
## Remarks
817+
Most plain text messages do not consist of a number of bytes that completely fill blocks. Often, there are not enough bytes to fill the last block. When this happens, a padding string is added to the text. For example, if the block length is 64 bits and the last block contains only 40 bits, 24 bits of padding are added. See the <xref:System.Security.Cryptography.PaddingMode> enumeration for a description of specific modes.
818+
819+
]]></format>
820+
</remarks>
821+
<exception cref="T:System.Security.Cryptography.CryptographicException">The padding mode is not one of the <see cref="T:System.Security.Cryptography.PaddingMode" /> values.</exception>
771822
</Docs>
772823
</Member>
773824
</Members>

‎xml/System.Security.Cryptography/DESCryptoServiceProvider.xml

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -133,9 +133,16 @@
133133
</ReturnValue>
134134
<Parameters />
135135
<Docs>
136-
<summary>To be added.</summary>
137-
<returns>To be added.</returns>
138-
<remarks>To be added.</remarks>
136+
<summary>Creates a symmetric decryptor object with the current <see cref="P:System.Security.Cryptography.SymmetricAlgorithm.Key" /> property and initialization vector (<see cref="P:System.Security.Cryptography.SymmetricAlgorithm.IV" />).</summary>
137+
<returns>A symmetric decryptor object.</returns>
138+
<remarks>
139+
<format type="text/markdown"><![CDATA[
140+
141+
## Remarks
142+
This method decrypts an encrypted message created using the <xref:System.Security.Cryptography.SymmetricAlgorithm.CreateEncryptor%2A> overload with the same signature.
143+
144+
]]></format>
145+
</remarks>
139146
</Docs>
140147
</Member>
141148
<Member MemberName="CreateDecryptor">
@@ -238,9 +245,18 @@
238245
</ReturnValue>
239246
<Parameters />
240247
<Docs>
241-
<summary>To be added.</summary>
242-
<returns>To be added.</returns>
243-
<remarks>To be added.</remarks>
248+
<summary>Creates a symmetric encryptor object with the current <see cref="P:System.Security.Cryptography.SymmetricAlgorithm.Key" /> property and initialization vector (<see cref="P:System.Security.Cryptography.SymmetricAlgorithm.IV" />).</summary>
249+
<returns>A symmetric encryptor object.</returns>
250+
<remarks>
251+
<format type="text/markdown"><![CDATA[
252+
253+
## Remarks
254+
If the current <xref:System.Security.Cryptography.SymmetricAlgorithm.Key%2A> property is `null`, the <xref:System.Security.Cryptography.SymmetricAlgorithm.GenerateKey%2A> method is called to create a new random <xref:System.Security.Cryptography.SymmetricAlgorithm.Key%2A>. If the current <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property is `null`, the <xref:System.Security.Cryptography.SymmetricAlgorithm.GenerateIV%2A> method is called to create a new random <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A>.
255+
256+
Use the <xref:System.Security.Cryptography.SymmetricAlgorithm.CreateDecryptor%2A> overload with the same signature to decrypt the result of this method.
257+
258+
]]></format>
259+
</remarks>
244260
</Docs>
245261
</Member>
246262
<Member MemberName="CreateEncryptor">

‎xml/System.Security.Cryptography/RijndaelManaged.xml

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -171,9 +171,16 @@
171171
</ReturnValue>
172172
<Parameters />
173173
<Docs>
174-
<summary>To be added.</summary>
175-
<returns>To be added.</returns>
176-
<remarks>To be added.</remarks>
174+
<summary>Creates a symmetric decryptor object with the current <see cref="P:System.Security.Cryptography.SymmetricAlgorithm.Key" /> property and initialization vector (<see cref="P:System.Security.Cryptography.SymmetricAlgorithm.IV" />).</summary>
175+
<returns>A symmetric decryptor object.</returns>
176+
<remarks>
177+
<format type="text/markdown"><![CDATA[
178+
179+
## Remarks
180+
This method decrypts an encrypted message created using the <xref:System.Security.Cryptography.SymmetricAlgorithm.CreateEncryptor%2A> overload with the same signature.
181+
182+
]]></format>
183+
</remarks>
177184
</Docs>
178185
</Member>
179186
<Member MemberName="CreateDecryptor">
@@ -266,9 +273,17 @@
266273
</ReturnValue>
267274
<Parameters />
268275
<Docs>
269-
<summary>To be added.</summary>
270-
<returns>To be added.</returns>
271-
<remarks>To be added.</remarks>
276+
<summary>Creates a symmetric encryptor object with the current <see cref="P:System.Security.Cryptography.SymmetricAlgorithm.Key" /> property and initialization vector (<see cref="P:System.Security.Cryptography.SymmetricAlgorithm.IV" />).</summary>
277+
<returns>A symmetric encryptor object.</returns>
278+
<remarks>
279+
<format type="text/markdown"><![CDATA[
280+
281+
## Remarks
282+
If the current <xref:System.Security.Cryptography.SymmetricAlgorithm.Key%2A> property is `null`, the <xref:System.Security.Cryptography.SymmetricAlgorithm.GenerateKey%2A> method is called to create a new random <xref:System.Security.Cryptography.SymmetricAlgorithm.Key%2A>. If the current <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property is `null`, the <xref:System.Security.Cryptography.SymmetricAlgorithm.GenerateIV%2A> method is called to create a new random <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A>.
283+
284+
Use the <xref:System.Security.Cryptography.SymmetricAlgorithm.CreateDecryptor%2A> overload with the same signature to decrypt the result of this method.
285+
]]></format>
286+
</remarks>
272287
</Docs>
273288
</Member>
274289
<Member MemberName="CreateEncryptor">

‎xml/System.Security.Cryptography/SymmetricAlgorithm.xml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -713,7 +713,7 @@
713713
<ReturnType>System.Int32</ReturnType>
714714
</ReturnValue>
715715
<Docs>
716-
<summary>Gets or sets the feedback size, in bits, of the cryptographic operation.</summary>
716+
<summary>Gets or sets the feedback size, in bits, of the cryptographic operation for the Cipher Feedback (CFB) and Output Feedback (OFB) cipher modes.</summary>
717717
<value>The feedback size in bits.</value>
718718
<remarks>
719719
<format type="text/markdown"><![CDATA[
@@ -1060,6 +1060,8 @@ Allows an <see cref="T:System.Object" /> to attempt to free resources and perfor
10601060
10611061
## Remarks
10621062
The valid key sizes are specified by the particular symmetric algorithm implementation and are listed in the <xref:System.Security.Cryptography.SymmetricAlgorithm.LegalKeySizes%2A> property.
1063+
1064+
Changing the `KeySize` value resets the key and generates a new random key. This happens whenever the `KeySize` property setter is invoked (including when it's assigned the same value).
10631065
10641066
]]></format>
10651067
</remarks>

‎xml/System.Security.Cryptography/TripleDES.xml

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -384,9 +384,15 @@
384384
<ReturnType>System.Security.Cryptography.KeySizes[]</ReturnType>
385385
</ReturnValue>
386386
<Docs>
387-
<summary>To be added.</summary>
388-
<value>To be added.</value>
389-
<remarks>To be added.</remarks>
387+
<summary>Gets the block sizes, in bits, that are supported by the symmetric algorithm.</summary>
388+
<value>An array that contains the block sizes supported by the algorithm.</value>
389+
<remarks>
390+
<format type="text/markdown"><![CDATA[
391+
392+
## Remarks
393+
For TripleDES, the only legal block size is 64 bits.
394+
]]></format>
395+
</remarks>
390396
</Docs>
391397
</Member>
392398
<Member MemberName="LegalKeySizes">
@@ -414,9 +420,15 @@
414420
<ReturnType>System.Security.Cryptography.KeySizes[]</ReturnType>
415421
</ReturnValue>
416422
<Docs>
417-
<summary>To be added.</summary>
418-
<value>To be added.</value>
419-
<remarks>To be added.</remarks>
423+
<summary>Gets the key sizes, in bits, that are supported by the symmetric algorithm.</summary>
424+
<value>An array that contains the key sizes supported by the algorithm.</value>
425+
<remarks>
426+
<format type="text/markdown"><![CDATA[
427+
428+
## Remarks
429+
For TripleDES, the legal key sizes are 128 and 192 bits.
430+
]]></format>
431+
</remarks>
420432
</Docs>
421433
</Member>
422434
</Members>

0 commit comments

Comments
 (0)