dotnet / dotnet/dotnet-api-docs
Improve language for platform-specific cryptographic primitives when steering toward factory methods
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
Some cryptographic implementations like ECDiffieHellmanCng, ECDiffieHellmanOpenSsl (repeat for RSA, DSA, ECDsas) have language something to the affect of:
> This class should only be used directly when doing platform interop with the system OpenSSL library. When platform interop is not needed, you should use the [ECDiffieHellman.Create](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.ecdiffiehellman.create?view=net-7.0) factory methods instead of a specific derived implementation.
Some feedback has shown that this language isn't necessary clear in some cases, such as noted in https://github.com/dotnet/runtime/issues/89006#issuecomment-1638775213.
Some types lack this remark entirely, like ECDiffieHellmanCng.
Desired outcomes:
1. All platform-specific cryptographic primitives clearly note when it is more appropriate to use the .Create() factory method.
2. The language is consistent. The text in RSAOpenSsl seems better than ECDiffieHellmanOpenSsl.
Contributor guide
Assessment
This issue has not been assessed yet.