=======================================================================

This version of HPACK is a beta release of the final version. A
previous version, version 0.75 was released as a prototype to get
feedback from users for the final version. The 0.75 release carried a
warning message that it was a prototype only and not for general use.
The 0.78 release supersedes version 0.75, and includes:

- Improved portability to all OS's (the Mac port was done in a *single
day*), and easier portability to different mutations of Unix.

- Public-key and conventional encryption of archives or individual
files.

- Data authentication/manipulation detection using RSA digital
signatures.

- Multi-disk archive handling (your mileage may vary on this).

- Improved support for OS-specific features such as OS/2 extended
attributes.

- Various small improvements based on suggestions from users.

- Improved support for multilingual versions (extended ASCII, Japanese
DBCS, Unicode, etc). Currently HPACK is available in four different
languages.

- High-quality Postscript documentation.

Note: HPACK is a 100% matter product. In the unlikely event that it
should contact antimatter in any form, a catastrophic explosion will
result.

=======================================================================


General Layout
==============

The executable distribution of HPACK contains the following files:

README.1ST - This file.
HPACK{.EXE} - The HPACK archiver
HPACK.DOC - The HPACK documentation.
HPACKEXT.DOC - The extended documentation for advanced users.
REGISTER.DOC - HPACK registration form.
HPACK.SIG - Digital signature for executable (MSDOS, OS/2 only)
KEY.ASC - My PGP 2.0 public key (MSDOS, OS/2 only)

The layout of the source distribution is given in the file HPACKSTD.TXT.


Running HPACK: MSDOS and OS/2
=============================

The OS/2 version is quite similar to the DOS version, except that it is
HPFS-aware and will handle extended attributes for files and directories if
this is specified by the [-a]ttribute switch. This version will also give an
HPACK archive certain extended attributes such as type and icon information.
Apart from that, it behaves as the DOS version. The archive containing HPACK
in fact contains two executables, HPACK_16.EXE and HPACK_32.EXE.
HPACK_16.EXE is a 16-bit version for use with OS/2 versions before 2.0, and
HPACK_32.EXE is a 32-bit version for use with OS/2 versions 2.0 and above.
The appropriate executable should be renamed to HPACK.EXE before use.


Running HPACK: Unix
===================

The Unix version of HPACK is distributed in source form as hpack78.tar.Z.
It has been tested under AIX RS6000, AIX 386, AIX 370, Irix, ISC Unix,
Posix, SunOs, SVR4, and Ultrix and is known to compile succesfully on these
systems (the tar.Z was created by moving HPACKed DOS source onto a DECstation
and extracting and re-compressing it there. Note that in some cases the code
run wasn't the latest, up-to-the-minute release so it may be necessary to
tweak a line or two). Hopefully it should be possible to compile it on other
systems with a minimum amount of modification. Before compiling it on a new
system, you should briefly read at least the second half of HPACKSTD.TXT in
the DOCS directory (everything after the "Getting Started" heading) which
contains notes on porting and an overview of the system-specific functions
contained in the code. Edit the makefile for your system (Unix flavour),
also edit DEFS.H (if necessary) as appropriate. Depending on your Unix
flavour you will probably have to tune SYSTEM.H and UNIX.C a bit (eg if
you've got a mkdir() or not, a memmove(), a rename(), and a few other odds
and ends). It took about half an hour for Ultrix (of which about 20 minutes
was spent waiting for the compiler), in general it only seems to take a few
minutes to adapt it to any new Unix variant.

The only problems you may run into is with running it on 64-bit systems, I
don't have any experience with them so maybe I'm just being pessimistic,
certainly the move from 16 to 32-bit showed up only one minor problem which
was fixed in about 5 minutes.

Once you get it going, send the diffs to me ([email protected]) and I'll
integrate them into the code. If you can't get it to compile on one of the
above systems, I can probably arrange to mail you an executable - hassle me
via email.


Running HPACK: Mac
==================

The Mac version is currently a rather simplistic port of the generic CLI
code. When run, it will prompt for a command-line as used by the CLI
version, and display all output on the console window. A full Mac
implementation should eventually become available, based on the Windows
version.

The Mac port was done in a single day, mainly to demonstrate how easy it was
to move it to virtually any OS, even one whose filesystem interface is
radically different from the generic Unix-like one assumed by the high-level
code. The fact that it was done in one day shows when the program is run, if
anyone wants to add the usual GUI paraphernalia let me know.

THIS IS NOT THE FINAL FORM OF THE MACINTOSH VERSION OF HPACK. IN ITS FINAL
FORM HPACK WILL HAVE THE USUAL MACINTOSH USER INTERFACE, NOT THE CURRENT
COMMAND-LINE ONE. THE CURRENT VERSION HAS BEEN RELEASED MAINLY TO PROVIDE A
MEANS OF TRANSFERRING ARCHIVES TO/FROM THE MAC (and also to persuade someone
to add a Mac interface to it :-).

Important note: When working on a port like this, never promise to buy
everyone in the room pizza if it works the first time you run it.


Running HPACK: Amiga
====================

The Amiga HPACK is virtually identical to the generic Unix-like command-
line version. Unfortunately, due to lack of access to Amiga hardware, this
version hasn't been tested much (if someone gives me an A4000 I'll test it to
death, I promise).

When compiling the code, Lattice C will give about half a dozen warnings per
file about unrecognised pragmas, function return value mismatches, and
conversion from const pointer to non-const or volatile blah blah blah. These
are just Lattice C being Lattice C and can be ignored. The problem can be
fixed by removing all #pragma directives and 'const' keywords, not using any
of the compiler built-in functions (memset, strcpy, etc), and ignoring the
fact that it doesn't like returning an int + constant from an int-valued
function. In addition, Lattice C has a number of code generation bugs which
HPACK must work around. Basically the Amiga HPACK exists despite of Lattice
C rather than because of it.


Running HPACK: Archimedes
=========================

The Archimedes HPACK is virtually identical to the generic Unix-like
command-line version. The main extra feature is the addition of the -zinvert
command which will convert filenames like x.c and y.h to the files x and y in
directories c and h. Since this isn't implemented yet it shouldn't bother
you much anyway (NB it'll be added when the directory-handling functions
mkdir() and mv() are implemented, or when I get lots of email asking me to do
it).

When compiling the code, Desktop C will give several warnings for some files
about type conversions, which can either be worked around with expressions
like a = ( int ) ( ( int ) b + ( int ) c ) ), or ignored. As with the Amiga
version, I couldn't do too much testing on this one.


Running HPACK: Atari ST
=======================

This version is actually currently vapourware - the machine it was being
built on suffered a hard drive crash and the executable and all changes to
the code were lost. However the person who did the port claims it would take
about half a day to get a version running again from the current code. Sorry
about this folks (again, if someone gives me an ST I'll do the port myself
:-).


Ghod it's slow!
===============

I know - it's difficult to have both speed and portability (or to rehash an
old saying: "Fast, portable, good - choose any two"). HPACK can never really
compete with 'one-platform wonder' archivers which are highly tuned for a
particular system. HPACK has been tuned for compression performance, not
speed - it is recommended that, if the OS supports it, it be run in the
background with the [-s]tealth mode switch.


Where to get HPACK:
===================

The latest version of HPACK should always be available from the following
BBS systems and archive sites:

Black Cat BBS +64 9 360-2506. Log on as "HPACK" with password "HPACK".
This account has access to a files area containing copies of HPACK for
various systems, and public and private message areas (Areas #2 (private)
and #11 (public)) for feedback on HPACK.

+49 234 770457 (data (V.32bis/V.42bis) + fax G3 incl. v.17), FIDO address
2:245/302.7, sysop: Peter Sowa. This BBS contains the German versions of
the HPACK executables. Note the since communcation is by snail mail, new
releases may take a week or so to appear.

The garbo.uwasa.fi (128.214.87.1) archive site and all garbo mirror sites
worldwide.

The nic.funet.fi archive site an all mirror sites worldwide.

The kauri.vuw.ac.nz archive site. If possible only NZ users should use
this site since the bandwidth of the overseas link is somewhat limited.


Availability of HPACK for Other Systems:
========================================

Anyone want to port HPACK to their particular pet system? It's about 500K
of ANSI C code, with some low-level system I/O thrown in to confuse you
(through some mysterious process this amount increases by about 10K a week,
so get it now before it gets too much). A knowledge of assembly language is
probably necessary on low-end systems to speed up a few of the core
compression routines. If you want to port it to any other system, drop me a
line.....

Currently HPACK is in the process of being ported to, or has been ported to,
a number of systems. The systems, together with email contact addresses/
phone numbers for the people claiming to be working on ports, are:

HPACK/DOS Peter Gutmann - [email protected] or
[email protected]
Ph.+64 9 426-5097
HPACK/UNIX Stuart Woolford - [email protected]
Ph.+64 9 426-3464
HPACK/OS2 John Burnell - [email protected]
HPACK/Windoze Lynn Prentice - [email protected]
HPACK/OS2 PM
HPACK/Mac Peter Gutmann - [email protected] or
[email protected]
Ph.+64 9 426-5097
HPACK/Archimedes Peter Gutmann - [email protected] or
[email protected]
Ph.+64 9 426-5097
HPACK/Amiga Peter Gutmann - [email protected] or
[email protected]
Ph.+64 9 426-5097


International Versions of HPACK:
================================

All the text strings contained within HPACK are generated from a
definitions file via a preprocessing tool. To create versions of HPACK in
other languages, all that is necessary is to translate the text in the
definitions file, run it through the preprocessor, and rebuild HPACK. This
will then change all the text strings, prompts, etc into the form given in
the definitions file. This file is available on request from the HPACK
author, or as part of the Unix source distribution. Currently English,
German, Dutch, and Italian versions exist.


Security of HPACK Authentication/Encryption:
============================================

There has been some talk recently on how trivial it is to break the
authentication/encryption used by many archivers. To answer any worries
about the security of HPACK encryption/authentication, I have included with
the source code distribution two sample archives, DATA/CRYPT.HPK and
DATA/SECURE.HPK, for which I offer the following challenge:

SECURE.HPK contains a single stored file called SAMPLE.TXT dated 1st May
1992, with the file itself containing the text '01234567890123456789'.
I challenge anyone to alter this archive in any way and yet retain the
valid signature (that is, HPACK when checking it should report that it
still contains my valid signature). Alternatively, I challenge anyone
to create an HPACK archive which contains a forged signature from me.
Sample signature generation/checking code is included in the HPACK
source.

CRYPT.HPK contains twenty conventional-key encrypted text files which
contain 2 lines each of HPACK.DOC, beginning at the start of the
document (for a total of 40 lines worth of plaintext). The encryption
password is a simple lowercase-only English phrase, and is identical
for all twenty files. The nature of the data is such that most of it
won't even be compressed - it'll be stored as is. These conditions
reflect the absolute worst-case situation in archive encryption, where
the attacker knows the encrypted plaintext, the password is relatively
simple, and HPACK's most insecure encryption method is used (this
provides a realistic basis for an attack on the encryption. Any
encryption method, no matter how bad, can be made to appear secure if
the initial conditions are biased enough).

I challenge anyone to provide me with either the passphrase used to
encrypt the data, or to encrypt the next 2 lines of HPACK.DOC in such
a way that they can be decrypted with the password. Sample
en/decryption code is available as part of HPACK or a I will email
anyone who requests it a reference implementation in C.

In addition I will encrypt any data you like with the given passphrase, if
this will help in trying to break the encryption. In fact I'll do anything
short of revealing the password if this helps with an attack on the
encryption. Finally, I will make the password available after some
reasonable period of time, say 6 months, so users can reassure themselves
that it is indeed a genuine password and not some fake garbled mess cooked up
just to make the encryption look good.

The attacks can be mounted on any computer system using any amount of CPU
power and/or custom hardware. More details on the merits of the
encryption/authentication algorithms, along with possible methods of attack,
are given in the file HPACKEXT.DOC.


Credits:
========

Thanks to the following people for helping in HPACK:

Stuart Woolford for the Unix port and endless arguments about the code.
Conrad Bullock and John Burnell for the OS/2 port.

Stuart Woolford and John Burnell for tirelessly finding bugs and making many
helpful suggestions.

All the people listed in the makefile for moving it to their version of Unix
and providing feedback.

Steven Perreau, Hexen Hammer, and David Dix for providing a discussion
(read: flaming argument) forum for HPACK developers on their BBS's over the
years.

Lynn Prentice for allowing the use of the Black Cat BBS to distribute HPACK.

Arrigo Triulzi for providing the Italian translation of HPACK.
Peter de Vocht for providing the Dutch translation of HPACK.
Peter Sowa for providing the German translation of HPACK.

PurpleX for putting up with many silly questions and sarcastic remarks about
the Mac API.

Nick Little for compiling HPACK on a Amiga 500 using Lattice C (wow!)

TMOTA and Edouard Poor for compiling HPACK on the Archimedes.

Philip Zimmermann for letting me steal his ideas (and in some cases code)
from the PGP encryption program.

Lutz Frank for letting me use his 680x0 assembly-language primitives.

All kcbbs users for putting up with endless stirring about HPACK.


The HPACK Curse:
================

In early June 1992 one of the Mac HPACKers downloaded a new release of the
code from a BBS. Shortly thereafter his hard drive died, taking multiple
megabytes of data with it and incapacitating his Mac. He logged onto another
BBS which had an HPACK forum and complained about this. After he logged off,
the VT100 he was using also expired.

In mid-August 1992 an attempt was made to place a copy of the DOS HPACK
executable on an ftp site for pickup by someone interested in it. Shortly
before it was to take place, the machines which were to be used were
unexpectedly shut down for four days for power maintenance. Once they were
back up, the comms machine which handled all ftp traffic became unstable due
to a mysterious hardware problem. This problem remained in evidence for
several weeks.

In late September 1992 the Amiga 500 being used to compile the Amiga HPACK
was destroyed by a power-line spike. As of this writing it is still dead.

In October 1992 the Atari ST hard drive on which the Atari HPACK was being
stored crashed for the last time. This is an interesting case in which the
hardware exhibited a limited degree of precognizance, having crashed several
times even before HPACK was installed.

Does this mean HPACK is cursed? Find out more in the next release....


HPACK as a Compiler Test:
=========================

The HPACK source code may be useful as a benchmark for compilers, as it has
displayed an amazing ability to unearth compiler bugs. It has turned up a
bug in TurboC/TurboC++/BorlandC++ under MSDOS, bugs all over Lattice C
(mainly in the code generator) on the Amiga, a bug in the Sun acc compiler,
a bug in the Xenix cc, a bug in the RS6000 cc optimizer, a bug (or at least a
peculiarity) in the Amiga DICE compiler preprocessor, and has managed to
break the optimizers in TopSpeed C, Watcom C, the Irix cc, Ultrix vcc, and
Desktop C. Various sarcastic comments on the compilers in question are
present in code workarounds at various places (except for the RS6000 cc,
whose optimzer is too awesome to criticize even if it does generate incorrect
code).

It has been suggested that all C compilers should be made to carry a "Safe
for use with HPACK" rating.


The HPACK Warranty:
===================

1. Customer Obligations
-----------------------

1.1. Customer assumes full responsibility that this program meets the
specifications, capacity, capabilities, and other requirements of said
customer, and agrees not to bother the author if the program does not perform
as expected, or performs other than expected, or does not perform at all.

1.2. Customer assumes full responsibility for any deaths or injuries that
may result from the normal or abnormal operation of this program. In the
event of casualties exceeding 1000 persons or property damage in excess of
$10 million, customer agrees that he or she has stolen the program and we
didn't even know he or she had it.

1.3. Customer agrees not to say bad things about the program or the author
to anyone claiming to be from "60 Minutes".

2. Very Limited Warranty and Conditions of Sale
------------------------------------------------

2.1. For a period of 90 minutes, commencing from the time you first thought
about getting this program, we warrant that this program may or may not be
free of any manufacturing defects. It will be replaced during the warranty
period upon payment of an amount equal to the original purchase price plus
$10.00 for handling. This warranty is void if the program has been examined
or run by the user, or if the manual has been read.

2.2. This program is sold on an AS WAS basis. The author makes no warranty
that it is, in fact, what we say it is in our propaganda, or that it will
perform any useful function. We have no obligation whatsoever other than to
provide you with this fine disclaimer.

2.3. Some countries do not allow limitations as to how long an implied
warranty lasts, so we refuse to imply anything.

2.4. There is an extremely small but nonzero chance that, through a process
known as "tunnelling", this program may spontaneously disappear from its
present location and reappear at any random place in the universe, including
your neighbours computer system. The author will not be responsible for any
damages or inconvenience that may result.

3. Limitation of Liability
--------------------------

3.1. We have no liability or responsibility to the customer, the customers
agents, our creditors, your creditors, or anyone else.

-------------------------

Testimony from one of our satisfied customers:

"I hear this crash and I find a rock, wrapped in paper, next to my living room
window. I open up the note and it says, 'You want it in writing? You got it.
Next time, use a *real* archiver. HPACK. We know where you live'."

So why aren't *you* using HPACK?