Skip to content

Commit e1007c7

Browse files
bartonjsRon Petrusha
bartonjs
and
Ron Petrusha
committed
Add documentation for the rest of the Pkcs12SafeBag derived types (#2926)
* Add documentation for the rest of the Pkcs12SafeBag derived types * Apply suggestions from code review Co-Authored-By: Ron Petrusha <[email protected]>
1 parent b44eb2b commit e1007c7

File tree

4 files changed

+86
-28
lines changed

4 files changed

+86
-28
lines changed

‎xml/System.Security.Cryptography.Pkcs/Pkcs12KeyBag.xml

Lines changed: 38 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
</Base>
1616
<Interfaces />
1717
<Docs>
18-
<summary>To be added.</summary>
18+
<summary>Represents the KeyBag from PKCS#12, a container whose contents are a PKCS#8 PrivateKeyInfo. This class cannot be inherited.</summary>
1919
<remarks>To be added.</remarks>
2020
</Docs>
2121
<Members>
@@ -36,10 +36,29 @@
3636
<Parameter Name="skipCopy" Type="System.Boolean" />
3737
</Parameters>
3838
<Docs>
39-
<param name="pkcs8PrivateKey">To be added.</param>
40-
<param name="skipCopy">To be added.</param>
41-
<summary>To be added.</summary>
42-
<remarks>To be added.</remarks>
39+
<param name="pkcs8PrivateKey">A BER-encoded PKCS#8 PrivateKeyInfo value.</param>
40+
<param name="skipCopy"><see langword="true"/> to store <paramref name="pkcs8PrivateKey"/> without making a defensive copy; otherwise, <see langword="false"/>. The default is <see langword="false"/>.</param>
41+
<summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12KeyBag"/> from an existing encoded PKCS#8 PrivateKeyInfo value.</summary>
42+
<remarks>
43+
<format type="text/markdown"><![CDATA[
44+
45+
## Remarks
46+
47+
This method validates that `pkcs8PrivateKey` is a single BER-encoded value, but it does not verify that the value is a proper PKCS#8 PrivateKeyInfo value.
48+
49+
Transporting private keys in a KeyBag is permitted by the PKCS#12 standard, but not all PFX readers support pairing certificates with keys from a KeyBag.
50+
For best support, transport keys in a ShroudedKeyBag (<xref:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag>).
51+
52+
The default behavior of this method is to make a defensive copy of `pkcs8PrivateKey`.
53+
When the `skipCopy` parameter is `true`, this defensive copy is skipped.
54+
If the defensive copy is skipped and the contents of `pkcs8PrivateKey` change during the lifetime of the returned value or of any object produced by its
55+
methods or properties, then methods and properties on those objects may produce nonsense results or throw exceptions due to the corrupted state.
56+
Callers are therefore advised to only use a `true` value for the `skipCopy` parameter when they can be reasonably assured that the data will stay intact.
57+
58+
]]></format>
59+
</remarks>
60+
<exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="pkcs8privateKey"/> parameter does not represent a single ASN.1 BER-encoded value.</exception>
61+
<altmember cref="M:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddKeyUnencrypted(System.Security.Cryptography.AsymmetricAlgorithm)" />
4362
</Docs>
4463
</Member>
4564
<Member MemberName="Pkcs8PrivateKey">
@@ -59,10 +78,20 @@
5978
<ReturnType>System.ReadOnlyMemory&lt;System.Byte&gt;</ReturnType>
6079
</ReturnValue>
6180
<Docs>
62-
<summary>To be added.</summary>
63-
<value>To be added.</value>
64-
<remarks>To be added.</remarks>
81+
<summary>Gets a memory value containing the PKCS#8 PrivateKeyInfo value transported by this bag.</summary>
82+
<value>A memory value containing the PKCS#8 PrivateKeyInfo value transported by this bag.</value>
83+
<remarks>
84+
<format type="text/markdown"><![CDATA[
85+
86+
## Remarks
87+
88+
No validation is performed that the returned value is a valid PKCS#8 PrivateKeyInfo value.
89+
90+
This property is an alias for the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag.EncodedBagValue?displayProperty=nameWithType> property.
91+
92+
]]></format>
93+
</remarks>
6594
</Docs>
6695
</Member>
6796
</Members>
68-
</Type>
97+
</Type>

‎xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContentsBag.xml

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,9 @@
1515
</Base>
1616
<Interfaces />
1717
<Docs>
18-
<summary>To be added.</summary>
18+
<summary>Represents the SafeContentsBag from PKCS#12, a container whose contents are a PKCS#12 SafeContents value. This class cannot be inherited.</summary>
1919
<remarks>To be added.</remarks>
20+
<altmember cref="T:System.Security.Cryptography.Pkcs.Pkcs12SafeContents" />
2021
</Docs>
2122
<Members>
2223
<Member MemberName="SafeContents">
@@ -36,10 +37,10 @@
3637
<ReturnType>System.Security.Cryptography.Pkcs.Pkcs12SafeContents</ReturnType>
3738
</ReturnValue>
3839
<Docs>
39-
<summary>To be added.</summary>
40-
<value>To be added.</value>
40+
<summary>Gets the SafeContents value contained within this bag.</summary>
41+
<value>The SafeContents value contained within this bag.</value>
4142
<remarks>To be added.</remarks>
4243
</Docs>
4344
</Member>
4445
</Members>
45-
</Type>
46+
</Type>

‎xml/System.Security.Cryptography.Pkcs/Pkcs12SecretBag.xml

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
</Base>
1616
<Interfaces />
1717
<Docs>
18-
<summary>To be added.</summary>
18+
<summary>Represents the SecretBag from PKCS#12, a container whose contents are arbitrary data with a type identifier. This class cannot be inherited.</summary>
1919
<remarks>To be added.</remarks>
2020
</Docs>
2121
<Members>
@@ -37,9 +37,10 @@
3737
</ReturnValue>
3838
<Parameters />
3939
<Docs>
40-
<summary>To be added.</summary>
41-
<returns>To be added.</returns>
40+
<summary>Gets the Object Identifier (OID) which identifies the data type of the secret value.</summary>
41+
<returns>The Object Identifier (OID) which identifies the data type of the secret value.</returns>
4242
<remarks>To be added.</remarks>
43+
<altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SecretBag.SecretValue"/>
4344
</Docs>
4445
</Member>
4546
<Member MemberName="SecretValue">
@@ -59,10 +60,11 @@
5960
<ReturnType>System.ReadOnlyMemory&lt;System.Byte&gt;</ReturnType>
6061
</ReturnValue>
6162
<Docs>
62-
<summary>To be added.</summary>
63-
<value>To be added.</value>
63+
<summary>Gets a memory value containing the BER-encoded contents of the bag.</summary>
64+
<value>A memory value containing the BER-encoded contents of the bag.</value>
6465
<remarks>To be added.</remarks>
66+
<altmember cref="M:System.Security.Cryptography.Pkcs.Pkcs12SecretBag.GetSecretType()"/>
6567
</Docs>
6668
</Member>
6769
</Members>
68-
</Type>
70+
</Type>

‎xml/System.Security.Cryptography.Pkcs/Pkcs12ShroudedKeyBag.xml

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
</Base>
1616
<Interfaces />
1717
<Docs>
18-
<summary>To be added.</summary>
18+
<summary>Represents the ShroudedKeyBag from PKCS#12, a container whose contents are a PKCS#8 EncryptedPrivateKeyInfo. This class cannot be inherited.</summary>
1919
<remarks>To be added.</remarks>
2020
</Docs>
2121
<Members>
@@ -36,10 +36,26 @@
3636
<Parameter Name="skipCopy" Type="System.Boolean" />
3737
</Parameters>
3838
<Docs>
39-
<param name="encryptedPkcs8PrivateKey">To be added.</param>
40-
<param name="skipCopy">To be added.</param>
41-
<summary>To be added.</summary>
42-
<remarks>To be added.</remarks>
39+
<param name="encryptedPkcs8PrivateKey">A BER-encoded PKCS#8 EncryptedPrivateKeyInfo value.</param>
40+
<param name="skipCopy"><see langword="true"/> to store <paramref name="encryptedPkcs8PrivateKey"/> without making a defensive copy; otherwise, <see langword="false"/>. The default is <see langword="false"/>.</param>
41+
<summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from an existing encoded PKCS#8 EncryptedPrivateKeyInfo value.</summary>
42+
<remarks>
43+
<format type="text/markdown"><![CDATA[
44+
45+
## Remarks
46+
47+
This method validates that `encryptedPkcs8PrivateKey` is a single BER-encoded value, but it does not verify that the value is a proper PKCS#8 EncryptedPrivateKeyInfo value.
48+
49+
The default behavior of this method is to make a defensive copy of `encryptedPkcs8PrivateKey`.
50+
When the `skipCopy` parameter is `true`, this defensive copy is skipped.
51+
If the defensive copy is skipped and the contents of `encryptedPkcs8PrivateKey` change during the lifetime of the returned value or of any object produced by its
52+
methods or properties, then methods and properties on those objects may produce nonsense results or throw exceptions due to the corrupted state.
53+
Callers are therefore advised to only use a `true` value for the `skipCopy` parameter when they can be reasonably assured that the data will stay intact.
54+
55+
]]></format>
56+
</remarks>
57+
<exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="encryptedPkcs8privateKey"/> parameter does not represent a single ASN.1 BER-encoded value.</exception>
58+
<altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddShroudedKey" />
4359
</Docs>
4460
</Member>
4561
<Member MemberName="EncryptedPkcs8PrivateKey">
@@ -59,10 +75,20 @@
5975
<ReturnType>System.ReadOnlyMemory&lt;System.Byte&gt;</ReturnType>
6076
</ReturnValue>
6177
<Docs>
62-
<summary>To be added.</summary>
63-
<value>To be added.</value>
64-
<remarks>To be added.</remarks>
78+
<summary>Gets a memory value containing the PKCS#8 EncryptedPrivateKeyInfo value transported by this bag.</summary>
79+
<value>A memory value containing the PKCS#8 EncryptedPrivateKeyInfo value transported by this bag.</value>
80+
<remarks>
81+
<format type="text/markdown"><![CDATA[
82+
83+
## Remarks
84+
85+
No validation is performed that the returned value is a valid PKCS#8 EncryptedPrivateKeyInfo value.
86+
87+
This property is an alias for the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag.EncodedBagValue?displayProperty=nameWithType> property.
88+
89+
]]></format>
90+
</remarks>
6591
</Docs>
6692
</Member>
6793
</Members>
68-
</Type>
94+
</Type>

0 commit comments

Comments
 (0)