dotnet / dotnet/dotnet-api-docs

Improve language for platform-specific cryptographic primitives when steering toward factory methods

Open
#9,146 1 comment 2 reactions 0 assignees View on GitHub
area-System.Security Pri3
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.