Skip to content

Commit 51e8ae8

Browse files
bartonjsThraka
authored andcommitted
Document Pkcs12SafeBag (#2921)
* Document Pkcs12SafeBag * Closing tags is good.
1 parent 48651a0 commit 51e8ae8

File tree

1 file changed

+45
-20
lines changed

1 file changed

+45
-20
lines changed

xml/System.Security.Cryptography.Pkcs/Pkcs12SafeBag.xml

Lines changed: 45 additions & 20 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>Defines the core behavior of a SafeBag value from the PKCS#12 specification and provides a base for derived classes.</summary>
1919
<remarks>To be added.</remarks>
2020
</Docs>
2121
<Members>
@@ -37,11 +37,24 @@
3737
<Parameter Name="skipCopy" Type="System.Boolean" />
3838
</Parameters>
3939
<Docs>
40-
<param name="bagIdValue">To be added.</param>
41-
<param name="encodedBagValue">To be added.</param>
42-
<param name="skipCopy">To be added.</param>
43-
<summary>To be added.</summary>
44-
<remarks>To be added.</remarks>
40+
<param name="bagIdValue">The Object Identifier (OID), in dotted decimal form, indicating the data type of this SafeBag.</param>
41+
<param name="encodedBagValue">The ASN.1 BER encoded value of the SafeBag contents.</param>
42+
<param name="skipCopy"><see langword="true"/> to store <paramref name="encodedBagValue"/> without making a defensive copy; otherwise, <see langword="false"/>. The default is <see langword="false"/>.</param>
43+
<summary>Called from constructors in derived classes to initialize the <see cref="T:System.Security.Cryptography.Pkcs12.Pkcs12SafeBag"/> class.</summary>
44+
<remarks>
45+
<format type="text/markdown"><![CDATA[
46+
## Remarks
47+
The default behavior of this method is to make a defensive copy of `encodedBagValue`.
48+
When the `skipCopy` parameter is `true`, this defensive copy is skipped.
49+
If the defensive copy is skipped and the contents of `encodedBagValue` change during the lifetime of the value, or any object produced by its
50+
methods or properties, then methods and properties on those objects may produce nonsense results or throw exceptions due to the corrupted state.
51+
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.
52+
53+
If the `bagIdValue` is not a legal dotted decimal format of an OID value an exception will be thrown from <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag.Encode> or <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag.TryEncode>.
54+
]]></format>
55+
</remarks>
56+
<exception cref="T:System.ArgumentNullException">The <paramref name="bagIdValue"/> parameter is <see langword="null"/> or the empty string.</exception>
57+
<exception cref="T:System.Security.Cryptography.CryptographicException">The <paramref name="encodedBagValue"/> parameter does not represent a single ASN.1 BER-encoded value.</exception>
4558
</Docs>
4659
</Member>
4760
<Member MemberName="Attributes">
@@ -61,8 +74,8 @@
6174
<ReturnType>System.Security.Cryptography.CryptographicAttributeObjectCollection</ReturnType>
6275
</ReturnValue>
6376
<Docs>
64-
<summary>To be added.</summary>
65-
<value>To be added.</value>
77+
<summary>Gets the modifiable collection of attributes to encode with the SafeBag value.</summary>
78+
<value>The modifiable collection of attributes to encode with the SafeBag value.</value>
6679
<remarks>To be added.</remarks>
6780
</Docs>
6881
</Member>
@@ -84,9 +97,10 @@
8497
</ReturnValue>
8598
<Parameters />
8699
<Docs>
87-
<summary>To be added.</summary>
88-
<returns>To be added.</returns>
100+
<summary>Encodes the SafeBag value and returns it as a byte array.</summary>
101+
<returns>A byte array representing the encoded form of the SafeBag.</returns>
89102
<remarks>To be added.</remarks>
103+
<exception cref="T:System.Security.Cryptography.CryptographicException">The object identifier value passed to the constructor was invalid.</exception>
90104
</Docs>
91105
</Member>
92106
<Member MemberName="EncodedBagValue">
@@ -106,9 +120,19 @@
106120
<ReturnType>System.ReadOnlyMemory&lt;System.Byte&gt;</ReturnType>
107121
</ReturnValue>
108122
<Docs>
109-
<summary>To be added.</summary>
110-
<value>To be added.</value>
111-
<remarks>To be added.</remarks>
123+
<summary>Gets the ASN.1 BER encoding of the contents of this SafeBag.</summary>
124+
<value>The ASN.1 BER encoding of the contents of this SafeBag.</value>
125+
<remarks>
126+
<format type="text/markdown"><![CDATA[
127+
128+
## Remarks
129+
130+
In the encoded structure, the SafeBag.bagValue value is tagged as `[0] EXPLICIT`. The value of this property is only the contents within the explicit tag.
131+
The explicit tag is automatically applied by <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag.Encode> or <xref:System.Security.Cryptography.Pkcs.Pkcs12SafeBag.TryEncode>,
132+
and is removed during <xref:System.Security.Cryptography.Pkcs12.Pkcs12Info.Decode%2A> and similar methods.
133+
134+
]]></format>
135+
</remarks>
112136
</Docs>
113137
</Member>
114138
<Member MemberName="GetBagId">
@@ -129,8 +153,8 @@
129153
</ReturnValue>
130154
<Parameters />
131155
<Docs>
132-
<summary>To be added.</summary>
133-
<returns>To be added.</returns>
156+
<summary>Gets the Object Identifier (OID) identifying the content type of this SafeBag.</summary>
157+
<returns>The Object Identifier (OID) identifying the content type of this SafeBag.</returns>
134158
<remarks>To be added.</remarks>
135159
</Docs>
136160
</Member>
@@ -155,12 +179,13 @@
155179
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" />
156180
</Parameters>
157181
<Docs>
158-
<param name="destination">To be added.</param>
159-
<param name="bytesWritten">To be added.</param>
160-
<summary>To be added.</summary>
161-
<returns>To be added.</returns>
182+
<param name="destination">The byte span to receive the encoded SafeBag value.</param>
183+
<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>
184+
<summary>Attempts to encode the SafeBag value into a provided buffer.</summary>
185+
<returns><see langword="true"/> if <paramref name="destination"/> is big enough to receive the output; otherwise, <see langword="false"/>.</returns>
162186
<remarks>To be added.</remarks>
187+
<exception cref="T:System.Security.Cryptography.CryptographicException">The object identifier value passed to the constructor was invalid.</exception>
163188
</Docs>
164189
</Member>
165190
</Members>
166-
</Type>
191+
</Type>

0 commit comments

Comments
 (0)