Skip to content

Add missing, and update existing, ECDH API documentation. #3542

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 11 commits into from
Nov 23, 2019
Merged

Add missing, and update existing, ECDH API documentation. #3542

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
cd014f3
Add missing, and update existing, ECDH API documentation.
bartonjs Nov 20, 2019
e6750fb
Apply feedback
bartonjs Nov 20, 2019
7015450
suggestions by carlossanlop
carlossanlop Nov 22, 2019
2cf008d
avoid CI edits/loc issues
mairaw Nov 22, 2019
6706d98
avoid CI edits
mairaw Nov 22, 2019
b45bd78
rollback link change
mairaw Nov 22, 2019
2a7fb0a
fix broken links
mairaw Nov 22, 2019
3d3ac29
fix one more broken link
mairaw Nov 22, 2019
e6d043a
fix more links
mairaw Nov 22, 2019
eb4005e
Fix hashtag ctor
carlossanlop Nov 23, 2019
c0b8b5b
Fix xrefs
carlossanlop Nov 23, 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
195 changes: 150 additions & 45 deletions xml/System.Security.Cryptography/ECDiffieHellman.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,7 @@
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Derives bytes that can be used as a key using a hash function .</summary>
<summary>Performs key derivation using a specified hash algorithm.</summary>
</Docs>
</MemberGroup>
<Member MemberName="DeriveKeyFromHash">
Expand Down Expand Up @@ -294,9 +294,9 @@
</Parameters>
<Docs>
<param name="otherPartyPublicKey">The other party's public key.</param>
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
<summary>Derives bytes that can be used as a key using a hash function, given another party's public key and hash algorithm's name.</summary>
<returns>The key material from the key exchange with the other party's public key.</returns>
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
<summary>Performs key derivation using a specified hash algorithm.</summary>
<returns>The hash of the shared secret.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

Expand All @@ -306,7 +306,19 @@
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.

-or-

The <paramref name="hashAlgorithm"/> parameter does not specify a hash.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.

-or-

This instance represents only a public key.</exception>
</Docs>
</Member>
<Member MemberName="DeriveKeyFromHash">
Expand Down Expand Up @@ -340,15 +352,37 @@
</Parameters>
<Docs>
<param name="otherPartyPublicKey">The other party's public key.</param>
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
<param name="secretPrepend">A value to prepend to the derived secret before hashing.</param>
<param name="secretAppend">A value to append to the derived secret before hashing.</param>
<summary>When implemented in a derived class, derives bytes that can be used as a key using a hash function, given another party's public key, hash algorithm's name, a prepend value and an append value.</summary>
<returns>The key material from the key exchange with the other party's public key.</returns>
<remarks>To be added.</remarks>
<summary>When implemented in a derived class, performs key derivation using a specified hash algorithm with optional prepended or appended data.</summary>
<returns>The hash of the shared secret after prepending or appending data as requested.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This method internally performs the Elliptic Curve Diffie-Hellman key agreement to produce the shared secret (`z`).
The return value from this method is the result of `HASH(secretPrepend || z || secretAppend)` using the specified hash algorithm, where `||` signifies concatenation.

If the value of `secretPrepend` or `secretAppend` is `null`, they are treated as empty arrays.

]]></format>
</remarks>
<exception cref="T:System.NotImplementedException">A derived class must override this method.</exception>
<exception cref="T:System.ArgumentException">
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
<exception cref="T:System.ArgumentException">The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.

-or-

The <paramref name="hashAlgorithm"/> parameter does not specify a hash.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.

-or-

This instance represents only a public key.</exception>
</Docs>
</Member>
<MemberGroup MemberName="DeriveKeyFromHmac">
Expand All @@ -357,7 +391,7 @@
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Derives bytes that can be used as a key using a Hash-based Message Authentication Code (HMAC).</summary>
<summary>Performs key derivation using a specified HMAC (Hash-based Message Authentication Code) algorithm.</summary>
</Docs>
</MemberGroup>
<Member MemberName="DeriveKeyFromHmac">
Expand Down Expand Up @@ -392,8 +426,8 @@
<param name="otherPartyPublicKey">The other party's public key.</param>
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
<param name="hmacKey">The key for the HMAC.</param>
<summary>Derives bytes that can be used as a key using a Hash-based Message Authentication Code (HMAC).</summary>
<returns>The key material from the key exchange with the other party's public key.</returns>
<summary>Performs key derivation using a specified HMAC (Hash-based Message Authentication Code) algorithm.</summary>
<returns>The HMAC of the shared secret.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

Expand All @@ -402,8 +436,19 @@

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
<exception cref="T:System.ArgumentException">The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.

-or-

The <paramref name="hashAlgorithm"/> parameter does not specify a hash.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.

-or-

This instance represents only a public key.</exception>
</Docs>
</Member>
<Member MemberName="DeriveKeyFromHmac">
Expand Down Expand Up @@ -442,12 +487,35 @@
<param name="hmacKey">The key for the HMAC.</param>
<param name="secretPrepend">A value to prepend to the derived secret before hashing.</param>
<param name="secretAppend">A value to append to the derived secret before hashing.</param>
<summary>When implemented in a derived class, derives bytes that can be used as a key using a Hash-based Message Authentication Code (HMAC).</summary>
<returns>The key material from the key exchange with the other party's public key.</returns>
<remarks>To be added.</remarks>
<summary>When implemented in a derived class, performs key derivation using a specified HMAC (Hash-based Message Authentication Code) algorithm with optional prepended or appended data.</summary>
<returns>The HMAC of the shared secret after prepending or appending data as requested.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This method internally performs the Elliptic Curve Diffie-Hellman key agreement to produce the shared secret (`z`).

When `hmacKey` is `null`, the return value from this method is the result of `HMAC-HASH(z, secretPrepend || z || secretAppend)` using the specified HMAC algorithm, where `||` signifies concatenation. Otherwise, the return value from this method is the result of `HMAC-HASH(hmacKey, secretPrepend || z || secretAppend)`.

If the value of `secretPrepend` or `secretAppend` is `null`, they are treated as empty arrays.

]]></format>
</remarks>
<exception cref="T:System.NotImplementedException">A derived class must override this method.</exception>
<exception cref="T:System.ArgumentException">
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
<exception cref="T:System.ArgumentException">The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.

-or-

The <paramref name="hashAlgorithm"/> parameter does not specify a hash.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.

-or-

This instance represents only a public key.</exception>
</Docs>
</Member>
<Member MemberName="DeriveKeyMaterial">
Expand Down Expand Up @@ -483,16 +551,28 @@
</Parameters>
<Docs>
<param name="otherPartyPublicKey">The other party's public key.</param>
<summary>Derives bytes that can be used as a key, given another party's public key.</summary>
<returns>The key material from the key exchange with the other party's public key.</returns>
<summary>When implemented in a derived class, performs a key derivation on the shared secret.</summary>
<returns>The result of the key derivation function, using the shared secret as an input.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
For more information about public keys, see the <xref:System.Security.Cryptography.ECDiffieHellmanPublicKey> class.

## Remarks

The default behavior of this method is equivalent to calling <xref:System.Security.Cryptography.ECDiffieHellman.DeriveKeyFromHash%2A> specifying SHA-256 as the hash algorithm with no prepend or append values.
Some implementations allow the behavior of this method to be changed,
and callers are advised to call whichever method explicitly says it performs the key derivation they need.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.

-or-

This instance represents only a public key.</exception>
</Docs>
</Member>
<Member MemberName="DeriveKeyTls">
Expand Down Expand Up @@ -527,16 +607,37 @@
<param name="otherPartyPublicKey">The other party's public key.</param>
<param name="prfLabel">The ASCII-encoded PRF label.</param>
<param name="prfSeed">The 64-byte PRF seed.</param>
<summary>When implemented in a derived class, derives bytes that can be used as a key using a Transport Layer Security (TLS) Pseudo-Random Function (PRF) derivation algorithm.</summary>
<returns>The key material from the key exchange with the other party's public key.</returns>
<remarks>To be added.</remarks>
<summary>When implemented in a derived class, performs key derivation using the TLS (Transport Layer Security) 1.1 PRF (Pseudo-Random Function).</summary>
<returns>The first 48 bytes from the TLS 1.1 PRF, using the shared secret as the key.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This method internally performs the Elliptic Curve Diffie-Hellman key agreement to produce the shared secret (`z`).

The return value of this method is a 48 byte output of the TLS 1.1 PRF (Pseudo-Random Function),
`PRF(z, prfLabel, prfSeed)`.

For more information, see [IETF RFC 4346, section 5](https://tools.ietf.org/html/rfc4346#section-5).

]]></format>
</remarks>
<exception cref="T:System.NotImplementedException">A derived class must override this method.</exception>
<exception cref="T:System.ArgumentException">
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="prfLabel" /> or <paramref name="prfSeed" /> is <see langword="null" />.</exception>
<paramref name="otherPartyPublicKey"/>, <paramref name="prfLabel" /> or <paramref name="prfSeed" /> is <see langword="null" />.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">
<paramref name="prfSeed" /> is not exactly 64 bytes in length.</exception>
<paramref name="prfSeed" /> is not exactly 64 bytes in length.

-or-

The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.

-or-

This instance represents only a public key.</exception>
</Docs>
</Member>
<Member MemberName="ExportECPrivateKey">
Expand Down Expand Up @@ -757,8 +858,10 @@
<format type="text/markdown"><![CDATA[

## Remarks
This method only supports the binary (BER/CER/DER) encoding of ECPrivateKey.
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.

This method only supports the binary (BER/CER/DER) encoding of ECPrivateKey.
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The contents of <paramref name="source" /> do not represent an ASN.1-BER-encoded PKCS#8 ECPrivateKey structure.
Expand Down Expand Up @@ -803,11 +906,13 @@ The key import failed.
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
## Remarks

The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by the EncryptedPrivateKeyInfo contents.
This enables compatibility with other systems which use a text encoding other than UTF-8 when processing passwords with PBKDF2 (Password-Based Key Derivation Function 2).
This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo.
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
Expand All @@ -830,8 +935,7 @@ The contents of <paramref name="source" /> represent the key in a format that is

-or-

The algorithm-specific key import failed.
</exception>
The algorithm-specific key import failed.</exception>
</Docs>
</Member>
<Member MemberName="ImportEncryptedPkcs8PrivateKey">
Expand Down Expand Up @@ -872,6 +976,7 @@ The algorithm-specific key import failed.
When the contents of `source` indicate an algorithm that uses PBKDF1 (Password-Based Key Derivation Function 1) or PBKDF2 (Password-Based Key Derivation Function 2), the password is converted to bytes via the UTF-8 encoding.
This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo.
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
Expand All @@ -890,8 +995,7 @@ The contents of <paramref name="source" /> represent the key in a format that is

-or-

The algorithm-specific key import failed.
</exception>
The algorithm-specific key import failed.</exception>
</Docs>
</Member>
<Member MemberName="ImportParameters">
Expand Down Expand Up @@ -973,6 +1077,7 @@ The algorithm-specific key import failed.
## Remarks
This method only supports the binary (BER/CER/DER) encoding of PrivateKeyInfo.
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The contents of <paramref name="source" /> do not represent an ASN.1-BER-encoded PKCS#8 PrivateKeyInfo structure.
Expand All @@ -987,8 +1092,7 @@ The contents of <paramref name="source" /> represent the key in a format that is

-or-

The algorithm-specific key import failed.
</exception>
The algorithm-specific key import failed.</exception>
</Docs>
</Member>
<Member MemberName="ImportSubjectPublicKeyInfo">
Expand Down Expand Up @@ -1026,6 +1130,7 @@ The algorithm-specific key import failed.
## Remarks
This method only supports the binary (DER) encoding of SubjectPublicKeyInfo.
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The contents of <paramref name="source" /> do not represent an ASN.1-DER-encoded X.509 SubjectPublicKeyInfo structure.
Expand All @@ -1040,8 +1145,7 @@ The contents of <paramref name="source" /> represent the key in a format that is

-or-

The algorithm-specific key import failed.
</exception>
The algorithm-specific key import failed.</exception>
</Docs>
</Member>
<Member MemberName="KeyExchangeAlgorithm">
Expand Down Expand Up @@ -1263,14 +1367,14 @@ The algorithm-specific key import failed.
## Remarks
The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by `pbeParameters`.
This enables compatibility with other systems which use a text encoding other than UTF-8 when processing passwords with PBKDF2 (Password-Based Key Derivation Function 2).

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.

-or-

<paramref name="pbeParameters" /> indicates that <see cref="F:System.Security.Cryptography.PbeEncryptionAlgorithm.TripleDes3KeyPkcs12" /> should be used, which requires <see cref="T:System.Char" />-based passwords.
</exception>
<paramref name="pbeParameters" /> indicates that <see cref="F:System.Security.Cryptography.PbeEncryptionAlgorithm.TripleDes3KeyPkcs12" /> should be used, which requires <see cref="T:System.Char" />-based passwords.</exception>
<altmember cref="Overload:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey" />
</Docs>
</Member>
Expand Down Expand Up @@ -1313,6 +1417,7 @@ The algorithm-specific key import failed.

## Remarks
When `pbeParameters` indicates an algorithm that uses PBKDF2 (Password-Based Key Derivation Function 2), the password is converted to bytes via the UTF-8 encoding.

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.</exception>
Expand Down
Loading