You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Document Pkcs12Builder
* Add missing exception
* Fix some bad end tag.
* Apply suggestions from code review
Co-Authored-By: Ron Petrusha <[email protected]>
<paramname="safeContents">The contents to add to the PFX.</param>
62
+
<paramname="passwordBytes">The byte array to use as a password when encrypting the contents.</param>
63
+
<paramname="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
+
<formattype="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
+
<exceptioncref="T:System.ArgumentNullException">The <paramrefname="safeContents"/> or <paramrefname="pbeParameters"/> parameter is <seelangword="null"/>.</exception>
78
+
<exceptioncref="T:System.ArgumentException">The <paramrefname="safeContents"/> parameter value is already encrypted.</exception>
79
+
<exceptioncref="T:System.InvalidOperationException">The PFX is already sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="true"/>).</exception>
80
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException"><paramrefname="pbeParameters"/> indicates that <seecref="F:System.Security.Cryptography.PbeEncryptionAlgorithm.TripleDes3KeyPkcs12"/> should be used, which requires <seecref="T:System.Char"/>-based passwords.</exception>
<paramname="safeContents">The contents to add to the PFX.</param>
105
+
<paramname="passwordBytes">The byte span to use as a password when encrypting the contents.</param>
106
+
<paramname="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
+
<formattype="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
+
<exceptioncref="T:System.ArgumentNullException">The <paramrefname="safeContents"/> or <paramrefname="pbeParameters"/> parameter is <seelangword="null"/>.</exception>
121
+
<exceptioncref="T:System.ArgumentException">The <paramrefname="safeContents"/> parameter value is already encrypted.</exception>
122
+
<exceptioncref="T:System.InvalidOperationException">The PFX is already sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="true"/>).</exception>
123
+
<exceptioncref="T:System.Security.Cryptography.CryptographicException"><paramrefname="pbeParameters"/> indicates that <seecref="F:System.Security.Cryptography.PbeEncryptionAlgorithm.TripleDes3KeyPkcs12"/> should be used, which requires <seecref="T:System.Char"/>-based passwords.</exception>
<paramname="safeContents">The contents to add to the PFX.</param>
148
+
<paramname="password">The span to use as a password when encrypting the contents.</param>
149
+
<paramname="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
+
<formattype="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
+
<exceptioncref="T:System.ArgumentNullException">The <paramrefname="safeContents"/> or <paramrefname="pbeParameters"/> parameter is <seelangword="null"/>.</exception>
163
+
<exceptioncref="T:System.ArgumentException">The <paramrefname="safeContents"/> parameter value is already encrypted.</exception>
164
+
<exceptioncref="T:System.InvalidOperationException">The PFX is already sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="true"/>).</exception>
<paramname="safeContents">The contents to add to the PFX.</param>
189
+
<paramname="password">The string to use as a password when encrypting the contents.</param>
190
+
<paramname="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
+
<formattype="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
+
<exceptioncref="T:System.ArgumentNullException">The <paramrefname="safeContents"/> or <paramrefname="pbeParameters"/> parameter is <seelangword="null"/>.</exception>
204
+
<exceptioncref="T:System.ArgumentException">The <paramrefname="safeContents"/> parameter value is already encrypted.</exception>
205
+
<exceptioncref="T:System.InvalidOperationException">The PFX is already sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="true"/>).</exception>
<paramname="safeContents">The contents to add to the PFX.</param>
229
+
<summary>Add contents to the PFX without encrypting them.</summary>
230
+
<remarks>
231
+
<formattype="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
+
<exceptioncref="T:System.ArgumentNullException">The <paramrefname="safeContents"/> parameter is <seelangword="null"/>.</exception>
242
+
<exceptioncref="T:System.InvalidOperationException">The PFX is already sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="true"/>).</exception>
175
243
</Docs>
176
244
</Member>
177
245
<MemberMemberName="Encode">
@@ -192,9 +260,12 @@
192
260
</ReturnValue>
193
261
<Parameters />
194
262
<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>
<exceptioncref="T:System.InvalidOperationException">The PFX is not sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="false"/>).</exception>
198
269
</Docs>
199
270
</Member>
200
271
<MemberMemberName="IsSealed">
@@ -214,9 +285,11 @@
214
285
<ReturnType>System.Boolean</ReturnType>
215
286
</ReturnValue>
216
287
<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>
<paramname="password">The password to use as a key for computing the MAC.</param>
318
+
<paramname="hashAlgorithm">The hash algorithm to use when computing the MAC.</param>
319
+
<paramname="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
+
<formattype="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
+
<exceptioncref="T:System.ArgumentOutOfRangeException">The <paramrefname="iterationCount"/> parameter is less than or equal to 0.</exception>
335
+
<exceptioncref="T:System.InvalidOperationException">The PFX is already sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="true"/>).</exception>
<paramname="password">The password to use as a key for computing the MAC.</param>
361
+
<paramname="hashAlgorithm">The hash algorithm to use when computing the MAC.</param>
362
+
<paramname="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
+
<formattype="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
+
<exceptioncref="T:System.ArgumentOutOfRangeException">The <paramrefname="iterationCount"/> parameter is less than or equal to 0.</exception>
378
+
<exceptioncref="T:System.InvalidOperationException">The PFX is already sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="true"/>).</exception>
278
379
</Docs>
279
380
</Member>
280
381
<MemberMemberName="SealWithoutIntegrity">
@@ -295,8 +396,18 @@
295
396
</ReturnValue>
296
397
<Parameters />
297
398
<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
+
<formattype="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
+
<exceptioncref="T:System.InvalidOperationException">The PFX is already sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="true"/>).</exception>
<paramname="destination">The byte span to receive the PKCS#12 PFX data.</param>
435
+
<paramname="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramrefname="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><seelangword="true"/> if <paramrefname="destination"/> is big enough to receive the output; otherwise, <seelangword="false"/>.</returns>
327
438
<remarks>To be added.</remarks>
439
+
<exceptioncref="T:System.InvalidOperationException">The PFX is not sealed (<seecref="P:System.Security.Cryptography.Pkcs.Pkcs12Builder.IsSealed"/> is <seelangword="false"/>).</exception>
0 commit comments