Remove .NET Framework remarks (System.Security.Cryptography)#12655
Open
gewarren wants to merge 1 commit into
Open
Remove .NET Framework remarks (System.Security.Cryptography)#12655gewarren wants to merge 1 commit into
gewarren wants to merge 1 commit into
Conversation
github-actions
Bot
added
the
area-System.Security
Contributor
|
Tagging subscribers to this area: @dotnet/area-system-security, @vcsjones |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the .NET API reference XML docs in System.Security.Cryptography* to remove .NET Framework-specific remarks, exceptions, and usage notes now that .NET Framework API reference docs have moved to a separate repo.
Changes:
- Removed or rewrote remarks that referenced .NET Framework-only features and behaviors (CAS, app.config, AppDomains, framework-version notes).
- Normalized several exception descriptions to remove framework qualifiers (for example, “In all cases.”).
- Cleaned up and reflowed various remarks blocks and IMPORTANT/NOTE callouts.
Reviewed changes
Copilot reviewed 41 out of 41 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| xml/System.Security.Cryptography/SymmetricAlgorithm.xml | Rewords remarks to drop .NET Framework phrasing and adjusts Create() docs. |
| xml/System.Security.Cryptography/SHA256.xml | Removes .NET Framework-specific return/exception details for Create overloads. |
| xml/System.Security.Cryptography/RSACryptoServiceProvider.xml | Removes AppDomain/version-specific wording from UseMachineKeyStore remarks. |
| xml/System.Security.Cryptography/RSACng.xml | Removes .NET Framework version-specific exception behavior from VerifyHash docs. |
| xml/System.Security.Cryptography/RSA.xml | Removes .NET Framework version notes and normalizes exception text. |
| xml/System.Security.Cryptography/RijndaelManaged.xml | Removes .NET Framework vs .NET Core block-size distinctions, simplifying to modern .NET behavior. |
| xml/System.Security.Cryptography/ProtectedData.xml | Rewords Windows-only support notes and adds/updates PlatformNotSupportedException text. |
| xml/System.Security.Cryptography/Oid.xml | Updates property summaries to reflect init-only narrative (but signatures still show settable). |
| xml/System.Security.Cryptography/KeyedHashAlgorithm.xml | Removes .NET Framework versioning notes; normalizes PNSE text. |
| xml/System.Security.Cryptography/HMACSHA512.xml | Removes legacy .NET Framework 2.0 SP notes and replaces with placeholder remarks. |
| xml/System.Security.Cryptography/HMACSHA384.xml | Removes legacy .NET Framework 2.0 SP notes and replaces with placeholder remarks. |
| xml/System.Security.Cryptography/HMAC.xml | Removes config-system mention and normalizes PNSE text. |
| xml/System.Security.Cryptography/HashAlgorithm.xml | Removes obsoletion/version notes and normalizes PNSE text. |
| xml/System.Security.Cryptography/FromBase64Transform.xml | Converts markdown remarks to XML paragraphs for CanTransformMultipleBlocks. |
| xml/System.Security.Cryptography/ECDsa.xml | Rewords remarks/parameter guidance to remove .NET Framework mention. |
| xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml | Rewords PlatformNotSupportedException descriptions to remove framework qualifiers. |
| xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml | Normalizes whitespace and replaces some .NET Framework-specific remarks/exceptions. |
| xml/System.Security.Cryptography/ECDiffieHellmanCng.xml | Removes argument/format exception documentation and normalizes PNSE text. |
| xml/System.Security.Cryptography/ECDiffieHellman.xml | Rewords remarks to remove .NET Framework mention and reformats lists. |
| xml/System.Security.Cryptography/DSACryptoServiceProvider.xml | Removes AppDomain/version-specific wording from UseMachineKeyStore remarks. |
| xml/System.Security.Cryptography/CryptoStream.xml | Removes .NET Framework comparison from partial-read IMPORTANT notes and async remarks. |
| xml/System.Security.Cryptography/CryptoConfig.xml | Removes .NET Framework config file references and partial-trust/CAS-related remarks. |
| xml/System.Security.Cryptography/CngProvider.xml | Removes “service packs / .NET Framework releases” wording from remarks. |
| xml/System.Security.Cryptography/CngKeyBlobFormat.xml | Removes “service packs / .NET Framework releases” wording from remarks. |
| xml/System.Security.Cryptography/CngAlgorithmGroup.xml | Removes “service packs / .NET Framework releases” wording from remarks. |
| xml/System.Security.Cryptography/CngAlgorithm.xml | Removes “service packs / .NET Framework releases” wording from remarks. |
| xml/System.Security.Cryptography/AsymmetricAlgorithm.xml | Removes config-system mention and normalizes PNSE text. |
| xml/System.Security.Cryptography/AsnEncodedData.xml | Rewords remarks to remove .NET Framework mention and trims extra whitespace. |
| xml/System.Security.Cryptography.Xml/SignedXml.xml | Removes .NET Framework version-specific certificate-verification notes. |
| xml/System.Security.Cryptography.Xml/EncryptedXml.xml | Rewords remarks to remove .NET Framework mention and trims redundant constructor remarks. |
| xml/System.Security.Cryptography.X509Certificates/X509Store.xml | Removes .NET Framework version-based IDisposable guidance and replaces dispose remarks. |
| xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml | Rewords SyncRoot remarks to remove .NET Framework phrasing. |
| xml/System.Security.Cryptography.X509Certificates/X509Extension.xml | Rewords list intro to remove .NET Framework mention and reformats list. |
| xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml | Removes .NET Framework-introduced version note for certain flags. |
| xml/System.Security.Cryptography.X509Certificates/X509Chain.xml | Removes .NET Framework version-based IDisposable guidance and replaces dispose remarks. |
| xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml | Removes .NET Framework-only permission/version notes and normalizes PNSE text. |
| xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml | Removes .NET Framework version-based IDisposable guidance and replaces various remarks/exceptions. |
| xml/System.Security.Cryptography.Pkcs/SignerInfo.xml | Removes CAS permission notes and normalizes countersignature remarks spacing. |
| xml/System.Security.Cryptography.Pkcs/SignedCms.xml | Removes CAS permission notes; normalizes silent parameter doc and exception text. |
| xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml | Removes .NET Framework vs .NET Core algorithm-default notes and CAS permission remarks. |
| xml/System.Security.Cryptography.Pkcs/CmsSigner.xml | Removes .NET Framework-only support note and normalizes PNSE text. |
| <exception cref="T:System.NotSupportedException">The operating system does not support this method.</exception> | ||
| <exception cref="T:System.OutOfMemoryException">The system ran out of memory while encrypting the data.</exception> | ||
| <exception cref="T:System.PlatformNotSupportedException">.NET Core and .NET 5+ only: Calls to the <c>Protect</c> method are supported on Windows operating systems only.</exception> | ||
| <exception cref="T:System.PlatformNotSupportedException">The operation system is not Windows.</exception> |
| </ReturnValue> | ||
| <Docs> | ||
| <summary>Gets or sets the friendly name of the identifier.</summary> | ||
| <summary>Gets or initializes the friendly name of the identifier.</summary> |
| </ReturnValue> | ||
| <Docs> | ||
| <summary>Gets or sets the dotted number of the identifier.</summary> | ||
| <summary>Gets or initializes the dotted number of the identifier.</summary> |
|
|
||
| ## Remarks | ||
| This constructor is called by classes that derive from the <xref:System.Security.Cryptography.ECDiffieHellman> class. The <xref:System.Security.Cryptography.ECDiffieHellmanCng> class is the only implementation that is currently included in the .NET Framework. For information about how to create a new implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm, see the <xref:System.Security.Cryptography.ECDiffieHellman.Create*> method. | ||
| This constructor is called by classes that derive from the <xref:System.Security.Cryptography.ECDiffieHellman> class. The <xref:System.Security.Cryptography.ECDiffieHellmanCng> class is the only implementation that is currently included in the .NET. For information about how to create a new implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm, see the <xref:System.Security.Cryptography.ECDiffieHellman.Create*> method. |
|
|
||
| > [!IMPORTANT] | ||
| > In .NET 6 and later versions, when `Stream.Read` or `Stream.ReadAsync` is called with a buffer of length `N`, the operation completes when either at least 1 byte has been read from the stream, or the underlying stream that it wraps returns 0 from a call to `Read`, indicating no more data is available. In .NET Framework, `Stream.Read` and `Stream.ReadAsync` do not return until all `N` bytes have been read from the stream or the underlying stream returns 0 from a call to `Read`. If your code assumes the `Read` methods won't return until all `N` bytes have been read, it could fail to read all the content. For more information, see [Partial and zero-byte reads in streams](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). | ||
| > When `Stream.Read` or `Stream.ReadAsync` is called with a buffer of length `N`, the operation completes when either at least 1 byte has been read from the stream, or the underlying stream that it wraps returns 0 from a call to `Read`, indicating no more data is available. If your code assumes the `Read` methods won't return until all `N` bytes have been read, it could fail to read all the content. For more information, see [Partial and zero-byte reads in streams](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). |
Comment on lines
+292
to
+293
| <para>Prior to .NET 5, only one block can be transformed at a time, so this property returns `false`.</para> | ||
| <para>Starting in .NET 5, multiple blocks can be transformed, so this property returns `true`.</para> |
| All cryptographic classes in the .NET Framework that hold sensitive data implement a `Clear` method. When called, the `Clear` method overwrites all sensitive data within the object with zeros and then releases the object so that it can be safely garbage collected. When the object has been zeroed and released, you should then call the `Dispose` method with the `disposing` parameter set to `True` to dispose of all managed and unmanaged resources associated with the object. | ||
|
|
||
|
|
||
| All cryptographic classes in .NET that hold sensitive data implement a `Clear` method. When called, the `Clear` method overwrites all sensitive data within the object with zeros and then releases the object so that it can be safely garbage collected. When the object has been zeroed and released, you should then call the `Dispose` method with the `disposing` parameter set to `True` to dispose of all managed and unmanaged resources associated with the object. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
.NET Framework API ref has moved to its own repo (https://github.com/dotnet/dotnetfw-api-docs), so we can clean up .NET Framework remarks, exceptions, and code examples out of this repo. Contributes to #12513.
Removes remarks and examples related to:
Also remarks all remarks from obsolete APIs.
Hide whitespace changes