= Encrypted Zephyr classes =

BarnOwl contains support for encrypting traffic to Zephyr classes,
based on a modified version of the `zcrypt` program by Philip
Lisiecki.

== Using zcrypt ==

If the `zcrypt` variable in BarnOwl is enabled (as it is by default), BarnOwl will
automatically attempt to decrypt zephyrs received with the opcode
`crypt`.

To send encrypted zephyrs, use the `zcrypt` command, which behaves
identically to the `zwrite` command, except that it encrypts the
bodies of outgoing zephyrs.

If you want to add a keybinding like `z` (which starts a `zwrite` command) for encrypted zephyrs, you can run the following command:
{{{
  startup bindkey recv C command start-command zcrypt 
}}}
(Note the presence of a trailing space after 'zcrypt'.)

BarnOwl will automatically reply to zephyrs with the opcode `crypt` using the `zcrypt` command.

== The zcrypt key file ==

In order to determine the key to use to encrypt zephyrs, BarnOwl uses
the file "$HOME/.crypt-table".  This table contains class-level and
instance-level key file information.  The file may also contain a
default key file for all classes/instances that have no key file
explicitly defined.  Note that an entry with the instance defined
takes precendence over one without the class.  Here is a sample
`.crypt-table`:

{{{
     crypt-xxx: AES: /afs/athena/user/n/e/nelhage/keys/key-xxx
     crypt-yyy: /afs/athena/user/n/e/nelhage/keys/key-yyy
     crypt-yyy-123: /tmp/yyy123.key
     crypt-default: /afs/athena/user/n/e/nelhage/Public/testkey
}}}

This `.crypt-table` will use `keys/key-xxx` for class `xxx`, using AES
encryption via GPG.

Class `yyy` will use the `key-yyy` key, unless the instance is "123",
in which case, the key file will be "/tmp/yyy123.key".  If none of
these conditions are met, zcrypt will use the default key file,
`Public/testkey`.

== AES encryption ==

By default, for backwards-compatibility, BarnOwl encrypts messages
using the `DES` encryption algorithm in
[http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation#Electronic_codebook_.28ECB.29 ECB mode]. '''This is an extremely weak cipher''', and should not be considered resistant to any sort of dedicated attack.

As of BarnOwl 1.6, BarnOwl supports encrypting messages using GPG and
the modern AES cryptosystem. To enable this mode, prefix a keyfile
with the string `AES:` in the `.crypt-table` file. This will cause
BarnOwl to shell out to GPG for encryption, using the contents of the
file as the passphrase.

== Troubleshooting ==

If BarnOwl fails to send or receive encrypted messages, you can use
the `:show errors` command to view the output of the `zcrypt` command,
which will often contain more information about what went wrong.

== The `zcrypt` binary ==

The BarnOwl distribution and locker contain a `zcrypt` program with is
backwards-compatible with Philip Lisiecki's, but supports the AES
encryption feature described above. This program can be used by other
scripts or zephyr clients to encrypt and decrypt messages.