Closed Bug 838775 Opened 12 years ago Closed 10 years ago

Documentation for PSM/NSS is atrocious

Categories

(Core :: Security: PSM, defect)

x86_64
Linux
defect
Not set
normal

Tracking

()

RESOLVED WONTFIX

People

(Reporter: mmc, Unassigned)

Details

It would save everyone time if MDN pages on how to use PSM/NSS were up to date. This should include stuff like - best practices for initializing NSS - best practices for shutting down cleanly - which implementations are deprecated - which implementations are threadsafe https://developer.mozilla.org/en-US/docs/NSS_FAQ https://developer.mozilla.org/en-US/docs/Mozilla_Crypto_FAQ are badly out of date and probably doing more harm than good.
Assignee: nobody → mmc
It would probably make more sense for one of the potential PSM peers to do this, rather than someone who's only used NSS once.
Monica has some ideas of things that need to be documented. I think it would be good for her to propose some documentation, at least, and then we can work together to document things better.
(In reply to Monica Chew from comment #1) > It would probably make more sense for one of the potential PSM peers to do > this, rather than someone who's only used NSS once. Right now, there's so much undocumented stuff that it's not clear where to even get started. I think it would be good to at least get your input as to what needs documented, especially since you are least familiar with the code but you have had to interact with it, and it seemed like you had some ideas already for what should be documented. David and Camilo's suggestions for the documentation would also be good.
The easiest thing for developers is to have an in-order list of things they need to do to call anything in NSS safely. Things I needed to know: - nsICryptoHash is deprecated in favor of NSS, and is not threadsafe anyway. Don't use it except from JS. - Don't use the mfbt implementation of SHA-1. - NSS must be initialized by initializing the PSM service on the main thread, it's OK to access it on worker threads after that. - There's no documentation on what header files in NSS it's ok or recommended to use, of https://mxr.mozilla.org/mozilla-central/source/security/manager/ssl/src/Makefile.in#98 - NSS resources must never be used after NSS is shutdown. Callers should subclass nsNSSShutDownObject and call isAlreadyShutDown. - Take nsNSSShutDownPreventionLock within blocks that call NSS to make sure NSS does not change state within the block. - NSS resources must be deallocated in nsNSSShutDownObject::destructorSafeDestroyNSSReference(), the comments in https://mxr.mozilla.org/mozilla-central/source/security/manager/ssl/src/nsNSSShutDown.h#183 were sufficiently clear. I think this makes the Scoped*Types useless, because we can never rely on NSS being initialized in the scoped type destructor. Is there an example where they can be used safely? It would be useful to include list of NSS related bugs so people can learn from those mistakes (looks like double free, orphaned pointers, use after free mistakes are all easy to make)
Camilo's been using the nssShutDown stuff recently, too, so maybe he's got some more feedback for documentation.
Assignee: mmc → cviecco
Monica, please split the bug into sub-bugs so that we can actually make some progress.
Assignee: cviecco → mmc
It looks like mhamrick may be interested in this, based on irc chats.
Assignee: mmc → mhamrick
aye. the documentation is pretty crappy. i'm thinking i'll write some sample code for how to do various things, then write words around the code. kudos to mmc for providing a list of things to document.
Awesome :) Another important metric of crappiness is findability: whatever you do has got to be discoverable from searching mdn/mxr/your search engine of choice. sheppy may have some tips on that.
Assignee: mhamrick → nobody
This is never going to happen.
Status: NEW → RESOLVED
Closed: 10 years ago
Resolution: --- → WONTFIX
You need to log in before you can comment on or make changes to this bug.