PC-Online 1998 February/PCOnline_02_1998.iso/filesbbs/win3x/pgpjn.exe/READ.ME

Text File | 1996-05-17 | 17.1 KB | 312 lines

PGP Open Encryptor Interface 1.1 for WinPMail 2.23 and above.
Copyright 1995 by John Navas, All Rights Reserved.

The author grants explicit permission for the source code to be used
or modified as required, subject only to the conditions that the
copyright notices are preserved; that the source code not be used in
any product distributed in competition with this product; and that by
using this code you agree that the code is provided without warranty
of any kind, either explicit or implied, and you use it at your own
risk.

NOTE:  The latest information on and the latest version of
this interface is always available on the World Wide Web at
http://web.aimnet.com/~jnavas/winpmail.htm

WARNING:  THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF
ANY KIND.  SUPPORT IS NOT AVAILABLE.  USE AT YOUR OWN RISK.

AUTHOR'S NOTE:  For real security you should NEVER use encryption
modules that are not provided in SOURCE CODE form.  Otherwise, you
have NO WAY OF KNOWING IF THE MODULE ITSELF IS COMPROMISING YOUR
SECURITY.

This module implements an interface to Pretty Good Privacy (tm)
and (c) Copyright 1990-1994 Philip Zimmermann. All rights reserved.

PGP information is available at http://www.mantis.co.uk/pgp/pgp.html
The MIT distribution of PGP is at ftp://net-dist.mit.edu:/pub/PGP/
ViaCrypt (commercial version of PGP) is at http://www.viacrypt.com/
The International PGP Home Page is at http://www.ifi.uio.no/~staalesc/PGP/

This interface is designed to work only with Pegasus Mail for Windows
Version 2.23 and above, one of the very best email packages, and one
that is completely free (as is this interface).  Information on
Pegasus Mail is available at http://www.cuslm.ca/pegasus/

Release notes for PGP Open Encryptor Interface version 1.1:

1.  Substantially updated the documentation (including adding
    basic use instructions and troubleshooting sections).
2.  Fixed a problem where encrypted messages that do not actually
    contain encrypted material would be blank in the message Reader.
3.  Substantially improved error-checking and reporting.
4.  Append an advisory text string to a decrypted message (as well
    as the appropriate system sound) if and only if a digital
    signature is found.  (I hated to do this, but I got tired of
    explaining that the digital signature is invisible in decrypted
    messages, and there was no other good way to notify the user.)

Release notes for PGP Open Encryptor Interface version 1.01:

1.  Fixed a problem where signature verification reported that no
    signature could be found when the real condition was that no
    key could be found to verify the signature.

General Release notes:

1.  Only public key cryptography is supported in this release, NOT
    conventional cryptography.
2.  Basic Key Management functions are implemented:
    a.  To add a public key block contained in a message to your Key
        Ring, either Open or select the message before invoking Key
        Management.  (If a public key block is placed in a digitally
        signed and/or encrypted message, it will not be recognized
        automatically by this interface.)  You can also invoke Key
        Management and paste a public key block into the dialog from
        the Windows Clipboard (which does of course work with a
        signed and/or encrypted message).
    b.  You can check to see if a given email address is on your Key
        Ring -- just paste the email address (without the name) into
        the dialog box control.
    No other Key Management functions are implemented at this time.
3.  Both digital signing and signature verification are implemented:
    a.  If a secret pass phrase is needed (and not provided in
        the PGPPASS environment variable), it MUST be provided each
        time in the WinPMail Password field.
    b.  Please note that signature verification of non-encrypted
        messages is a strictly *manual* process -- you must expliticly
        use the WinPMail menu.  This is a characteristic of WinPMail,
        NOT this interface.
4.  When encrypting:
    a.  The recipient email address (e.g., [e-mail]) will
        normally select the appropriate public key automatically, but
        it may be overridden with an entry in the WinPMail Password
        field if the message is not also being digitally signed.
    b   You should NEVER enter a secret pass phrase when encrypting
        unless you are also signing the message.  (See use
        instructions below.)
    c.  Your recipient may need to add also-known-as entries to
        his/her public key to ensure that you match on various forms
        of email addresses (e.g., also known as
        [e-mail]).
5.  If encryption or signing fails (e.g., because the recipient is not
    on your key ring, or because your secret pass phrase was
    incorrect), an empty message will be sent.  This is a
    characteristic of WinPMail, NOT this interface.
6.  Copies to self of encrypted and/or signed messages are NOT
    encrypted and/or signed.  This is a characteristic of WinPMail, NOT
    this interface.  (If you want an encrypted and/or signed copy, BCC
    yourself.)
7.  It is normally NOT possible for you to decrypt message that you
    have encrypted for someone else (since you do not have that
    person's secret key).  However, you can establish a master
    decryption key by setting the PGPJNKEY environment variable to a
    string needed to select the appropriate public key (yours or not).
    TEST FOR PROPER OPERATION (BY DECRYPTING A MESSAGE ENCRYPTED FOR
    SOMEONE ELSE) BEFORE YOU DEPEND ON IT!  It may be a good idea to
    add an also-known-as alias just for this purpose.
8.  The Cancel button does not work on the Decryption dialog box.
    This is a characteristic of WinPMail, NOT this interface.
9.  When you do a Find on a folder, WinPMail puts up the Decryption key
    dialog for every encrypted message, even when you are only
    searching headers, which can make the process painful.  This is a
    characteristic of WinPMail, NOT this interface.
10. Attachments to encrypted messages are NOT supported.  (Outgoing
    attachments to encrypted messages are NOT encrypted, and incoming
    binary attachments are corrupted.)  This is a characteristic of
    WinPMail, NOT this interface.
11. Windows 3.10, Windows for Workgroups 3.11, and Windows 95 are
    supported.  Windows NT and OS/2 have NOT been tested and are NOT
    currently supported.  (Windows NT is likely to work, but OS/2 in
    not likely to work because of subtle incompatibilities in IBM's
    implementation of certain Windows API functions.)  USE THEM AT YOUR
    OWN RISK.
12. MIT PGP 2.6.2 is supported in this release.  Other versions of PGP
    have NOT been tested and are NOT currently supported.  (The
    international version of PGP 2.6.2 is likely to work.)  ViaCrypt PGP
    has NOT been tested for this release, but is expected to be
    supported in a subsequent release.  USE THEM AT YOUR OWN RISK.
13. Reassembly and decryption of multiple-part PGP messages is NOT
    supported.
14. PGP messages sent by other WinPMail Open Encryptor PGP interfaces
    may not trigger this interface.  (Other PGP sources should not be a
    problem.)  This is a characteristic of WinPMail, NOT this
    interface.
15. A good way to set the PGPPASS environment variable is to type it into
    RAM in a step in your AUTOEXEC.BAT file (so that it's not stored on
    disk).  A good way to do that is with the freeware 'setenv'
    <ftp://ftp.uoknor.edu/mirrors/SimTel/msdos/envutil/stnvjw25.zip> e.g.,
    setenv PGPPASS %prompt %noecho Enter your secret PGP passphrase:
16. Be careful not to use too long a "secret pass phrase" if you're going
    to type it in each time -- because of the DOS command line length
    limit, very long secret pass phrases may be truncated (and therefore
    fail).

To install the PGP Open Encryptor Interface:

1.  UnZIP in a subdirectory of FORMS called PGPJN
    (e.g., \PMAIL\FORMS\PGPJN).  Do NOT use a different name -- it MUST
    be exactly PGPJN!
2.  Copy the PGPJNP.FFF file up to your WinPMail directory (e.g.,
    \PMAIL).
3.  Make sure that you have set the environment variable TEMP (in your
    AUTOEXEC.BAT file) to point to a valid hard disk directory where
    this interface can create temporary files.
4.  Make sure that PGP is installed correctly, and that the PGPPATH
    environment variable is set correctly.  (If PGPPATH is set, PGP
    does not need to be in your PATH.)
5.  Run PGP manually through both public key encryption to yourself
    and decryption of what you encrypted BEFORE using this interface.
    (You must of course first generate your own secret-public key pair.)
6.  Encrypt and send a message to yourself with this interface to test
    operation BEFORE using it for real email.

Simple use instructions for this interface:

1.  Get PGP working manually BEFORE trying to use this interface!
    (Do NOT ask me for help on PGP!)
2.  To Encrypt messages to a given recipient, or to Verify incoming
    Digital Signatures, you MUST have that person's public key on your
    PGP Key Ring (which is maintained by PGP).  When you have a PGP
    PUBLIC KEY BLOCK (it will say just that) that you want to Add to
    your PGP Key Ring:
    a.  Select a message in a WinPMail Folder or open a message in the
        WinPMail Reader.
    b.  Use the Folder or Reader menu Special | Key Management to open
        my Key Management dialog.
    c.  If you selected or opened a message that contains a PGP PUBLIC
        KEY BLOCK, it will automatically appear in the Key Management
        dialog box.  Otherwise you can use the Windows Clipboard to
        paste a PGP Public Key Block into the dialog box.
    d.  Click on "Add Key to Ring".
    e.  Click on "Close" when you are done with Key Management.
    f.  The recipient's public key is normally selected automatically
        by the recipient's email address (NOT the recipient's name),
        so make sure that the recipient includes the email address in
        the PGP PUBLIC KEY BLOCK (together with any alternates that
        you might need/want to use).
3.  To check to see if a given person's public key is on your PGP Key
    Ring (which is maintained by PGP):
    a.  Select a message in a WinPMail Folder or open a message in the
        WinPMail Reader.
    b.  Use the Folder or Reader menu Special | Key Management to open
        my Key Management dialog.
    c.  Type in the name or email address, or paste it in from the
        Windows Clipboard.  (You can only check one at a time.)
    d.  Click on "Check for Key".
    e.  Click on "Close" when you are done with Key Management.
    f.  The recipient's public key is normally selected automatically
        by the recipient's email address (NOT the recipient's name),
        so make sure that the recipient includes the email address in
        the PGP PUBLIC KEY BLOCK (together with any alternates that
        you might need/want to use).
4.  To actually Encrypt a message that you have composed:
    a.  Click the "Encrypt..." check box on the header of the Message
        composer window to bring up the Message Encryptions dialog
        box.
    b.  Select "(JN) PGP Public Key" next to "Encryption method."  If
        you don't see "(JN) PGP Public Key" in the list of available
        encryptors, then YOU HAVE NOT INSTALLED MY INTERFACE PROPERLY.
    c.  You normally do NOT have to enter a "Password"!  The recipient
        email address is normally used to automatically select the
        recipient's public key.  (You can use the "Password" field to
        override the email address for looking up the public key if
        you KNOW that the email address won't work properly.)
    d.  "Encrypt message" should already be checked.
    e.  Click on "OK".
    f.  Remember that attachments to encrypted messages are NOT
        supported.
    g.  Send the message as usual.
    h.  Note:  If you are using WinPMail in an off-line environment,
        encryption will not occur until the message is actually being
        transmitted.  If PGP cannot find your recipient's Public Key,
        an error dialog will appear and a blank message will be sent.
5.  To add a Digital Signature to a message that you have composed:
    a.  To use the Digital Signature feature you MUST have created
        your own secret/public key pair.  See the PGP documentation
        for how to do this.  (Do NOT ask me for help on PGP!)
    b.  Click the "Encrypt..." check box on the header of the Message
        composer window to bring up the Message Encryptions dialog
        box.
    c.  Select "(JN) PGP Public Key" next to "Encryption method."  If
        you don't see "(JN) PGP Public Key" in the list of available
        encryptors, then YOU HAVE NOT INSTALLED MY INTERFACE PROPERLY.
    d.  If you have defined a "secret pass phrase" for your own PGP
        secret key, and if you have not set the PGPPASS environment
        variable, you MUST enter your "secret pass phrase" in the
        "Password" control.  (See the Release Notes above for how to
        set PGPPASS in your AUTOEXEC.BAT file.)
    e.  UNcheck "Encrypt message" and check "Add digital signature".
    f.  Click on "OK".
    g.  Remember that attachments to digitally-signed messages are
        NOT supported.
    h.  Send the message as usual.
    i.  Note:  If you are using WinPMail in an off-line environment,
        digital signing will not occur until the message is actually
        being transmitted.  If your "secret pass phrase is invalid",
        an error dialog will appear and a blank message will be sent.
6.  To BOTH Encrypt and add a Digital Signature to a message that
    you have composed, combine the above procedures.  Note that
    you will not be able to override the recipient's email address
    with the "Password" control, since that is reserved for your
    "secret pass phrase" (even if you don't have one).
7.  Decryption:  When you try to open (or otherwise access; e.g.,
    a folder Find) an encrypted message that you have received,
    WinPMail will automatically open the "Enter key to decrypt
    message" dialog box.  If you have defined a "secret pass phrase"
    for your own PGP secret key, and if you have not set the PGPPASS
    environment variable, you MUST enter your "secret pass phrase"
    (each time) in the "Password" control.  (See the Release Notes
    above for how to set PGPPASS in your AUTOEXEC.BAT file.)
8.  To Verify an incoming Digital Signature (which is strictly an
    explicit MANUAL process):
    a.  You MUST have that sender's public key on your PGP Key Ring
        (which is maintained by PGP).  See above for how to add a
        PGP PUBLIC KEY BLOCK to your PGP Key Ring.
    b.  From either the Folder (with the message selected) or Reader
        menus, use the menu item Special | Find/verify digital
        signature...

Troubleshooting:

1.  If you get the error dialog "File error, Cannot find PGPJN.DLL",
    then you did not install this interface correctly!  Go back over
    the installation instructions and make sure the directory you
    created is EXACTLY as specified (i.e., PGPJN).
2.  If you get the error dialog "PGP Interface, TEMP environment
    variable not set properly!" then you failed to set the TEMP
    environment variable to a valid directory where this interface
    can create temporary files.  Go back over the installation
    instructions.
3.  If when decrypting you get the error dialog:
       This message can only be read by:
       xxxxx
       You do not have the secret key needed to decrypt this file.
    where "xxxxx" is your email address, check to be sure that it
    does appear that way on your Key Ring with Key Management |
    Check for Key.  If it does, you may have FORGOTTEN TO ENTER
    YOUR SECRET PASS PHRASE, or ENTERED YOUR SECRET PASS PHRASE
    INCORRECTLY.
4.  Signing of messages by default uses the LAST secret key that you
    created (i.e., the first key on your secret keyring).  If you
    have created more than one secret key, this can cause signing to
    fail.  The work-around is to specify the secret key to use for
    signing with the "MyName" option in your PGP CONFIG.TXT file.
5.  Setting non-default options in your PGP CONFIG.TXT file may
    cause problems.  Restore the defaults and retest your problem.
6.  You can only verify digital signatures if you have the sender's
    public key on your Key Ring!
7.  A public key that you can add to your Key Ring is framed with
    "PGP PUBLIC KEY BLOCK", not "PGP SIGNATURE".  The latter are
    digital signatures that cannot be added to your Key Ring.
8.  While I do NOT provide support (particularly for PGP), I do
    welcome bug/problem reports.  Please be sure to COMPLETELY
    REREAD THIS ENTIRE FILE *BEFORE* submitting a bug/problem
    report -- you may have overlooked the answer to your problem.
9.  If an error dialog from this Interface is involved in any way,
    please be SURE to use the Windows clipboard to copy the text
    from the error dialog into your problem report.

John Navas <[e-mail]>