This is to avoid outputting invalid character data.  Decrypting
    originally textual data with <function>pgp_pub_decrypt_bytea</function> is fine.
   </para>
   <para>
    The <parameter>options</parameter> parameter can contain option settings,
    as described below.
   </para>
  </sect3>

  <sect3 id="pgcrypto-pgp-enc-funcs-pgp-key-id">
   <title><function>pgp_key_id()</function></title>

   <indexterm>
    <primary>pgp_key_id</primary>
   </indexterm>

<synopsis>
pgp_key_id(bytea) returns text
</synopsis>
   <para>
    <function>pgp_key_id</function> extracts the key ID of a PGP public or secret key.
    Or it gives the key ID that was used for encrypting the data, if given
    an encrypted message.
   </para>
   <para>
    It can return 2 special key IDs:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      <literal>SYMKEY</literal>
     </para>
     <para>
      The message is encrypted with a symmetric key.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>ANYKEY</literal>
     </para>
     <para>
      The message is public-key encrypted, but the key ID has been removed.
      That means you will need to try all your secret keys on it to see
      which one decrypts it.  <filename>pgcrypto</filename> itself does not produce
      such messages.
     </para>
    </listitem>
   </itemizedlist>
   <para>
    Note that different keys may have the same ID.   This is rare but a normal
    event. The client application should then try to decrypt with each one,
    to see which fits &mdash; like handling <literal>ANYKEY</literal>.
   </para>
  </sect3>

  <sect3 id="pgcrypto-pgp-enc-funcs-armor">
   <title><function>armor()</function>, <function>dearmor()</function></title>

   <indexterm>
    <primary>armor</primary>
   </indexterm>

   <indexterm>
    <primary>dearmor</primary>
   </indexterm>

<synopsis>
armor(data bytea [ , keys text[], values text[] ]) returns text
dearmor(data text) returns bytea
</synopsis>
   <para>
    These functions wrap/unwrap binary data into PGP ASCII-armor format,
    which is basically Base64 with CRC and additional formatting.
   </para>

   <para>
    If the <parameter>keys</parameter> and <parameter>values</parameter> arrays are specified,
    an <firstterm>armor header</firstterm> is added to the armored format for each
    key/value pair. Both arrays must be single-dimensional, and they must
    be of the same length.  The keys and values cannot contain any non-ASCII
    characters.
   </para>
  </sect3>

  <sect3 id="pgcrypto-pgp-enc-funcs-pgp-armor-headers">
   <title><function>pgp_armor_headers</function></title>

   <indexterm>
    <primary>pgp_armor_headers</primary>
   </indexterm>

<synopsis>
pgp_armor_headers(data text, key out text, value out text) returns setof record
</synopsis>
   <para>
    <function>pgp_armor_headers()</function> extracts the armor headers from
    <parameter>data</parameter>.  The return value is a set of rows with two columns,
    key and value.  If the keys or values contain any non-ASCII characters,
    they are treated as UTF-8.
   </para>
  </sect3>

  <sect3 id="pgcrypto-pgp-enc-funcs-opts">
   <title>Options for PGP Functions</title>

   <para>
    Options are named to be similar to GnuPG.  An option's value should be
    given after an equal sign; separate options from each other with commas.
    For example:
<programlisting>
pgp_sym_encrypt(data, psw, 'compress-algo=1, cipher-algo=aes256')
</programlisting>
   </para>

   <para>
    All of the options except <literal>convert-crlf</literal> apply only to
    encrypt functions.  Decrypt functions get the parameters from the PGP
    data.
   </para>

   <para>
    The most interesting options are probably
    <literal>compress-algo</literal> and <literal>unicode-mode</literal>.
    The rest should have reasonable defaults.
   </para>

  <sect4 id="pgcrypto-pgp-enc-funcs-opts-cipher-algo">
   <title>cipher-algo</title>

   <para>
    Which cipher algorithm to use.
   </para>