home *** CD-ROM | disk | FTP | other *** search
/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / HPACK78S.ZIP / docs / hpackstd.txt < prev    next >
Text File  |  1992-12-03  |  65KB  |  1,438 lines
  1.                             HPACK Technical Information
  2.                             ===========================
  3.  
  4.                                (HPACK Level 1 Format)
  5.  
  6.                         HPACKSTD.TXT  Updated 1 July 1992
  7.        "Programming is like sex: One mistake and you have to support it
  8.                             for the rest of your life"
  9.  
  10.  
  11. The HPACK Philosophy:
  12. ---------------------
  13.  
  14.   HPACK was designed along four principles:
  15.  
  16.  - Reasonable compression.
  17.    HPACK's compression currently outperforms all other known archivers running
  18.    in comparable amounts of memory.
  19.  
  20.  - Archive flexibility and portability.
  21.    HPACK's  method  of  storing system-specific information was designed to be
  22.    the  most  easily  portable possible.  The HPACK format can store virtually
  23.    anything you care to throw at it.
  24.  
  25.  - Ease of use.
  26.    The general rule was to only include the functionality that could be fitted
  27.    on a single page of help screen.
  28.  
  29.  - The use of sound algorithms.
  30.    Adding  encryption and authentication options which people will trust their
  31.    data to is of little use if they can be broken in a matter of moments.
  32.  
  33. The  following  document  describes  the  strategy  used  to  implement  these
  34. principles.
  35.  
  36. This  document  describes  the  layout of the Level 1 HPACK format, which is a
  37. reduced version of the full HPACK format  to  enable  it  to  run  on  current
  38. low-end  systems  (mainly  memory-limited  MSDOS machines).  The Level 2 HPACK
  39. format consists of a superset  of  the  Level  1  format  which  is  specified
  40. entirely  using  ASN.1  (Abstract  Syntax  Notation One) and encoded using the
  41. Basic/Distinguished  Encoding  Rules.   The  Level  2  format   is   currently
  42. unimplemented  due to its need for support for things like 64 and 128-bit data
  43. types, and the fact that it will be  written  entirely  based  on  C++  STREAM
  44. objects allowing any program to easily access HPACK data files.  In general at
  45. the  time  of  writing  those systems which have a usable C++ compiler are too
  46. limited to handle the Level 2 format, and those which can handle it don't have
  47. a C++ compiler worth using (or don't have a C++ compiler at all).
  48.  
  49.  
  50. Archive Layout:
  51. ---------------
  52.  
  53.   A standard HPACK archive is laid out as follows:
  54.  
  55.     ======================================
  56.           BYTE[4]: Archive ID: 'HPAK'
  57.     ======================================
  58.                 File 1 data
  59.     --------------------------------------
  60.                     .
  61.                     .
  62.                     .
  63.     --------------------------------------
  64.                 File n data
  65.     ======================================
  66.                 Dir 1 data
  67.     --------------------------------------
  68.                     .
  69.                     .
  70.                     .
  71.     --------------------------------------
  72.                 Dir n data
  73.     ======================================
  74.                Dir 1 header
  75.                     .
  76.                     .
  77.                     .
  78.                Dir n header
  79.     --------------------------------------
  80.               File 1 header
  81.                     .
  82.                     .
  83.                     .
  84.               File n header
  85.     --------------------------------------
  86.             Dirname 1, '\0'
  87.                     .
  88.                     .
  89.                     .
  90.             Dirname n, '\0'
  91.     --------------------------------------
  92.             Filename 1, '\0'
  93.                     .
  94.                     .
  95.                     .
  96.             Filename n, '\0'
  97.     --------------------------------------
  98.         WORD: No directory headers
  99.         WORD: No file headers
  100.         LONG: Length of directory block
  101.         WORD: Directory block checksum
  102.         BYTE: Special info
  103.         BYTE[4]: Archive ID: 'HPAK'
  104.     ======================================
  105.  
  106. Each  archive  begins  with  the ID string 'HPAK', followed by the actual data
  107. stored in the archive.  These files are stored as one continuous block of  raw
  108. data,  with  an  optional  auxDataLength  data  block  following each block of
  109. archived data.  The file  and directory headers  are  in  a  format  described
  110. below.   The  fileNames  and  dirNames  are stored in null-terminated ASCII or
  111. EBCDIC (depending on the source system) format with the  extensions  described
  112. below.
  113.  
  114. The trailer information is stored as follows:
  115.  
  116. typedef struct {
  117.                WORD noDirHdrs;          /* No.of directory headers */
  118.                WORD noFileHdrs;         /* No.of file headers */
  119.                LONG dirInfoSize;        /* Length of archive directory block */
  120.                BYTE specialInfo;        /* The kludge byte */
  121.                WORD checksum;           /* CRC16 of dir.block */
  122.                BYTE archiveID[ 4 ];     /* 'HPAK' or 0x4850414B */
  123.                } ARCHIVE_TRAILER;
  124.  
  125. The dirInfoSize block covers the combined length of the dirHdrs, fileHdrs, and
  126. file and directory names.  The checksum covers the dirInfoSize data as well as
  127. the  fields  in  the  trailer struct up to the checksum field itself (in other
  128. words  all  directory  information  apart from itself and the archiveID).  The
  129. high three bits of the byte of  special  info  currently  have  the  following
  130. values for the prototype versions of HPACK:
  131.  
  132.   0x20 - LZW version, used for development only.
  133.   0x40 - LZA version.  Compression =  2.82 bits/byte (no longer used).
  134.   0x60 - LZA' version. Compression =  2.61 bits/byte.
  135.   0x80 - LZA" version. Compression = ~2.58 bits/byte (est).
  136.   0xA0 - MBWA prot.1.  Compression = ~2.75 bits/byte (est).
  137.   0xC0 - MBWA prot.2.  Compression = ~2.55 bits/byte (est).
  138.  
  139. A special info ID with any of the 3 high bits set  indicates the  archive  was
  140. created with a prototype version of HPACK.
  141.  
  142. The  release  version  of  HPACK  will use this byte as a bitfield to indicate
  143. various extensions to the standard format.  Currently only the low 5 bits  are
  144. used, the remaining high bits being used to indicate the prototype level:
  145.  
  146. typedef struct {
  147.                unsigned multiEnd   : 1; /* Last part of multipart archive */
  148.                unsigned multipart  : 1; /* Part of a multipart archive */
  149.                unsigned secured    : 1; /* Secured archive */
  150.                unsigned encrypted  : 1; /* Encrypted archive */
  151.                unsigned blockCopr  : 1; /* Block compressed archive */
  152.                unsigned spare      : 3; /* Currently unused */
  153.                } SPECIALINFO;
  154.  
  155. There  is  also a possibility that one bit will be used for to flag the use of
  156. the notorious 'B' format (in which  the  archive  directory  as  well  as  the
  157. archive data is compressed).
  158.  
  159.  
  160. Archive Directory Structure:
  161. ----------------------------
  162.  
  163.   An HPACK file header is defined in FILEHDR.H, and is arranged as follows:
  164.  
  165. First,  there is a bitfield to hold information such as the system the archive
  166. was created on and various information pertaining to the file.  This  bitfield
  167. is  described as a struct, but is handled internally via bitmasks to eliminate
  168. any endianness problems:
  169.  
  170. typedef struct {
  171.                unsigned origLen    : 1; /* fileLen field WORD/LONG bit */
  172.                unsigned coprLen    : 1; /* dataLen field WORD/LONG bit */
  173.                unsigned otherLen   : 2; /* dirIndex/extraLen field length */
  174.                unsigned isSpecial  : 1; /* Whether this is a special entry */
  175.                unsigned hasExtra   : 1; /* If there is extra data attached */
  176.                unsigned isText     : 1; /* Whether this is a text file */
  177.                unsigned dataFormat : 3; /* Storage type */
  178.                unsigned systemType : 6; /* The sys.the arc.was created on */
  179.                } ARCHIVEINFO;
  180.  
  181. The data formats are as follows:
  182.  
  183.   enum { STORED, PACKED, <5 x spare> };
  184.  
  185. If  the  isSpecial  bit  is set then this entry is to be treated as a non-data
  186. file entry.  The file header as stored on disk is followed  by  an  additional
  187. WORD  which  indicates the type of the file.  All files of type SPECIAL reside
  188. in their own namespace, making it possible to have multiple files of the  same
  189. name in one directory provided their types are different.
  190.  
  191. If the hasExtra bit is set,  the  header  is  followed  by  a  BYTE  with  the
  192. following layout:
  193.  
  194. typedef struct {
  195.                unsigned secured     : 1; /* Data is secured */
  196.                unsigned encrypted   : 1; /* Data is encrypted */
  197.                unsigned linked      : 1; /* File is linked to other file(s) */
  198.                unsigned unicode     : 1; /* Filename is Unicode */
  199.                unsigned extraLength : 4; /* Length of extra information */
  200.                } EXTRAINFO;
  201.  
  202. If  the  file  is  linked  to  another  file,  the link ID is stored in a WORD
  203. immediately following the header itself, but after the type  SPECIAL  word  if
  204. there  is  one  present.   All  files  with the same link ID are seperate file
  205. entities  which  share  common  data and in some cases common attributes.  The
  206. linkID is simply a magic number connecting all files with the same ID.
  207.  
  208. Linked files or directories can be of two types,  anchor  nodes  or  dependant
  209. nodes.    An   anchor   node   contains  the  physical  data  for  the  linked
  210. file(s)/directorie(s).  A dependant node is a file entry which  points  to  an
  211. anchor node.  Each link chain must have one or more  anchor  node  (containing
  212. the actual file/directory data).  A link ID has the following layout:
  213.  
  214. typedef struct {
  215.                unsigned anchor     :  1; /* Whether this is an anchor node */
  216.                unsigned linkID     : 15; /* Magic number for ID */
  217.                } LINKINFO;
  218.  
  219. The extra information field is  a  deliberately  short  field  used  to  store
  220. mission-critical information such as the following:
  221.  
  222. Apple IIgs: WORD - File type
  223.             LONG - Auxiliary file type
  224. Archimedes: WORD - File type
  225. Macintosh:  LONG - File type
  226.             LONG - File creator/owner
  227.  
  228. The  extra  information is stored immediately following the header itself, but
  229. after the type SPECIAL word and link ID if there are any present.  If only the
  230. encryption, authentication, or link bits are used, the  extraLength  field  is
  231. set  to  0. This field also allows for the storage of very short items of data
  232. as pure headers of type SPECIAL only (ie with no associated data).   Currently
  233. this option is unused but may be used in the future.
  234.  
  235. Data integrity checking is performed either by a CRC16 checksum on stored data
  236. or  a  checksum  calculated  by  the  LZA/MBWA  compressor  as  part  of   the
  237. compression/decompression  process.   The  CRC16's are only used on very short
  238. stored files (where their probability of  picking  up  errors  is  good);  for
  239. longer  files the checksum mechanism which is built into the compressor itself
  240. is used.  Taking into account  the  types  of  errors  that  will  occur  over
  241. transimission  lines,  a  16-bit CRC will catch all single bit errors, all two
  242. bit errors, all odd numbers of errors and all burst errors of up to  16  bits.
  243. The checksumming built into the compressor will by its nature detect virtually
  244. all  errors  (the  exact details are quite complex to explain and are based on
  245. the way the compressed data is encoded).
  246.  
  247. The system types are as follows:
  248.  
  249. enum { MSDOS, UNIX, AMIGA, MACINTOSH, ARCHIMEDES, OS2, IIGS, ATARI, VMS,
  250.        PRIMOS, <53x spare> };
  251.  
  252. The file headers are stored as variable-length records, with  the  lengths  of
  253. the  fileLen,  dataLen, auxDataLen, and dirIndex fields being given by various
  254. bits in the archiveInfo field.  The first field  written  is  the  archiveInfo
  255. field  itself;  when  the  record  is  read  in,  the  length bits are used to
  256. determine the lengths of the fields and the  appropriate  routines  called  to
  257. read  in  BYTE's,  WORD's,  or LONG's.  These routines are independant of data
  258. endianness.  The length bits are as follows:
  259.  
  260.   origLen:   0 = fileLen = WORD
  261.              1 = fileLen = LONG
  262.   coprLen:   0 = dataLen = WORD
  263.              1 = dataLen = LONG
  264.   otherLen: 00 = dirIndex = ROOT_DIR, auxDataLen = BYTE
  265.             01 = dirIndex = BYTE, auxDataLen = BYTE
  266.             10 = dirIndex = BYTE, auxDataLen = WORD
  267.             11 = dirIndex = WORD, auxDataLen = LONG
  268.  
  269. The file header as stored in memory is as follows:
  270.  
  271. typedef struct {
  272.                LONG fileTime;           /* Mod. date + time of the file */
  273.                LONG fileLen;            /* Original data length */
  274.                LONG dataLen;            /* Compressed data length */
  275.                LONG auxDataLen;         /* Auxiliary data field */
  276.                WORD dirIndex;           /* Where the file is in the dir.tree */
  277.                ARCHIVEINFO archiveInfo; /* File-specific bitflags */
  278.                } FILEHDR;
  279.  
  280. The dataLen field is the length of the compressed data, not counting any extra
  281. information which may be stored in the auxDataLen field.
  282.  
  283. The date field contains the modification date of the file, and  is  stored  as
  284. the  number  of  seconds since 00:00:00 GMT on 01/01/1970 (the time may not be
  285. entirely correct on systems which don't store time zone information).
  286.  
  287.   An HPACK directory header  is  defined  in  FILEHDR.H,  and  is  arranged  as
  288. follows:
  289.  
  290.   First,  there  is  a  bitfield  to  hold  information such as the system the
  291. archive was created on and various information pertaining to the  file.   This
  292. bitfield  is  described as a struct, but is handled internally via bitmasks to
  293. eliminate any endianness problems:
  294.  
  295. typedef struct {
  296.                unsigned otherLen   : 2; /* parentIndex/dataLen field length */
  297.                unsigned isSpecial  : 1; /* Whether this is a special entry */
  298.                unsigned linked     : 1; /* Dir is linked to other dir(s) */
  299.                unsigned unicode    : 1; /* Directory name is Unicode */
  300.                unsigned spare      : 3; /* Reserved */
  301.                } DIRINFO;
  302.  
  303. The directory headers are stored as variable-length records, with  the  lengths
  304. of  the  dataLen  and  parentIndex  fields  being  given by various bits in the
  305. dirInfo field.  The first field written is the dirInfo field itself;  when  the
  306. record  is  read  in,  the length bits are used to determine the lengths of the
  307. fields and the appropriate routines  called  to  read  in  BYTE's,  WORD's,  or
  308. LONG's.   These  routines  are independant of data endianness.  The length bits
  309. are as follows:
  310.  
  311.   otherLen: 00 = parentIndex = ROOT_DIR, dataLen = 0
  312.             01 = parentIndex = BYTE, dataLen = BYTE
  313.             10 = parentIndex = BYTE, dataLen = WORD
  314.             11 = parentIndex = WORD, dataLen = LONG
  315.  
  316.   The directory header as stored in memory is as follows:
  317.  
  318. typedef struct {
  319.                LONG dirTime;      /* Mod. date + time of the directory */
  320.                LONG dataLen;      /* The length of the sys-specific dir.info */
  321.                WORD parentIndex;  /* The pointer to this directories parent */
  322.                BYTE dirInfo;      /* Directory-specific bitflags */
  323.                } DIRHDR;
  324.  
  325. The dataLen LONG defines the length of the directory data field, which contains
  326. system-specific  information  such  as  permission bits for the directory.  The
  327. date field contains the modification date and time of the directory in the same
  328. format as the file date.
  329.  
  330. If the isSpecial bit is set, it indicates that this entry is to be treated as a
  331. special directory entry.  The directory header as stored on disk is followed by
  332. an additional WORD which indicates the type of the directory.
  333.  
  334. If  the  directory  is  linked to another directory, the link ID is stored in a
  335. WORD immediately following the header itself, but after the type  SPECIAL  word
  336. if  there  is  one present.  All directories with the same link ID are seperate
  337. directory entities which share common data and in some cases common attributes.
  338. The linkID is simply a magic number connecting all directories  with  the  same
  339. ID, and has the same format as file linkID's.
  340.  
  341.   The layout of file and directory headers as  stored  within  an  archive  is
  342. shown  below.   All the variable or optional fields are controlled by the flag
  343. bits outlined above.
  344.  
  345. File Header:
  346.  
  347.     WORD                 : Header information bits which control the
  348.                            following fields.
  349.     None or BYTE or WORD : Index of directory file is in
  350.     None or BYTE or WORD or LONG : Auxiliary data size
  351.     LONG                 : File time
  352.     WORD or LONG         : Original file size
  353.     WORD or LONG         : Compressed file size
  354.  
  355.     Optional WORD        : File type
  356.     Optional BYTE        : Extra header information bits which control
  357.                            the following fields.
  358.     Optional WORD        : Link ID
  359.     Optional variable-length field : System-specific extra information.
  360.  
  361. Directory Header:
  362.  
  363.     BYTE                 : Header information bits which control the
  364.                            following fields
  365.     None or BYTE or WORD : Index of directory directory is in
  366.     None or BYTE or WORD or LONG : Directory data size
  367.     LONG                 : Directory time
  368.  
  369.     Optional WORD        : Directory type
  370.     Optional WORD        : Link ID
  371.  
  372.   File  and  directory  names  are  stored  as null-terminated ASCII or EBCDIC
  373. strings, depending on the system they originated on.  In addition, HPACK  will
  374. recognise Unicode/ISO 10646 strings as file and directory  names  as  well  as
  375. standard  ASCII/ISO 646  or EBCDIC ones.  Unicode is used since it encompasses
  376. virtually  all  of  the  widely-varying  standards  for  non-ASCII  fonts  and
  377. character  systems  available  today.  The multibyte character set employed in
  378. Unicode is stored externally in big-endian format as is the rest of  the  data
  379. used in HPACK.
  380.  
  381. HPACK  will  recognise  Unicode data in file and directory names but currently
  382. ignores it.
  383.  
  384.  
  385. HPACK Directory Structure:
  386. --------------------------
  387.  
  388.   Unlike many other archivers, HPACK doesn't store directories  merely  as  an
  389. extension  to  a filename.  Instead, HPACK maintains a full internal directory
  390. tree allowing comlete reproduction of any directory structure.   The  internal
  391. directory  structure  which  is  laid  out  as follows (assuming the following
  392. sample directory structure):
  393.  
  394.   / -+- A -+- B -+- C     This directory tree is encoded in a manner similar
  395.      |     |     |        to that of the strings in LZW compression.   Every
  396.      |     |     +- C1    entry contains a pointer  back  to a  chain of its
  397.      |     +- B1          parents.  Directories  are scanned in  depth-first
  398.      +- A1 -- B2          order.  The tree is  stored in a dynamically-sized
  399.      |                    array which also contains a list of files and sub-
  400.      +- A2                directories for each directory,  and  an index for
  401.                           the directory name in the string table.
  402.  
  403. A sample run on the above directory is:
  404.  
  405.          +-------------------------------+
  406.   +----+ +----+                          |
  407.   v    | v    |                          |
  408. A = 1, B = 2, C = 3, Pop to B (pred(C)), C1 = 4, Pop to B (pred(C1)),
  409.        +------------+                                  +------------+  +----+
  410.        v            |                                  v            |  v    |
  411. Pop to A (pred(B)), B1 = 5, Pop to A (pred(B1), Pop to / (pred(A)), A1 = 6, B2
  412.                              +-------------+
  413.                              v             |
  414. Pop to A1 (pred(B2)), Pop to / (pred(A1)), A2 = 8, Pop to / (pred(A2)), Exit.
  415.  
  416.     Typical links within the array are shown below:
  417.  
  418.          +-----------------+
  419.    +-----|-------------+   |
  420.    +-----|-+ +-----+   |   |
  421.    +---+ | | +-+   |   |   |
  422.    v   | v | v |   |   |   |
  423.   +---+|--+|--+|--+|--+|--+|--+-/  /--+---+
  424.   |   |   |   |   |   |   |   | /  /  |   |
  425.   +---+---+---+---+---+---+---+-/  /--+---+
  426.  
  427. The root directory is directory 0 and is never explicitly written to  or  read
  428. from  disk; all subdirectories are added off the root directory, starting with
  429. a directory index of 1.
  430.  
  431. The  directory  structure  should  be  stored  in  depth-first order, and with
  432. contiguous directory numbers;  there  is  code  in  ARCDIR.C  to  rebuild  the
  433. directory  tree in the correct order which should be called after changes have
  434. been made to the directory structure.
  435.  
  436.  
  437. Storing Miscellaneous Data:
  438. ----------------------------
  439.  
  440.   All  crufties in an HPACK archive are stored in a files' auxData field and a
  441. directories' data field in a tagged format.  Each file and directory can  have
  442. up  to 4GB of crufties associated with it, typically attributes, icons, access
  443. control information, GUI information such as window positions and  sizes,  and
  444. so on.
  445.  
  446. The  tags  used  to  denote  the  crufties  are  either   16-bit   or   longer
  447. variable-length values, with the following format:
  448.  
  449.   Short-format tags: These tags are of the  form  <10 bits Tag ID><6 bits data
  450.                      length>.  Tag ID's range from 0x000-0x3FE.
  451.  
  452.   typedef struct {
  453.                  unsigned tagID    : 10; /* Tag ID for this tag */
  454.                  unsigned tagLen   : 6;  /* Length of this tag */
  455.                  } SHORT_TAG;
  456.  
  457.   Long-format tags:  These tags have a short-format tag ID of 0x3FF,  and  are
  458.                      treated  as  one 24-bit value by combining the tag ID and
  459.                      data length fields, and the following byte.   The  actual
  460.                      data length is given  in  a  BYTE,  WORD  or  LONG  which
  461.                      follows  the  basic  tag.  If the tag data is compressed,
  462.                      the uncompressed data length is given in a WORD  or  LONG
  463.                      following the actual length.   The  size  of  the  length
  464.                      fields  is  indicated  by the dataLength bits, and are as
  465.                      follows:
  466.  
  467.                        dataLen = 00   length = BYTE, uncompr.length = WORD
  468.                        dataLen = 01   length = WORD, uncompr.length = WORD
  469.                        dataLen = 10   length = WORD, uncompr.length = LONG
  470.                        dataLen = 11   length = LONG, uncompr.length = LONG
  471.  
  472.   typdef struct {
  473.                 unsigned longTagID : 10; /* Always 0x3FF for long-format tag */
  474.                 unsigned dataLen   :  2; /* Length of length/ucoprLen fields */
  475.                 unsigned dataFormat:  3; /* Storage type */
  476.                 unsigned tagID     :  9; /* Tag ID for this tag */
  477.                 } LONG_TAG;
  478.  
  479. This  format  results  in 1023  short-form  tags and 512 long-form  tags.  Tag
  480. length fields cover the tagged data itself, but  not  any  parts  of  the  tag
  481. header.
  482.  
  483.   Example of short format tag:  MSDOS attributes (1 byte):
  484.  
  485.      WORD : ( MSDOS_ATTR | 1 )
  486.        [data: 1 byte]
  487.  
  488.   Example of uncompressed long format tag: Authentication information
  489.         (84 bytes):
  490.  
  491.      WORD : ( LONG_BASE | LONGTAG_BYTE_WORD | TAGFORMAT_STORED )
  492.      BYTE : SECURITY_INFO
  493.      BYTE : 0x54
  494.        [data: 84 bytes of authentication information]
  495.  
  496.   Example of compressed (packed) long format tag:  Long  format  comment  (182
  497.         bytes, compressed to 92 bytes):
  498.  
  499.      WORD : ( LONG_BASE | LONGTAG_BYTE_WORD | TAGFORMAT_PACKED )
  500.      BYTE : COMMENT
  501.      BYTE : 0x5C
  502.      BYTE : 0xB6
  503.        [data: 92 bytes of compressed comment]
  504.  
  505.   Example  of  compressed  (packed)  extended  tag:  Macintosh  resource  fork
  506.         (269,128 bytes, compressed to 167,241 bytes):
  507.  
  508.      WORD : ( LONG_BASE | LONGTAG_LONG_LONG | TAGFORMAT_PACKED )
  509.      BYTE : RESOURCE_FORK
  510.      LONG : 0x00041B48
  511.      LONG : 0x00028D49
  512.        [data: 167,241 bytes of compressed resource fork)
  513.  
  514. All  tags  are  defined in the file TAGS.H, which acts as a master tags record
  515. for all versions of HPACK.  If an unknown tag is encountered, the tags  length
  516. field may be used to skip the information which it defines.
  517.  
  518. Note   that   HPACK   has  routines  called  writeTag()  and  readTag()  which
  519. automatically sort out what types of tags to use and how to store  information
  520. on  lengths  etc.   The  above  information  is  provided  mainly  to  give an
  521. indication on how the data is actually stored within an archive.
  522.  
  523.  
  524. Encryption/Authentication Data Format:
  525. --------------------------------------
  526.  
  527.   The  format  for  encryption/authentication  information  used  by  HPACK is
  528. vaguely  compatible  with  that  used  by  Philip  Zimmerman's  PGP encryption
  529. package.  HPACK recognises three types of security information packets:
  530.  
  531. Signature packets:
  532.  
  533.   A signature packet contains the algorithm ID of the signing  algorithm,  the
  534. key  ID  of  the  key used to create the packet, and the message digest packet
  535. stored as an encrypted multiprecision integer.
  536.  
  537.             Algo
  538.   CTB  len   ID        keyID         Encrypted MPI - MD packet   crc16
  539.   +-+  +-+  +-+  +-+-+-+-+-+-+-+-+  +-------------------------+  +-+-+
  540.   | |  | |  | |  |               |  |                         |  |   |
  541.   +-+  +-+  +-+  +-+-+-+-+-+-+-+-+  +-------------------------+  +-+-+
  542.  
  543.   A message digest information packet contains the algorithm ID of the message
  544. digest algorithm, the  message  digest  itself,  and a timestamp stored in the
  545. usual format.
  546.  
  547.             Algo
  548.   CTB  len   ID            Message digest           Timestamp
  549.   +-+  +-+  +-+  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  +-+-+-+-+
  550.   | |  | |  | |  |                               |  |       |
  551.   +-+  +-+  +-+  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  +-+-+-+-+
  552.  
  553.   A  message  digest  packet  may be prepended to signed data and contains the
  554. algorithm ID of the message digest algorithm.
  555.  
  556.             Algo
  557.   CTB  len   ID  crc16
  558.   +-+  +-+  +-+  +-+-+
  559.   | |  | |  | |  |   |
  560.   +-+  +-+  +-+  +-+-+
  561.  
  562. Conventional-key encryption packets:
  563.  
  564.   A conventional-key encryption  packet  contains  the  algorithm  ID  of  the
  565. encryption algorithm and any extra keying information needed by the algorithm.
  566. This keying information usually takes the form of a  64-bit  IV  used  by  the
  567. block cipher employed for the conventional-key encryption.
  568.  
  569.             Algo   Keying
  570.   CTB  len   ID  information crc16
  571.   +-+  +-+  +-+  +--------+  +-+-+
  572.   | |  | |  | |  |        |  |   |
  573.   +-+  +-+  +-+  +--------+  +-+-+
  574.  
  575. Public-key encryption packets:
  576.  
  577.   A  public-key  encryption packet contains the algorithm ID of the public-key
  578. encryption algorithm, the key ID of the key used to create the packet, and the
  579. conventional key encryption information stored as an encrypted  multiprecision
  580. integer.  Use of an IV is unnecessary  since  the  conventional-key encryption
  581. information contains a random key which differs for each packet.
  582.  
  583.             Algo
  584.   CTB  len   ID        keyID         Encrypted MPI - CK encr.info   crc16
  585.   +-+  +-+  +-+  +-+-+-+-+-+-+-+-+  +----------------------------+  +-+-+
  586.   | |  | |  | |  |               |  |                            |  |   |
  587.   +-+  +-+  +-+  +-+-+-+-+-+-+-+-+  +----------------------------+  +-+-+
  588.  
  589.   A  conventional  key  encryption  information  (DEK)  packet  contains   the
  590. algorithm  ID  of the encryption algorithm, and the key material needed by the
  591. algorithm (this varies from algorithm to algorithm).
  592.  
  593.             Algo
  594.   CTB  len   ID          Key material
  595.   +-+  +-+  +-+  +-------------------------+
  596.   | |  | |  | |  |                         |
  597.   +-+  +-+  +-+  +-------------------------+
  598.  
  599.   Multiprecision integers are stored in big-endian format with a 16-bit prefix
  600. which gives the number of significant bits.  If the bitcount is not a multiple
  601. of  8,  the  remaining  bits are zero-padded.  A multiprecision integer with a
  602. value of zero is stored with a zero in the bitcount  field  and  no  following
  603. value byte.
  604.  
  605.   The  CTB is the cipher type byte, which specifies the type of data structure
  606. which follows it.  The CTB bits have the following meaning:
  607.  
  608.  Bits                 Content
  609.   7-4     1010 - Designates the byte as a CTB
  610.    3      'More' bit - if set indicates another packet follows
  611.   2-0     Packet type field:
  612.           000 - Public-key-encryption packet
  613.           001 - Signature packet
  614.           010 - Message digest packet
  615.           011 - Message digest information packet
  616.           100 - Conventional-key-encryption packet
  617.           101 - Conventional-key-encryption information (DEK) packet
  618.           110 - Reserved for future use
  619.           111 - Reserved for future use
  620.  
  621.   Data authentication information is given  by  way  of  a  signature  packet.
  622. Encryption information is given either by way of a conventional- or public-key
  623. encryption packet.
  624.  
  625.  
  626. Archive Encryption:
  627. -------------------
  628.  
  629.   HPACK  archives  can  be  block encrypted with either public- or private-key
  630. encryption schemes.  The archive directory  and  archive  data  are  encrypted
  631. seperately,   allowing  two  levels  of  access  to  the  archive,  either  to
  632. information  on  the  contents  of  the  archive  (in   terms   of   directory
  633. information), or full access to the entire archive.
  634.  
  635.   If   the  archive  is  block  encrypted,  the  archive  data  and  directory
  636. information areas are prefixed  with  either  a  public-  or  conventional-key
  637. encryption  packet  containing  the  information  necessary  to allow HPACK to
  638. decrypt the following data.  In addition the byte of special  info  will  have
  639. the  encrypted  bit  set  to  indicate that this is an encrypted archive.  The
  640. archive data which is encrypted begins after the initial 'HPAK' ID string  and
  641. ends  at  the  start of the directory information; the directory data which is
  642. encrypted begins at the start of the directory information  and  ends  at  the
  643. start  of  the  archive  trailer.   Thus  the  entire archive is enclosed in a
  644. security  veil  which  allows  no  access  to  any  information  without   the
  645. appropriate key(s) or password(s) to unlock it.
  646.  
  647.  
  648. Archive Authentication:
  649. -----------------------
  650.  
  651.   HPACK archives can have authentication  information  attached  to  them,  in
  652. which case the archive layout ends as follows:
  653.                     .
  654.                     .
  655.                     .
  656.              Filename  n,  '\0'
  657.     --------------------------------------
  658.         WORD: No directory headers
  659.         WORD: No file headers
  660.         LONG: Length of directory block
  661.         WORD: Directory block checksum
  662.     --------------------------------------
  663.         Authentication information
  664.     --------------------------------------
  665.         WORD: Authentication info.length
  666.         BYTE: Special info
  667.         BYTE[4]: Archive ID: 'HPAK'
  668.     ======================================
  669.  
  670.   An  extra block of data is inserted between the directory block checksum and
  671. the  archive  ID,  consisting  of  a  WORD  containing  the  length   of   the
  672. authentication  information,  and  the  authentication information itself.  In
  673. addition the byte of special info will have the secured bit  set  to  indicate
  674. that  this  is  a secured archive.  The data which is checked begins after the
  675. initial 'HPAK'  ID  string  and  ends  at  the  start  of  the  authentication
  676. information  itself; thus the entire archive is enclosed in a security wrapper
  677. which  it  is  computationally  infeasible  to  destroy.   The  authentication
  678. information  can  either be used to validate the archive, or it can be skipped
  679. and the archive handled as normal.  If  the  archive  is  altered,  a  warning
  680. should be issued that this will destroy the authentication information.
  681.  
  682.   Currently  authentication is handled by generating an RSA Data Security Inc.
  683. MD5 message digest for the archive and signing  it  with  the  RSA  public-key
  684. cryptosystem.   However,  alternative forms of authentication (such as the use
  685. of the ElGamal PKC) can easily be substituted.
  686.  
  687.  
  688. Multipart Archives:
  689. -------------------
  690.  
  691.   HPACK  supports  multipart  archives  by  treating  them as a single virtual
  692. archive, with the I/O code taking care of disk swapping  requirements  and  so
  693. on.   The main archiver code sees all archives as a single contiguous block of
  694. data, whether they are spread over several disks or not  (it  is  for  example
  695. possible  to  create  a  multipart  archive without even using HPACK simply by
  696. splitting up an existing archive into segments and adding the  archive  ID  to
  697. the  start  and  the ID and multipart information to the end of each segment).
  698. The end of each internal segment is as follows:
  699.                     .
  700.                     .
  701.                     .
  702.                  Raw data
  703.     --------------------------------------
  704.         WORD: Segment number
  705.         BYTE: Special info
  706.         BYTE[4]: Archive ID: 'HPAK'
  707.     ======================================
  708.  
  709. The end of the final segment is as follows:
  710.                     .
  711.                     .
  712.                     .
  713.              Filename  n,  '\0'
  714.     --------------------------------------
  715.         WORD: No.directory headers
  716.         WORD: No.file headers
  717.         LONG: Length of directory block
  718.         WORD: Directory block checksum
  719.     --------------------------------------
  720.          Authentication information
  721.                 (if present)
  722.     ======================================
  723.         LONG: Length of 1st segment
  724.                     .
  725.                     .
  726.                     .
  727.         LONG: Length of nth segment
  728.     --------------------------------------
  729.         WORD: Authentication info length
  730.         WORD: Total number of segments
  731.         LONG: Pos.of end of last segment
  732.         WORD: Segment block checksum
  733.         BYTE: Special info
  734.         BYTE[4]: Archive ID: 'HPAK'
  735.     ======================================
  736.  
  737.   The  segment list covers the entire archive to the start of the segment list
  738. itself.  Unlike the rest of the archive, the segment list  and  final  trailer
  739. are  always  located  on  the  same disk; since no segmentation information is
  740. present when these are read in they must be on the same physical  medium.   If
  741. the  segment  list and trailer must be placed on a seperate disk, the high bit
  742. of the total segment count should be set to indicate  that  the  rest  of  the
  743. archive  is  on  a  seperate  disk.   The  segment  block  checksum covers all
  744. information from the start of the segment list to the checksum itself.
  745.  
  746.   When HPACK detects a full disk it should write as much of the  current  data
  747. as  can  still  fit on the disk, append the trailer information, and request a
  748. new disk.  The existing code does this by checking how much data  was  written
  749. and  comparing it to the amount that was supposed to be written: If the result
  750. is less, the disk is full.  A simpler approach would be to check how much room
  751. is available on the disk before writing it, however  this  will  not  work  on
  752. multitasking  OS's  since  the  disk  space  can  change  between  the call to
  753. determine the space and the call to write the data.  The code  in  HPACK  uses
  754. the  data  write  to  lock the disk space available to it, and then backtracks
  755. over the data if necessary.   This  atomic  write  ensures  there  can  be  no
  756. problems with multiple processes accessing the same disk volume.
  757.  
  758.   Reading a multipart archive is performed as a multi-stage process in which a
  759. bootstrap read is used to read the segments, and then the full archive is read
  760. as usual:
  761.  
  762.   Step 0:   Locate end of archive
  763.             Read in disk number and offset of segment list start
  764.   Step 1:   Ask for correct disk if not there already
  765.             Seek to segment list start
  766.   Step 2:   Read in segmentation information
  767.             Enable virtual filesystem I/O  once  segmentation  information  is
  768.             available.
  769.  
  770.  
  771. HPACK Command Format:
  772. ---------------------
  773.  
  774.   It  is  recommended that the following commands be used for the CLI versions
  775. of HPACK.  All CLI versions should be standardised to use this command  format
  776. (where  the  commands  are applicable) to make it possible to use HPACK on any
  777. system without  having  to  relearn  the  command  set.   All  system-specific
  778. switches  should  be  specified  using  the  -z option (eg under DOS -zv = use
  779. volume label, -zs =  use  disk  serial  number,  under  Unix  zlower  =  force
  780. lowercase  on  file/directory names, znoumask = ignore umask on file/directory
  781. creation).  See HPACK.DOC for more information on these commands.
  782.  
  783.   Command letters are:
  784.  
  785.   [A] - Add files to an archive.
  786.   [X] - Extract files from an archive.
  787.   [V] - Directory of files inside an archive.
  788.   [P] - View a file within an archive.
  789.   [T] - Test the integrity of an archive.
  790.   [D] - Delete files from an archive.
  791.   [F] - Freshen files to an archive.
  792.   [R] - Replace files in an archive.
  793.   [U] - Update files to an archive.
  794.  
  795.   Option letters are:
  796.  
  797.   -0 - Store without compression.
  798.   -a - Store file attributes.
  799.   -b - Specify a base pathname for files.
  800.   -c - Encrypt files (public- or private-key encryption).
  801.   -d - Directory options (Mkdir, Rmdir, Mvdir, path specifiers etc).
  802.   -e - Add error recovery information.
  803.   -f - Force file move.
  804.   -i - Interactive mode - prompt for all files.
  805.   -k - Overwrite existing archives.
  806.   -l - Add authentication information.
  807.   -m - Generate multipart archive
  808.   -o - Overwrite on extraction options (-oa All, -on None, -os Smart,
  809.                                         -op Prompt)
  810.   -r - Recurse through subdirectories.
  811.   -s - Stealth mode.
  812.   -t - Touch files on extraction.
  813.   -u - Unified compression mode.
  814.   -v - View files options (-vf Files, -vd Directories, -vs Sort files).
  815.   -w - Treat files as archive comments.
  816.   -x - Translate options for text files (-x smart, -xr CR, -xl LF, -xc CRLF,
  817.                                          -xxnn Hex, -xe EBCDIC, -xp Prime,
  818.                                          -xa ASCII as appropriate)
  819.   -z - System-specific commands
  820.  
  821.   If possible the following wildcard chars should be used (these are the  Unix
  822. chars which seem to be the most common ones):
  823.  
  824.   *       - Matches multiple characters
  825.   ?       - Matches any one character
  826.   [...]   - Matches any of the enclosed range of characters '...'.
  827.   [^...]  - As above, but matches anything *not* in the range.
  828.   \       - Literal char escape (this becomes '#' in the Atari ST, MSDOS, and
  829.               version since these systems use '\' as the directory seperator).
  830.  
  831.  
  832. HPACK Program Structure:
  833. ------------------------
  834.  
  835.   The  HPACK  archiver has a number of layers which interface between the user
  836. and the host OS.  This archiver  structure  is  shown  below,  with  the  user
  837. interface  at  the  top  and the filesystem interface at the bottom.  The core
  838. archiver routines, which should need few changes, are in the centre.  Note the
  839. multiple levels of filesystem I/O handling present towards the  bottom  -  any
  840. necessary  extra  functionality for fileysystem I/O can be transparently added
  841. at this level.
  842.  
  843.                         Host OS screen I/O
  844.       -----------------------------------------------------
  845.                                /  \                           /  \
  846.                                |  |                           |  | = data
  847.                                \  /                           \  /   flow
  848.       +---------------------------------------------------+
  849.       |           GUI.C / CLI.C archiver frontend         |    ^
  850.       |   FRONTEND.C, SCRIPT.C, DISPLAY.C user interface  |    | = control
  851.       +---------------------------------------------------+    v    flow
  852.             ^              ^                   ^
  853.             |              |                   |
  854.             v              v                   v
  855.       +------------+ +-----------+ +----------------------+ +------------+
  856.       |  ARCDIR.C  | |  TAGS.C   | |       ARCHIVE.C      | |  ERROR.C   |
  857.       | ARCDIRIO.C | |           | |  compression manager | |   error    |
  858.       |            | |   extra   | +----------------------+ |  handling  |
  859.       |   archive  | |   data/   |             |            +------------+
  860.       |  directory | |information| +----------------------+ +------------+
  861.       |   manager  | |  manager  | | Plug-in copr.modules | | HPAKTEXT.C |
  862.       +------------+ +-----------+ +----------------------+ |  language- |
  863.            /  \           /  \               /  \           | independant|
  864.            |  |           |  |               |  |           | text system|
  865.            \  /           \  /               \  /           +------------+
  866.       +---------------------------------------------------+
  867.       |     CRYPT.C encryption/authentication handling    |
  868.       +---------------------------------------------------+
  869.                                /  \
  870.                                |  |
  871.                                \  /
  872.       +---------------------------------------------------+
  873.       |         FASTIO.C, FILESYS.C virtual file I/O      |
  874.       +---------------------------------------------------+
  875.                                /  \
  876.                                |  |
  877.                                \  /
  878.       -----------------------------------------------------
  879.                         Host OS file I/O
  880.  
  881.  
  882. HPACK and Portability:
  883. ----------------------
  884.  
  885.   HPACK has been written to be as portable as possible - the  main  difference
  886. between  the  CLI and GUI versions are the use of either cli.c or gui.c at the
  887. highest level of the user-interface system in the above  diagram.   All  other
  888. code  is  common  to both CLI and GUI versions for all operating systems.  The
  889. baseline version of HPACK is the original CLI version (which has  been  around
  890. for about two years longer than any other version).
  891.  
  892.   The  portability  problems, at least to another CLI-based OS, are apparently
  893. not severe: The Xenix port of version 0.71 of HPACK (by Stuart the  Hut)  took
  894. only  a few  days  to accomplish.  The original Macintosh port of version 0.77
  895. was done in a single day.
  896.  
  897. Level 1 HPACK has been successfully compiled using the following compilers:
  898.  
  899.     - DICE
  900.     - Generic Unix cc (many variants)
  901.     - Irix cc
  902.     - Microsoft C
  903.     - MiNT gcc
  904.     - Norcroft Arm C
  905.     - Orca/C
  906.     - SAS/Lattice C
  907.     - SunOs acc
  908.     - Think C
  909.     - TopSpeed C
  910.     - Turbo C
  911.     - Unix gcc
  912.     - VAX vcc
  913.     - Watcom C (the only C compiler named after a toilet)
  914.     - Zortech C
  915.  
  916.  
  917. Getting Started:
  918. ----------------
  919.  
  920.          "Any given HPACK port, when running correctly, is obsolete"
  921.  
  922.   If  your  source  came  in  a zipfile, unzip it with the -d option to create
  923. subdirectories as appropriate.  If it came as a tar.Z the files  will  already
  924. be in the correct directories.
  925.  
  926. Edit  DEFS.H for your system, and edit the supplied makefile for whatever your
  927. setup is. If your system supports system-level I/O most of  the  files  should
  928. compile  without too many errors, especially if the system is at least vaguely
  929. Unix-compatible.  The nonstandard functions are aliased to  calls  to  hputs()
  930. which  print  a  warning  message that they should be implemented later. For a
  931. CLI-based version all that is left is to implement the  nonstandard  functions
  932. and tune things like the handling of paths and filenames for each system. Most
  933. of this is contained in FILESYS.C and <os_name>.C
  934.  
  935. One  point  to note is that the MD5Transform() routine in MD5.C seems to break
  936. some optimizing compilers, so the version which has been broken up  into  four
  937. parts may have to be used to allow it to compile.
  938.  
  939.  
  940. HPACKIO and HPACKLIB:
  941. ---------------------
  942.  
  943.   All  I/O  functions  are  handled  by  the  three  libraries,  HPACKIO  (for
  944. filesystem  I/O), HPACKLIB (for console I/O), and SYSTEM (for miscellaneous OS
  945. routines).   These  libraries  contain  code  to  interface  HPACK  with   the
  946. underlying  OS  of the host system at the lowest level (HPACKIO corresponds to
  947. the system-level I/O functions, HPACKLIB corresponds to the  stdio  functions,
  948. and  SYSTEM  contains various nonstandard routines).  The library routines are
  949. organised as follows:
  950.  
  951. HPACKIO Library:
  952.  
  953.   hcreat();       - Create a given file
  954.   hopen();        - Open a given file
  955.   hclose();       - Close a given file
  956.   hread();        - Read data from a file
  957.   hwrite();       - Write data to a file
  958.   hlseek();       - Move the file position indicator
  959.   htell();        - Return current file position indicator
  960.   htruncate();    - Truncate a file at the current file position
  961.   hunlink();      - Remove a file
  962.   hmkdir();       - Create a directory
  963.   hrename();      - Rename a file
  964.   hchmod();       - Set the file's attributes
  965.  
  966. HPACKLIB Library:
  967.  
  968.   hputchar();     - Output a single char
  969.   hputchars();    - As hputchar() but with stealth mode checking
  970.   hputs();        - Output a string, adding CRLF at end with steath mode chk.
  971.   hprintf();      - Output a formatted string
  972.   hprintfs();     - As hprintf() but with stealth mode checking
  973.   hgetch();       - Get a single char, no echo
  974.   hmalloc();      - Allocate a block of memory
  975.   hfree();        - Free a block of memory
  976.  
  977. SYSTEM Library:
  978.  
  979.   setFileTime();  - Set the file's timestamp (non-standard)
  980.   setDirTime();   - Set the directory's timestamp (non-standard)
  981.   getCountry();   - Get country information for printing dates (non-standard)
  982.   getScreenSize();- Get the screen size for user I/O (non-standard)
  983.   isSameFile();   - Determine whether two pathnames refer to same file (nonstd)
  984.   findFirst();    - Return first matching entry in directory (non-standard)
  985.   findNext();     - Return following matching entries in directory (non-std)
  986.   findEnd();      - End of findFirst/Next() routines (non-standard)
  987.   copyExtraInfo();- Copy any extra information from one file to anoter(non-std)
  988.  
  989. By  default  HPACKIO.H  and  HPACKLIB.H define these functions as the standard
  990. system-level I/O functions.  However some  of  the  functions  (in  particular
  991. those  in  SYSTEM.H)  are nonstandard and will need to be supplied by the user
  992. (an implementation for Unix is contained in the file UNIX.C, an implementation
  993. for OS/2 is contained in the file OS2.C).  The I/O functions often make use of
  994. file descriptors (given here as FD) to refer to files, and are as follows:
  995.  
  996. int hcreat( const char *fileName, int mode );
  997.     Create file 'fileName' with access mode 'mode'.
  998. int hopen( const char *fileName, int mode );
  999.     Open file 'fileName' with access mode 'mode'.
  1000. int hclose( const FD theFile );
  1001.     Close file associated with 'theFile'.
  1002. int hread( const FD theFile, const BYTE *buffer, const int count );
  1003.     Reads  'count'  bytes of data from the file associated with 'theFile' into
  1004.     buffer 'buffer'.
  1005. int hwrite( const FD theFile, const BYTE *buffer, const int count );
  1006.     Writes  'count'  bytes  of data to the file associated with 'theFile' from
  1007.     buffer 'buffer'.
  1008. int hlseek( const FD theFile, const long offset, const int origin );
  1009.     Moves the file position indicator for the file associated  with  'theFile'
  1010.     to offset 'offset' from starting position 'origin'.
  1011. long htell( const FD theFile );
  1012.     Returns current file position indicator in file 'theFile'.
  1013. int htruncate( const FD theFile );
  1014.     Truncates the file associated with 'theFile' at the current file position.
  1015. int hunlink( const char *fileName );
  1016.     Removes file 'fileName'.
  1017. int hmkdir( const char *dirName );
  1018.     Creates directory 'dirName'.
  1019. int hrename( const char *oldName, const char *newName );
  1020.     Renames file 'oldName' to file 'newName'.
  1021. int hchmod( const char *fileName, const int mode );
  1022.     Set the file 'fileName's attributes to 'mode'.
  1023.  
  1024. The HPACKLIB functions are as follows:
  1025.  
  1026. int hputchar( const int ch );
  1027.     Writes 'ch' to STDOUT.
  1028. int hputchars( const char ch );
  1029.     Writes 'ch' to STDOUT with stealth-mode checking.
  1030. int hputs( const char *str );
  1031.     Outputs string 'str' to STDOUT, adding CRLF at end with steath mode check.
  1032. int hprintf( const char *format, ... );
  1033.     Output a formatted string with format specified by 'format' to STDOUT.
  1034. int hprintfs( const char *format, ... );
  1035.     As hprintf() but with stealth mode checking.
  1036. int hgetch( void );
  1037.     Get a single character, no echo.  This function is not  entirely  portable
  1038.     but  is  used  in  place  of  the  standard getchar() since getchar() uses
  1039.     buffered I/O, making it possible for users to enter an arbitrary number of
  1040.     characters in response to a question which needs a yes/no answer.
  1041. void hflush( FILE *stream );
  1042.     Flush screen output buffers (required by Unix, and little else).
  1043. void *hmalloc( const int size );
  1044.     Allocates a block of memory of size 'size'.
  1045. int hfree( void *memBlock );
  1046.     Frees a block of memory pointed to by 'memBlock'.
  1047.  
  1048. The SYSTEM functions are as follows:
  1049.  
  1050. int setFileTime( const FD theFile, const long time );
  1051.     Set the file 'theFile's timestamp to 'time' (non-standard).
  1052. int setDirTime( const FD theDir, const long time );
  1053.     Set the directory 'theDir's timestamp to 'time' (non-standard)
  1054. int getCountry( void );
  1055.     Get  country  information  for  printing  dates (0 = US, 1 = European, 2 =
  1056.     Japanese format) (non-standard).
  1057. void getScreenSize( void );
  1058.     Get  the  screen  dimensions  and  place  them  in  the  global  variables
  1059.     screenHeight and screenWidth (non-standard).
  1060. BOOLEAN isSameFile( const char *pathName1, const char *pathName2 );
  1061.     Determine whether the two pathnames refer to the same file.  MSDOS  can do
  1062.     this by qualifying the names using an undocumented interrupt and comparing
  1063.     them;  Unix  can  check the device numbers and inodes.  This takes care of
  1064.    things like links, aliases, and so on (non-standard).
  1065. BOOLEAN findFirst( const char *filePath, const ATTR matchAttr, \
  1066.                    const FILEHDR *fileInfo );
  1067.     Returns first matching directory entry on 'filePath' (for example  "a/b/c"
  1068.     would  return  "c"  in  directory  "a/b"  (if it existed)) with attributes
  1069.     matching 'matchAttr' and places info in 'fileInfo'.  Returns TRUE if  file
  1070.     found, FALSE otherwise (non-standard).
  1071. BOOLEAN findNext( const FILEHDR *fileInfo );
  1072.     Returns next matching directory entry and places info in 'fileInfo'  (non-
  1073.     standard).
  1074. void findEnd( const FILEHDR *fileInfo );
  1075.     Cleanup  function for findFirst()/findNext() calls, to be called after the
  1076.     last call to findNext() for a particular directory (non-standard).
  1077. void copyExtraInfo( const FD srcFD, const FD destFD );
  1078.     Copy any extra information (icons, extended attributes, etc) which are not
  1079.     part of the normal file data from one file to another (non-standard).
  1080.  
  1081.  
  1082. HPACK Source Files:
  1083. -------------------
  1084.  
  1085. The HPACK source files are as follows:
  1086.  
  1087.   arcdir.h    - Interface and data structures for ARCDIR.C
  1088.   choice.h    - The commands available for HPACK
  1089.   error.h     - Interface for the error() routine
  1090.   errorlvl.h  - Error level return codes
  1091.   filehdr.h   - The file header structure
  1092.   filesys.h   - interface for the filesystem handling routines
  1093.   flags.h     - The switches available for HPACK
  1094.   frontend.h  - Interface for FRONTEND.C
  1095.   system.h    - System-specific information for OS interface routines
  1096.   tags.h      - The master tags file for all versions of HPACK
  1097.   timeinfo.h  - Time format header and conversion routines
  1098.   wildcard.h  - Interface for the wildcard handling routines
  1099.  
  1100.   arcdir.c    - Archive directory management routines
  1101.   arcdirio.c  - Archive directory file I/O routines
  1102.   archive.c   - The routines to store data in/retrieve data from an archive
  1103.   frontend.c  - The archiver frontend, which contains most of archiver glue
  1104.   viewfile.c  - The routine to display an archive directory
  1105.  
  1106.   cli.c       - Generic CLI version frontend routines
  1107.   gui.c       - Generic GUI version frontend routines
  1108.  
  1109.   error.c     - The error() routine
  1110.   filesys.c   - The filesystem handling routines
  1111.   script.c    - The command-line and script filename handling routines
  1112.   tags.c      - Tags handling code
  1113.   wildcard.c  - Wildcard handling routines
  1114.  
  1115.   amiga.c     - Amiga OS-specific routines
  1116.   arc.c       - Archimedes OS-specific routines
  1117.   atari.c     - Atari ST OS-specific routines
  1118.   mac.c       - Macintosh OS-specific routines
  1119.   os2.c       - OS/2 1.x OS-specific routines
  1120.   os2_32.c    - OS/2 2.0 OS-specific routines
  1121.   unix.c      - Unix OS-specific routines
  1122.   vms.c       - VMS OS-specific routines
  1123.  
  1124.   crc/crc16.h     - The CRC16 interface
  1125.   crc/crc16.c     - Block CRC16 routines
  1126.  
  1127.   crypt/crypt.h   - The encryption system header file
  1128.   crypt/crypt.c   - The encryption management code
  1129.   crypt/md5.h     - MD5 message digest header file
  1130.   crypt/md5.c     - MD5 message digest routines
  1131.   crypt/nsea.h    - Conventional-key encryption header file
  1132.   crypt/nsea.c    - Conventional-key encryption routines
  1133.   crypt/rsa.h     - The RSA library interface
  1134.   crypt/rsa.c     - The RSA encryption library
  1135.   crypt/packet.h  - Encryption packet definitions
  1136.  
  1137.   io/display.c    - Formatted text display code
  1138.   io/fastio.h     - Interface for the fast I/O routines
  1139.   io/fastio.c     - The fast I/O system
  1140.  
  1141.   store/store.h   - Interface to the store/unstore routines
  1142.   store/store.c   - File store/unstore routines
  1143.  
  1144.   data/ebcdic.h   - EBCDIC translation table
  1145.  
  1146. For the LZW version:
  1147.  
  1148.   lzw/lzw.h       - Information for the LZW compression/decompression routines
  1149.   lzw/lzw.c       - LZW buffer allocation routines
  1150.   lzw/lzw_pack.c  - LZW compression routine
  1151.   lzw/lzw_unpk.c  - LZW decompression routine
  1152.  
  1153. For the LZA' version:
  1154.  
  1155.   lza/lza.c       - The LZA' main compressor/decompressor
  1156.   lza/pack.c      - The arithmetic coder pack() routine
  1157.   lza/unpack.c    - The arithmetic coder unpack() routine
  1158.   lza/model.h
  1159.   lza/model.c     - The model for literals
  1160.   lza/model3.h
  1161.   lza/model3.c    - The model for high positions
  1162.   lza/model4.h
  1163.   lza/model4.c    - The model for low positions
  1164.  
  1165. Multilingual support files:
  1166.  
  1167.   language/hpaktext.def - Text definitions file
  1168.  
  1169.   language/hpaktext.h   - Interface for English (default) HPACK
  1170.   language/hpak_de.h    - Interface for German HPACK
  1171.   language/hpak_nl.h    - Interface for Dutch HPACK
  1172.   language/hpak_it.h    - Interface for Italian HPACK
  1173.   language/hpaktext.c   - English (default) text for HPACK
  1174.   language/hpak_de.c    - German text for HPACK
  1175.   language/hpak_nl.c    - Dutch text for HPACK
  1176.   langauge/hpak_it.c    - Italian text for HPACK
  1177.  
  1178. Supplementary files:
  1179.  
  1180.   makefile          - Makefile for the Unix version
  1181.   makefile.os2      - Makefile for the OS/2 version
  1182.  
  1183.   docs/readme.1st   - README file for HPACK
  1184.   docs/hpack.1      - HPACK manpage (nroff source for HPACK.DOC)
  1185.   docs/hpack.doc    - The HPACK documentation
  1186.   docs/hpack.ps     - The HPACK documentation in PostScript format
  1187.   docs/hpackext.doc - The HPACK extended documentation
  1188.   docs/hpackstd.txt - The HPACK standards document
  1189.   docs/hpaktest.txt - The HPACK torture test
  1190.   docs/hpaksmpl.txt - The HPACK sample archives (uuencoded)
  1191.   docs/hpakidea.txt - New ideas for HPACK
  1192.  
  1193.   data/stdarg.h     - <stdarg.h> for those systems which don't have it
  1194.   data/stdlib.h     - <stdlib.h> for those systems which don't have it
  1195.  
  1196.   data/winhpack.h   - Windoze include file for HPACK
  1197.   data/winhpack.rc  - Windoze resource file for HPACK
  1198.  
  1199.   data/hpack.pi.rsrc.hqx    - BinHex'd Mac resource file for HPACK
  1200.   data/hpack.pi.hqx - BinHex'd ThinkC project file for HPACK
  1201.  
  1202.   data/testio.c     - Test code for <os_name>.C filesystem I/O routines.  This
  1203.                       module  can  be  linked  with <os_name>.C  to  produce a
  1204.                       standalone  executable  which  will  test  most  of  the
  1205.                       filesystem I/O  calls  without  linking  in the  rest of
  1206.                       HPACK.
  1207.  
  1208.   data/*.gif        - Suggested   screen / dialog   layout  for  GUI  versions
  1209.                       (actually  screen  dumps  from  the  Windows  version of
  1210.                       HPACK).  The individual files are:
  1211.   data/addfiles.gif - Add files dialog
  1212.   data/authent.gif  - Authentication options dialog
  1213.   data/encrypt.gif  - Encryption options dialog
  1214.   data/extract.gif  - Extract files dialog
  1215.   data/mainscrn.gif - Main HPACK screen
  1216.   data/miscopt.gif  - Miscellaneous options dialog
  1217.   data/overwrit.gif - Overwrite options dialog
  1218.   data/translat.gif - Translate options dialog
  1219.  
  1220. PGP 2.0 Keyring Maintenance:
  1221.  
  1222.   keycvt/makefile   - Unix makefile for building the key conversion utility
  1223.   keycvt/keycvt.c   - PGP 2.0 -> HPACK secret key format converter
  1224.   keycvt/idea.c     - Cipher for decrypting PGP 2.0 secret keys
  1225.   keycvt/md5.h
  1226.   keycvt/md5.c      - Message digest code needed by keycvt
  1227.   keycvt/mdc.h
  1228.   keycvt/mdc.c      - Cipher for encrypting HPACK secret keys
  1229.  
  1230.  
  1231. Coding:
  1232. -------
  1233.  
  1234.   The following notes outline some of the coding conventions used in HPACK.
  1235.  
  1236.  - System-specific code:
  1237.  
  1238.    The system being used should be specified on the command-line (generally in
  1239.    the  makefile)  by a define of the form __<system>__, for example __MSDOS__
  1240.    or __UNIX__.  For some systems extra defines may be necessary, for  example
  1241.    Unix  systems may require the extra defines BSD, SYSV, IRIX, ULTRIX, POSIX,
  1242.    etc.  Any system-specific code should  be  enabled/disabled  through  these
  1243.    defines.  As an example, to build  HPACK  under  Ultrix,  the  command-line
  1244.    options  for  the compiler would include '-D__UNIX__' and '-DULTRIX' (again
  1245.    these are given in the makefile).
  1246.  
  1247.  - General assumptions about types:
  1248.  
  1249.    The following types are defined in DEFS.H
  1250.  
  1251.    typedef <8-bit unsigned value>   BYTE
  1252.    typedef <16-bit unsigned value>  WORD
  1253.    typedef <32-bit unsigned value>  LONG
  1254.    typedef <64-bit unsigned value>  QUAD
  1255.    typedef <128-bit unsigned value> LQUAD
  1256.  
  1257.    When  used  in HPACK archives, all data are stored in big-endian format, ie
  1258.    for  a  WORD  the  byte ordering is [MSB:LSB].  The get/put byte/word/long/
  1259.    quad/lquad functions perform automatic endianness conversion. The choice of
  1260.    endianness is largely irrelevant because of this automatic conversion;  the
  1261.    final  decision  was  made  based  on the fact that various Internet and US
  1262.    Government encryption standards require data to be big-endian.
  1263.  
  1264.    A BOOLEAN is any value capable of holding a value of TRUE or  FALSE  (1  or
  1265.    0).   The  standard  HPACK  distribution uses unsigned chars simply because
  1266.    these take up the least space.
  1267.  
  1268.  - Endianness and packing/non-packing of structs:
  1269.  
  1270.    The get/put byte/word/long/quad/lquad routines perform automatic endianness
  1271.    conversion  as  data  is  read/written.   The  field-by-field  reading  and
  1272.    writing of structs avoids any  problems  with  compilers  which  align  all
  1273.    struct fields to word or longword boundaries.
  1274.  
  1275.  - Bitfields:
  1276.  
  1277.    The ANSI standard  for  bitfields  states  that  they  are  implementation-
  1278.    dependant.   HPACK  implements  bitfields  using  bitmasks  to  avoid  this
  1279.    problem.
  1280.  
  1281.  - Coding style:
  1282.  
  1283.    Try and keep the coding style identical to that used throught the  rest  of
  1284.    HPACK.  I will probably go through and change any submitted code to conform
  1285.    to this coding style in order to preserve a unified style across all source
  1286.    files.   At  least  one  reason  for  this  is  that  the  automatic format
  1287.    conversion program 'mangle' expects code to be laid out in  a  certain  way
  1288.    and will probably break if it hits an unexpected code layout.
  1289.  
  1290.  - Making changes to HPACK code:
  1291.  
  1292.    In  general  the  main HPACK code should be modified as little as possible.
  1293.    All changes should be restricted to <os_name>.C  and  SYSTEM.H.   Again,  I
  1294.    will   nitpick   any  submitted  code  and  recommend  moving  things  into
  1295.    <os_name>.C if necessary.  The reason behind this is  that  too  much  code
  1296.    which  runs  over  multiple systems consists of an indecipherable morass of
  1297.    #ifdef'd code blocks for every system it has ever  been  compiled  on.  The
  1298.    purpose of the 'h'-functions, <os_name>.C, and SYSTEM.H, is to keep this to
  1299.    an absolute minimum.
  1300.  
  1301.  
  1302. Releasing an HPACK Port:
  1303. ------------------------
  1304.  
  1305.   In  order  to  ensure  complete  consistency  across  all versions of HPACK,
  1306. several points should be observed:
  1307.  
  1308.  - The file TAGS.H should *never* be modified.  If  any  changes  are  needed,
  1309.    they  should  be  submitted to me, and I will make the changes if necessary
  1310.    and redistribute the new TAGS.H to all HPACK coders.  This is necessary  to
  1311.    ensure all parts of HPACK archives are understandable by all other versions
  1312.    of HPACK (as far as this is possible).
  1313.  
  1314.  - There  is  a  file HPAKTEST.TXT included in this distribution which gives a
  1315.    checklist of features in the basic version of HPACK (this is also known  as
  1316.    "The HPACK Torture Test").  Only ports which *completely* pass the test (as
  1317.    far  as is applicable) should be released as final releases.  Non-complying
  1318.    versions should be labelled  alpha-,  beta-,  or  development  releases  as
  1319.    appropriate  (I  waited over 2 years before releasing the first versions of
  1320.    HPACK to make sure I'd Got It Right the first time).
  1321.  
  1322.  
  1323. HPACK on non-ANSI Systems:
  1324. --------------------------
  1325.  
  1326.   Some systems have strange non-ANSI compilers (which nevertheless claim to be
  1327. ANSI - some of them (eg Nyarlathotep, the ESIX compiler)  are  more  like  the
  1328. missing  link  than  a C compiler).  To convert HPACK for these compilers, the
  1329. program 'mangle' is included  as  DATA/MANGLE.C.   Mangle  can  transform  the
  1330. source  in a variety of bizarre and unusual ways, and takes as input a list of
  1331. options telling it what to do with the  code,  and  a  filename  on  which  to
  1332. perform  the transformations (NB some of the mangling options may not be legal
  1333. in some countries - use at your own risk).  Options include:
  1334.  
  1335.   -c - Get rid of '\' line  continuation  characters  (except  in  macros  and
  1336.        strings).
  1337.   -e - Change all occurrences of
  1338.          #elif
  1339.        to
  1340.          #else
  1341.          #if
  1342.            ...
  1343.          #endif
  1344.   -f - Turn function headers into K&R versions, for example
  1345.          int getFileID( const char *fileName, int dirID )
  1346.        becomes
  1347.          int getFileID( fileName, dirID )
  1348.              char *fileName;
  1349.              int dirID;
  1350.   -i - Unindent all  lines  beginning  with  '#'  (some  preprocessors  expect
  1351.        directives to always begin in column 1).
  1352.   -k - Delete 'const' from the code.
  1353.   -n - Turn enumerations into #defines and integer types.
  1354.   -p - Change all occurrences of 'void *' to 'char *'.
  1355.   -r - Delete '#pragma' lines from the code.
  1356.   -s - Concatenate strings split over multiple lines with '\'.
  1357.   -t - Turn function prototypes into nameless ANSI versions, for example
  1358.          int getFileID( const char *fileName, int dirID );
  1359.        becomes
  1360.          int getFileID( const char *, int );
  1361.   -v - Delete all 'void's in the code (return values become 'int', parameters
  1362.        disappear).
  1363.   -w - Turn function prototypes into K&R versions, for example
  1364.          int getFileID( const char *fileName, int dirID );
  1365.        becomes
  1366.          int getFileID();
  1367.  
  1368.   Mangle is written in ANSI C so it may be necessary to find another system on
  1369. which to cross-mangle the code before compiling it on the destination  system.
  1370. Note  that  mangle  expects  the  code to be formatted in a certain way (as it
  1371. always is in HPACK).  It doesn't appear to break any code even when subject to
  1372. maximum mangling, but I gave up checking the  code  after  the  300th  warning
  1373. message from a genuine ANSI compiler (these warnings were mainly  due  to  the
  1374. destruction of function prototypes).
  1375.  
  1376.   At  least  one  compiler,  if  told  to  #include "a/b", will try to include
  1377. "a/a/b".  The compiler owner tells me all SYSV compilers  do  this,  in  which
  1378. case I extend my condolences.
  1379.  
  1380.   If  your  system  doesn't  have  a <stdlib.h>, there is one in the directory
  1381. 'data' which can be moved into the main HPACK directory.
  1382.  
  1383.   If your system doesn't have a <stdarg.h>, there is also one  in  the  'data'
  1384. directory.  When compiling error.c, define NO_STDARG to include different code
  1385. which  doesn't  assume  ANSI  va_arg functions.  This code assumes all data is
  1386. passed on the stack, and may have to be altered for RISC machines which try to
  1387. pass as much as possible in registers.
  1388.  
  1389.  
  1390. Who's Doing What:
  1391. -----------------
  1392.  
  1393.   The following is a list of people currently claiming to be working on  HPACK
  1394. and their email contact addresses and phone numbers:
  1395.  
  1396.   HPACK/DOS     Peter Gutmann   - pgut1@cs.aukuni.ac.nz (preferred)
  1397.                                   peter@nacjack.gen.nz or
  1398.                                   peterg@kcbbs.gen.nz
  1399.                                   Ph.(09) 426-5097
  1400.   HPACK/Windoze Lynn Prentice   - lprent@kcbbs.gen.nz
  1401.   HPACK/Unix    Stuart Woolford - stuartw@ccu1.aukuni.ac.nz
  1402.                                   Ph.(09) 426-3464
  1403.   HPACK/OS2     John Burnell    - johnb@maths.grace.cri.nz
  1404.   HPACK/IIGS    Corey Murtagh   - Corey_Murtagh@kcbbs.gen.nz
  1405.                                   Ph.(09) 277-5800
  1406.   HPACK/Mac     Peter Gutmann   - pgut1@cs.aukuni.ac.nz (preferred)
  1407.                                   peter@nacjack.gen.nz or
  1408.                                   peterg@kcbbs.gen.nz
  1409.                                   Ph.(09) 426-5097
  1410.  
  1411.  
  1412. Bonus Info:  HPACK Character Sheet:
  1413. -----------------------------------
  1414.  
  1415. HPACK
  1416. (Archiver Supremus Maximus)
  1417.  
  1418. FREQUENCY: 8 (Amiga, Archimedes, Atari ST, Macintosh, MSDOS, Windoze, OS/2,
  1419.               Unix)
  1420. NO. APPEARING: Not a lot
  1421. ARMOUR CLASS: 8 (2 on an OS with protection)
  1422. MOVE: Bloody slow
  1423. HIT DICE: Constantly
  1424. % IN LAIR: 100
  1425. TREASURE TYPE: Easter eggs (many)
  1426. NO. OF ATTACKS: Unlimited
  1427. DAMAGE/ATTACK: May affect sanity of users.  Has been known to destroy
  1428.                hardware - see "The HPACK Curse" in README.1ST.
  1429. SPECIAL ATTACKS: Running HPACK may be classed as a denial of service-type
  1430.                  attack by some systems administrators.
  1431. SPECIAL DEFENSES: Mutates constantly to confuse foes
  1432. MAGIC RESISTANCE: Immune to interrupts of all kinds (there are rumours of
  1433.                   variants of HPACK which will even survive system resets).
  1434. INTELLIGENCE: Just enough to be considered alive.
  1435. ALIGNMENT: Chaotic evil
  1436. SIZE: S (but growing)
  1437. PSIONICS:  Psionics?  How do you spell that?
  1438.