8000 Add missing, and update existing, ECDsa API documentation (#3564) · CAndRyan/dotnet-api-docs@a70f832 · GitHub
[go: up one dir, main page]
Skip to content

Commit a70f832

Browse files
bartonjscarlossanlop
bartonjs
authored and
carlossanlop
committed
Add missing, and update existing, ECDsa API documentation (dotnet#3564)
* Add missing, and update existing, ECDsa API documentation * Address feedback * Fix another warning
1 parent 3c03165 commit a70f832

File tree

3 files changed

+307
-140
lines changed

3 files changed

+307
-140
lines changed

‎xml/System.Security.Cryptography/ECDsa.xml

Lines changed: 52 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -461,8 +461,8 @@
461461
<Parameter Name="curve" Type="System.Security.Cryptography.ECCurve" Index="0" FrameworkAlternate="netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8" />
462462
</Parameters>
463463
<Docs>
464-
<param name="curve">The curve to use.</param>
465-
<summary>When overridden in a derived class, generates a new public/private key pair for the specified curve.</summary>
464+
<param name="curve">The curve to use to generate the key.</param>
465+
<summary>When overridden in a derived class, generates a new ephemeral public/private key pair for the specified curve, replacing the current key.</summary>
466466
<remarks>To be added.</remarks>
467467
<exception cref="T:System.NotSupportedException">A derived class must override this method.</exception>
468468
</Docs>
@@ -1158,7 +1158,7 @@ The algorithm-specific key import failed.
11581158
<Docs>
11591159
<param name="hash">The hash value of the data that is being signed.</param>
11601160
<summary>Generates a digital signature for the specified hash value.</summary>
1161-
<returns>A digital signature that consists of the given hash value encrypted with the private key.</returns>
1161+
<returns>A digital signature for the specified hash value.</returns>
11621162
<remarks>To be added.</remarks>
11631163
<exception cref="T:System.ArgumentNullException">The <paramref name="hash" /> parameter is <see langword="null" />.</exception>
11641164
</Docs>
@@ -1432,13 +1432,22 @@ The algorithm-specific key import failed.
14321432
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="3" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
14331433
</Parameters>
14341434
<Docs>
1435-
<param name="data">To be added.</param>
1436-
<param name="destination">To be added.</param>
1437-
<param name="hashAlgorithm">To be added.</param>
1438-
<param name="bytesWritten">To be added.</param>
1439-
<summary>To be added.</summary>
1440-
<returns>To be added.</returns>
1441-
<remarks>To be added.</remarks>
1435+
<param name="data">The data to be hashed.</param>
1436+
<param name="destination">The buffer to receive the hash value.</param>
1437+
<param name="hashAlgorithm">The algorithm to use to hash the data.</param>
1438+
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
1439+
<summary>Attempts to compute the hash value of the specified read-only span of bytes into the provided destination by using the specified hashing algorithm.</summary>
1440+
<returns><see langword="false"/> if <paramref name="destination"/> is not long enough to receive the hash value.</returns>
1441+
<remarks>
1442+
<format type="text/markdown"><![CDATA[
1443+
1444+
## Remarks
1445+
1446+
The default implementation of this method is to call <xref:System.Security.Cryptography.ECDsa.HashData(System.Byte[],System.Int32,System.Int32,System.Security.Cryptography.HashAlgorithmName)> and copy the result to `destination`.
1447+
Derived types should override this method to avoid the intermediate array creation.
1448+
1449+
]]></format>
1450+
</remarks>
14421451
</Docs>
14431452
</Member>
14441453
<Member MemberName="TrySignData">
@@ -1470,12 +1479,12 @@ The algorithm-specific key import failed.
14701479
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="3" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
14711480
</Parameters>
14721481
<Docs>
1473-
<param name="data">To be added.</param>
1474-
<param name="destination">To be added.</param>
1475-
<param name="hashAlgorithm">To be added.</param>
1476-
<param name="bytesWritten">To be added.</param>
1477-
<summary>To be added.</summary>
1478-
<returns>To be added.</returns>
1482+
<param name="data">The data to be signed.</param>
1483+
<param name="destination">The buffer to receive the signature.</param>
1484+
<param name="hashAlgorithm">The algorithm to use to hash the data for signing.</param>
1485+
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
1486+
<summary>Attempts to compute the ECDSA digital signature for the specified read-only span of bytes into the provided destination by using the specified hashing algorithm and the current key.</summary>
1487+
<returns><see langword="false"/> if <paramref name="destination"/> is not long enough to receive the signature.</returns>
14791488
<remarks>To be added.</remarks>
14801489
</Docs>
14811490
</Member>
@@ -1507,11 +1516,11 @@ The algorithm-specific key import failed.
15071516
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
15081517
</Parameters>
15091518
<Docs>
1510-
<param name="hash">To be added.</param>
1511-
<param name="destination">To be added.</param>
1512-
<param name="bytesWritten">To be added.</param>
1513-
<summary>To be added.</summary>
1514-
<returns>To be added.</returns>
1519+
<param name="hash">The hash value of the data that is being signed.</param>
1520+
<param name="destination">The buffer to receive the signature.</param>
1521+
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
1522+
<summary>Attempts to compute the ECDSA digital signature for the specified read-only span of bytes representing a data hash into the provided destination by using the current key.</summary>
1523+
<returns><see langword="false"/> if <paramref name="destination"/> is not long enough to receive the signature.</returns>
15151524
<remarks>To be added.</remarks>
15161525
</Docs>
15171526
</Member>
@@ -1523,7 +1532,7 @@ The algorithm-specific key import failed.
15231532
<AssemblyVersion>4.3.0.0</AssemblyVersion>
15241533
</AssemblyInfo>
15251534
<Docs>
1526-
<summary>Verifies that a digital signature is valid.</summary>
1535+
<summary>Verifies that a digital signature is appropriate for the current key and provided data with a specified hash algorithm.</summary>
15271536
</Docs>
15281537
</MemberGroup>
15291538
<Member MemberName="VerifyData">
@@ -1563,7 +1572,7 @@ The algorithm-specific key import failed.
15631572
<param name="data">The signed data.</param>
15641573
<param name="signature">The signature data to be verified.</param>
15651574
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
1566-
<summary>Verifies that a digital signature is valid by calculating the hash value of the specified data using the specified hash algorithm and comparing it to the provided signature.</summary>
1575+
<summary>Verifies that a digital signature is appropriate for the current key and provided data with a specified hash algorithm.</summary>
15671576
<returns>
15681577
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
15691578
<remarks>To be added.</remarks>
@@ -1614,7 +1623,7 @@ The algorithm-specific key import failed.
16141623
<param name="data">The signed data.</param>
16151624
<param name="signature">The signature data to be verified.</param>
16161625
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
1617-
<summary>Verifies that a digital signature is valid by calculating the hash value of the specified stream using the specified hash algorithm and comparing it to the provided signature.</summary>
1626+
<summary>Verifies that a digital signature is appropriate for the current key and provided data with a specified hash algorithm.</summary>
16181627
<returns>
16191628
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
16201629
<remarks>To be added.</remarks>
@@ -1656,12 +1665,14 @@ The algorithm-specific key import failed.
16561665
<Parameter Name="hashAlgorithm" Type="System.Security.Cryptography.HashAlgorithmName" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
16571666
</Parameters>
16581667
<Docs>
1659-
<param name="data">To be added.</param>
1660-
<param name="signature">To be added.</param>
1661-
<param name="hashAlgorithm">To be added.</param>
1662-
<summary>To be added.</summary>
1663-
<returns>To be added.</returns>
1668+
<param name="data">The signed data.</param>
1669+
<param name="signature">The signature to be verified.</param>
1670+
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
1671+
<summary>Verifies that a digital signature is appropriate for the current key and provided data with a specified hash algorithm.</summary>
1672+
<returns><see langword="true"/> if the signature is valid; otherwise, <see langword="false"/>.</returns>
16641673
<remarks>To be added.</remarks>
1674+
<exception cref="T:System.ArgumentException">
1675+
<paramref name="hashAlgorithm" />.<see cref="P:System.Security.Cryptography.HashAlgorithmName.Name" /> is <see langword="null" /> or <see cref="F:System.String.Empty" />.</exception>
16651676
</Docs>
16661677
</Member>
16671678
<Member MemberName="VerifyData">
@@ -1705,7 +1716,7 @@ The algorithm-specific key import failed.
17051716
<param name="count">The number of bytes to hash.</param>
17061717
<param name="signature">The signature data to be verified.</param>
17071718
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
1708-
<summary>Verifies that a digital signature is valid by calculating the hash value of the data in a portion of a byte array using the specified hash algorithm and comparing it to the provided signature.</summary>
1719+
<summary>Verifies that a digital signature is appropriate for the current key and provided portion of data with a specified hash algorithm.</summary>
17091720
<returns>
17101721
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
17111722
<remarks>To be added.</remarks>
@@ -1763,19 +1774,13 @@ The algorithm-specific key import failed.
17631774
<Parameter Name="signature" Type="System.Byte[]" />
17641775
</Parameters>
17651776
<Docs>
1766-
<param name="hash">The hash value of a block of data.</param>
1767-
<param name="signature">The digital signature to be verified.</param>
1768-
<summary>Verifies a digital signature against the specified hash value.</summary>
1777+
<param name="hash">The hash value of the data to be verified.</param>
1778+
<param name="signature">The digital signature of the data to be verified against the hash value.</param>
1779+
<summary>Verifies that a digital signature is appropriate for the current key and provided data hash.</summary>
17691780
<returns>
1770-
<see langword="true" /> if the hash value equals the decrypted signature; otherwise, <see langword="false" />.</returns>
1771-
<remarks>
1772-
<format type="text/markdown"><![CDATA[
1773-
1774-
## Remarks
1775-
The signature is first decrypted by using the public key, and then compared to the hash value for verification.
1776-
1777-
]]></format>
1778-
</remarks>
1781+
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
1782+
<remarks>To be added.</remarks>
1783+
<exception cref="T:System.ArgumentNullException"><paramref name="hash"/> or <paramref name="signature"/> is <see langword="null"/>.</exception>
17791784
</Docs>
17801785
</Member>
17811786
<Member MemberName="VerifyHash">
@@ -1805,10 +1810,11 @@ The algorithm-specific key import failed.
18051810
<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" />
18061811
</Parameters>
18071812
<Docs>
1808-
<param name="hash">To be added.</param>
1809-
<param name="signature">To be added.</param>
1810-
<summary>To be added.</summary>
1811-
<returns>To be added.</returns>
1813+
<param name="hash">The hash value of the data to be verified.</param>
1814+
<param name="signature">The digital signature of the data to be verified against the hash value.</param>
1815+
<summary>Verifies that a digital signature is appropriate for the current key and provided data hash.</summary>
1816+
<returns>
1817+
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
18121818
<remarks>To be added.</remarks>
18131819
</Docs>
18141820
</Member>

0 commit comments

Comments
 (0)
0