source: postlfs/security/nss.xml@ d4eee5e0

<?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;

  <!ENTITY nss-download-http "http://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_13_1_RTM/src/nss-&nss-version;.tar.gz">
  <!ENTITY nss-download-ftp  "ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_13_1_RTM/src/nss-&nss-version;.tar.gz">
  <!ENTITY nss-md5sum        "c500f96d33ba1390c8a35c667e05e542">
  <!ENTITY nss-size          "5.7 MB">
  <!ENTITY nss-buildsize     "44 MB (more than double this to run the test suite)">
  <!ENTITY nss-time          "0.7 SBU (at least an additional 3.5 SBU to run the test suite)">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

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

    &lfs70_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>
    </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"/> (internal sqlite is
    incompatable with existing or future installations)</para>


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

  </sect2>

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

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

<screen><userinput>bash
[ $(arch) = x86_64 ] &amp;&amp; export USE_64=1
export BUILD_OPT=1 &amp;&amp;
cat /usr/include/sqlite3.h &amp;&gt; /dev/null &amp;&amp;
export NSS_USE_SYSTEM_SQLITE=1
export NSPR_INCLUDE_DIR=/usr/include/nspr &amp;&amp;
export USE_SYSTEM_ZLIB=1 &amp;&amp;
export ZLIB_LIBS=-lz &amp;&amp;
patch -Np1 -i ../nss-&nss-version;-standalone-1.patch &amp;&amp;
make -C mozilla/security/nss nss_build_all</userinput></screen>

    <para>If you wish to test the results, you'll need to set the domain name of
    your system in the <envar>DOMSUF</envar> environment variable. Most of the
    tests will fail if you don't provide the correct domain name. The voluminous
    output will report how many of the several thousand tests passed, and if any
    failed.  To review the details of any failures, you may wish to capture
    stdout and stderr in a file.</para>

    <para>To run the tests, ensure you change the
    <command>export DOMSUF</command> command below to an appropriate value,
    e.g., <parameter>mydomain.com</parameter> or, if you do not have any domain
    in your <filename>/etc/hosts</filename> replace this with the developers'
    recommendation of
    <command>"export HOST=localhost DOMSUF=localdomain"</command> and issue the
    following commands:</para>

<screen><userinput>bash

export NSS_LINUXDIR=$(basename `ls -d $PWD/mozilla/dist/Linux*`) &amp;&amp;
export DOMSUF=<replaceable>&lt;validdomain.name&gt;</replaceable> &amp;&amp;
export PATH=$PATH:$PWD/mozilla/dist/$NSS_LINUXDIR/bin &amp;&amp;
export TEST_RESULTSDIR=$PWD/mozilla/tests_results/security &amp;&amp;

cd mozilla/security/nss/tests &amp;&amp;
sed -i 's/gmake/make/' common/init.sh &amp;&amp;
./all.sh &amp;&amp;

grep Passed $TEST_RESULTSDIR/$(hostname).1/results.html | wc -l &amp;&amp;

exit</userinput></screen>

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

<screen role="root"><userinput>export NSS_LINUXDIR=$(basename `ls -d $PWD/mozilla/dist/Linux*`) &amp;&amp;
cd mozilla/dist &amp;&amp;
install -v -m755 $NSS_LINUXDIR/lib/*.so /usr/lib &amp;&amp;
install -v -m644 $NSS_LINUXDIR/lib/{*.chk,libcrmf.a} /usr/lib &amp;&amp;
install -v -m755 -d /usr/include/nss &amp;&amp;
install -v -m755 $NSS_LINUXDIR/bin/{certutil,nss-config,pk12util} /usr/bin &amp;&amp;
install -v -m644 $NSS_LINUXDIR/lib/pkgconfig/nss.pc /usr/lib/pkgconfig &amp;&amp;
cp -v -RL {public,private}/nss/* /usr/include/nss &amp;&amp;
chmod 644 /usr/include/nss/*</userinput></screen>

    <para>Now as the unprivileged user, exit the <command>bash</command>
    shell started at the beginning of the installation to restore the
    environment to the original state.</para>

<screen><userinput>exit</userinput></screen>

  </sect2>

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

    <para><command>bash</command>: Shells are started as many environment
    variables are created during the installation process. Exiting the shells
    serves the purpose of restoring the environment and returning back to the
    original directory when the installation is complete.</para>

    <para><command>[ $(arch) = x86_64 ] &amp;&amp; export USE_64=1</command>:
    This command is <emphasis>required on x86_64</emphasis>, otherwise the
    build will attempt to create 32-bit objects and fail in a non-multilib
    system. The [ $(arch) = x86_64 ] test ensures it has no effect on a 32 bit
    system.</para>

    <para><command>cat /usr/include/sqlite3.h ... </command>: tests if
    <application>sqlite</application> is installed and if so it sets the
    environment variable NSS_USE_SYSTEM_SQLITE=1 so that
    <filename class="libraryfile">libsoftokn3.so</filename> will link against
    the system version of sqlite.</para>

    <para><command>export BUILD_OPT=1</command>: This variable is set so that
    the build is performed with no debugging symbols built into the binaries
    and that the default compiler optimizations are used.</para>

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

    <para><command>export USE_SYSTEM_ZLIB=1</command>: This command ensures that
    the system installed library is used instead of the in-tree version.</para>

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

    <para><command>export NSS_LINUXDIR=...</command>: This variable is set so
    that the exact name of the architecture specific directories where the
    binaries are stored in the source tree can be determined.</para>

    <para><command>make -C mozilla/security/nss nss_build_all</command>: This
    command builds the <application>NSS</application> libraries and creates a
    <filename class='directory'>dist</filename> directory which houses all the
    programs, libraries and interface headers. None of the programs created by
    this process are installed onto the system using the default instructions
    (except for <application>nss-config</application>).  If you need any of
    these programs installed, you can find them in the
    <filename class='directory'>mozilla/*.OBJ/dist/bin</filename> directory of
    the source tree.</para>

    <para><command>sed -i 's/gmake/make/' common/init.sh</command>: This
    command changes the command used to compile some test programs.</para>

  </sect2>

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

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

      <seglistitem>
        <seg>nss-config</seg>
        <seg>libcrmf.a, libfreebl3.so, libnss3.so, libnssckbi.so,
        libnssdbm3.so, libnssutil3.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="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>
    </variablelist>

  </sect2>

</sect1>