You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Add missing asymmetric key import/export documentation
This includes both:
* Overrides of AsymmetricAlgorithm methods
* New algorithm-specific formats
* Fix incorrect reference to pbeParameters on ImportEncrypted
<paramname="passwordBytes">The bytes to use as a password when decrypting the key material.</param>
495
+
<paramname="source">The bytes of a PKCS#8 EncryptedPrivateKeyInfo structure in the ASN.1-BER encoding.</param>
496
+
<paramname="bytesRead">When this method returns, contains a value that indicates the number of bytes read from <paramrefname="source"/>. This parameter is treated as uninitialized.</param>
497
+
<summary>Imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a byte-based password, replacing the keys for this object.</summary>
498
+
<remarks>
499
+
<formattype="text/markdown"><![CDATA[
500
+
501
+
## Remarks
502
+
The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by the EncryptedPrivateKeyInfo contents.
503
+
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).
504
+
This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo.
505
+
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
506
+
]]></format>
507
+
</remarks>
508
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
509
+
510
+
-or-
511
+
512
+
The contents of <paramrefname="source"/> indicate the Key Derivation Function (KDF) to apply is the legacy PKCS#12 KDF, which requires <seecref="T:System.Char"/>-based passwords.
513
+
514
+
-or-
515
+
516
+
The contents of <paramrefname="source"/> do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure.
517
+
518
+
-or-
519
+
520
+
The contents of <paramrefname="source"/> indicate the key is for an algorithm other than the algorithm represented by this instance.
521
+
522
+
-or-
523
+
524
+
The contents of <paramrefname="source"/> represent the key in a format that is not supported.
<paramname="password">The password to use for decrypting the key material.</param>
560
+
<paramname="source">The bytes of a PKCS#8 EncryptedPrivateKeyInfo structure in the ASN.1-BER encoding.</param>
561
+
<paramname="bytesRead">When this method returns, contains a value that indicates the number of bytes read from <paramrefname="source"/>. This parameter is treated as uninitialized.</param>
562
+
<summary>Imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a char-based password, replacing the keys for this object.</summary>
563
+
<remarks>
564
+
<formattype="text/markdown"><![CDATA[
565
+
566
+
## Remarks
567
+
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.
568
+
This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo.
569
+
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
570
+
]]></format>
571
+
</remarks>
572
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
573
+
574
+
-or-
575
+
576
+
The contents of <paramrefname="source"/> do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure.
577
+
578
+
-or-
579
+
580
+
The contents of <paramrefname="source"/> indicate the key is for an algorithm other than the algorithm represented by this instance.
581
+
582
+
-or-
583
+
584
+
The contents of <paramrefname="source"/> represent the key in a format that is not supported.
<paramname="source">The bytes of a PKCS#8 PrivateKeyInfo structure in the ASN.1-BER encoding.</param>
657
+
<paramname="bytesRead">When this method returns, contains a value that indicates the number of bytes read from <paramrefname="source"/>. This parameter is treated as uninitialized.</param>
658
+
<summary>Imports the public/private keypair from a PKCS#8 PrivateKeyInfo structure after decryption, replacing the keys for this object.</summary>
659
+
<remarks>
660
+
<formattype="text/markdown"><![CDATA[
661
+
662
+
## Remarks
663
+
This method only supports the binary (BER/CER/DER) encoding of PrivateKeyInfo.
664
+
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
665
+
]]></format>
666
+
</remarks>
667
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException">The contents of <paramrefname="source"/> do not represent an ASN.1-BER-encoded PKCS#8 PrivateKeyInfo structure.
668
+
669
+
-or-
670
+
671
+
The contents of <paramrefname="source"/> indicate the key is for an algorithm other than the algorithm represented by this instance.
672
+
673
+
-or-
674
+
675
+
The contents of <paramrefname="source"/> represent the key in a format that is not supported.
<paramname="source">The bytes of an X.509 SubjectPublicKeyInfo structure in the ASN.1-DER encoding.</param>
710
+
<paramname="bytesRead">When this method returns, contains a value that indicates the number of bytes read from <paramrefname="source"/>. This parameter is treated as uninitialized.</param>
711
+
<summary>Imports the public key from an X.509 SubjectPublicKeyInfo structure after decryption, replacing the keys for this object.</summary>
712
+
<remarks>
713
+
<formattype="text/markdown"><![CDATA[
714
+
715
+
## Remarks
716
+
This method only supports the binary (DER) encoding of SubjectPublicKeyInfo.
717
+
If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
718
+
]]></format>
719
+
</remarks>
720
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException">The contents of <paramrefname="source"/> do not represent an ASN.1-DER-encoded X.509 SubjectPublicKeyInfo structure.
721
+
722
+
-or-
723
+
724
+
The contents of <paramrefname="source"/> indicate the key is for an algorithm other than the algorithm represented by this instance.
725
+
726
+
-or-
727
+
728
+
The contents of <paramrefname="source"/> represent the key in a format that is not supported.
729
+
730
+
-or-
731
+
732
+
The algorithm-specific key import failed.
733
+
</exception>
635
734
</Docs>
636
735
</Member>
637
736
<MemberGroupMemberName="SignData">
@@ -901,13 +1000,27 @@ Creating the signature otherwise failed.</exception>
<paramname="passwordBytes">The bytes to use as a password when encrypting the key material.</param>
1004
+
<paramname="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
1005
+
<paramname="destination">The byte span to receive the PKCS#8 EncryptedPrivateKeyInfo data.</param>
1006
+
<paramname="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramrefname="destination"/>. This parameter is treated as uninitialized.</param>
1007
+
<summary>Attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a byte-based password.</summary>
1008
+
<returns><seelangword="true"/> if <paramrefname="destination"/> is big enough to receive the output; otherwise, <seelangword="false"/>.</returns>
1009
+
<remarks>
1010
+
<formattype="text/markdown"><![CDATA[
1011
+
1012
+
## Remarks
1013
+
The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by `pbeParameters`.
1014
+
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).
1015
+
]]></format>
1016
+
</remarks>
1017
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.
1018
+
1019
+
-or-
1020
+
1021
+
<paramrefname="pbeParameters"/> indicates that <seecref="F:System.Security.Cryptography.PbeEncryptionAlgorithm.TripleDes3KeyPkcs12"/> should be used, which requires <seecref="T:System.Char"/>-based passwords.
<paramname="password">The password to use when encrypting the key material.</param>
1054
+
<paramname="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
1055
+
<paramname="destination">The byte span to receive the PKCS#8 EncryptedPrivateKeyInfo data.</param>
1056
+
<paramname="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramrefname="destination"/>. This parameter is treated as uninitialized.</param>
1057
+
<summary>Attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a char-based password.</summary>
1058
+
<returns><seelangword="true"/> if <paramrefname="destination"/> is big enough to receive the output; otherwise, <seelangword="false"/>.</returns>
1059
+
<remarks>
1060
+
<formattype="text/markdown"><![CDATA[
1061
+
1062
+
## Remarks
1063
+
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.
1064
+
]]></format>
1065
+
</remarks>
1066
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.</exception>
<paramname="destination">The byte span to receive the PKCS#8 PrivateKeyInfo data.</param>
1097
+
<paramname="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramrefname="destination"/>. This parameter is treated as uninitialized.</param>
1098
+
<summary>Attempts to export the current key in the PKCS#8 PrivateKeyInfo format into a provided buffer.</summary>
1099
+
<returns><seelangword="true"/> if <paramrefname="destination"/> is big enough to receive the output; otherwise, <seelangword="false"/>.</returns>
979
1100
<remarks>To be added.</remarks>
1101
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.</exception>
<paramname="destination">The byte span to receive the X.509 SubjectPublicKeyInfo data.</param>
1132
+
<paramname="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramrefname="destination"/>. This parameter is treated as uninitialized.</param>
1133
+
<summary>Attempts to export the current key in the X.509 SubjectPublicKeyInfo format into a provided buffer.</summary>
1134
+
<returns><seelangword="true"/> if <paramrefname="destination"/> is big enough to receive the output; otherwise, <seelangword="false"/>.</returns>
1012
1135
<remarks>To be added.</remarks>
1136
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.</exception>
0 commit comments