You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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 Daniel Fisher (@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.
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.
Activity
lennybacon commentedon Oct 7, 2024
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 commentedon Oct 7, 2024
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 Daniel Fisher (@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 commentedon Oct 8, 2024
Mitch Lindgren (@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 commentedon Oct 8, 2024
Mitch Lindgren (@mlindgren) Good to see your response I just need one sample of how this library is used if you could please.