838775 - Documentation for PSM/NSS is atrocious

Status: RESOLVED WONTFIX

(Core :: Security: PSM, defect)

Description

[[:mmc] Monica Chew (no longer reading bugmail)]

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.

Comment 1

[[:mmc] Monica Chew (no longer reading bugmail)]

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

[Brian Smith (:briansmith, :bsmith, use NEEDINFO?)]

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

[Brian Smith (:briansmith, :bsmith, use NEEDINFO?)]

(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.

Comment 4

[[:mmc] Monica Chew (no longer reading bugmail)]

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)

Comment 5

[[:mmc] Monica Chew (no longer reading bugmail)]

Camilo's been using the nssShutDown stuff recently, too, so maybe he's got some more feedback for documentation.

Comment 6

[Camilo Viecco (:cviecco)]

Monica, please split the bug into sub-bugs so that we can actually make some progress.

Comment 7

[[:mmc] Monica Chew (no longer reading bugmail)]

It looks like mhamrick may be interested in this, based on irc chats.

Comment 8

[Meadhbh Hamrick :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.

Comment 9

[[:mmc] Monica Chew (no longer reading bugmail)]

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.

Comment 10

[[:mmc] Monica Chew (no longer reading bugmail)]

This is never going to happen.