source: postlfs/security/openssl.xml@ defca61

<?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
           "https://openssl.org/source/openssl-&openssl-version;.tar.gz">
  <!ENTITY openssl-download-ftp
           "ftp://openssl.org/source/openssl-&openssl-version;.tar.gz">
  <!ENTITY openssl-md5sum        "a06c547dac9044161a477211049f60ef">
  <!ENTITY openssl-size          "5.1 MB">
  <!ENTITY openssl-buildsize     "67 MB (additional 1 MB for the tests)">
  <!ENTITY openssl-time          "1.1 SBU (additional 0.3 SBU for the tests)">
]>

<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, such as
      <application>OpenSSH</application>, email applications and web browsers
      (for accessing HTTPS sites).
    </para>

    &lfs77_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 patch:
          <ulink url="&patch-root;/openssl-&openssl-version;-fix_parallel_build-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

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

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="mitkrb"/>
    </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> with the following commands:
    </para>

<!-- libdir=lib so it doesn't write over /usr/lib64 symlink on 64 bit system.
     Might break packaging. -->

<screen><userinput>patch -Np1 -i ../openssl-&openssl-version;-fix_parallel_build-1.patch &amp;&amp;

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

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

    <para>
      If you want to disable installing the static libraries, use this sed:
    </para>

<screen><userinput>sed -i 's# libcrypto.a##;s# libssl.a##' Makefile</userinput></screen>

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

<!-- dev note: make INSTALL_PREFIX=<DESTDIR> MANDIR=/usr/share/man MANSUFFIX=ssl install -->

<screen role="root"><userinput>make MANDIR=/usr/share/man MANSUFFIX=ssl install &amp;&amp;
install -dv -m755 /usr/share/doc/openssl-&openssl-version;  &amp;&amp;
cp -vfr doc/*     /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 MANSUFFIX=ssl 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> and
      appends "ssl" suffix to the manual page names to avoid conflicts with
      manual pages installed by other packages.
    </para>

    <para>
      <option>make -j1 test</option>: although the patch for fixing parallel
      builds alters the <filename>Makefile</filename> in the
      <filename class="directory">test</filename> directory, there is still a
      race which can cause a test to fail.
    </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 validation of downloaded certificates. For example, these
        certificates can be used by <xref linkend='git'/>,
        <xref linkend='curl'/> 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} and libssl.{so,a}
        </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>