The following short descriptions will explain how to use the Pond/EMail gateway either from Pond or with your EMail client.

Pond users

This assumes that you already have a running Pond client (either GUI or console-based) and a valid Pond identity on a Pond home server. If you need help with Pond itself, you will find all you need here.

1. Register with the gateway

To register as a Pond user, go to the registration page and select the "Pond" tab.

Make up a shared secret for the initial key exchange (just as you would if you want to peer with other Pond users) and enter it into the input field and submit the form.

If your registration succeeds (if your shared secret is valid for a PANDA key exchange), you will see a "success" page. This page will display a unique PeerId that is assigned to your Pond identity on the gateway. Write down this identifier and keep it secret.

Now create a new Pond contact for the gateway and enter the same shared secret you used in the registration. Once the key exchange is complete, you can start exchange messages with EMail users or services.

2. Receiving messages from an email address

Before you can receive email messages in Pond, you need to tell a potential sender your email address. Every Pond user on the gateway has an unlimited number of email addresses at her/his disposal that are generated from the PeerId by the Pond user. So you can give away a separate email address to every email user or service you want to exchange messages with.

Each of your email addresses has the form:

pondgw+<Token>@hoi-polloi.org

The Token that is part of your email address is derived from your PeerId. To generate new tokens, go to the token generator page.

3. Send a message to an email address

Compose a message to the gateway contact and send it. The first two lines of the message must specify the receiving email address and the return path for replies (which includes a token like in the previous section), the rest of the message is up to you:

To: fred@company.edu

From: pondgw+<token>@hoi-polloi.org

<...the rest of the message

goes here...>

Please note the following:

  • As a registered Pond user you can specify any email address as a recipient; the gateway currently does not limit message forwarding to registered email users only. This policy may change if we start noticing Pond user sending SPAM to email addresses.

  • If you specify an invalid email address, the gateway will never acknowledge your message; this is the only feedback you will get. If you see the message acknowledged, you know it had been handled by the gateway and was forwarded to the recipient. If the delivery of the message fails on the other side of the gateway, you will never get a notification.

  • We highly recommend to only send additionally encrypted content, so the forwarding gateway cannot read the plaintext message. Since the receiving email address probably has an OpenPGP public key, it is the easiest to use GnuPG to encrypt the message first and then paste it into the Pond message you want to send:

    To: fred@company.edu

    -----BEGIN PGP MESSAGE-----

    Version: GnuPG v2

     

    <Base64-encoded data>

    -----END PGP MESSAGE-----

EMail users

As an email user you don't have to register with the gateway. If you want to receive messages from Pond users in encrypted form (OpenPGP-compatible encryption like GnuPG), you need to register first and upload your public key.

1. Register with the gateway

Before you can start the registration, you need to have a file that contains your public OpenPGP key. Most encryption plug-ins for email clients allow you to export your public key to a file. If asked, export the key in the so-called "armored" format; if you are not asked, your plug-in will use that format by default. If you fail to create the required key file, you can only register using the email registration method

1.1. Web-based registration

To register as an EMail user, go to the registration page and select the "EMail" tab.

Enter your email address, browse for the file that contains your public OpenPGP key and submit the form.

If your registration succeeds (if your email address looks valid and was not already registered and if your public key is in a usable form), you will see a page that informs you that a confirmation email has been send to the address you have specified. This confirmation email will contain a link you need to follow with the next two days to complete your registration. Once the confirmation is received, you will be able to send messages to Pond users.

1.2. EMail-based registration

Write an unsigned, unencrypted email to the gateway at 'pondgw@hoi-polloi.org' where the first line of the message reads "register"; the rest of the message (if any) is gracefully ignored by the gateway. Attach your public key to the message (all encryption plug-ins into email clients allow you to do this) and send it.

Like in the web-based registration you will receive an confirmation email with a link that you need to follow within two days to complete your registration. Once the confirmation is received, you will be able to send messages to Pond users.

2. Send a message to a Pond user

You should have received an email address from your Pond client where she/he will receive your messages. Write an email to that address as you would for any other email recipient.

We highly recommend the following:

  • Send the email signed (with your private key) and encrypted to the public key of the gateway. This ensures a secure forward of the message to the gateway.

  • Only send additionally encrypted content, so the forwarding gateway cannot read the plaintext message. Since the receiving Pond identity has no OpenPGP public key (by default), you need to negotiate with your Pond peer how to secure emails send to the Pond account. Once you have settled for a procedure (like using GnuPG in symmetric mode with a shared secret), encrypt the message first and then paste it into the email message you want to send.