Skip to content

Commit 72af7a5

Browse files
bartonjsRon Petrusha
bartonjs
authored and
Ron Petrusha
committed
Document Pkcs12Info (#2914)
* Document Pkcs12Info * fixed bad tag * Update Pkcs12Info.xml * Apply suggestions from code review Co-Authored-By: Ron Petrusha <[email protected]> * Remove erroneous 12s, add a remarks to the new VerifyWithMac MemberGroup * Fixed broken xref. * Added <Docs> element * Apply more feedback
1 parent d2cd895 commit 72af7a5

File tree

1 file changed

+78
-21
lines changed

1 file changed

+78
-21
lines changed

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

Lines changed: 78 additions & 21 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 data from PKCS#12 PFX contents. This class cannot be inherited.</summary>
1919
<remarks>To be added.</remarks>
2020
</Docs>
2121
<Members>
@@ -36,8 +36,8 @@
3636
<ReturnType>System.Collections.ObjectModel.ReadOnlyCollection&lt;System.Security.Cryptography.Pkcs.Pkcs12SafeContents&gt;</ReturnType>
3737
</ReturnValue>
3838
<Docs>
39-
<summary>To be added.</summary>
40-
<value>To be added.</value>
39+
<summary>Gets a read-only collection of the SafeContents values present in the PFX AuthenticatedSafe.</summary>
40+
<value>A read-only collection of the SafeContents values present in the PFX AuthenticatedSafe.</value>
4141
<remarks>To be added.</remarks>
4242
</Docs>
4343
</Member>
@@ -62,12 +62,25 @@
6262
<Parameter Name="skipCopy" Type="System.Boolean" />
6363
</Parameters>
6464
<Docs>
65-
<param name="encodedBytes">To be added.</param>
66-
<param name="bytesConsumed">To be added.</param>
67-
<param name="skipCopy">To be added.</param>
68-
<summary>To be added.</summary>
69-
<returns>To be added.</returns>
70-
<remarks>To be added.</remarks>
65+
<param name="encodedBytes">The data to interpret as a PKCS#12 PFX.</param>
66+
<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>
67+
<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>
68+
<summary>Reads the provided data as a PKCS#12 PFX and returns an object view of the contents.</summary>
69+
<returns>An object view of the PKCS#12 PFX decoded from the input.</returns>
70+
<remarks>
71+
<format type="text/markdown"><![CDATA[
72+
73+
## Remarks
74+
75+
The default behavior of this method is to make a defensive copy of the first `bytesConsumed` bytes from `encodedBytes`.
76+
When the `skipCopy` parameter is `true`, this defensive copy is skipped.
77+
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
78+
methods or properties, then methods and properties on those objects may produce nonsense results or throw exceptions due to the corrupted state.
79+
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.
80+
81+
]]></format>
82+
</remarks>
83+
<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>
7184
</Docs>
7285
</Member>
7386
<Member MemberName="IntegrityMode">
@@ -87,11 +100,33 @@
87100
<ReturnType>System.Security.Cryptography.Pkcs.Pkcs12IntegrityMode</ReturnType>
88101
</ReturnValue>
89102
<Docs>
90-
<summary>To be added.</summary>
91-
<value>To be added.</value>
103+
<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>
104+
<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>
92105
<remarks>To be added.</remarks>
93106
</Docs>
94-
</Member>
107+
</Member>
108+
<MemberGroup MemberName="VerifyMac">
109+
<AssemblyInfo>
110+
<AssemblyName>System.Security.Cryptography.Pkcs</AssemblyName>
111+
<AssemblyVersion>4.0.4.0</AssemblyVersion>
112+
<AssemblyVersion>4.1.0.0</AssemblyVersion>
113+
</AssemblyInfo>
114+
<Docs>
115+
<summary>Attempts to verify the integrity of the <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.AuthenticatedSafe" /> contents with a password.</summary>
116+
<remarks>
117+
<format type="text/markdown"><![CDATA[
118+
119+
## Remarks
120+
It's not possible to distinguish the error due to the password being incorrect from the error due to the contents having been altered.
121+
122+
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,
123+
but the file format doesn't make that a requirement.
124+
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.Pkcs.Pkcs12SafeContents.Decrypt%2A>.
125+
126+
]]></format>
127+
</remarks>
128+
</Docs>
129+
</MemberGroup>
95130
<Member MemberName="VerifyMac">
96131
<MemberSignature Language="C#" Value="public bool VerifyMac (ReadOnlySpan&lt;char&gt; password);" />
97132
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance bool VerifyMac(valuetype System.ReadOnlySpan`1&lt;char&gt; password) cil managed" />
@@ -112,10 +147,21 @@
112147
<Parameter Name="password" Type="System.ReadOnlySpan&lt;System.Char&gt;" />
113148
</Parameters>
114149
<Docs>
115-
<param name="password">To be added.</param>
116-
<summary>To be added.</summary>
117-
<returns>To be added.</returns>
118-
<remarks>To be added.</remarks>
150+
<param name="password">The password to use to attempt to verify integrity.</param>
151+
<summary>Attempts to verify the integrity of the <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.AuthenticatedSafe"/> contents with a password represented by a <see cref="T:System.ReadOnlySpan{System.Char}"/>.</summary>
152+
<returns><see langword="true"/> if the password successfully verifies the integrity of the <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.AuthenticatedSafe"/> contents; <see langword="false"/> if the password is not correct or the contents have been altered.</returns>
153+
<remarks>
154+
<format type="text/markdown"><![CDATA[
155+
156+
## Remarks
157+
158+
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.
159+
`ReadOnlySpan<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.
160+
161+
]]></format>
162+
</remarks>
163+
<exception cref="T:System.InvalidOperationException">The <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.IntegrityMode"/> value is not <see cref="F:System.Security.Cryptography.Pkcs.Pkcs12IntegrityMode.Password"/>.</exception>
164+
<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>
119165
</Docs>
120166
</Member>
121167
<Member MemberName="VerifyMac">
@@ -138,11 +184,22 @@
138184
<Parameter Name="password" Type="System.String" />
139185
</Parameters>
140186
<Docs>
141-
<param name="password">To be added.</param>
142-
<summary>To be added.</summary>
143-
<returns>To be added.</returns>
144-
<remarks>To be added.</remarks>
187+
<param name="password">The password to use to attempt to verify integrity.</param>
188+
<summary>Attempts to verify the integrity of the <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.AuthenticatedSafe"/> contents with a password represented by a <see cref="T:System.String"/>.</summary>
189+
<returns><see langword="true"/> if the password successfully verifies the integrity of the <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.AuthenticatedSafe"/> contents; <see langword="false"/> if the password is not correct or the contents have been altered.</returns>
190+
<remarks>
191+
<format type="text/markdown"><![CDATA[
192+
193+
## Remarks
194+
195+
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.
196+
If the `null` string returns `true`, then <xref:System.String.Empty?displayProperty=nameWithType> returns `false`, and vice versa.
197+
198+
]]></format>
199+
</remarks>
200+
<exception cref="T:System.InvalidOperationException">The <see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Info.IntegrityMode"/> value is not <see cref="F:System.Security.Cryptography.Pkcs.Pkcs12IntegrityMode.Password"/>.</exception>
201+
<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>
145202
</Docs>
146203
</Member>
147204
</Members>
148-
</Type>
205+
</Type>

0 commit comments

Comments
 (0)