Skip to content

Add documentation for the rest of the Pkcs12SafeBag derived types #2926

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 2 commits into from
Aug 5, 2019
Merged

Add documentation for the rest of the Pkcs12SafeBag derived types #2926

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b315d21
Add documentation for the rest of the Pkcs12SafeBag derived types
bartonjs Aug 4, 2019
53d0098
Apply suggestions from code review
bartonjs Aug 5, 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
47 changes: 38 additions & 9 deletions xml/System.Security.Cryptography.Pkcs/Pkcs12KeyBag.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Represents the KeyBag from PKCS#12, a container whose contents are a PKCS#8 PrivateKeyInfo. This class cannot be inherited.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -36,10 +36,29 @@
<Parameter Name="skipCopy" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="pkcs8PrivateKey">To be added.</param>
<param name="skipCopy">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="pkcs8PrivateKey">A BER-encoded PKCS#8 PrivateKeyInfo value.</param>
<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>
<summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12KeyBag"/> from an existing encoded PKCS#8 PrivateKeyInfo value.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

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.

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.
For best support, transport keys in a ShroudedKeyBag (<xref:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag>).

The default behavior of this method is to make a defensive copy of `pkcs8PrivateKey`.
When the `skipCopy` parameter is `true`, this defensive copy is skipped.
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
methods or properties, then methods and properties on those objects may produce nonsense results or throw exceptions due to the corrupted state.
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.

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="pkcs8privateKey"/> parameter does not represent a single ASN.1 BER-encoded value.</exception>
<altmember cref="M:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddKeyUnencrypted(System.Security.Cryptography.AsymmetricAlgorithm)" />
</Docs>
</Member>
<Member MemberName="Pkcs8PrivateKey">
Expand All @@ -59,10 +78,20 @@
<ReturnType>System.ReadOnlyMemory&lt;System.Byte&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets a memory value containing the PKCS#8 PrivateKeyInfo value transported by this bag.</summary>
<value>A memory value containing the PKCS#8 PrivateKeyInfo value transported by this bag.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

No validation is performed that the returned value is a valid PKCS#8 PrivateKeyInfo value.

This property is an alias for the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag.EncodedBagValue?displayProperty=nameWithType> property.

]]></format>
</remarks>
</Docs>
</Member>
</Members>
</Type>
</Type>
9 changes: 5 additions & 4 deletions xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContentsBag.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Represents the SafeContentsBag from PKCS#12, a container whose contents are a PKCS#12 SafeContents value. This class cannot be inherited.</summary>
<remarks>To be added.</remarks>
<altmember cref="T:System.Security.Cryptography.Pkcs.Pkcs12SafeContents" />
</Docs>
<Members>
<Member MemberName="SafeContents">
Expand All @@ -36,10 +37,10 @@
<ReturnType>System.Security.Cryptography.Pkcs.Pkcs12SafeContents</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the SafeContents value contained within this bag.</summary>
<value>The SafeContents value contained within this bag.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
</Members>
</Type>
</Type>
14 changes: 8 additions & 6 deletions xml/System.Security.Cryptography.Pkcs/Pkcs12SecretBag.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Represents the SecretBag from PKCS#12, a container whose contents are arbitrary data with a type identifier. This class cannot be inherited.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -37,9 +37,10 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Gets the Object Identifier (OID) which identifies the data type of the secret value.</summary>
<returns>The Object Identifier (OID) which identifies the data type of the secret value.</returns>
<remarks>To be added.</remarks>
<altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs12SecretBag.SecretValue"/>
</Docs>
</Member>
<Member MemberName="SecretValue">
Expand All @@ -59,10 +60,11 @@
<ReturnType>System.ReadOnlyMemory&lt;System.Byte&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets a memory value containing the BER-encoded contents of the bag.</summary>
<value>A memory value containing the BER-encoded contents of the bag.</value>
<remarks>To be added.</remarks>
<altmember cref="M:System.Security.Cryptography.Pkcs.Pkcs12SecretBag.GetSecretType()"/>
</Docs>
</Member>
</Members>
</Type>
</Type>
44 changes: 35 additions & 9 deletions xml/System.Security.Cryptography.Pkcs/Pkcs12ShroudedKeyBag.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Represents the ShroudedKeyBag from PKCS#12, a container whose contents are a PKCS#8 EncryptedPrivateKeyInfo. This class cannot be inherited.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -36,10 +36,26 @@
<Parameter Name="skipCopy" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="encryptedPkcs8PrivateKey">To be added.</param>
<param name="skipCopy">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="encryptedPkcs8PrivateKey">A BER-encoded PKCS#8 EncryptedPrivateKeyInfo value.</param>
<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>
<summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12ShroudedKeyBag"/> from an existing encoded PKCS#8 EncryptedPrivateKeyInfo value.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

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.

The default behavior of this method is to make a defensive copy of `encryptedPkcs8PrivateKey`.
When the `skipCopy` parameter is `true`, this defensive copy is skipped.
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
methods or properties, then methods and properties on those objects may produce nonsense results or throw exceptions due to the corrupted state.
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.

]]></format>
</remarks>
<exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="encryptedPkcs8privateKey"/> parameter does not represent a single ASN.1 BER-encoded value.</exception>
<altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12SafeContents.AddShroudedKey" />
</Docs>
</Member>
<Member MemberName="EncryptedPkcs8PrivateKey">
Expand All @@ -59,10 +75,20 @@
<ReturnType>System.ReadOnlyMemory&lt;System.Byte&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets a memory value containing the PKCS#8 EncryptedPrivateKeyInfo value transported by this bag.</summary>
<value>A memory value containing the PKCS#8 EncryptedPrivateKeyInfo value transported by this bag.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

No validation is performed that the returned value is a valid PKCS#8 EncryptedPrivateKeyInfo value.

This property is an alias for the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag.EncodedBagValue?displayProperty=nameWithType> property.

]]></format>
</remarks>
</Docs>
</Member>
</Members>
</Type>
</Type>