Skip to content

Commit 7457a0e

Browse files
bartonjscarlossanlop
bartonjs
authored and
carlossanlop
committed
Add missing, and update existing, ECDH API documentation. (#3542)
* Add missing, and update existing, ECDH API documentation. * Apply feedback * suggestions by carlossanlop * avoid CI edits/loc issues * avoid CI edits * rollback link change * fix broken links * fix one more broken link * fix more links * Fix hashtag ctor * Fix xrefs
1 parent ccd05b0 commit 7457a0e

File tree

3 files changed

+452
-164
lines changed

3 files changed

+452
-164
lines changed

‎xml/System.Security.Cryptography/ECDiffieHellman.xml

Lines changed: 150 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -262,7 +262,7 @@
262262
<AssemblyVersion>4.0.0.0</AssemblyVersion>
263263
</AssemblyInfo>
264264
<Docs>
265-
<summary>Derives bytes that can be used as a key using a hash function .</summary>
265+
<summary>Performs key derivation using a specified hash algorithm.</summary>
266266
</Docs>
267267
</MemberGroup>
268268
<Member MemberName="DeriveKeyFromHash">
@@ -294,9 +294,9 @@
294294
</Parameters>
295295
<Docs>
296296
<param name="otherPartyPublicKey">The other party's public key.</param>
297-
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
298-
<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>
299-
<returns>The key material from the key exchange with the other party's public key.</returns>
297+
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
298+
<summary>Performs key derivation using a specified hash algorithm.</summary>
299+
<returns>The hash of the shared secret.</returns>
300300
<remarks>
301301
<format type="text/markdown"><![CDATA[
302302
@@ -306,7 +306,19 @@
306306
]]></format>
307307
</remarks>
308308
<exception cref="T:System.ArgumentException">
309-
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
309+
The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.
310+
311+
-or-
312+
313+
The <paramref name="hashAlgorithm"/> parameter does not specify a hash.
314+
</exception>
315+
<exception cref="T:System.ArgumentNullException">
316+
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
317+
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.
318+
319+
-or-
320+
321+
This instance represents only a public key.</exception>
310322
</Docs>
311323
</Member>
312324
<Member MemberName="DeriveKeyFromHash">
@@ -340,15 +352,37 @@
340352
</Parameters>
341353
<Docs>
342354
<param name="otherPartyPublicKey">The other party's public key.</param>
343-
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
355+
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
344356
<param name="secretPrepend">A value to prepend to the derived secret before hashing.</param>
345357
<param name="secretAppend">A value to append to the derived secret before hashing.</param>
346-
<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>
347-
<returns>The key material from the key exchange with the other party's public key.</returns>
348-
<remarks>To be added.</remarks>
358+
<summary>When implemented in a derived class, performs key derivation using a specified hash algorithm with optional prepended or appended data.</summary>
359+
<returns>The hash of the shared secret after prepending or appending data as requested.</returns>
360+
<remarks>
361+
<format type="text/markdown"><![CDATA[
362+
363+
## Remarks
364+
365+
This method internally performs the Elliptic Curve Diffie-Hellman key agreement to produce the shared secret (`z`).
366+
The return value from this method is the result of `HASH(secretPrepend || z || secretAppend)` using the specified hash algorithm, where `||` signifies concatenation.
367+
368+
If the value of `secretPrepend` or `secretAppend` is `null`, they are treated as empty arrays.
369+
370+
]]></format>
371+
</remarks>
349372
<exception cref="T:System.NotImplementedException">A derived class must override this method.</exception>
350-
<exception cref="T:System.ArgumentException">
351-
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
373+
<exception cref="T:System.ArgumentException">The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.
374+
375+
-or-
376+
377+
The <paramref name="hashAlgorithm"/> parameter does not specify a hash.
378+
</exception>
379+
<exception cref="T:System.ArgumentNullException">
380+
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
381+
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.
382+
383+
-or-
384+
385+
This instance represents only a public key.</exception>
352386
</Docs>
353387
</Member>
354388
<MemberGroup MemberName="DeriveKeyFromHmac">
@@ -357,7 +391,7 @@
357391
<AssemblyVersion>4.0.0.0</AssemblyVersion>
358392
</AssemblyInfo>
359393
<Docs>
360-
<summary>Derives bytes that can be used as a key using a Hash-based Message Authentication Code (HMAC).</summary>
394+
<summary>Performs key derivation using a specified HMAC (Hash-based Message Authentication Code) algorithm.</summary>
361395
</Docs>
362396
</MemberGroup>
363397
<Member MemberName="DeriveKeyFromHmac">
@@ -392,8 +426,8 @@
392426
<param name="otherPartyPublicKey">The other party's public key.</param>
393427
<param name="hashAlgorithm">The hash algorithm to use to derive the key material.</param>
394428
<param name="hmacKey">The key for the HMAC.</param>
395-
<summary>Derives bytes that can be used as a key using a Hash-based Message Authentication Code (HMAC).</summary>
396-
<returns>The key material from the key exchange with the other party's public key.</returns>
429+
<summary>Performs key derivation using a specified HMAC (Hash-based Message Authentication Code) algorithm.</summary>
430+
<returns>The HMAC of the shared secret.</returns>
397431
<remarks>
398432
<format type="text/markdown"><![CDATA[
399433
@@ -402,8 +436,19 @@
402436
403437
]]></format>
404438
</remarks>
405-
<exception cref="T:System.ArgumentException">
406-
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
439+
<exception cref="T:System.ArgumentException">The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.
440+
441+
-or-
442+
443+
The <paramref name="hashAlgorithm"/> parameter does not specify a hash.
444+
</exception>
445+
<exception cref="T:System.ArgumentNullException">
446+
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
447+
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.
448+
449+
-or-
450+
451+
This instance represents only a public key.</exception>
407452
</Docs>
408453
</Member>
409454
<Member MemberName="DeriveKeyFromHmac">
@@ -442,12 +487,35 @@
442487
<param name="hmacKey">The key for the HMAC.</param>
443488
<param name="secretPrepend">A value to prepend to the derived secret before hashing.</param>
444489
<param name="secretAppend">A value to append to the derived secret before hashing.</param>
445-
<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>
446-
<returns>The key material from the key exchange with the other party's public key.</returns>
447-
<remarks>To be added.</remarks>
490+
<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>
491+
<returns>The HMAC of the shared secret after prepending or appending data as requested.</returns>
492+
<remarks>
493+
<format type="text/markdown"><![CDATA[
494+
495+
## Remarks
496+
497+
This method internally performs the Elliptic Curve Diffie-Hellman key agreement to produce the shared secret (`z`).
498+
499+
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)`.
500+
501+
If the value of `secretPrepend` or `secretAppend` is `null`, they are treated as empty arrays.
502+
503+
]]></format>
504+
</remarks>
448505
<exception cref="T:System.NotImplementedException">A derived class must override this method.</exception>
449-
<exception cref="T:System.ArgumentException">
450-
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
506+
<exception cref="T:System.ArgumentException">The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.
507+
508+
-or-
509+
510+
The <paramref name="hashAlgorithm"/> parameter does not specify a hash.
511+
</exception>
512+
<exception cref="T:System.ArgumentNullException">
513+
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
514+
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.
515+
516+
-or-
517+
518+
This instance represents only a public key.</exception>
451519
</Docs>
452520
</Member>
453521
<Member MemberName="DeriveKeyMaterial">
@@ -483,16 +551,28 @@
483551
</Parameters>
484552
<Docs>
485553
<param name="otherPartyPublicKey">The other party's public key.</param>
486-
<summary>Derives bytes that can be used as a key, given another party's public key.</summary>
487-
<returns>The key material from the key exchange with the other party's public key.</returns>
554+
<summary>When implemented in a derived class, performs a key derivation on the shared secret.</summary>
555+
<returns>The result of the key derivation function, using the shared secret as an input.</returns>
488556
<remarks>
489557
<format type="text/markdown"><![CDATA[
490558
491-
## Remarks
492-
For more information about public keys, see the <xref:System.Security.Cryptography.ECDiffieHellmanPublicKey> class.
493-
559+
## Remarks
560+
561+
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.
562+
Some implementations allow the behavior of this method to be changed,
563+
and callers are advised to call whichever method explicitly says it performs the key derivation they need.
564+
494565
]]></format>
495566
</remarks>
567+
<exception cref="T:System.ArgumentException">
568+
The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.</exception>
569+
<exception cref="T:System.ArgumentNullException">
570+
<paramref name="otherPartyPublicKey" /> is <see langword="null"/>.</exception>
571+
<exception cref="T:System.Security.Cryptography.CryptographicException">The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.
572+
573+
-or-
574+
575+
This instance represents only a public key.</exception>
496576
</Docs>
497577
</Member>
498578
<Member MemberName="DeriveKeyTls">
@@ -527,16 +607,37 @@
527607
<param name="otherPartyPublicKey">The other party's public key.</param>
528608
<param name="prfLabel">The ASCII-encoded PRF label.</param>
529609
<param name="prfSeed">The 64-byte PRF seed.</param>
530-
<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>
531-
<returns>The key material from the key exchange with the other party's public key.</returns>
532-
<remarks>To be added.</remarks>
610+
<summary>When implemented in a derived class, performs key derivation using the TLS (Transport Layer Security) 1.1 PRF (Pseudo-Random Function).</summary>
611+
<returns>The first 48 bytes from the TLS 1.1 PRF, using the shared secret as the key.</returns>
612+
<remarks>
613+
<format type="text/markdown"><![CDATA[
614+
615+
## Remarks
616+
617+
This method internally performs the Elliptic Curve Diffie-Hellman key agreement to produce the shared secret (`z`).
618+
619+
The return value of this method is a 48 byte output of the TLS 1.1 PRF (Pseudo-Random Function),
620+
`PRF(z, prfLabel, prfSeed)`.
621+
622+
For more information, see [IETF RFC 4346, section 5](https://tools.ietf.org/html/rfc4346#section-5).
623+
624+
]]></format>
625+
</remarks>
533626
<exception cref="T:System.NotImplementedException">A derived class must override this method.</exception>
534627
<exception cref="T:System.ArgumentException">
535-
<paramref name="otherPartyPublicKey" /> is over a different curve than this key.</exception>
628+
The curve used by <paramref name="otherPartyPublicKey" /> has a different size than the curve from this key.</exception>
536629
<exception cref="T:System.ArgumentNullException">
537-
<paramref name="prfLabel" /> or <paramref name="prfSeed" /> is <see langword="null" />.</exception>
630+
<paramref name="otherPartyPublicKey"/>, <paramref name="prfLabel" /> or <paramref name="prfSeed" /> is <see langword="null" />.</exception>
538631
<exception cref="T:System.Security.Cryptography.CryptographicException">
539-
<paramref name="prfSeed" /> is not exactly 64 bytes in length.</exception>
632+
<paramref name="prfSeed" /> is not exactly 64 bytes in length.
633+
634+
-or-
635+
636+
The curve used by <paramref name="otherPartyPublicKey" /> is different than the curve from this key.
637+
638+
-or-
639+
640+
This instance represents only a public key.</exception>
540641
</Docs>
541642
</Member>
542643
<Member MemberName="ExportECPrivateKey">
@@ -757,8 +858,10 @@
757858
<format type="text/markdown"><![CDATA[
758859
759860
## Remarks
760-
This method only supports the binary (BER/CER/DER) encoding of ECPrivateKey.
761-
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
861+
862+
This method only supports the binary (BER/CER/DER) encoding of ECPrivateKey.
863+
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
864+
762865
]]></format>
763866
</remarks>
764867
<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.
@@ -803,11 +906,13 @@ The key import failed.
803906
<remarks>
804907
<format type="text/markdown"><![CDATA[
805908
806-
## Remarks
909+
## Remarks
910+
807911
The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by the EncryptedPrivateKeyInfo contents.
808912
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).
809913
This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo.
810914
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
915+
811916
]]></format>
812917
</remarks>
813918
<exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
@@ -830,8 +935,7 @@ The contents of <paramref name="source" /> represent the key in a format that is
830935

831936
-or-
832937

833-
The algorithm-specific key import failed.
834-
</exception>
938+
The algorithm-specific key import failed.</exception>
835939
</Docs>
836940
</Member>
837941
<Member MemberName="ImportEncryptedPkcs8PrivateKey">
@@ -872,6 +976,7 @@ The algorithm-specific key import failed.
872976
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.
873977
This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo.
874978
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
979+
875980
]]></format>
876981
</remarks>
877982
<exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
@@ -890,8 +995,7 @@ The contents of <paramref name="source" /> represent the key in a format that is
890995

891996
-or-
892997

893-
The algorithm-specific key import failed.
894-
</exception>
998+
The algorithm-specific key import failed.</exception>
895999
</Docs>
8961000
</Member>
8971001
<Member MemberName="ImportParameters">
@@ -973,6 +1077,7 @@ The algorithm-specific key import failed.
9731077
## Remarks
9741078
This method only supports the binary (BER/CER/DER) encoding of PrivateKeyInfo.
9751079
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
1080+
9761081
]]></format>
9771082
</remarks>
9781083
<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.
@@ -987,8 +1092,7 @@ The contents of <paramref name="source" /> represent the key in a format that is
9871092

9881093
-or-
9891094

990-
The algorithm-specific key import failed.
991-
</exception>
1095+
The algorithm-specific key import failed.</exception>
9921096
</Docs>
9931097
</Member>
9941098
<Member MemberName="ImportSubjectPublicKeyInfo">
@@ -1026,6 +1130,7 @@ The algorithm-specific key import failed.
10261130
## Remarks
10271131
This method only supports the binary (DER) encoding of SubjectPublicKeyInfo.
10281132
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
1133+
10291134
]]></format>
10301135
</remarks>
10311136
<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.
@@ -1040,8 +1145,7 @@ The contents of <paramref name="source" /> represent the key in a format that is
10401145

10411146
-or-
10421147

1043-
The algorithm-specific key import failed.
1044-
</exception>
1148+
The algorithm-specific key import failed.</exception>
10451149
</Docs>
10461150
</Member>
10471151
<Member MemberName="KeyExchangeAlgorithm">
@@ -1263,14 +1367,14 @@ The algorithm-specific key import failed.
12631367
## Remarks
12641368
The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by `pbeParameters`.
12651369
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).
1370+
12661371
]]></format>
12671372
</remarks>
12681373
<exception cref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.
12691374

12701375
-or-
12711376

1272-
<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.
1273-
</exception>
1377+
<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>
12741378
<altmember cref="Overload:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey" />
12751379
</Docs>
12761380
</Member>
@@ -1313,6 +1417,7 @@ The algorithm-specific key import failed.
13131417
13141418
## Remarks
13151419
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.
1420+
13161421
]]></format>
13171422
</remarks>
13181423
<exception cref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.</exception>

0 commit comments

Comments
 (0)