source: postlfs/security/openssl.xml@ 286c613d

<?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        "40b6ea380cc8a5bf9734c2f8bf7e701e">
  <!ENTITY openssl-size          "3.9 MB">
  <!ENTITY ca-bundle-download    "http://anduin.linuxfromscratch.org/files/BLFS/BLFS-ca-bundle-&ca-bundle-version;.tar.bz2">
  <!ENTITY ca-bundle-size        "240 KB">
  <!ENTITY ca-bundle-md5sum      "6c85a8bbfcf1f1ad539c72efb4a06cfb">
  <!ENTITY openssl-buildsize     "48 MB">
  <!ENTITY openssl-time          "1.0 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>

    &lfs70_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>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 patches: <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 for full
    coverage by 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;

./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>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make MANDIR=/usr/share/man install                &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>

  </sect2>

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

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

  </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 users will want to install Certificate Authority Certificates
      for validataion of downloaded certificates.  For example, these
      certificates are used by <xref linkend='firefox'/> or <xref
      linkend='wget'/> when accessing secure (https protocol) sites.  To do this, 
      follow the instructions from the <xref linkend='cacerts'/> page.</para> 

      <para>Users who just want to use <application>OpenSSL</application> for
      providing functions to other programs such as
      <application>OpenSSH</application> and web browsers do not need to worry
      about additional configuration. This is an advanced topic and so those
      who do need it would normally be expected to either know how to properly
      update <filename>/etc/ssl/openssl.cnf</filename> or 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,
        libgost.so, libnuron.so, libpadlock.so, libsureware.so, and
        libubsec.so)</seg>
        <seg>/etc/ssl, /usr/include/openssl, /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>