path: root/chapter08/openssl.xml

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

<sect1 id="ch-system-openssl" role="wrap">
  <?dbhtml filename="openssl.html"?>

  <sect1info condition="script">
    <productname>openssl</productname>
    <productnumber>&openssl-version;</productnumber>
    <address>&openssl-url;</address>
  </sect1info>

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

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

  <sect2 role="package">
    <title/>

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

    <segmentedlist>
      <segtitle>&buildtime;</segtitle>
      <segtitle>&diskspace;</segtitle>

      <seglistitem>
        <seg>&openssl-fin-sbu;</seg>
        <seg>&openssl-fin-du;</seg>
      </seglistitem>
    </segmentedlist>

  </sect2>

  <sect2 role="installation">
    <title>Installation of OpenSSL</title>
<!--
    <para>First fix a problem with some advanced architectures with avx512
    capability:</para>

 <screen><userinput remap="pre">sed -e '/bn_reduce.*m1/i\    factor_size /= sizeof(BN_ULONG) * 8;' \
    -i crypto/bn/rsaz_exp_x2.c</userinput></screen>
-->
    <para>Prepare OpenSSL for compilation:</para>

<screen><userinput remap="configure">./config --prefix=/usr         \
         --openssldir=/etc/ssl \
         --libdir=lib          \
         shared                \
         zlib-dynamic</userinput></screen>

    <para>Compile the package:</para>

<screen><userinput remap="make">make</userinput></screen>

    <para>To test the results, issue:</para>

<screen><userinput remap="test">make test</userinput></screen>

    <para>One test, 30-test_afalg.t, is known to fail if the host kernel
    does not have <option>CONFIG_CRYPTO_USER_API_SKCIPHER</option> enabled,
    or does not have any options providing an AES with CBC implementation
    (for example, the combination of <option>CONFIG_CRYPTO_AES</option>
    and <option>CONFIG_CRYPTO_CBC</option>, or
    <option>CONFIG_CRYPTO_AES_NI_INTEL</option> if the CPU supports AES-NI)
    enabled.  If it fails, it can safely be ignored.</para>

    <para>Install the package:</para>

<screen><userinput remap="install">sed -i '/INSTALL_LIBS/s/libcrypto.a libssl.a//' Makefile
make MANSUFFIX=ssl install</userinput></screen>

    <para>Add the version to the documentation directory name, to be
    consistent with other packages:</para>

<screen><userinput remap="install">mv -v /usr/share/doc/openssl /usr/share/doc/openssl-&openssl-version;</userinput></screen>

    <para>If desired, install some additional documentation:</para>

<screen><userinput remap="install">cp -vfr doc/* /usr/share/doc/openssl-&openssl-version;</userinput></screen>

    <note>
      <para>
        You should update OpenSSL when a new version which fixes vulnerabilities
        is announced.  Since OpenSSL 3.0.0, the OpenSSL versioning scheme
        follows the MAJOR.MINOR.PATCH format.  API/ABI compatibility
        is guaranteed for the same MAJOR version number.  Because LFS
        installs only the shared libraries, there is no need to recompile
        packages which link to
        <filename class="libraryfile">libcrypto.so</filename> or
        <filename class="libraryfile">libssl.so</filename>
        <emphasis>when upgrading to a version with the same MAJOR version
        number</emphasis>.
      </para>

      <!-- https://bugzilla.mindrot.org/show_bug.cgi?id=3548 -->
      <para>
        If <application>OpenSSH</application> is installed, it will be an
        exception of the general rule above.  It contains an
        over-restrictive OpenSSL version check, so both SSH client and SSH
        server will refuse to start if OpenSSL
        is updated with MAJOR version number unchanged but MINOR version
        number changed.  You need to rebuild
        <application>OpenSSH</application> after such an upgrade.
        <emphasis role='bold'>If <application>OpenSSH</application> is being
        used to access the system, you must rebuild and reinstall it
        after upgrading OpenSSL to a new MINOR version number before logout
        or you won't be able to login via SSH anymore.</emphasis>
      </para>

      <para>
        However, any running programs linked to those libraries need to be stopped
        and restarted. Read the related entries in
        <xref linkend='pkgmgmt-upgrade-issues'/> for details.
      </para>

    </note>

  </sect2>

  <!-- - - - - - - - - - -->
  <!-- Multilib - 32bit  -->
  <!-- - - - - - - - - - -->
  
  <sect2 arch="ml_32,ml_all" role="installation">
    <title>Installation of OpenSSL - 32bit</title>

    <para>Clean previous build:</para>

<screen><userinput remap="pre">make distclean</userinput></screen>

    <para>Prepare OpenSSL for compilation:</para>

<screen><userinput remap="configure">./config --prefix=/usr         \
         --openssldir=/etc/ssl \
         --libdir=lib32        \
         shared                \
         zlib-dynamic          \
         linux-x86</userinput></screen>

    <para>Compile the package:</para>

<screen><userinput remap="make">make</userinput></screen>

    <para>Install the package:</para>

<screen><userinput remap="install">make DESTDIR=$PWD/DESTDIR install
cp -Rv DESTDIR/usr/lib32/* /usr/lib32
rm -rf DESTDIR</userinput></screen>

  </sect2><!-- m32 -->

  <!-- - - - - - - - - - -->
  <!-- Multilib - x32bit -->
  <!-- - - - - - - - - - -->
  
  <sect2 arch="ml_x32,ml_all" role="installation">
    <title>Installation of OpenSSL - x32bit</title>

    <para>Clean previous build:</para>

<screen><userinput remap="pre">make distclean</userinput></screen>

    <para>Prepare OpenSSL for compilation:</para>

<screen><userinput remap="configure">./config --prefix=/usr         \
         --openssldir=/etc/ssl \
         --libdir=libx32       \
         shared                \
         zlib-dynamic          \
         linux-x32</userinput></screen>

    <para>Compile the package:</para>

<screen><userinput remap="make">make</userinput></screen>

    <para>Install the package:</para>

<screen><userinput remap="install">make DESTDIR=$PWD/DESTDIR install
cp -Rv DESTDIR/usr/libx32/* /usr/libx32
rm -rf DESTDIR</userinput></screen>

  </sect2><!-- mx32 -->

  <sect2 id="contents-openssl" role="content">
    <title>Contents of OpenSSL</title>

    <segmentedlist>
      <segtitle>Installed programs</segtitle>
      <segtitle>Installed libraries</segtitle>
      <segtitle>Installed directories</segtitle>

      <seglistitem>
        <seg>
          c_rehash and openssl
        </seg>
        <seg>
          libcrypto.so and libssl.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.  Use of <command>c_rehash</command> is considered
            obsolete and should be replaced by
            <command>openssl rehash</command> command
          </para>
          <indexterm zone="ch-system-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="ch-system-openssl openssl-prog">
            <primary sortas="b-openssl">openssl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcrypto">
        <term><filename class="libraryfile">libcrypto.so</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="ch-system-openssl libcrypto">
            <primary sortas="c-libcrypto">libcrypto.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libssl">
        <term><filename class="libraryfile">libssl.so</filename></term>
        <listitem>
          <para>
            implements the Transport Layer Security (TLS v1) protocol.
            It provides a rich API, documentation
            on which can be found by running <command>man 7 ssl</command>
          </para>
          <indexterm zone="ch-system-openssl libssl">
            <primary sortas="c-libssl">libssl.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>