Closed
Bug 838775
Opened 12 years ago
Closed 10 years ago
Documentation for PSM/NSS is atrocious
Categories
(Core :: Security: PSM, defect)
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.
Updated•12 years ago
|
Assignee: nobody → mmc
Reporter | ||
Comment 1•12 years ago
|
||
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.
Comment 2•12 years ago
|
||
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.
Comment 3•12 years ago
|
||
(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.
Reporter | ||
Comment 4•12 years ago
|
||
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)
Reporter | ||
Comment 5•11 years ago
|
||
Camilo's been using the nssShutDown stuff recently, too, so maybe he's got some more feedback for documentation.
Assignee: mmc → cviecco
Comment 6•11 years ago
|
||
Monica, please split the bug into sub-bugs so that we can actually make some progress.
Assignee: cviecco → mmc
Reporter | ||
Comment 7•11 years ago
|
||
It looks like mhamrick may be interested in this, based on irc chats.
Assignee: mmc → mhamrick
Comment 8•11 years ago
|
||
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.
Reporter | ||
Comment 9•11 years ago
|
||
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.
Updated•11 years ago
|
Assignee: mhamrick → nobody
Reporter | ||
Comment 10•10 years ago
|
||
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.
Description
•