keychain.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section id="chap-Joomla_Platform_Manual-Keychain">
  <title>The Keychain Package</title>

  <para>The keychain provides a way to securely store sensitive information such as access credentials or any other data.</para>

  <para>The system relies on three files:</para>

  <simplelist>
    <member>a public key;</member>

    <member>a private key;</member>

    <member>a passphrase file; and</member>

    <member>a keychain file.</member>
  </simplelist>

  <para>The <emphasis>passphrase file</emphasis> is generated by using the <emphasis>private key</emphasis> to encrypt the
  passphrase. This is so that the passphrase file can be decrypted by the <emphasis>public key</emphasis> without requiring the
  knowledge of the passphrase for the private key. This means it can be deployed onto a server without requiring manual
  intervention or a passphrased stored plain text on disk. Because of this the public key should not be stored in a repository and
  should be stored on servers in a protected location.</para>

  <para>The <emphasis>keychain file</emphasis> is the actual valuable contents. It is encrypted using the passphrase stored in the
  passphrase file (which itself is decrypted using the public key).</para>

  <para>This provides a balance between not storing credentials plain text but also making the system reasonably
  independent.</para>

  <para>A good example of where the keychain is useful is where some code needs to establish a connection with another server or
  service using some access credentials (usually a username and password, but any number of authentication credentials could be
  used); using clear text credentials in the code, which is probably stored on a relatively public code repository, can be avoided
  by storing the credentials in an encrypted data file that the keychain can read.</para>

  <section>
    <title>Key Storage</title>

    <para>You can store the private key in a code repository but you <emphasis role="bold">MUST NOT</emphasis> commit the
    <emphasis role="bold">public key</emphasis>. Doing so will compromise the security of the keychain (you will need to
    regenerate the private key if you accidentally do commit it).</para>
  </section>

  <xi:include href="../classes/jkeychain.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

  <section>
    <title>Keychain Management Utility</title>

    <para>The keychain management utility (<filename>/bin/keychain.php</filename>) allows you to manage keychain resources and
    data from the command line.</para>

    <section>
      <title>Usage</title>

      <programlisting>$ keychain.php [--keychain=/path/to/keychain]
	[--passphrase=/path/to/passphrase.dat] [--public-key=/path/to/public.pem]
	[command] [&lt;args&gt;]</programlisting>

      <para>Options</para>

      <simplelist>
        <member>--keychain=/path/to/keychain - Path to a keychain file to manipulate.</member>

        <member>--passphrase=/path/to/passphrase.dat - Path to a passphrase file containing the encryption/decryption
        key.</member>

        <member>--public-key=/path/to/public.pem - Path to a public key file to decrypt the passphrase file.</member>
      </simplelist>

      <para>Commands</para>

      <itemizedlist>
        <listitem>
          <para><command>list</command> [--print-values]</para>

          <para>Lists all entries in the keychain. Optionally pass --print-values to print the values as well.</para>
        </listitem>

        <listitem>
          <para><command>create</command> entry_name entry_value</para>

          <para>Creates a new entry in the keychain called "entry_name" with the plaintext value "entry_value". NOTE: This is an
          alias for change.</para>
        </listitem>

        <listitem>
          <para><command>change</command> entry_name entry_value</para>

          <para>Updates the keychain entry called "entry_name" with the value "entry_value".</para>
        </listitem>

        <listitem>
          <para><command>delete</command> entry_name</para>

          <para>Removes an entry called "entry_name" from the keychain.</para>
        </listitem>

        <listitem>
          <para><command>read</command> entry_name</para>

          <para>Outputs the plaintext value of "entry_name" from the keychain.</para>
        </listitem>

        <listitem>
          <para><command>init</command></para>

          <para>Creates a new passphrase file and prompts for a new passphrase.</para>
        </listitem>
      </itemizedlist>

      <para></para>
    </section>

    <section>
      <title>Generating Keys</title>

      <para>On a command line with openssl installed (any Mac OS X or Linux box is suitable):</para>

      <programlisting>$ openssl genrsa -des3 -out private.key 1024</programlisting>

      <para>This command will generate a new private key in the file "private.key". This can be then used to create a new public
      key file:</para>

      <programlisting>$ openssl rsa -in private.key -pubout -out publickey.pem</programlisting>

      <para>This will use the private key we just created in private.key to output a new public key into the file
      publickey.pem.</para>
    </section>

    <section>
      <title>Generating Keys with Certificates</title>

      <para>If you need to generate keys with certificates (exact details will vary from system to system), on a command line with
      openssl installed:</para>

      <programlisting>openssl req -x509 -days 3650 -newkey rsa:1024 -keyout private.key -out publickey.pem</programlisting>

      <para>This will create a new private key in the file private.key and a new public key in the file publickey.pem. You will be
      asked for a passphrase to secure the private key. and then prompted for information to be incorporated into the certificate
      request:</para>

      <programlisting>Country Name (2 letter code) [AU]: US
State or Province Name (full name) [Some-State]: New York
Locality Name (eg, city) []: New York
Organization Name (eg, company) [Internet Widgits Pty Ltd]: Open Source Matters, Inc.
Organizational Unit Name (eg, section) []: Joomla! Platform
Common Name (eg, YOUR name) []: Joomla Credentials
Email Address []: platform@joomla.org</programlisting>

      <para>Once this is done there will be a private.key and publickey.pem file that you can use for managing the passphrase
      file.</para>
    </section>

    <section>
      <title>Initialise a new passphrase file</title>

      <para>This step requires that you have already generated a private key (and assumes the <filename>keychain.php</filename>
      file is executable and in your lookup path). The following command will initialise a new passphrase file:</para>

      <programlisting>$ keychain.php init --passphrase=/path/to/passphrase.file --private-key=/path/to/private.key</programlisting>

      <para>This will prompt for two things:</para>

      <simplelist>
        <member>the passphrase to store in <filename>passphrase.file</filename>; and</member>

        <member>the passphrase for the private key.</member>
      </simplelist>

      <para>It will create a new file at <filename>/path/to/passphrase.file</filename> replacing any file that might be there
      already.</para>
    </section>

    <section>
      <title>Create a new entry in the keychain</title>

      <para>This step requires that you have already generated the private key and the passphrase file. The following command will
      create or update an entry in the keychain:</para>

      <programlisting>$ keychain.php create --passphrase=/path/to/passphrase.file --public-key=/path/to/publickey.pem --keychain=/path/to/keychain.dat  name  value</programlisting>

      <para>An existing keychain file will attempt to be loaded and then key name will be set to value.</para>
    </section>

    <section>
      <title>Create a new public key from private key</title>

      <para>If you know the passphrase for the private key but have lost the public key you can regenerate the public key:</para>

      <programlisting>openssl rsa -in private.key -pubout -out publickey.pem</programlisting>

      <para>This will use the private key in the file <filename>private.key</filename> and output a new public key to
      <filename>publickey.pem</filename>. If the private key has a passphrase on it, you will be prompted to enter the
      passphrase.</para>
    </section>
  </section>
</section>