Skip to content

Commit c4ad828

Browse files
bartonjsRon Petrusha
andcommitted
Document Pkcs12Builder (#2919)
* Document Pkcs12Builder * Add missing exception * Fix some bad end tag. * Apply suggestions from code review Co-Authored-By: Ron Petrusha <[email protected]>
1 parent 684dbf4 commit c4ad828

File tree

1 file changed

+158
-46
lines changed

1 file changed

+158
-46
lines changed

xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml

Lines changed: 158 additions & 46 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>Enables the creation of PKCS#12 PFX data values. This class cannot be inherited.</summary>
1919
<remarks>To be added.</remarks>
2020
</Docs>
2121
<Members>
@@ -33,7 +33,7 @@
3333
</AssemblyInfo>
3434
<Parameters />
3535
<Docs>
36-
<summary>To be added.</summary>
36+
<summary>Initializes a new value of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs12Builder" /> class.</summary>
3737
<remarks>To be added.</remarks>
3838
</Docs>
3939
</Member>
@@ -58,11 +58,26 @@
5858
<Parameter Name="pbeParameters" Type="System.Security.Cryptography.PbeParameters" />
5959
</Parameters>
6060
<Docs>
61-
<param name="safeContents">To be added.</param>
62-
<param name="passwordBytes">To be added.</param>
63-
<param name="pbeParameters">To be added.</param>
64-
<summary>To be added.</summary>
65-
<remarks>To be added.</remarks>
61+
<param name="safeContents">The contents to add to the PFX.</param>
62+
<param name="passwordBytes">The byte array to use as a password when encrypting the contents.</param>
63+
<param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the contents.</param>
64+
<summary>Add contents to the PFX in an bundle encrypted with a byte-based password from a byte array.</summary>
65+
<remarks>
66+
<format type="text/markdown"><![CDATA[
67+
68+
## Remarks
69+
The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by `pbeParameters`.
70+
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).
71+
72+
The contents of `safeContents` are read during the call to this method, encrypted, and stored internally as encrypted content.
73+
Any changes to the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeContents> or any <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag> it references made after this method call are not reflected in the final output.
74+
75+
]]></format>
76+
</remarks>
77+
<exception cref="T:System.ArgumentNullException">The <paramref name="safeContents"/> or <paramref name="pbeParameters"/> parameter is <see langword="null"/>.</exception>
78+
<exception cref="T:System.ArgumentException">The <paramref name="safeContents"/> parameter value is already encrypted.</exception>
79+
<exception cref="T:System.InvalidOperationException">The PFX is already sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="true"/>).</exception>
80+
<exception cref="T:System.Security.Cryptography.CryptographicException"><paramref name="pbeParameters"/> indicates that <see cref="F:System.Security.Cryptography.PbeEncryptionAlgorithm.TripleDes3KeyPkcs12"/> should be used, which requires <see cref="T:System.Char"/>-based passwords.</exception>
6681
</Docs>
6782
</Member>
6883
<Member MemberName="AddSafeContentsEncrypted">
@@ -86,11 +101,26 @@
86101
<Parameter Name="pbeParameters" Type="System.Security.Cryptography.PbeParameters" />
87102
</Parameters>
88103
<Docs>
89-
<param name="safeContents">To be added.</param>
90-
<param name="passwordBytes">To be added.</param>
91-
<param name="pbeParameters">To be added.</param>
92-
<summary>To be added.</summary>
93-
<remarks>To be added.</remarks>
104+
<param name="safeContents">The contents to add to the PFX.</param>
105+
<param name="passwordBytes">The byte span to use as a password when encrypting the contents.</param>
106+
<param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the contents.</param>
107+
<summary>Add contents to the PFX in an bundle encrypted with a byte-based password from a span.</summary>
108+
<remarks>
109+
<format type="text/markdown"><![CDATA[
110+
111+
## Remarks
112+
The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by `pbeParameters`.
113+
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).
114+
115+
The contents of `safeContents` are read during the call to this method, encrypted, and stored internally as encrypted content.
116+
Any changes to the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeContents> or any <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag> it references made after this method call are not reflected in the final output.
117+
118+
]]></format>
119+
</remarks>
120+
<exception cref="T:System.ArgumentNullException">The <paramref name="safeContents"/> or <paramref name="pbeParameters"/> parameter is <see langword="null"/>.</exception>
121+
<exception cref="T:System.ArgumentException">The <paramref name="safeContents"/> parameter value is already encrypted.</exception>
122+
<exception cref="T:System.InvalidOperationException">The PFX is already sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="true"/>).</exception>
123+
<exception cref="T:System.Security.Cryptography.CryptographicException"><paramref name="pbeParameters"/> indicates that <see cref="F:System.Security.Cryptography.PbeEncryptionAlgorithm.TripleDes3KeyPkcs12"/> should be used, which requires <see cref="T:System.Char"/>-based passwords.</exception>
94124
</Docs>
95125
</Member>
96126
<Member MemberName="AddSafeContentsEncrypted">
@@ -114,11 +144,24 @@
114144
<Parameter Name="pbeParameters" Type="System.Security.Cryptography.PbeParameters" />
115145
</Parameters>
116146
<Docs>
117-
<param name="safeContents">To be added.</param>
118-
<param name="password">To be added.</param>
119-
<param name="pbeParameters">To be added.</param>
120-
<summary>To be added.</summary>
121-
<remarks>To be added.</remarks>
147+
<param name="safeContents">The contents to add to the PFX.</param>
148+
<param name="password">The span to use as a password when encrypting the contents.</param>
149+
<param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the contents.</param>
150+
<summary>Add contents to the PFX in an bundle encrypted with a char-based password from a span.</summary>
151+
<remarks>
152+
<format type="text/markdown"><![CDATA[
153+
154+
## Remarks
155+
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.
156+
157+
The contents of `safeContents` are read during the call to this method, encrypted, and stored internally as encrypted content.
158+
Any changes to the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeContents> or any <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag> it references made after this method call are not reflected in the final output.
159+
160+
]]></format>
161+
</remarks>
162+
<exception cref="T:System.ArgumentNullException">The <paramref name="safeContents"/> or <paramref name="pbeParameters"/> parameter is <see langword="null"/>.</exception>
163+
<exception cref="T:System.ArgumentException">The <paramref name="safeContents"/> parameter value is already encrypted.</exception>
164+
<exception cref="T:System.InvalidOperationException">The PFX is already sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="true"/>).</exception>
122165
</Docs>
123166
</Member>
124167
<Member MemberName="AddSafeContentsEncrypted">
@@ -142,11 +185,24 @@
142185
<Parameter Name="pbeParameters" Type="System.Security.Cryptography.PbeParameters" />
143186
</Parameters>
144187
<Docs>
145-
<param name="safeContents">To be added.</param>
146-
<param name="password">To be added.</param>
147-
<param name="pbeParameters">To be added.</param>
148-
<summary>To be added.</summary>
149-
<remarks>To be added.</remarks>
188+
<param name="safeContents">The contents to add to the PFX.</param>
189+
<param name="password">The string to use as a password when encrypting the contents.</param>
190+
<param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the contents.</param>
191+
<summary>Add contents to the PFX in an bundle encrypted with a char-based password from a string.</summary>
192+
<remarks>
193+
<format type="text/markdown"><![CDATA[
194+
195+
## Remarks
196+
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.
197+
198+
The contents of `safeContents` are read during the call to this method, encrypted, and stored internally as encrypted content.
199+
Any changes to the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeContents> or any <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag> it references made after this method call are not reflected in the final output.
200+
201+
]]></format>
202+
</remarks>
203+
<exception cref="T:System.ArgumentNullException">The <paramref name="safeContents"/> or <paramref name="pbeParameters"/> parameter is <see langword="null"/>.</exception>
204+
<exception cref="T:System.ArgumentException">The <paramref name="safeContents"/> parameter value is already encrypted.</exception>
205+
<exception cref="T:System.InvalidOperationException">The PFX is already sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="true"/>).</exception>
150206
</Docs>
151207
</Member>
152208
<Member MemberName="AddSafeContentsUnencrypted">
@@ -169,9 +225,21 @@
169225
<Parameter Name="safeContents" Type="System.Security.Cryptography.Pkcs.Pkcs12SafeContents" />
170226
</Parameters>
171227
<Docs>
172-
<param name="safeContents">To be added.</param>
173-
<summary>To be added.</summary>
174-
<remarks>To be added.</remarks>
228+
<param name="safeContents">The contents to add to the PFX.</param>
229+
<summary>Add contents to the PFX without encrypting them.</summary>
230+
<remarks>
231+
<format type="text/markdown"><![CDATA[
232+
233+
## Remarks
234+
If the `safeContents` value is already encrypted, this method adds it to the PFX as-is.
235+
236+
The contents of `safeContents` are read during the call to this method, and stored internally as the encoded form of their content.
237+
Any changes to the <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeContents> or any <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag> it references made after this method call are not reflected in the final output.
238+
239+
]]></format>
240+
</remarks>
241+
<exception cref="T:System.ArgumentNullException">The <paramref name="safeContents"/> parameter is <see langword="null"/>.</exception>
242+
<exception cref="T:System.InvalidOperationException">The PFX is already sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="true"/>).</exception>
175243
</Docs>
176244
</Member>
177245
<Member MemberName="Encode">
@@ -192,9 +260,12 @@
192260
</ReturnValue>
193261
<Parameters />
194262
<Docs>
195-
<summary>To be added.</summary>
196-
<returns>To be added.</returns>
263+
<summary>Encodes the contents of a sealed PFX and returns it as a byte array.</summary>
264+
<returns>A byte array representing the encoded form of the PFX.</returns>
197265
<remarks>To be added.</remarks>
266+
<altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12Builder.SealWithMac"/>
267+
<altmember cref="M:System.Security.Cryptography.Pkcs.Pkcs12Builder.SealWithoutIntegrity"/>
268+
<exception cref="T:System.InvalidOperationException">The PFX is not sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="false"/>).</exception>
198269
</Docs>
199270
</Member>
200271
<Member MemberName="IsSealed">
@@ -214,9 +285,11 @@
214285
<ReturnType>System.Boolean</ReturnType>
215286
</ReturnValue>
216287
<Docs>
217-
<summary>To be added.</summary>
218-
<value>To be added.</value>
288+
<summary>Gets a value that indicates whether the PFX data has been sealed.</summary>
289+
<value>A value that indicates whether the PFX data has been sealed.</value>
219290
<remarks>To be added.</remarks>
291+
<altmember cref="Overload:System.Security.Cryptography.Pkcs.Pkcs12Builder.SealWithMac"/>
292+
<altmember cref="M:System.Security.Cryptography.Pkcs.Pkcs12Builder.SealWithoutIntegrity"/>
220293
</Docs>
221294
</Member>
222295
<Member MemberName="SealWithMac">
@@ -241,11 +314,25 @@
241314
<Parameter Name="iterationCount" Type="System.Int32" />
242315
</Parameters>
243316
<Docs>
244-
<param name="password">To be added.</param>
245-
<param name="hashAlgorithm">To be added.</param>
246-
<param name="iterationCount">To be added.</param>
247-
<summary>To be added.</summary>
248-
<remarks>To be added.</remarks>
317+
<param name="password">The password to use as a key for computing the MAC.</param>
318+
<param name="hashAlgorithm">The hash algorithm to use when computing the MAC.</param>
319+
<param name="iterationCount">The iteration count for the Key Derivation Function (KDF) used in computing the MAC.</param>
320+
<summary>Seals the PFX against further changes by applying a password-based Message Authentication Code (MAC) over the contents with a password from a span.</summary>
321+
<remarks>
322+
<format type="text/markdown"><![CDATA[
323+
324+
## Remarks
325+
326+
Any hash algorithm that this method accepts can be processed by the <xref:System.Security.Cryptography.Pkcs.Pkcs12Info> class.
327+
Some choices of hash algorithm may cause failures in <xref:System.Security.Cryptography.X509Certificates.X509Certificate2.%23ctor%2A> or <xref:System.Security.Cryptography.X509Certificates.X509Certificate2Collection.Import%2A?displayProperty=nameWithType> on some operating systems, because these methods depend on system libraries for support.
328+
329+
The hash algorithm used on a fresh installation of Windows 7 when exporting via <xref:System.Security.Cryptography.X509Certificates.X509Certificate.Export%2A?displayProperty=nameWithtype> as a PKCS#12 PFX is <xref:System.Security.Cryptography.HashAlgorithmName.SHA1> with an iteration count of 2000.
330+
Due to collision problems with SHA1, Microsoft recommends a security model based on SHA256 or better; however, some PFX readers may only support SHA1.
331+
332+
]]></format>
333+
</remarks>
334+
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="iterationCount"/> parameter is less than or equal to 0.</exception>
335+
<exception cref="T:System.InvalidOperationException">The PFX is already sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="true"/>).</exception>
249336
</Docs>
250337
</Member>
251338
<Member MemberName="SealWithMac">
@@ -270,11 +357,25 @@
270357
<Parameter Name="iterationCount" Type="System.Int32" />
271358
</Parameters>
272359
<Docs>
273-
<param name="password">To be added.</param>
274-
<param name="hashAlgorithm">To be added.</param>
275-
<param name="iterationCount">To be added.</param>
276-
<summary>To be added.</summary>
277-
<remarks>To be added.</remarks>
360+
<param name="password">The password to use as a key for computing the MAC.</param>
361+
<param name="hashAlgorithm">The hash algorithm to use when computing the MAC.</param>
362+
<param name="iterationCount">The iteration count for the Key Derivation Function (KDF) used in computing the MAC.</param>
363+
<summary>Seals the PFX against further changes by applying a password-based Message Authentication Code (MAC) over the contents with a password from a string.</summary>
364+
<remarks>
365+
<format type="text/markdown"><![CDATA[
366+
367+
## Remarks
368+
369+
Any hash algorithm that this method accepts can be processed by the <xref:System.Security.Cryptography.Pkcs.Pkcs12Info> class.
370+
Some choices of hash algorithm may cause failures in <xref:System.Security.Cryptography.X509Certificates.X509Certificate2.%23ctor%2A> or <xref:System.Security.Cryptography.X509Certificates.X509Certificate2Collection.Import%2A?displayProperty=nameWithType> on some operating systems, because these methods depend on system libraries for support.
371+
372+
The hash algorithm used on a fresh installation of Windows 7 when exporting via <xref:System.Security.Cryptography.X509Certificates.X509Certificate.Export%2A?displayProperty=nameWithType> as a PKCS#12 PFX is <xref:System.Security.Cryptography.HashAlgorithmName.SHA1> with an iteration count of 2000.
373+
Due to collision problems with SHA1, Microsoft recommends a security model based on SHA256 or better; however, some PFX readers may only support SHA1.
374+
375+
]]></format>
376+
</remarks>
377+
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="iterationCount"/> parameter is less than or equal to 0.</exception>
378+
<exception cref="T:System.InvalidOperationException">The PFX is already sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="true"/>).</exception>
278379
</Docs>
279380
</Member>
280381
<Member MemberName="SealWithoutIntegrity">
@@ -295,8 +396,18 @@
295396
</ReturnValue>
296397
<Parameters />
297398
<Docs>
298-
<summary>To be added.</summary>
299-
<remarks>To be added.</remarks>
399+
<summary>Seals the PFX from further changes without applying tamper-protection.</summary>
400+
<remarks>
401+
<format type="text/markdown"><![CDATA[
402+
403+
## Remarks
404+
405+
This method exists for compatibility with the PKCS#12 specification, but its use is not recommended for purposes other than testing.
406+
When building a PFX that can be used by the overloads of <xref:System.Security.Cryptography.X509Certificates.X509Certificate2.%23ctor%2A> or <xref:System.Security.Cryptography.X509Certificates.X509Certificate2Collection.Import%2A?displayProperty=nameWithType> which do not accept a password parameter, use the <xref:System.Security.Cryptography.Pkcs.Pkcs12Builder.SealWithMac(System.String, System.Security.Cryptography.HashAlgorithmName, System.Int32)> method with <xref:System.String.Empty?displayProperty=nameWithType> as the password.
407+
408+
]]></format>
409+
</remarks>
410+
<exception cref="T:System.InvalidOperationException">The PFX is already sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="true"/>).</exception>
300411
</Docs>
301412
</Member>
302413
<Member MemberName="TryEncode">
@@ -320,12 +431,13 @@
320431
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" />
321432
</Parameters>
322433
<Docs>
323-
<param name="destination">To be added.</param>
324-
<param name="bytesWritten">To be added.</param>
325-
<summary>To be added.</summary>
326-
<returns>To be added.</returns>
434+
<param name="destination">The byte span to receive the PKCS#12 PFX data.</param>
435+
<param name="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
436+
<summary>Attempts to encode the contents of a sealed PFX into a provided buffer.</summary>
437+
<returns><see langword="true"/> if <paramref name="destination"/> is big enough to receive the output; otherwise, <see langword="false"/>.</returns>
327438
<remarks>To be added.</remarks>
439+
<exception cref="T:System.InvalidOperationException">The PFX is not sealed (<see cref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <see langword="false"/>).</exception>
328440
</Docs>
329441
</Member>
330442
</Members>
331-
</Type>
443+
</Type>

0 commit comments

Comments
 (0)