source: postlfs/security/openssl.xml@ ae7796d

<?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 openssl-download-http "http://www.openssl.org/source/openssl-&openssl-version;.tar.gz">
  <!ENTITY openssl-download-ftp  "ftp://ftp.openssl.org/source/openssl-&openssl-version;.tar.gz">
  <!ENTITY openssl-md5sum        "05a0ece1372392a2cf310ebb96333025">
  <!ENTITY openssl-size          "4.1 MB">
  <!ENTITY ca-bundle-download    "http://anduin.linuxfromscratch.org/files/BLFS/BLFS-ca-bundle-&ca-bundle-version;.tar.bz2">
  <!ENTITY ca-bundle-size        "224 KB">
  <!ENTITY ca-bundle-md5sum      "84287d75a4137d00020b1b89a472f5e7">
  <!ENTITY openssl-buildsize     "47 MB">
  <!ENTITY openssl-time          "1.1 SBU (additional 0.3 SBU to run the test suite)">
]>

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

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

  <title>OpenSSL-&openssl-version;</title>

  <indexterm zone="openssl">
    <primary sortas="a-OpenSSL">OpenSSL</primary>
  </indexterm>

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

    <para>The <application>OpenSSL</application> package contains management
    tools and libraries relating to cryptography.  These are useful for
    providing cryptography functions to other packages, notably
    <application>OpenSSH</application>, email applications and web browsers
    (for accessing HTTPS sites).</para>

    &lfs65_checked;

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

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Required patch: <ulink
        url="&patch-root;/openssl-&openssl-version;-fix_manpages-1.patch"/></para>
      </listitem>
    </itemizedlist>

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

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="mitkrb"/> or
    <xref linkend="heimdal"/>, and <xref linkend="bc"/> (required to run the
    test suite during the build)</para>

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

  </sect2>

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

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

<screen><userinput>patch -Np1 -i ../openssl-&openssl-version;-fix_manpages-1.patch &amp;&amp;
tar -vxf ../BLFS-ca-bundle-&ca-bundle-version;.tar.bz2 &amp;&amp;
sed -i.bak 's/ -ldes//' configure

./config --prefix=/usr         \
         --openssldir=/etc/ssl \
         shared                \
         zlib-dynamic          &amp;&amp;
make</userinput></screen>

    <para>To test the results, issue: <command>make test</command>.</para>

    <!-- <para>To test the results, issue: <command>make test</command>.  Note that the
    test results/output depend on the availability of /etc/ssl/openssl.cnf.  If
    running the tests for the first time run the following as the 
    <systemitem class="username">root</systemitem> user before running the
    tests:</para>

<screen role="root"><userinput>install -v -m755 d /etc/ssl &amp;&amp;
install -v ./apps/openssl.cnf /etc/ssl/</userinput></screen> -->

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

<screen role="root"><userinput>make MANDIR=/usr/share/man install                &amp;&amp;
cp -v -r certs /etc/ssl                           &amp;&amp;
install -v -d -m755 /usr/share/doc/openssl-&openssl-version; &amp;&amp;
cp -v -r doc/{HOWTO,README,*.{txt,html,gif}} \
    /usr/share/doc/openssl-&openssl-version;</userinput></screen>

    <para>While still the <systemitem class="username">root</systemitem> user,
    create a single file that contains all of the installed certificates:</para>

<screen role="root"><userinput>for pem in /etc/ssl/certs/*.pem
do
   cat $pem
   echo ""
done &gt; /etc/ssl/ca-bundle.crt</userinput></screen>

  </sect2>

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

    <para>
    <command>tar -vxf ../BLFS-ca-bundle-&ca-bundle-version;.tar.bz2</command>:
    <application>OpenSSL</application> no longer includes any root certificates. 
    This package adds root certificates as provided by mozilla.org.</para>

    <para><command>sed -i.bak 's/ -ldes/lkrb5/' configure</command>:
    This command fixes a build crash if you used the
    <option>--with-kerberos5</option> parameter and you built the
    <application>Heimdal</application> package in accordance with the BLFS
    instructions. The command is harmless in all other instances.</para>

    <para><parameter>shared</parameter>: This parameter forces the creation of
    shared libraries along with the static libraries.</para>

    <para><parameter>zlib-dynamic</parameter>: This parameter adds
    compression/decompression functionality using the
    <filename class="libraryfile">libz</filename> library.</para>

    <para><option>no-rc5 no-idea</option>: When added to the
    <command>./config</command> command, this will eliminate the building
    of those encryption methods. Patent licenses may be needed for you to
    utilize either of those methods in your projects.</para>

    <para><command>make MANDIR=/usr/share/man install</command>: This command
    installs <application>OpenSSL</application> with the man pages in
    <filename class='directory'>/usr/share/man</filename> instead of
    <filename class='directory'>/etc/ssl/man</filename>.</para>

    <!-- <para><option>enable-tlsext</option>: When added to the
    <command>./config</command> command, this switch will enable TLS
    Extensions. Currently this is only RFC 3546 and 4507bis for Server Name
    Indication.  This allows the use of multiple SSL certificates with multiple
    virtual hosts in Apache, while using only one IP address and one port for
    all virtual hosts.</para> -->

    <!-- <para><option>zlib-dynamic</option>: When added to the
    <command>./config</command> command, this switch will enable 
    use of <filename>libz.so</filename> for compression/decompression.</para> -->

    <para><command>cp -v -r certs /etc/ssl</command>: This installs both the
    sample certificates and documentation included with
    <application>OpenSSL</application>, and the certificates that were extracted
    from the BLFS-ca-bundle-&ca-bundle-version; package.</para>

    <para><command>for pem in /etc/ssl/certs/*.pem...</command>: This group of
    commands creates a single-file certificate bundle 
    (<filename>/etc/ssl/ca-bundle.crt</filename>) that is usable by many
    other software packages.  <filename>ca-bundle.crt</filename> should be
    recreated anytime that a certificate is added to
    <filename class="directory">/etc/ssl/certs</filename>.</para>

  </sect2>

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

    <sect3 id="openssl-config">
      <title>Config Files</title>

      <para><filename>/etc/ssl/openssl.cnf</filename></para>

      <indexterm zone="openssl openssl-config">
        <primary sortas="e-etc-ssl-openssl.cnf">/etc/ssl/openssl.cnf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>Most people who just want to use <application>OpenSSL</application>
      for providing functions to other programs such as
      <application>OpenSSH</application> and web browsers won't need to worry
      about configuring <application>OpenSSL</application>. Configuring
      <application>OpenSSL</application> is an advanced topic and so those
      who do would normally be expected to either know how to do it or to be
      able to find out how to do it.</para>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>c_rehash and openssl</seg>
        <seg>libcrypto.{so,a}, libssl.{so,a}, and additional encryption
        libraries in /usr/lib/engines/ (lib4758cca.so, libaep.so,
        libatalla.so, libcapi.so, libchil.so, libcswift.so, libgmp.so, libnuron.so,
        libsureware.so, and libubsec.so)</seg>
        <seg>/etc/ssl, /usr/include/ssl, /usr/lib/engines
        and /usr/share/doc/openssl-&openssl-version;</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="c_rehash">
        <term><command>c_rehash</command></term>
        <listitem>
          <para>is a <application>Perl</application> script that scans
          all files in a directory and adds symbolic links to their hash
          values.</para>
          <indexterm zone="openssl c_rehash">
            <primary sortas="b-c_rehash">c_rehash</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="openssl-prog">
        <term><command>openssl</command></term>
        <listitem>
          <para>is a command-line tool for using the various cryptography
          functions of <application>OpenSSL</application>'s crypto
          library from the shell. It can be used for various functions which are
          documented in <command>man 1 openssl</command>.</para>
          <indexterm zone="openssl openssl-prog">
            <primary sortas="b-openssl">openssl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcrypto">
        <term><filename class='libraryfile'>libcrypto.{so,a}</filename></term>
        <listitem>
          <para>implements a wide range of cryptographic algorithms used in
          various Internet standards. The services provided by  this library
          are used by the <application>OpenSSL</application> implementations of
          SSL, TLS and S/MIME, and they have also been used to implement
          <application>OpenSSH</application>, <application>OpenPGP</application>,
          and other cryptographic standards.</para>
          <indexterm zone="openssl libcrypto">
            <primary sortas="c-libcrypto">libcrypto.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libssl">
        <term><filename class='libraryfile'>libssl.{so,a}</filename></term>
        <listitem>
          <para>implements the Secure Sockets Layer (SSL v2/v3) and Transport
          Layer Security (TLS v1) protocols. It provides a rich API, documentation
          on which can be found by running <command>man 3 ssl</command>.</para>
          <indexterm zone="openssl libssl">
            <primary sortas="c-libssl">libssl.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>