<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!-- $Id: pgp.xml,v 1.1 2006/07/03 12:24:25 cs Exp $ -->

<chapter id='configure-pgp'>
<title> PGP</title>

<para>
OTRS is able to sign or encrypt outgoing messages with PGP. Also encrypted
incomming messages can be decrypted. Encryption and decryption is done with
the GPL tool GnuPG. To setup GnuPG for OTRS the following steps have to be
performed:
</para>

<para>
<orderedlist numeration="arabic">
    <listitem>
    <para>
    The first step is to install GnuPGt via the package manager of your
    operating system.
    </para>
    </listitem>
    <listitem>
    <para>
    In the next step GnuPG has to be configured for the usage with OTRS.
    The needed direcotries for GnuPG and a private key have to be created.
    The following command has to be executed as OTRS user from a shell.
    </para>

    <para>
    <screen>
    linux:~# su otrs
    linux:/root$ cd
    linux:~$ pwd
    /opt/otrs
    linux:~$ gpg --gen-key
    gpg (GnuPG) 1.4.2; Copyright (C) 2005 Free Software Foundation, Inc.
    This program comes with ABSOLUTELY NO WARRANTY.
    This is free software, and you are welcome to redistribute it
    under certain conditions. See the file COPYING for details.

    gpg: directory `/opt/otrs/.gnupg' created
    gpg: new configuration file `/opt/otrs/.gnupg/gpg.conf' created
    gpg: WARNING: options in `/opt/otrs/.gnupg/gpg.conf' are not yet active during t
    his run
    gpg: keyring `/opt/otrs/.gnupg/secring.gpg' created
    gpg: keyring `/opt/otrs/.gnupg/pubring.gpg' created
    Please select what kind of key you want:
       (1) DSA and Elgamal (default)
       (2) DSA (sign only)
       (5) RSA (sign only)
    Your selection? 1
    DSA keypair will have 1024 bits.
    ELG-E keys may be between 1024 and 4096 bits long.
    What keysize do you want? (2048)
    Requested keysize is 2048 bits
    Please specify how long the key should be valid.
         0 = key does not expire
      &lt;n&gt;  = key expires in n days
      &lt;n&gt;w = key expires in n weeks
      &lt;n&gt;m = key expires in n months
      &lt;n&gt;y = key expires in n years
    Key is valid for? (0)
    Key does not expire at all
    Is this correct? (y/N) y

    You need a user ID to identify your key; the software constructs the user ID
    from the Real Name, Comment and Email Address in this form:
        "Heinrich Heine (Der Dichter) &lt;heinrichh@duesseldorf.de&gt;"

    Real name: Ticket System
    Email address: support@example.com
    Comment: Private PGP Key for the ticket system with address support@example.com
    You selected this USER-ID:
    "Ticket System (Private PGP Key for the ticket system with address support@examp
    le.com) &lt;support@example.com&gt;"

    Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
    You need a Passphrase to protect your secret key.

    Passphrase: secret
    Repeat passphrase: secret

    We need to generate a lot of random bytes. It is a good idea to perform
    some other action (type on the keyboard, move the mouse, utilize the
    disks) during the prime generation; this gives the random number
    generator a better chance to gain enough entropy.
    ++++++++++.+++++++++++++++++++++++++....+++++.+++++...+++++++++++++++++++++++++.
    +++++++++++++++++++++++++.+++++.+++++.+++++++++++++++++++++++++&gt;++++++++++&gt;+++++
    .......&gt;+++++&lt;+++++................................+++++

    Not enough random bytes available.  Please do some other work to give
    the OS a chance to collect more entropy! (Need 280 more bytes)

    ++++++++++.+++++..++++++++++..+++++....++++++++++++++++++++.+++++++++++++++.++++
    ++++++++++++++++++++++++++.++++++++++.+++++++++++++++.++++++++++.+++++++++++++++
    ..+++++&gt;.+++++....&gt;+++++........................................................
    ...........................................................&gt;+++++&lt;+++++.........
    .............+++++^^^
    gpg: /opt/otrs/.gnupg/trustdb.gpg: trustdb created
    gpg: key 7245A970 marked as ultimately trusted
    public and secret key created and signed.

    gpg: checking the trustdb
    gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
    gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
    pub   1024D/7245A970 2006-02-03
          Key fingerprint = 2ED5 BC36 D2B6 B055 7EE1  5833 1D7B F967 7245 A970
     uid                  Ticket System (Private pgp key for ticket system with addre
    ss support@example.com) &lt;support@example.com&gt;
    sub   2048g/52B97069 2006-02-03

    linux:~$
    </screen>
    </para>

    <para>
    Like shown in the screen above for the most settings the default is OK.
    Only the values for the key owner have to be entered correctly and a
    propper password has to be specified for the key.
    </para>
    </listitem>
    <listitem>
    <para>
    Now OTRS has to be prepared to use PGP. Open the SysConfig interface
    via the admin panel and search for ``PGP''. Select the sub group
     Crypt::PGP from the search results.
    </para>

    <para>
    In the screen for the PGP settings PGP should be activated for OTRS
    (first option). Also the path to the gpg program should be checked.
    </para>

    <para>
    The next config setting (PGP::Options) might to be changed. Via this
    config setting the parameters that are used for every execution of gpg
    by the OTRS user can be specified. Especialy the directory of the
    config files for GnuPG of the OTRS user is important. In the example
    <filename>/opt/otrs/.gnupg</filename> is used. Thsis directory was
    created in the first step of the PGP configuration.
    </para>

    <para>
    Via the last config option it is possible to specify the pairs of key
    IDs and their passwords for the own private keys. Because
    communication partners from outsite write to the ticket system and
    their messages are encrypted with the public key, OTRS can decrypt
    these messages with the ID/passwords specified here.
    </para>

    <para>
    How to get the id of your own private key? The ID of your own private
    key is allready shown during the key generation (see step 1 from
    above). It is also possible to get the ID if the following command is
    executed as OTRS user:
    </para>

    <para>
    <screen>
    linux:~# su otrs
    linux:/root$ cd
    linux:~$ pwd
    /opt/otrs
    linux:~$ gpg --list-keys
    /opt/otrs/.gnupg/pubring.gpg
    ----------------------------
    pub   1024D/7245A970 2006-02-03
    uid                  Ticket System (Private pgp key for ticket system with
    address support@example.com) &lt;support@example.com&gt;
    sub   2048g/52B97069 2006-02-03

    linux:~$
    </screen>
    </para>

    <para>
    The ID of the private key can be found in the line that starts with
    "sub". It is a hexa decimal string that is eight characters long,
    in the example above it is "52B97069". The password you have to
    specifiy for this key in the ticket system is the same like
    given during key generation.
    </para>

    <para>
    After these data have been inserted the "Update" button can be used to
    store the settings. OTRS is ready to receive and decrypt encoded
    messages now.
    </para>
    </listitem>
    <listitem>
    <para>
    The last step is the import of a customers public key. This ensures
    that also encrypted messages can be sent out to this customer. There
    are two possibilities to import a public key of a customer.
    </para>

    <para>
    The first possibility is to specify the public key of a customer in the
    interface for the customer management. A public can be given if a
    customer is created or modified.
    </para>

    <para>
    The second possibility is to specify the key via the PGP settings
    reachable from the admin area of OTRS. On the right site of this screen
    all allready imported public keys of customers are displaied. After PGP
    has been activated and configured for OTRS your own public     key should be
    listed there also. In the left area of the PGP setting screen it is
    possible to search for keys. Also a new public key can be uploaded into
    the system from a file.
    </para>

    <para>
    The files with the public key that need to be imported into OTRS have
    to be GnuPGP conform key files. In most cases the key stored in a file
    is an ``ASCII armored key''.. OTRS can deal with this format.
    </para>
    </listitem>
</orderedlist>
</para>
</chapter>