Skip to content

Add missing, and update existing, ECDsa API documentation #3564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 26, 2019
Merged

Add missing, and update existing, ECDsa API documentation #3564

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
79243c5
Add missing, and update existing, ECDsa API documentation
bartonjs Nov 25, 2019
f6e3ccf
Address feedback
bartonjs Nov 26, 2019
a394c1f
Fix another warning
bartonjs Nov 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 52 additions & 46 deletions xml/System.Security.Cryptography/ECDsa.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -461,8 +461,8 @@
<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" />
</Parameters>
<Docs>
<param name="curve">The curve to use.</param>
<summary>When overridden in a derived class, generates a new public/private key pair for the specified curve.</summary>
<param name="curve">The curve to use to generate the key.</param>
<summary>When overridden in a derived class, generates a new ephemeral public/private key pair for the specified curve, replacing the current key.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.NotSupportedException">A derived class must override this method.</exception>
</Docs>
Expand Down Expand Up @@ -1158,7 +1158,7 @@ The algorithm-specific key import failed.
<Docs>
<param name="hash">The hash value of the data that is being signed.</param>
<summary>Generates a digital signature for the specified hash value.</summary>
<returns>A digital signature that consists of the given hash value encrypted with the private key.</returns>
<returns>A digital signature for the specified hash value.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="hash" /> parameter is <see langword="null" />.</exception>
</Docs>
Expand Down Expand Up @@ -1432,13 +1432,22 @@ The algorithm-specific key import failed.
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="3" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
<param name="data">To be added.</param>
<param name="destination">To be added.</param>
<param name="hashAlgorithm">To be added.</param>
<param name="bytesWritten">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="data">The data to be hashed.</param>
<param name="destination">The buffer to receive the hash value.</param>
<param name="hashAlgorithm">The algorithm to use to hash the data.</param>
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
<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>
<returns><see langword="false"/> if <paramref name="destination"/> is not long enough to receive the hash value.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

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`.
Derived types should override this method to avoid the intermediate array creation.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="TrySignData">
Expand Down Expand Up @@ -1470,12 +1479,12 @@ The algorithm-specific key import failed.
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="3" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
<param name="data">To be added.</param>
<param name="destination">To be added.</param>
<param name="hashAlgorithm">To be added.</param>
<param name="bytesWritten">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="data">The data to be signed.</param>
<param name="destination">The buffer to receive the signature.</param>
<param name="hashAlgorithm">The algorithm to use to hash the data for signing.</param>
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
<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>
<returns><see langword="false"/> if <paramref name="destination"/> is not long enough to receive the signature.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -1507,11 +1516,11 @@ The algorithm-specific key import failed.
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
<param name="hash">To be added.</param>
<param name="destination">To be added.</param>
<param name="bytesWritten">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="hash">The hash value of the data that is being signed.</param>
<param name="destination">The buffer to receive the signature.</param>
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
<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>
<returns><see langword="false"/> if <paramref name="destination"/> is not long enough to receive the signature.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -1523,7 +1532,7 @@ The algorithm-specific key import failed.
<AssemblyVersion>4.3.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Verifies that a digital signature is valid.</summary>
<summary>Verifies that a digital signature is appropriate for the current key and provided data with a specified hash algorithm.</summary>
</Docs>
</MemberGroup>
<Member MemberName="VerifyData">
Expand Down Expand Up @@ -1563,7 +1572,7 @@ The algorithm-specific key import failed.
<param name="data">The signed data.</param>
<param name="signature">The signature data to be verified.</param>
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
<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>
<summary>Verifies that a digital signature is appropriate for the current key and provided data with a specified hash algorithm.</summary>
<returns>
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
Expand Down Expand Up @@ -1614,7 +1623,7 @@ The algorithm-specific key import failed.
<param name="data">The signed data.</param>
<param name="signature">The signature data to be verified.</param>
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
<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>
<summary>Verifies that a digital signature is appropriate for the current key and provided data with a specified hash algorithm.</summary>
<returns>
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
Expand Down Expand Up @@ -1656,12 +1665,14 @@ The algorithm-specific key import failed.
<Parameter Name="hashAlgorithm" Type="System.Security.Cryptography.HashAlgorithmName" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
<param name="data">To be added.</param>
<param name="signature">To be added.</param>
<param name="hashAlgorithm">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="data">The signed data.</param>
<param name="signature">The signature to be verified.</param>
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
<summary>Verifies that a digital signature is appropriate for the current key and provided data with a specified hash algorithm.</summary>
<returns><see langword="true"/> if the signature is valid; otherwise, <see langword="false"/>.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="hashAlgorithm" />.<see cref="P:System.Security.Cryptography.HashAlgorithmName.Name" /> is <see langword="null" /> or <see cref="F:System.String.Empty" />.</exception>
</Docs>
</Member>
<Member MemberName="VerifyData">
Expand Down Expand Up @@ -1705,7 +1716,7 @@ The algorithm-specific key import failed.
<param name="count">The number of bytes to hash.</param>
<param name="signature">The signature data to be verified.</param>
<param name="hashAlgorithm">The hash algorithm used to create the hash value of the data.</param>
<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>
<summary>Verifies that a digital signature is appropriate for the current key and provided portion of data with a specified hash algorithm.</summary>
<returns>
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
Expand Down Expand Up @@ -1763,19 +1774,13 @@ The algorithm-specific key import failed.
<Parameter Name="signature" Type="System.Byte[]" />
</Parameters>
<Docs>
<param name="hash">The hash value of a block of data.</param>
<param name="signature">The digital signature to be verified.</param>
<summary>Verifies a digital signature against the specified hash value.</summary>
<param name="hash">The hash value of the data to be verified.</param>
<param name="signature">The digital signature of the data to be verified against the hash value.</param>
<summary>Verifies that a digital signature is appropriate for the current key and provided data hash.</summary>
<returns>
<see langword="true" /> if the hash value equals the decrypted signature; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The signature is first decrypted by using the public key, and then compared to the hash value for verification.

]]></format>
</remarks>
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="hash"/> or <paramref name="signature"/> is <see langword="null"/>.</exception>
</Docs>
</Member>
<Member MemberName="VerifyHash">
Expand Down Expand Up @@ -1805,10 +1810,11 @@ The algorithm-specific key import failed.
<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" />
</Parameters>
<Docs>
<param name="hash">To be added.</param>
<param name="signature">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="hash">The hash value of the data to be verified.</param>
<param name="signature">The digital signature of the data to be verified against the hash value.</param>
<summary>Verifies that a digital signature is appropriate for the current key and provided data hash.</summary>
<returns>
<see langword="true" /> if the signature is valid; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
Loading