Skip to content

Commit d360cb4

Browse files
bartonjsRon Petrusha
bartonjs
and
Ron Petrusha
committed
Add missing documentation for DSA, and update some existing docs. (#2794)
* Add missing documentation for DSA, and update some existing docs. * (Attempt to) Fix some xrefs * Apply suggestions from code review Co-Authored-By: Ron Petrusha <ronpet@microsoft.com>
1 parent 49a5721 commit d360cb4

File tree

1 file changed

+100
-34
lines changed
  • xml/System.Security.Cryptography

1 file changed

+100
-34
lines changed

‎xml/System.Security.Cryptography/DSA.xml‎

Lines changed: 100 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,14 @@
4141
4242
To use a public-key system to digitally sign a message, the sender first applies a hash function to the message to create a message digest. The sender then encrypts the message digest with the sender's private key to create the sender's personal signature. Upon receiving the message and signature, the receiver decrypts the signature using the sender's public key to recover the message digest and hashes the message using the same hash algorithm that the sender used. If the message digest that the receiver computes exactly matches the message digest received from the sender, the receiver can assume that the message was not altered while in transit. Note that a signature can be verified by anyone, because the sender's public key is common knowledge.
4343
44-
Newer asymmetric algorithms are available. Consider using the <xref:System.Security.Cryptography.RSA> class, the <xref:System.Security.Cryptography.ECDsa> class, or the <xref:System.Security.Cryptography.ECDiffieHellman> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.
45-
46-
This algorithm supports key lengths from 512 bits to 1024 bits in increments of 64 bits.
44+
> [!IMPORTANT]
45+
> Newer asymmetric algorithms are available. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.
4746
47+
Two different versions of the DSA algorithm exist.
48+
The original form, described in FIPS 186-2, requires the use of SHA-1 as the hash algorithm and supports key lengths from 512 bits to 1024 bits in increments of 64 bits.
49+
An updated version of the algorithm was described in FIPS 186-3, which enabled the use of the SHA-2 family of hash algorithms and added support for 2048 bit keys and 3072 bit keys.
50+
Not all derived implementations of this type support the FIPS 186-3 enhancements to DSA. Support can be detected via the <xref:System.Security.Cryptography.AsymmetricAlgorithm.LegalKeySizes> property.
51+
4852
]]></format>
4953
</remarks>
5054
<related type="Article" href="~/docs/standard/security/cryptographic-services.md">Cryptographic Services</related>
@@ -163,7 +167,7 @@
163167
<returns>A new ephemeral DSA key with the specified key size.</returns>
164168
<remarks>To be added.</remarks>
165169
<exception cref="T:System.Security.Cryptography.CryptographicException">
166-
<paramref name="keySizeInBits" /> is different than <see cref="P:System.Security.Cryptography.AsymmetricAlgorithm.KeySize" />.</exception>
170+
<paramref name="keySizeInBits" /> is not permitted by <see cref="P:System.Security.Cryptography.AsymmetricAlgorithm.LegalKeySizes" />.</exception>
167171
</Docs>
168172
</Member>
169173
<Member MemberName="Create">
@@ -845,12 +849,28 @@
845849
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
846850
</Parameters>
847851
<Docs>
848-
<param name="hash">To be added.</param>
849-
<param name="destination">To be added.</param>
850-
<param name="bytesWritten">To be added.</param>
851-
<summary>To be added.</summary>
852-
<returns>To be added.</returns>
853-
<remarks>To be added.</remarks>
852+
<param name="hash">The hash to sign.</param>
853+
<param name="destination">The byte span to receive the signature.</param>
854+
<param name="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramref name="destination"/>.</param>
855+
<summary>Attempts to create the DSA signature for the specified hash into the provided buffer.</summary>
856+
<returns><see langword="true"/> if <paramref name="destination"/> is large enough to receive the result; otherwise, <see langword="false"/>.</returns>
857+
<remarks>
858+
<format type="text/markdown"><![CDATA[
859+
860+
## Remarks
861+
The default implementation of this method is to call <xref:System.Security.Cryptography.DSA.CreateSignature(System.Byte[])> and copy the result to `destination`.
862+
Derived types should override this method to avoid the intermediate array creation.
863+
]]></format>
864+
</remarks>
865+
<exception cref="T:System.Security.Cryptography.CryptographicException">This instance represents only a public key.
866+
867+
-or-
868+
869+
The implementation type only supports legacy DSA (FIPS 186-2), and <paramref name="hash" /> is not a 20-byte value.
870+
871+
-or-
872+
873+
Creating the signature otherwise failed.</exception>
854874
</Docs>
855875
</Member>
856876
<Member MemberName="TryExportEncryptedPkcs8PrivateKey">
@@ -1020,13 +1040,20 @@
10201040
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="3" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
10211041
</Parameters>
10221042
<Docs>
1023-
<param name="data">To be added.</param>
1024-
<param name="destination">To be added.</param>
1025-
<param name="hashAlgorithm">To be added.</param>
1026-
<param name="bytesWritten">To be added.</param>
1027-
<summary>To be added.</summary>
1028-
<returns>To be added.</returns>
1029-
<remarks>To be added.</remarks>
1043+
<param name="data">The data to be hashed.</param>
1044+
<param name="destination">The byte span to receive the hash value.</param>
1045+
<param name="hashAlgorithm">The name of the hash algorithm to use.</param>
1046+
<param name="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramref name="destination"/>.</param>
1047+
<summary>Attempts to compute the hash value of the provided data into a provided buffer.</summary>
1048+
<returns><see langword="true"/> if <paramref name="destination"/> is large enough to receive the result; otherwise, <see langword="false"/>.</returns>
1049+
<remarks>
1050+
<format type="text/markdown"><![CDATA[
1051+
1052+
## Remarks
1053+
The default implementation of this method is to call <xref:System.Security.Cryptography.DSA.HashData(System.Byte[], System.Int32, System.Int32, System.Security.Cryptography.HashAlgorithmName)> and copy the result to `destination`.
1054+
Derived types should override this method to avoid the intermediate array creation.
1055+
]]></format>
1056+
</remarks>
10301057
</Docs>
10311058
</Member>
10321059
<Member MemberName="TrySignData">
@@ -1058,12 +1085,12 @@
10581085
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="3" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
10591086
</Parameters>
10601087
<Docs>
1061-
<param name="data">To be added.</param>
1062-
<param name="destination">To be added.</param>
1063-
<param name="hashAlgorithm">To be added.</param>
1064-
<param name="bytesWritten">To be added.</param>
1065-
<summary>To be added.</summary>
1066-
<returns>To be added.</returns>
1088+
<param name="data">The data to hash and sign.</param>
1089+
<param name="destination">The byte span to receive the signature.</param>
1090+
<param name="hashAlgorithm">The name of the hash algorithm to use.</param>
1091+
<param name="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramref name="destination"/>.</param>
1092+
<summary>Attempts to create the DSA signature for the specified data into the provided buffer.</summary>
1093+
<returns><see langword="true"/> if <paramref name="destination"/> is large enough to receive the result; otherwise, <see langword="false"/>.</returns>
10671094
<remarks>To be added.</remarks>
10681095
</Docs>
10691096
</Member>
@@ -1121,6 +1148,11 @@
11211148
-or-
11221149

11231150
<paramref name="signature" /> is <see langword="null" />.</exception>
1151+
<exception cref="T:System.Security.Cryptography.CryptographicException">The implementation type only supports legacy DSA (FIPS 186-2), and the hash algorithm is not SHA-1.
1152+
1153+
-or-
1154+
1155+
Verifying the signature otherwise failed.</exception>
11241156
<exception cref="T:System.ArgumentException">
11251157
<paramref name="hashAlgorithm" />.<see cref="P:System.Security.Cryptography.HashAlgorithmName.Name" /> is <see langword="null" /> or <see cref="F:System.String.Empty" />.</exception>
11261158
</Docs>
@@ -1171,6 +1203,11 @@
11711203
<paramref name="signature" /> is <see langword="null" />.</exception>
11721204
<exception cref="T:System.ArgumentException">
11731205
<paramref name="hashAlgorithm" />.<see cref="P:System.Security.Cryptography.HashAlgorithmName.Name" /> is <see langword="null" /> or <see cref="F:System.String.Empty" />.</exception>
1206+
<exception cref="T:System.Security.Cryptography.CryptographicException">The implementation type only supports legacy DSA (FIPS 186-2), and the hash algorithm is not SHA-1.
1207+
1208+
-or-
1209+
1210+
Verifying the signature otherwise failed.</exception>
11741211
</Docs>
11751212
</Member>
11761213
<Member MemberName="VerifyData">
@@ -1201,12 +1238,19 @@
12011238
<Parameter Name="hashAlgorithm" Type="System.Security.Cryptography.HashAlgorithmName" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
12021239
</Parameters>
12031240
<Docs>
1204-
<param name="data">To be added.</param>
1205-
<param name="signature">To be added.</param>
1206-
<param name="hashAlgorithm">To be added.</param>
1207-
<summary>To be added.</summary>
1208-
<returns>To be added.</returns>
1241+
<param name="data">The signed data.</param>
1242+
<param name="signature">The signature to be verified.</param>
1243+
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
1244+
<summary>Verifies that a digital signature is valid by calculating the hash value of the data in a byte span using the specified hash algorithm and comparing it to the provided signature.</summary>
1245+
<returns><see langword="true" /> if the digital signature is valid; otherwise, <see langword="false" />.</returns>
12091246
<remarks>To be added.</remarks>
1247+
<exception cref="T:System.ArgumentException">
1248+
<paramref name="hashAlgorithm" />.<see cref="P:System.Security.Cryptography.HashAlgorithmName.Name" /> is <see langword="null" /> or <see cref="F:System.String.Empty" />.</exception>
1249+
<exception cref="T:System.Security.Cryptography.CryptographicException">The implementation type only supports legacy DSA (FIPS 186-2), and the hash algorithm is not SHA-1.
1250+
1251+
-or-
1252+
1253+
Verifying the signature otherwise failed.</exception>
12101254
</Docs>
12111255
</Member>
12121256
<Member MemberName="VerifyData">
@@ -1269,6 +1313,11 @@
12691313
-or-
12701314

12711315
<paramref name="offset" /> + <paramref name="count" /> - 1 results in an index that is beyond the upper bound of <paramref name="data" />.</exception>
1316+
<exception cref="T:System.Security.Cryptography.CryptographicException">The implementation type only supports legacy DSA (FIPS 186-2), and the hash algorithm is not SHA-1.
1317+
1318+
-or-
1319+
1320+
Verifying the signature otherwise failed.</exception>
12721321
</Docs>
12731322
</Member>
12741323
<Member MemberName="VerifySignature">
@@ -1310,6 +1359,11 @@
13101359
<returns>
13111360
<see langword="true" /> if <paramref name="rgbSignature" /> matches the signature computed using the specified hash algorithm and key on <paramref name="rgbHash" />; otherwise, <see langword="false" />.</returns>
13121361
<remarks>To be added.</remarks>
1362+
<exception cref="T:System.Security.Cryptography.CryptographicException">The implementation type only supports legacy DSA (FIPS 186-2), and the hash value is not 20 bytes long.
1363+
1364+
-or-
1365+
1366+
Verifying the signature otherwise failed.</exception>
13131367
<related type="Article" href="~/docs/standard/security/cryptographic-services.md">Cryptographic Services</related>
13141368
</Docs>
13151369
</Member>
@@ -1340,12 +1394,24 @@
13401394
<Parameter Name="signature" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
13411395
</Parameters>
13421396
<Docs>
1343-
<param name="hash">To be added.</param>
1344-
<param name="signature">To be added.</param>
1345-
<summary>To be added.</summary>
1346-
<returns>To be added.</returns>
1347-
<remarks>To be added.</remarks>
1397+
<param name="hash">The data hash to verify.</param>
1398+
<param name="signature">The signature to be verify.</param>
1399+
<summary>Verifies that a digital signature is valid for a provided data hash.</summary>
1400+
<returns><see langword="true" /> if the digital signature is valid for the hash; otherwise, <see langword="false" />.</returns>
1401+
<remarks>
1402+
<format type="text/markdown"><![CDATA[
1403+
1404+
## Remarks
1405+
The default implementation of this method calls <xref:System.Security.Cryptography.DSA.VerifySignature(System.Byte[], System.Byte[])> after copying the spans to arrays.
1406+
Derived types should override this method to avoid the intermediate array creation.
1407+
]]></format>
1408+
</remarks>
1409+
<exception cref="T:System.Security.Cryptography.CryptographicException">The implementation type only supports legacy DSA (FIPS 186-2), and the hash value is not 20 bytes long.
1410+
1411+
-or-
1412+
1413+
Verifying the signature otherwise failed.</exception>
13481414
</Docs>
13491415
</Member>
13501416
</Members>
1351-
</Type>
1417+
</Type>

0 commit comments

Comments
 (0)