home *** CD-ROM | disk | FTP | other *** search
PGPREXX 1.2 Aug 7, 1996 -------------------------------------------------------------------- This is release 1.2 of PGPREXX, a package of seven REXX scripts to give PGP functionality to any OS/2 mail program. It has been written by Lüko Willms in Frankfurt/Main, Germany <Lueko.Willms@T-Online.de>. For changes in version 1.2, see section 2.1 further below. Please send any comments to me via e-mail, snail mail, or fax. If you want to register (no charges), send me a postcard with some nice views of your city. Please find my full address at the end of this text. There are seven REXX scripts in this package: PGPenCod.CMD - signs and encodes any outgoing message PGPdeCod.CMD - decodes incoming PGP signed messages PGPckSig.CMD - checks PGP signatures in incoming messages PGPadKey.CMD - adds a PGP public key block from a message SPLTMAIL.CMD - auxiliary program to PGPenCod.CMD JOINMAIL.CMD - auxiliary program to PGPenCod.CMD PGPEXEC.CMD - auxiliary program to PGPenCod.CMD An eighth script is included to help overcome a temporary problem with the Post Road Mailer: NUL2SPAC.CMD - see section 6 Table of Contents ================= 1. Legal Stuff 2. Description 2.1 Format of Logfile 2.2 Changes in Version 1.2 2.3 Changes in version 1.1 3. Installation requirements 4. Installation 4.1 Post Road Mailer 4.2 PMMail 4.3 MR/2 ICE 5. Technicalities 6. Restrictions and known problems 6.1 MIME 7. Where to get PGP 8. Getting PGP 2.6.3i by FTP 8.1 Norway 8.2 Europe 9. PGP Return Codes 10. Where to get this software 11. How to contact the author 1. Legal Stuff -------------- PGPREXX is provided "as-is" without any warranties (or conditions), expressed or implied with respect to the software, including the implied warranties (or conditions) of merchantability and fitness for a particular purpose. The entire risk arising out of use or performance of the program remains with you. In no event, will the copyright holder be liable for any lost profits, lost savings, incidental or indirect damages or other economic consequential damages, even if I have been advised of the possibility of such damages. In addition, I will not be liable for any damages claimed on you based on any third party claim. Copyright 1996 Lüko Willms PGPREXX can be freely copied provided the packaging with the PGP signed inner ZIP archive remains intact. 2. Description -------------- These scripts have been tested sucessfully with Post Road Mailer (PRM) version 1.05, 1.99, and 2.0, PMMail 1.51 and 1.52 and MR/2 ICE versions from 1.05 upwards. PGP REXX might also work with other mailers like IBM's Ultimail or others which allow for User Exits or REXX scripts to be run from filters. Even more easy when the mailer uses SENDMAIL, since this is a separate program and process, and the PGP encoding can easily occur between queueing the message for sending and the actual sending. You use PGPdeCod.CMD to automatically decode any incoming message which has been encoded by PGP. The script will append the decoded message to the original message. Let me know if you think that this is a security risk. You use PGPckSig.CMD to check the PGP signature of a plaintext message. PGP's diagnosis is appended to the message file so that you can view it together with the message itself. PGPdeCode and PGPckSig have to be configured as a filter for incoming mail, triggered by searching for '-----BEGIN PGP MESSAGE-----' or '-----BEGIN PGP SIGNED MESSAGE-----' in the body of the message. To trigger PGPadKey.CMD, you have to configure the string '-----BEGIN PGP PUBLIC KEY BLOCK-----' as the string to seach for. You use PGPenCode.CMD to sign and encode outgoing messages. It will automatically sign all messages with the secret key of the sender. This is either the last entry of the "FROM:" header lines, or the last entry of the "SENDER:" header lines, when SENDER: is encountered. If all addresses in "TO:", "CC:" and "BCC:" header lines are found in your public key ring, then the message will be encrypted with the keys of those recipients. When one recipient is not found in the key ring, then the message is not encrypted at all. This is a potential security risk since a message you wanted to be encrypted is sent out in the net because you might have entered a recipient's address with a typing error; please let me know what you think about it or even suggest other solutions. If there was an error in PGP processing, PGPREXX will blank out the text. PGPenCode runs in a OS/2 window. PGP will prompt you for your PGP pass phrase to access your private key for signing the message. With PRM, you can configure PGPenCode to run in the foreground, with PMMAIL (up to 1.52) and MR/2 ICE (up to 1.03), you will have to bring its window to the foreground yourself: hit CTRL-ESC to open the window list and select the last entry. You will note that OS/2 is a real multi-tasking operating system: the three programs in the pipe are started simultaneously. 2.1 Format of Logfile --------------------- The logfile is written as text file PGPREXX.LOG to the same directory where the programs are loaded from. There is one line per message being processed with several fields separated by tabulator characters ('09'x). The order of the fields is as follows: Timestamp Indicator for action >>> = outgoing message (PGPenCod) deCod = Message was processed by PGPdeCod ckSig = Message was processed by PGPckSig Message-Id (when known) Result-Code 0 = success, everything else meaning an error detailed error list in section 9 of this text PGP UserIds userids for which has been enrypted and/or signed 2.2 Changes in Version 1.2 -------------------------- It is no longer necessary to put all scripts into a directory on the PATH; PGPenCode.CMD now calls the secondary scripts SPLTMAIL.CMD, JOINMIL.CMD and PGPEXEX.CMD from the directory itself is loaded from. All other scripts are named with full path name in the respective mailer configuration. In 1.1 I introduced an embarassing error, just by a last minute cosmetic change in routine JOINMAIL.CMD. This is fixed. Before uploading this version, I used the scripts myself for a longer period of time. SPLITMAIL.CMD has been renamed to SPLTMAIL.CMD to fit into 8.3 file name schemes on FAT drives. I implemented some basic logging, You will see which outgoing messages are only signed and which ones are encrypted and for whom, and which messages have been decoded and checked for signature. You also find the PGP result code, although is not always very useful. A list of the result codes and their meaning is in section 9 of this text. The logfile is written as file PGPREXX.LOG to the same directory that the programs are executed from. PGPdeSig.CMD is no longer supported. PGPckSig.CMD does it all and better. 2.3 Changes in version 1.1 -------------------------- PGPadKey.CMD was added for adding a PGP public key to your key ring. Documentation was updated, especially in respect to MR/2 ICE 1.04. Changes were made to procedure JOINMAIL.CMD and PGPenCod.CMD. JOINMAIL now waits indefinitely for exclusive WRITE access to the message file; in version 1.0 the procedure would give up waiting after trying 200 times what could result in appending the encrypted message to the plaintext message instead of replacing it. In PGPenCod.CMD, the comparison for a mailbox address from the message with a PGP key user-id was case sensitive 1.0; it is no longer case sensitive now, the same way that PGP itself does operate. Also, provisions were made to remove a trailing comment from a mailbox address. 3. Installation requirements ---------------------------- In order to run the scripts, you need to have PGP.EXE installed on the PATH. Check the end of this text on hints for getting PGP. You must have an environment variable named PGPPATH pointing to the directory where your PGP.EXE is found (e.g. in CONFIG.SYS: SET PGPPATH=C:\PGP). The keys in your public key ring need to have the e-mail address in their user-id (i.e. for me I need to have Lueko.Willms@T-Online.de and not just "Luko Willms" in the PGP key userid), otherwise the script won't be able to find the recipient and originator addresses in the key ring. 4. Installation --------------- Copy all seven scripts in a directory of your choice and configure your mailer to use the scripts. JOINMAIL, SPLTMAIL and PGPEXEC are only called internally, and don't need to be configured. Please note that the file name is PGPenCOD.CMD resp. PGPdeCOD.CMD, i.e. just COD and not CODE. This abbreviation is done to fit the file name in 8 characters. 4.1 Post Road Mailer .................... Open the SETTINGS menu and select the USER EXIT submenu. Go to SEND MESSAGE EXIT and enter the path and file name for PGPenCod.CMD. Mark EXIT IS ACTIVE and select the FOREGROUND radio button. Deactivate PRM's built in PGP support (which doesn't work properly, or at least until some point in the 1.99 beta series). Open the FEATURES drop down menu and select FEATURES. Select to ADD A NEW FILTER. Enter an appropriate DESCRIPTION (e.g. PGP Decode), ender '-----BEGIN PGP MESSAGE-----' as the SEARCH STRING (without quotes), enter the path and file name of PGPdeCod.CMD in the USER EXIT field. Hit the FOREGROUND radio button in the USER EXIT box. In OPTIONS, activate FILTER IS ACTIVE and CASE SENSITIVE; in SEARCH select MESSAGE BODY, in REACTION select NO REACTION. See section 6 for a problem with release 2.00 or 1.99 or PRM. 4.2 PMMail .......... This refers to version 1.51 and 1.52 of this mailer. Select ACCOUNT\UTILITY SETTINGS\FILTERS. Give an appropriate description, like "PGP decode", make TYPE = Incoming, in SEARCH select <BODY>, in FOR THE FOLLOWING TEXT enter '-----BEGIN PGP MESSAGE-----', in AND TAKE THE FOLLOWING ACTIONS activate EXECUTE REXX SCRIPT and enter the full path and file name for PGPdeCOD.CMD. Do the same for '-----BEGIN PGP SIGNED MESSAGE-----' and PGPckSig.CMD, and '-----BEGIN PGP PUBLIC KEY BLOCK-----' and PGPadKey.CMD. Select ACCOUNT\UTILITY SETTINGS\REXX Exits. Activate MESSAGE SEND EXIT and enter the full path and file name for PGPenCOD.CMD as the script to run. Alternatively you can configure PGPenCOD.CMD as a filter for outgoing messages and let it sign and enrypt only when a certain string is found in the outgoing message. Starting with PMMAIL 1.53, you can specify that the scripts run in the foreground. 4.3 MR/2 ICE ............ Select UTILITIES\FILTER MAINTENANCE, make a NEW filter. Give it an appropriate name, like PGP encrypt. For PGPenCod, select "On Event: PreSend" for FILTER TYPE, select ALWAYS for PROCESS WHEN MESSAGE, select LINK TO REXX as the DESIRED ACTIONS and enter the path and file name for PGPENCOD.CMD,with a leading asterisk to force foreground processing. Activate ENABLED. In version 1.07, there is a new filter type "To Outbox" which would be the best way, but it is not yet fully functional in this version. Make a NEW filter for incoming messages, select BODY among the SEARCH AREAS FOR and enter '-----BEGIN PGP MESSAGE-----' as the string to search for. Make the FILTER TYPE to INBOUND, select MATCHES in PROCESS WHEN MESSAGE, activate in DESIRED ACTIONS the LINK TO REXX and enter full path and file name for PGPdeCOD.CMD. Make other filters for incoming or stored messages for checking the PGP signature of a message or adding the PGP Public Key block from a message. Don't forget to put the leading asterisk before the path and file name of the REXX script to force foreground operation, where appropriate. MR/2 ICE offers an advantage here over the other mailers in so far as you can call filters to be processed on any message stored in your folders at any time, not only at reception or sending time. So you might be more at leasure to do the incoming processing at a time when you want, without the pressure of entering your pass phrase during online time. Up to 1.07, the "Filter Type: Demand" is not yet functional. Using the REXX script MSGUTIL.CMD, and using some CTRL-Fxx combination should do it, I was told by MR/2 ICE's author. 5. Technicalities ----------------- PGPdeCOD.CMD is simple and straightforward. PGPenCOD.CMD requires some more explanation. PGPenCOD.CMD first builds a table of all key user ids in your PGP key ring. Then it builds tables for all recipients, for all FROM addresses and all SENDER addresses. The latter three are reduced to the mailbox address (user@host.domain); this means that the PGP key will only be found when this e-mail address is included in the PGP key userid. When all recipients are found in the PGP key table, the message will be encrypted for all recipients, otherwise it will not be encrypted at all. The actual encoding is done by calling SPLTMAIL.CMD, PGP.EXE and then JOINMAIL.CMD in a pipe, i.e. without any temporary files created by the scripts themselves. SPLTMAIL sends all header lines via the SESSION queue to JOINMAIL. but writes the message body to standard output where it is captured by PGP. JOINMAIL receives the untouched header lines from the queue, and the PGP signed or encrypted (and signed) from PGP via standard input. Join mail waits until it can OPEN WRITE the message file handed over from the mail program, and overwrites the file by the newly created text. 6. Restrictions and known problems ---------------------------------- It can be a nuisance when you have to enter the pass phrase to access your private key for every message sent and every PGP encrypted message received. This could be overcome by starting your favorite mailer in a CMD file where you ask once for the pass phrase and then store it into an environment variable. It might be better to encrypt the outgoing messages for the sender, too, to avid that accidentally a message is sent out in plaintext, unencrypted, because someone's recipient address has suffered from a typo. Let me know what you think. In PRM 2.00 or the 1.99 beta series, PRM will not show the first part or all of the text which is appended by PGP to the end of the message as it came in. The problem does not occur when you print the message or quote it in a reply. This is caused by a NUL ('00'x) character near the end of the incoming message. You find a little REXX script named NUL2SPAC.CMD in this package which you can call as NUL2SPAC 1F2E3D4C.POP to change the NUL to a SPACE. You find the actual filename of the mail at the end of the folder list. You could also configure NUL2SPAC.CMD as the receive message exit so that it is executed for every incoming mail. You could also try to add it to the filter list (search for '-----BEGIN PGP'), but I have not yet managed to get it working; it seems that PRM only activates one filter per message. But you might be more cute than I am and avoid the error which I might have made. Innoval is aware of the problem, and hopefully will do away with it in release 2.01 announced for end of August 1996 or in 2.1 to come sometime later. Also with PRM, I observed that only the first calls to the PGP scripts will execute in the foreground, and from some point on only in the background. Check your window list with CTRL-ESC and select the appropriate window which will probably the last one in the list. 6.1 MIME -------- You will have problems when you use Content-Transfer-Encoding=Quoted-Printable and PGP encoding. Several users of MR/2 ICE have reported problems with this. MR/2 ICE converts the message to the format it will actually be transmitted to the next SMTP hop, and PGP will then encrypt it, but not change the Content-Transfer-Encoding=Quoted-Printable header line. So the receiving mailer will first interpret the Content-Transfer-Encoding and destroy the PGP checksum which is a line also starting with an equal sign (=). The solution will lie in adapting the ideas from PGP/MINE, I think, but this requires more work what I can't do at this moment in time. 7. Where to get PGP ------------------- As a private user, you can get PGP free of any charges via FTP, from Online services like Compuserve or BBSes. You should get version 2.6.3i (i stands for international) when you live outside the USA (see following paragraphs), and version 2.6.2 when you are a US citizen living in the USA or a Canadian citizen living in Canada. Then you can either download it from the MIT at http://web.mit.edu/network/pgp.html (MS-DOS, UNIX and Mac versions precompiled, or source code) or you contact the company Viacrypt for a commercial version at http://www.viacrypt.com or mailto://info@viacrypt.com. You might also get source code from www.ifi.uio.no which can be compiled for use in the USA, and which then corresponds to the latest 2.6.3 release. 8. Getting PGP 2.6.3i by FTP ---------------------------- This is an edited version of the list of PGP 2.6.3i FTP sites, reduced to those addresses relevant to OS/2. Executable programs for other operating systems like MS-DOS, Windows, Unix, Macintosh, Amiga, Atari, Archimedes are also available at those sites. 8.1 Norway .......... The main distribution site for PGPi is ftp.ifi.uio.no. The latest international PGP version can always be found here. You can call http://www.ifi.uio.no/~staalesc/PGP to get information or FTP directly to: ftp.ifi.uio.no /pub/pgp/doc/ - PGP User's Guide, drafts, specifications /pub/pgp/faq/ - FAQs /pub/pgp/lang/ - language modules /pub/pgp/pc/os2/ - OS/2 tools & binaries /pub/pgp/src/ - source code (all platforms) 8.2 Europe .......... PGP 2.6.3i is also available from a number of other European FTP sites. I am not aware of any export restrictions in the countries listed here. Standard disclaimer applies. ftp.cert.dfn.de /pub/tools/crypt/pgp/doc/ - Documentation /pub/tools/crypt/pgp/language/ - language modules /pub/tools/crypt/pgp/pc/os2/ - OS/2 binaries /pub/tools/crypt/pgp/unix/ - source code (all platforms) ftp.encomix.es /pub/pgp/lang/ - language modules /pub/pgp/pgp263i/ - source code and binaries (MS-DOS & OS/2) ftp.funet.fi /pub/crypt/cryptography/pgp/doc/ - Documentation /pub/crypt/cryptography/pgp/language/ - language modules /pub/crypt/cryptography/pgp/pc/os2/ - OS/2 binaries /pub/crypt/cryptography/pgp/unix/ - source code (all platforms) ftp.dsi.unimi.it /pub/security/crypt/PGP/ - source code, binaries, tools (all platforms) ftp.sunet.se /pub/security/tools/crypt/pgp/language/ - language modules /pub/security/tools/crypt/pgp/pc/os2/ - OS/2 binaries /pub/security/tools/crypt/pgp/unix/ - source code (all platforms) ftp.ox.ac.uk /pub/crypto/pgp/doc/ - Documentation /pub/crypto/pgp/language/ - language modules /pub/crypto/pgp/pc/os2/ - OS/2 binaries /pub/crypto/pgp/unix/ - source code (all platforms) Last updated April 11, 1996 by Staale Schumacher <stale@hypnotech.com> 9. PGP Return Codes ------------------- PGP Return Codes are logged to PGPREXX.LOG. This list is from the PGP source PGP.C version 2.6.3i: /* Possible error exit codes - not all of these are used. Note that we don't use the ANSI EXIT_SUCCESS and EXIT_FAILURE. To make things easier for compilers which don't support enum we use #defines */ #define EXIT_OK 0 #define INVALID_FILE_ERROR 1 #define FILE_NOT_FOUND_ERROR 2 #define UNKNOWN_FILE_ERROR 3 #define NO_BATCH 4 #define BAD_ARG_ERROR 5 #define INTERRUPT 6 #define OUT_OF_MEM 7 /* Keyring errors: Base value = 10 */ #define KEYGEN_ERROR 10 #define NONEXIST_KEY_ERROR 11 #define KEYRING_ADD_ERROR 12 #define KEYRING_EXTRACT_ERROR 13 #define KEYRING_EDIT_ERROR 14 #define KEYRING_VIEW_ERROR 15 #define KEYRING_REMOVE_ERROR 16 #define KEYRING_CHECK_ERROR 17 #define KEY_SIGNATURE_ERROR 18 #define KEYSIG_REMOVE_ERROR 19 /* Encode errors: Base value = 20 */ #define SIGNATURE_ERROR 20 #define RSA_ENCR_ERROR 21 #define ENCR_ERROR 22 #define COMPRESS_ERROR 23 /* Decode errors: Base value = 30 */ #define SIGNATURE_CHECK_ERROR 30 #define RSA_DECR_ERROR 31 #define DECR_ERROR 32 #define DECOMPRESS_ERROR 33 10. Where to get this software ----------------------------- The latest version of PRPREXX will be available as file PGPREXxx.ZIP, with xx being the version number, in Compuserve in the forums OS2USER, OS2UGER and NCSA (this is version 1.2, so it will be file name PGPREXX12.ZIP), on Hobbes and and ftp://ftp.ifi.uio.no/pub/pgp/pc/os2. As to Hobbes, I have uploaded the previous versions only to hobbes.cdrom.com, but it spread to other Hobbes sites as well. 11. How to contact the author ------------------------------ Send e-mail to one of the following addresses: Lueko.Willms@T-Online.de L.WILLMS@LINK-F.rhein-main.de 100021.64@compuserve.com Send paper mail to: Lüko Willms Nusszeil 54 D-60433 Frankfurt/Main Germany Dial phone number +49-69-529208 fon (i.e. voice) +49-69-519886 fax --------- End of Text ------------------------------------------------ 
