Documentation

[ShivCod]

Proper Documentation is not found to learn the library. if it is there Link/Path please.

[lennybacon]

What I’d like to see documented is also where in Windows it is used. I do a lot of cryptography on the OS but that is mostly SCHANNEL and CNG/CAPI. I’m curious what (system components) make use of the library. Maybe the question of how do I use it (syscalls) is answered by the first one.

[mlindgren]

Hi there! Currently, all of the documentation we have is in our headers, particularly symcrypt.h. We try to document the "public" APIs extensively, so if something is unclear or missing from the comments in the header file, please let us know and we'll update as necessary. The unit tests are the best place to look for sample code.

We realize that this is not ideal for ease of access, but as we're a small team and SymCrypt is a low-level crypto library which is usually consumed through higher level APIs (e.g. CNG or SCOSSL, adding documentation outside of the header files has not been a priority for us. (To answer @lennybacon's question, CNG is built on top of SymCrypt and we do recommend continuing to use CNG for Windows-specific code.) This is something we'd like to improve in the future if resourcing allows, but I can't make any promises at this point.

One option we've looked into is being able to auto-generate HTML documentation from the header files, but the existing solutions that we've looked at (e.g. Doxygen) seemed like they would require adding a lot of markup to our existing comments, and they don't appear to work well with our commenting style (e.g. we prefer to put comments after function declarations). If anyone has suggestions for a better tool to help with this, please let us know.

[lennybacon]

@mlindgren thanks for clarification and the recommendation! This is worth a lot.

What I would love to see, is more like an introduction tutorial. A few samples with explanations on how to use it (or you intend it to be used). But I know how much time and resources such things cost.

[ShivCod]

@mlindgren Good to see your response I just need one sample of how this library is used if you could please.