why is NSS_Initialize() missing from API docs?
Guenter
why is NSS_Initialize() not listed here:
http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc.html#1022864
or is there somewhere another API docu I've not yet found?
I'm 100% sure that I found it at some time, but unfortunately I didnt
bookmark it ...
I think I've read some time ago that NSS_Initialize() is now deprecated;
but if so nevertheless you should document it, and mention there that its
now deprecated.
Günter.
Nelson B Bolyard
> why is NSS_Initialize() not listed here:
> http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc.html#1022864
> or is there somewhere another API docu I've not yet found?
Because the sponsors of the NSS developers have put all their emphasis on
development of code, and not on documentation.
> I'm 100% sure that I found it at some time, but unfortunately I didnt
> bookmark it ...
> I think I've read some time ago that NSS_Initialize() is now deprecated;
> but if so nevertheless you should document it, and mention there that its
> now deprecated.
It is certainly not deprecated. NSS_Initialize is *THE* single most
flexible and powerful (and complex) way to initialize NSS. All the other
NSS_Init* functions are essentially wrapper functions for it.
I think it may be correctly said that some of the optional features that
can be enabled through the use of NSS_Initialize (such as
NSS_INIT_COOPERATE) are now deprecated, but NSS_Initialize itself is
certainly not.
> Günter.
Eddy Nigg
> On 2009-09-26 15:56 PDT, Guenter wrote:
>
>> why is NSS_Initialize() not listed here:
>> http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc.html#1022864
>> or is there somewhere another API docu I've not yet found?
>>
> Because the sponsors of the NSS developers have put all their emphasis on
> development of code, and not on documentation.
>
Like any other good Open Source project. One of the biggest failures for
OSS....
> It is certainly not deprecated. NSS_Initialize is *THE* single most
> flexible and powerful (and complex) way to initialize NSS.
And as that not documented?
--
Regards
Signer: Eddy Nigg, StartCom Ltd.
XMPP: star...@startcom.org
Blog: http://blog.startcom.org/
Twitter: http://twitter.com/eddy_nigg
Guenter
Am 27.09.2009, 06:57 Uhr, schrieb Nelson B Bolyard <nel...@bolyard.me>:
> On 2009-09-26 15:56 PDT, Guenter wrote:
>> why is NSS_Initialize() not listed here:
>> http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc.html#1022864
>> or is there somewhere another API docu I've not yet found?
>
> Because the sponsors of the NSS developers have put all their emphasis on
> development of code, and not on documentation.
ahhh yes, I see ....
then it gives me also no wonder why SSL_DIR is missing here:
https://developer.mozilla.org/en/NSS_reference/NSS_environment_variables
although its used by SECU_DefaultSSLDir():
http://archive.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_2_1_RTM/src/nss-3.2.1/mozilla/security/nss/cmd/lib/secutil.c
> I think it may be correctly said that some of the optional features that
> can be enabled through the use of NSS_Initialize (such as
> NSS_INIT_COOPERATE) are now deprecated, but NSS_Initialize itself is
> certainly not.
very interesting since exactly NSS_INIT_COOPERATE was the reason in first
place why I've posted here ...
can you perhaps explain a bit more about why its deprecated, and what to
use now?
thanks, Günter.
Wan-Teh Chang
> Hi,
> why is NSS_Initialize() not listed here:
> http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc.html#1022864
> or is there somewhere another API docu I've not yet found?
One reason was that we wanted to encourage people to use the
simpler NSS initialization functions such as NSS_Init, NSS_InitReadWrite,
or NSS_NoDB_Init. See
http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/security/nss/lib/nss/nss.h&rev=1.71&mark=173-174,198#173
I added a man page for NSS_Initialize:
https://developer.mozilla.org/en/NSS_Initialize
We can fix the documentation problem one function
at a time. Until then, the "NSS functions" page
(https://developer.mozilla.org/en/NSS_functions)
and the MXR source code cross reference
(http://mxr.mozilla.org/security/) have helped
my coworkers find the appropriate NSS functions
and use them correctly.
Wan-Teh
Guenter
Am 28.09.2009, 22:24 Uhr, schrieb Wan-Teh Chang <w...@google.com>:
> On Sat, Sep 26, 2009 at 3:56 PM, Guenter <tha...@4.spam> wrote:
>> Hi,
>> why is NSS_Initialize() not listed here:
>> http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc.html#1022864
>> or is there somewhere another API docu I've not yet found?
>
> One reason was that we wanted to encourage people to use the
> simpler NSS initialization functions such as NSS_Init, NSS_InitReadWrite,
> or NSS_NoDB_Init. See
> http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/security/nss/lib/nss/nss.h&rev=1.71&mark=173-174,198#173
>
> I added a man page for NSS_Initialize:
> https://developer.mozilla.org/en/NSS_Initialize
thank you very much - really nice!
Günter.
Nelson B Bolyard
> very interesting since exactly NSS_INIT_COOPERATE was the reason in first
> place why I've posted here ...
The PKCS#11 API standard defines two functions, C_Initialize & C_Finalize
in such a way that makes it difficult for two independent libraries running
in the same process to both use a common PKCS#11 module. If both try to
initialize a module, the second will get an error. When the first of
them finalizes the module, it finalizes the module for both. Essentially,
the only way for multiple libraries (or bodies of code) running in a
process to share a PKCS#11 module is for them to cooperate, and have one
of them be responsible for initialization and finalization, and the others
just "go along for the ride".
NSS_INIT_COOPERATE tells NSS to just "go along for the ride". It tells
NSS_Init to try to initialize any PKCS#11 modules, but if that fails with
the "already initialized" error, just ignore that error. NSS remembers
that flag, and later, when NSS_Shutdown is called, it does NOT call
C_Finalize. The idea is that NSS_INIT_COOPERATE tells NSS that some other
library is going to control the initialization and finalization of a
PKCS#11 module, so NSS should not forcefully finalize it.
To use this correctly, the application must ensure that some other code
initializes the PKCS#11 module, then NSS is initialized, and at shutdown
time, first NSS is shut down, then the other code is shutdown, and that
other code finalizes the PKCS#11 module. There are some (few) circum-
stances where this is feasible, but there are many more where it is not.
> can you perhaps explain a bit more about why its deprecated,
When this flag is set, there is NO WAY to get NSS to call C_Finalize on the
PKCS#11 modules it is using. But it is essential that C_Finalize get
called on PKCS#11 modules at various times for various purposes.
C_Finalize is what causes any buffers to be flushed and files to be closed.
But more importantly, on Unix/Linux systems, the PKCS#11 standard forbids
children from using modules that were inherited in an initialized state
from their parent via fork. That effectively means that prior to every
fork, every PKCS#11 module must be finalized, and after every fork, if
the parent needs to continue to use the module, the parent must
re-initialize it, and any new children who need it must initialize it.
It is possible to do this and get it right in some circumstances, but
unfortunately, we've seen numerous cases of application programmers who
used it incorrectly.
Perhaps it is fair to say that it is deprecated because few application
programs have ever used it correctly, and those who do not tend to blame
NSS for their problems. We're discouraging all but the best from using
it. But it's still supported, and I don't think it will go away soon.
> and what to use now?
Another related issue is when two libraries inside a process want to use NSS
independently of each other. It's the same problem as the PKCS#11
API has. They both want to initialize NSS. They both want to shut down
NSS. The first one to shut down pulls NSS out from under the other.
We're working on new variants of NSS_Initialize and NSS_Shutdown to
solve this problem. They may be in the next release of NSS. See
https://bugzilla.mozilla.org/show_bug.cgi?id=453495
Guenter
thanks very much for your detailed answer!
greets, Günter.