Skip to content

Document Pkcs12Info #2914

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 8 commits into from
Aug 6, 2019
Merged

Document Pkcs12Info #2914

Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1b500e2
Document Pkcs12Info
bartonjs Aug 2, 2019
ed48107
fixed bad tag
mairaw Aug 2, 2019
adb37a6
Update Pkcs12Info.xml
mairaw Aug 2, 2019
9e1963b
Apply suggestions from code review
bartonjs Aug 3, 2019
f25aad5
Remove erroneous 12s, add a remarks to the new VerifyWithMac MemberGroup
bartonjs Aug 3, 2019
4d5ed53
Fixed broken xref.
Aug 5, 2019
f45069a
Added <Docs> element
Aug 5, 2019
66fa4f1
Apply more feedback
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
97 changes: 76 additions & 21 deletions xml/System.Security.Cryptography.Pkcs/Pkcs12Info.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 data from PKCS#12 PFX contents. This class cannot be inherited.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -36,8 +36,8 @@
<ReturnType>System.Collections.ObjectModel.ReadOnlyCollection&lt;System.Security.Cryptography.Pkcs.Pkcs12SafeContents&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets a read-only collection of the SafeContents values present in the PFX AuthenticatedSafe.</summary>
<value>A read-only collection of the SafeContents values present in the PFX AuthenticatedSafe.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -62,12 +62,25 @@
<Parameter Name="skipCopy" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="encodedBytes">To be added.</param>
<param name="bytesConsumed">To be added.</param>
<param name="skipCopy">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="encodedBytes">The data to interpret as a PKCS#12 PFX.</param>
<param name="bytesConsumed">When this method returns, contains a value that indicates the number of bytes from <paramref name="encodedBytes"/> which were read by this method. This parameter is treated as uninitialized.</param>
<param name="skipCopy"><see langword="true"/> to store <paramref name="encodedBytes"/> without making a defensive copy; otherwise, <see langword="false"/>. The default is <see langword="false"/>.</param>
<summary>Reads the provided data as a PKCS#12 PFX and returns an object view of the contents.</summary>
<returns>An object view of the PKCS#12 PFX decoded from the input.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The default behavior of this method is to make a defensive copy of the first `bytesConsumed` bytes from `encodedBytes`.
When the `skipCopy` parameter is `true`, this defensive copy is skipped.
If the defensive copy is skipped and the contents of the first `bytesConsumed` bytes of `encodedBytes` 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 contents of the <paramref name="encodedBytes"/> parameter were not successfully decoded as a PKCS#12 PFX.</exception>
</Docs>
</Member>
<Member MemberName="IntegrityMode">
Expand All @@ -87,11 +100,19 @@
<ReturnType>System.Security.Cryptography.Pkcs.Pkcs12IntegrityMode</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets a value that indicates the type of tamper protection provided for the <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.AuthenticatedSafe"/> contents.</summary>
<value>One of the enumeration members that indicates the type of tamper protection provided for the <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.AuthenticatedSafe"/> contents.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
</Member>
<MemberGroup MemberName="VerifyMac">
<AssemblyInfo>
<AssemblyName>System.Security.Cryptography.Pkcs</AssemblyName>
<AssemblyVersion>4.0.4.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
</AssemblyInfo>
<summary>Attempts to verify the integrity of the <see cref="P:System.Security.Cryptography.Pkcs12.Pkcs12Info.AuthenticatedSafe" /> contents with a password.</summary>
</MemberGroup>
<Member MemberName="VerifyMac">
<MemberSignature Language="C#" Value="public bool VerifyMac (ReadOnlySpan&lt;char&gt; password);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance bool VerifyMac(valuetype System.ReadOnlySpan`1&lt;char&gt; password) cil managed" />
Expand All @@ -112,10 +133,27 @@
<Parameter Name="password" Type="System.ReadOnlySpan&lt;System.Char&gt;" />
</Parameters>
<Docs>
<param name="password">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="password">The password to use to attempt to verify integrity.</param>
<summary>Attempts to verify the integrity of the <see cref="P:System.Security.Cryptography.Pkcs12.Pkcs12Info.AuthenticatedSafe"/> contents with a password represented by a <see cref="T:System.ReadOnlySpan{System.Char}"/>.</summary>
<returns><see langword="true"/> if the password successfully verifies the integrity of the <see cref="P:System.Security.Cryptography.Pkcs12.Pkcs12Info.AuthenticatedSafe"/> contents; <see langword="false"/> if the password is not correct or the contents have been altered.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first two paragraphs of each overload are good candidates to put in the MemberGroup section.


It's not possible to distinguish the error due to the password being incorrect from the error due to the contents having been altered.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since these two paragraphs now appear in the member group, they can be removed from here.


It's usually the case that a password-protected PFX uses the same password for the MAC algorithm providing integrity and the encryption algorithm providing confidentiality,
but the file format doesn't make that a requirement.
Therefore, there is no guarantee that a password which results in a `true` return from this method will succeed on a call to <xref:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.Decrypt%2A>.

In the PKCS#12 specification, a distinction is made between a `null` password and an "empty" password, and that difference is reflected in the return value of this method.
<xref:System.ReadOnlySpan{System.Char}.Empty> represents the `null` password and `String.Empty.AsSpan()` represents the "empty" password. If one of those two values returns `true`, the other won't.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <see cref="P:System.Security.Cryptography.Pkcs12.Pkcs12Info.IntegrityMode"/> value is not <see cref="F:System.Security.Cryptography.Pkcs12.Pkcs12IntegrityMode.Password"/>.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">The hash algorithm option specified by the PKCS#12 PFX contents could not be identified or is not supported by this platform.</exception>
</Docs>
</Member>
<Member MemberName="VerifyMac">
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mairaw or @rpetrusha : This file doesn't have a MethodGroup entry for this overloaded member (and I feel like I've seen other new API in that state). I don't know if that means a) we're not bothering with them, b) there's an error in the ingestor which results in it not producing them c) there's an error in the validator that makes it not report them as missing d) other e) some multiple combination of a-d.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean the MemberGroup element to add summary, remarks, etc. that apply to all overloads?
If so, the reflection tool doesn't add them automatically and we're not required to document them.

When we want to avoid repeating the same text, we manually add them.

If I misunderstood, please let me know.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems, though, that the <summary> element of a member group is ignored if there aren't some <AssemblyInfo> elements present.

Expand All @@ -138,11 +176,28 @@
<Parameter Name="password" Type="System.String" />
</Parameters>
<Docs>
<param name="password">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="password">The password to use to attempt to verify integrity.</param>
<summary>Attempts to verify the integrity of the <see cref="P:System.Security.Cryptography.Pkcs12.Pkcs12Info.AuthenticatedSafe"/> contents with a password represented by a <see cref="T:System.String"/>.</summary>
<returns><see langword="true"/> if the password successfully verifies the integrity of the <see cref="P:System.Security.Cryptography.Pkcs12.Pkcs12Info.AuthenticatedSafe"/> contents; <see langword="false"/> if the password is not correct or the contents have been altered.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

It's not possible to distingush the error due to the password being incorrect from the error due to the contents having been altered.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since these two paragraphs now appear in the member group, they can be removed from here.


It's usually the case that a password-protected PFX uses the same password for the MAC algorithm providing integrity and the encryption algorithm providing confidentiality,
but the file format doesn't make that a requirement.
Therefore, there is no guarantee that a password which results in a `true` return from this method will succeed on a call to <xref:System.Security.Cryptography.Pkcs12.Pkcs12SafeContents.Decrypt%2A>.

In the PKCS#12 specification, a distinction is made between a `null` password and an "empty" password, and that difference is reflected in the return value of this method.
If the `null` string returns `true`, then <xref:System.String.Empty> returns `false`, and vice versa.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If the `null` string returns `true`, then <xref:System.String.Empty> returns `false`, and vice versa.
If the `null` string returns `true`, then <xref:System.String.Empty?displayProperty=nameWithType> returns `false`, and vice versa.


]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <see cref="P:System.Security.Cryptography.Pkcs12.Pkcs12Info.IntegrityMode"/> value is not <see cref="F:System.Security.Cryptography.Pkcs12.Pkcs12IntegrityMode.Password"/>.</exception>
<exception cref="T:System.Security.Cryptography.CryptographicException">The hash algorithm option specified by the PKCS#12 PFX contents could not be identified or is not supported by this platform.</exception>
</Docs>
</Member>
</Members>
</Type>
</Type>