Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update x500DistinguishedName snippets to include relevant code #7328

Merged
merged 4 commits into from
Jun 5, 2024

Conversation

bderusha
Copy link
Contributor

Summary

Adds x500DistinguishedNameFlag example to the general x500DistinguishedName snippets making the snippet more relevant to the X500DistinguishedNameFlags documentation page.

Fixes #7327

@bderusha bderusha requested a review from a team as a code owner October 27, 2021 20:01
@dotnet-issue-labeler dotnet-issue-labeler bot added the area-System.Security Issues related to security practices for .NET developers. label Oct 27, 2021
@ghost
Copy link

ghost commented Oct 27, 2021

Tagging subscribers to this area: @bartonjs, @vcsjones, @krwq, @GrabYourPitchforks
See info in area-owners.md if you want to be subscribed.

Issue Details

Summary

Adds x500DistinguishedNameFlag example to the general x500DistinguishedName snippets making the snippet more relevant to the X500DistinguishedNameFlags documentation page.

Fixes #7327

Author: bderusha
Assignees: -
Labels:

area-System.Security

Milestone: -

@dnfadmin
Copy link

dnfadmin commented Oct 27, 2021

CLA assistant check
All CLA requirements met.

@opbld34
Copy link

opbld34 commented Oct 27, 2021

Docs Build status updates of commit d38e40c:

✅ Validation status: passed

File Status Preview URL Details
samples/snippets/cpp/VS_Snippets_CLR/Cryptography.X509Certificates.X500DistinguishedName/CPP/x500.cpp ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR/Cryptography.X509Certificates.X500DistinguishedName/CS/x500.cs ✅Succeeded View
samples/snippets/visualbasic/VS_Snippets_CLR/Cryptography.X509Certificates.X500DistinguishedName/VB/x500.vb ✅Succeeded View

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

@jimbobmcgee
Copy link

Just a two-cents opinion from an end-user who discovered this issue whilst looking at the documentation for X500DistinguishedNameFlags but, while updating the snippet to actually use the enum is a great first step, it isn't hard to intuit how to use it from the X500DistinguishedName constructor itself, if you are familiar with the language.

What would be useful is if the documentation indicated whether using the enum affected how the input string was parsed or validated, or just set some property of the resulting X500DistinguishedName object.

For instance, one of the flags values is DoNotUsePlusSign, and the description for this is "The distinguished name does not use the plus sign.". If the input string to new X500DistinguishedName(...) did in fact contain a plus sign, what happens? An exception? Some automatic re-encoding of the input string? Some automatic re-encoding of the .ToString() output? It is not immediately clear from either the main description of X500DistinguishedNameFlags or the X500DistinguishedName(string, X500DistinguishedNameFlags) constructor.

If the example code instead used some literal input strings, and described the resulting output, e.g. something of the form...

(new X509DistinguishedName("CN=foo,O=Fabrikam+Co.,C=US", X509DistinguishedNameFlags.Reversed).ToString();    // returns "C=US,O=Fabrikam+Co.,CN=foo"
(new X509DistinguishedName("CN=foo,O=Fabrikam+Co.,C=US", X509DistinguishedNameFlags.DoNotUsePlusSign).ToString();    // throws SomethingException

...(but accurate), that might be more demonstrative of this enum.

Copy link

Learn Build status updates of commit ddc8a3b:

✅ Validation status: passed

File Status Preview URL Details
snippets/cpp/VS_Snippets_CLR/Cryptography.X509Certificates.X500DistinguishedName/CPP/x500.cpp ✅Succeeded
snippets/csharp/System.Security.Cryptography.X509Certificates/X500DistinguishedName/Overview/x500.cs ✅Succeeded View
snippets/visualbasic/VS_Snippets_CLR/Cryptography.X509Certificates.X500DistinguishedName/VB/x500.vb ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@gewarren gewarren merged commit fddd7a8 into dotnet:main Jun 5, 2024
3 checks passed
@bderusha bderusha deleted the bderusha/update-x500-samples branch June 6, 2024 13:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-System.Security Issues related to security practices for .NET developers.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

X500DistinguishedNameFlags examples do not contain relevant snippets
5 participants