source: postlfs/security/nss.xml@ faa948c

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

<!-- for when .0 is not part of the new tarball name, but always referenced -->
<!ENTITY nss-url "archive.mozilla.org/pub/security/nss/releases">

<!-- micro versions-->
<!--<!ENTITY nss-download-http "https://&nss-url;/NSS_3_&nss-minor-version;_&nss-micro-version;_RTM/src/nss-&nss-version;.tar.gz">-->

<!-- no micro versions -->
  <!ENTITY nss-download-http "https://&nss-url;/NSS_&nss-dir;_RTM/src/nss-&nss-version;.tar.gz">
  <!ENTITY nss-download-ftp  " ">
  <!ENTITY nss-md5sum        "589167c3be81d09b9e332ff17d46ebca">
  <!ENTITY nss-size          "69 MB">
  <!ENTITY nss-buildsize     "299 MB (add 261 MB for tests)">
  <!ENTITY nss-time          "1.2 SBU (with parallelism=4, add 15 SBU for tests on AMD Ryzens or at least 30 SBU on Intel machines)">
  <!-- On my system, I got 64.2 SBU, but Bruce gets 18 SBU. -renodr -->
  <!-- On my system, I got 63 SBU, but Xi gets ~18 SBU. -pierre (for 3.78) -->
  <!-- On my 3400G for 3.79 I got 16 SBU -ken -->
  <!-- Still 17 SBU for 3.81 - bdubbs -->
  <!-- 73 SBU but I'm on Intel. -renodr -->
  <!-- 3.86 amended the figures -ken
   3400G 14 SBU with 6.0.12, but the remeasured SBU has become very slow
   and maybe other people would see a ster SBU on a fresh build;
   i7-4790 35 SBU with 6.0.12, no failures
   Bruce's 3900X 19.3 SBU, his i7-12700K about 30 SBU, 12 failures 

   3.90: 
     Passed:             68593
     Failed:             0
     Failed with core:   0
     ASan failures:      0
     Unknown status:     2
     TinderboxPrint:Unknown: 2
   -->
]>

<sect1 id="nss" xreflabel="nss-&nss-version;">
  <?dbhtml filename="nss.html"?>


  <title>NSS-&nss-version;</title>

  <indexterm zone="nss">
    <primary sortas="a-NSS">NSS</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to NSS</title>

    <para>
      The Network Security Services (<application>NSS</application>) package is
      a set of libraries designed to support cross-platform development of
      security-enabled client and server applications. Applications built with
      NSS can support SSL v2 and v3, TLS, PKCS #5, PKCS #7, PKCS #11, PKCS #12,
      S/MIME, X.509 v3 certificates, and other security standards. This is
      useful for implementing SSL and S/MIME or other Internet security
      standards into an application.
    </para>

    &lfs120_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&nss-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&nss-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &nss-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &nss-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &nss-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &nss-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/nss-&nss-version;-standalone-1.patch"/>
        </para>
      </listitem>
<!--
      <listitem>
        <para>
          Required patch for processors lacking the <quote>adx</quote>
          instruction set:
          <ulink url="&patch-root;/nss-&nss-version;-illegal_instruction-1.patch"/>
        </para>
      </listitem>
-->
    </itemizedlist>

    <bridgehead renderas="sect3">NSS Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="nspr"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="sqlite"/> and
      <xref role="runtime" linkend="p11-kit"/> (runtime)
    </para>

    <para condition="html" role="usernotes">
      Editor Notes: <ulink url="&blfs-wiki;/nss"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of NSS</title>

<!--
    <note>
      <para>
        Some old generations processors lack an assembler instruction that
        is generated unconditionally by NSS-3.90. It leads to an
        "illegal instruction" fault when running firefox. The availability
        of this instruction is asserted by the <quote>adx</quote> flag
        in <filename>/proc/cpuinfo</filename>. If this flag is not set,
        apply the following patch:
      </para>
    </note>

<screen><userinput>grep -q adx /proc/cpuinfo || \
patch -Np1 -i ../nss-&nss-version;-illegal_instruction-1.patch</userinput></screen>

-->
    <para>
      Install <application>NSS</application> by running the following commands:
    </para>

<screen><userinput>patch -Np1 -i ../nss-&nss-version;-standalone-1.patch &amp;&amp;

cd nss &amp;&amp;

make BUILD_OPT=1                  \
  NSPR_INCLUDE_DIR=/usr/include/nspr  \
  USE_SYSTEM_ZLIB=1                   \
  ZLIB_LIBS=-lz                       \
  NSS_ENABLE_WERROR=0                 \
  $([ $(uname -m) = x86_64 ] &amp;&amp; echo USE_64=1) \
  $([ -f /usr/include/sqlite3.h ] &amp;&amp; echo NSS_USE_SYSTEM_SQLITE=1)</userinput></screen>

    <para>
      <!-- the unittest files get compiled automatically since nss-3.31.0 -->
      To run the tests, execute the following commands<!--(1 test is known to fail)-->:
    </para>

<screen remap="test"><userinput>cd tests &amp;&amp;
HOST=localhost DOMSUF=localdomain ./all.sh
cd ../</userinput></screen>

    <note>
      <para>Some information about the tests:</para>
      <itemizedlist spacing="compact">
      <listitem>
        <para>
           HOST=localhost and DOMSUF=localdomain are required.
           Without these variables, a FQDN is
           required to be specified and this generic way should work for
           everyone, provided <systemitem>localhost.localdomain</systemitem>
           is defined in <filename>/etc/hosts</filename>, as done in
           <ulink url="&lfs-root;/chapter09/network.html#ch-config-hosts">the
           LFS book</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
           The tests take a long time to run. If desired there is
           information in the all.sh script about running subsets of the
           total test suite.
        </para>
      </listitem>
      <listitem>
        <para>
           When interrupting the tests, the test suite
           fails to spin down test servers that are run. This leads to an
           infinite loop in the tests where the test suite tries to kill a server
           that doesn't exist anymore because it pulls the wrong PID.
        </para>
      </listitem>
      <listitem>
        <para>
           Test suite results (in HTML format!) can be found at
           ../../test_results/security/localhost.1/results.html
        </para>
      </listitem>
      <listitem>
        <para>
           A few tests might fail on some Intel machines for unknown reasons.
        </para>
      </listitem>
      </itemizedlist>
     </note>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>cd ../dist                                                          &amp;&amp;

install -v -m755 Linux*/lib/*.so              /usr/lib              &amp;&amp;
install -v -m644 Linux*/lib/{*.chk,libcrmf.a} /usr/lib              &amp;&amp;

install -v -m755 -d                           /usr/include/nss      &amp;&amp;
cp -v -RL {public,private}/nss/*              /usr/include/nss      &amp;&amp;

install -v -m755 Linux*/bin/{certutil,nss-config,pk12util} /usr/bin &amp;&amp;

install -v -m644 Linux*/lib/pkgconfig/nss.pc  /usr/lib/pkgconfig</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>BUILD_OPT=1</parameter>: This option is passed to
      <command>make</command> so that the build is performed with no debugging
      symbols built into the binaries and the default compiler optimizations are
      used.
    </para>

    <para>
      <parameter>NSPR_INCLUDE_DIR=/usr/include/nspr</parameter>: This option
      sets the location of the nspr headers.
    </para>

    <para>
      <parameter>USE_SYSTEM_ZLIB=1</parameter>: This option is passed to
      <command>make</command> to ensure that the
      <filename class="libraryfile">libssl3.so</filename> library is linked to
      the system installed <application>zlib</application> instead of the
      in-tree version.
    </para>

    <para>
      <parameter>ZLIB_LIBS=-lz</parameter>: This option provides the
      linker flags needed to link to the system <application>zlib</application>.
    </para>

    <para>
      <command>$([ $(uname -m) = x86_64 ] &amp;&amp; echo USE_64=1)</command>:
      The <parameter>USE_64=1</parameter> option is <emphasis>required on
      x86_64</emphasis>, otherwise <command>make</command> will try (and fail)
      to create 32-bit objects. The [ $(uname -m) = x86_64 ] test ensures it
      has no effect on a 32 bit system.
    </para>

    <para>
      <command>([ -f /usr/include/sqlite3.h ] &amp;&amp; echo
      NSS_USE_SYSTEM_SQLITE=1)</command>: This tests if
      <application>sqlite</application> is installed and if so it
      <command>echo</command>s the option NSS_USE_SYSTEM_SQLITE=1 to
      <command>make</command> so that
      <filename class="libraryfile">libsoftokn3.so</filename> will link against
      the system version of sqlite.
    </para>

    <para>
      <option>NSS_DISABLE_GTESTS=1</option>: If you don't need to run
      NSS test suite, append this option to <command>make</command> command,
      to prevent the compilation of tests and save some build time.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring NSS</title>

    <para>
      If <xref linkend="p11-kit"/> is installed, the
      <application>p11-kit</application> trust module
      (<filename>/usr/lib/pkcs11/p11-kit-trust.so</filename>) can be used as a
      drop-in replacement for <filename>/usr/lib/libnssckbi.so</filename> to
      transparently make the system CAs available to
      <application>NSS</application> aware applications, rather than the static
      list provided by <filename>/usr/lib/libnssckbi.so</filename>. As the
      <systemitem class="username">root</systemitem> user, execute the following
      command:
    </para>

<screen role="root"><userinput>ln -sfv ./pkcs11/p11-kit-trust.so /usr/lib/libnssckbi.so</userinput></screen>

    <para>
      Additionally, for dependent applications that do not use the internal
      database (<filename>/usr/lib/libnssckbi.so</filename>), the
      <filename>/usr/sbin/make-ca</filename> script included on the
      <xref linkend="make-ca"/> page can generate a system wide NSS DB with the
      <parameter>-n</parameter> switch, or by modifying the
      <filename>/etc/make-ca/make-ca.conf</filename> file.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          certutil, nss-config, and pk12util
        </seg>
        <seg>
          libcrmf.a, libfreebl3.so, libfreeblpriv3.so,
          libnss3.so, libnssckbi.so, libnssckbi-testlib.so,
          libnssdbm3.so, libnsssysinit.so, libnssutil3.so,
          libpkcs11testmodule.so, libsmime3.so, libsoftokn3.so,
          and libssl3.so
        </seg>
        <seg>
          /usr/include/nss
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="certutil">
        <term><command>certutil</command></term>
        <listitem>
          <para>
            is the Mozilla Certificate Database Tool. It is a command-line
            utility that can create and modify the Netscape Communicator
            cert8.db and key3.db database files. It can also list, generate,
            modify, or delete certificates within the cert8.db file and create
            or change the password, generate new public and private key pairs,
            display the contents of the key database, or delete key pairs within
            the key3.db file
          </para>
          <indexterm zone="nss certutil">
            <primary sortas="b-certutil">certutil</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nss-config">
        <term><command>nss-config</command></term>
        <listitem>
          <para>
            is used to determine the NSS library settings of the installed NSS
            libraries
          </para>
          <indexterm zone="nss nss-config">
            <primary sortas="b-nss-config">nss-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pk12util">
        <term><command>pk12util</command></term>
        <listitem>
          <para>
            is a tool for importing certificates and keys from pkcs #12 files
            into NSS or exporting them. It can also list certificates and keys
            in such files
          </para>
          <indexterm zone="nss pk12util">
            <primary sortas="b-pk12util">pk12util</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>