dotnet / dotnet/dotnet-api-docs

Improve or remove code examples for TripleDES, DES, and RC2.

Open
#8,140 3 comments 0 reactions 0 assignees View on GitHub
area-System.Security Pri3 untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

We have a number of examples for using these symmetric ciphers that I think either need to be significantly improved, or removed.

1. They demonstrate incorrect use of `CryptoStream`. Ex: https://github.com/dotnet/dotnet-api-docs/blob/13d97c7e536ce822c000883dba873a79d5d6e841/snippets/csharp/System.Security.Cryptography/DES/Create/memoryexample.cs#L99
2. They are incomplete examples. They, for example, do not demonstrate proper nonce management, they do not demonstrate proper authentication (authentication in cryptographic terms). It would be rather hard to demonstrate how to do these things properly in short examples, and nor do I think it's something that should be in API documentation.

The `CryptoStream` issue doesn't apply to `Aes` because we don't have that example for `Aes`, but we do have them for the other symmetric ciphers.

If we want to keep the examples, then they need to be re-written to 1. be correct 2. use modern APIs and 3. be heavily caveated that they are incomplete examples and do not demonstrate safe examples of using symmetric encryption.

/cc @bartonjs @GrabYourPitchforks

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.