home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 28 / amigaformatcd28.iso / -seriously_amiga- / archivers / codegroup / readme < prev    next >
Encoding:
Text File  |  1998-05-09  |  6.4 KB  |  146 lines
  1. CODEGROUP(1)             USER COMMANDS               CODEGROUP(1)
  2.  
  3. NAME
  4.      codegroup - encode / decode binary file as five letter code-
  5.      groups
  6.  
  7. SYNOPSIS
  8.      codegroup -d|-e [ -u ] [ infile [ outfile ] ]
  9.  
  10. DESCRIPTION
  11.      For decades, spies have written their  encoded  messages  in
  12.      groups of five letters.
  13.  
  14.      codegroup encodes any binary file into this  form,  allowing
  15.      it  to  be transmitted through any medium, and decodes files
  16.      containing codegroups  into  the  original  input.   Encoded
  17.      files  contain  a 16-bit cyclical redundancy check (CRC) and
  18.      file size to verify, when decoded, that the message is  com-
  19.      plete  and  correct.   Files being decoded may contain other
  20.      information before and after the  codegroups,  allowing  in-
  21.      the-clear annotations to be included.
  22.  
  23.      codegroup makes no attempt, on its own, to prevent your mes-
  24.      sage  from  being  read.   Cryptographic  security should be
  25.      delegated to a package intended for that  purpose,  such  as
  26.      pgp.   codegroup can then be applied to the encrypted binary
  27.      output, transforming it into easily transmitted text.   Text
  28.      created  by codegroup uses only upper case ASCII letters and
  29.      spaces.  Unlike files encoded with uuencode or pgp's ``ASCII
  30.      armour''  facility,  the  output  of codegroup can be easily
  31.      (albeit tediously) read over  the  telephone,  broadcast  on
  32.      shortwave radio to agents in the field, or sent by telegram,
  33.      telex, or Morse code.
  34.  
  35.      To illustrate the difference, here are the first  few  lines
  36.      of a binary file encoded by:
  37.  
  38.      uuencode:
  39.           begin 644 data.bin
  40.           M'XL("&7._R  VUO;V /9U+FN2XSF3G6H5OA1(?HOB<=/<7__X7TN<PJ[L&
  41.           M=?-&1;I+) B8 0;P?_Z'?WY_-=7Q"T_JSZ_6)X9?&"$OU9[N'A[A%^L^6=
  42.           M?^M[OOV+:9=UM9J^] MAS_ ;X0O]U];(Z?<WWE9_[/]ZMMOO[CG'^2MM
  43.           M_G(+,US/LWKZE1#C^YO?D_;O#G[7][2R^+0>XJ^&PI/[?7-7U]KU=]SSWQ?
  44.  
  45.      pgp:
  46.           -----BEGIN PGP MESSAGE-----
  47.           Version: 2.6.2i
  48.  
  49.           hIwCCb8iTku3pBUBA/9oSDlfk/On9bwjmTnB98Eejr6agkPSi3n6hd8JkAtJd33f
  50.           kzFq18Jo0xzRUWZ7Di6Jq/FXpeI1yztVDqispbcYOP0aDv4JZOSF1kRsmJ9xK9Bo
  51.           Cv4a967IXPkkRsjIAkx0B39dYxCzf8kHUn4THmyV/b2qLUZ0cc+mr8hxFfFpuYSM
  52.  
  53.      codegroup:
  54.           ZZZZZ YBPIL AIAIG FMOPP CPAAA DGNGP GPGPA ADNJN ELJKO ELIMO
  55.           GEOHF KIFGP IFBCB PKCPI YJMHE PHBHP PPOBH NCOHD AKLLL AGHFP
  56.           DEGEF LKELC EAIJI ABAGP AHPPO IHHPH OHPDF YNFPB ALEPO KMPKP
  57.           NGCHI GFPBI CBDML PFGHL LIHPC BOOBB HOLDO FJNHP OLHLL OPNIL
  58.  
  59.      Only codegroup conforms to the telegraphic convention of all
  60.      upper  case  letters.   Avoiding punctuation marks and lower
  61.      case letters makes the output of codegroup  much  easier  to
  62.      transmit over a voice or traditional telegraphic link.
  63.  
  64. OPTIONS
  65.      -decode     Decodes the input, previously created  by  code-
  66.                  group,  to  recover the original input file, and
  67.                  verifies it to detect truncation  or  corruption
  68.                  of the contents.
  69.  
  70.      -encode     Encodes the input into an output text file  con-
  71.                  taining five letter code groups (default).
  72.  
  73.      -usage      Print how-to-call information.
  74.  
  75.      All options may be abbreviated to a single letter.
  76.  
  77. APPLICATION NOTES
  78.      Encoding  a  binary  file  as  ASCII  characters  inevitably
  79.      increases  its size.  When used in conjunction with existing
  80.      compression and encryption tools, the  resulting  growth  in
  81.      file  size  is  usually  acceptable.   For example, a random
  82.      extract of electronic mail 32768 bytes in length was  chosen
  83.      as  a test sample.  Compression with gzip compacted the file
  84.      to 15062 bytes.  It was then encrypted for transmission to a
  85.      single  recipient  with  pgp, which resulted in a 15233 byte
  86.      file.  (Even though pgp has  its  own  compression,  smaller
  87.      files usually result from initial compression with gzip.  In
  88.      this case, pgp alone would have produced  a  file  of  15420
  89.      bytes.)
  90.  
  91.      codegroup transforms the encrypted file into  a  37296  byte
  92.      text  file.   Thus,  due to compression, the code groups for
  93.      the encrypted file are only a little larger than the  origi-
  94.      nal cleartext.
  95.  
  96.      Restricting the character set and including  spaces  between
  97.      groups  results  in  substantially  larger output files than
  98.      those produced by uuencode  and  pgp.   Files  encoded  with
  99.      codegroup  are  about  2.5 times the size of the input file,
  100.      while uuencode and pgp  expand  the  file  only  about  35%.
  101.      codegroup is thus preferable only for applications where its
  102.      limited character set is an advantage.
  103.  
  104. FILES
  105.      If no infile is specified or infile is a single ``-'', code-
  106.      group  reads from standard input; if no outfile is given, or
  107.      outfile is a single ``-'', output is sent to  standard  out-
  108.      put.   The input and output are processed strictly serially;
  109.      consequently codegroup may be used in pipelines.
  110.  
  111. BUGS
  112.      When a CRC error is detected, no indication is given of  the
  113.      location  in  the  file  where  the error(s) occurred.  When
  114.      sending large files, you may want to break them into  pieces
  115.      with  the  splits utility (available from the Web page cited
  116.      below) so, in case of error, only the erroneous pieces  have
  117.      to be re-sent.
  118.  
  119.      It might be nice to embed the original file name  and  modes
  120.      in  the encoded output, but this opens the door to all kinds
  121.      of system-dependent problems.  You can always  include  this
  122.      information  as  text before the first codegroup, or send an
  123.      archive created with tar or zip.
  124.  
  125. SEE ALSO
  126.      gzip(1), pgp(1), splits(1), tar(1), uuencode(1), zip(1)
  127.  
  128. EXIT STATUS
  129.      codegroup returns  status  0  if  processing  was  completed
  130.      without errors, 1 if errors were detected in decoding a file
  131.      which indicate the output is incorrect or incomplete, and  2
  132.      if  processing  could not be performed at all due, for exam-
  133.      ple, to a nonexistent input file or no codegroups  found  in
  134.      the input.
  135.  
  136. AUTHOR
  137.           John Walker
  138.           kelvin@fourmilab.ch
  139.           <http://www.fourmilab.ch/>
  140.  
  141.      This software is in the public domain.  Permission  to  use,
  142.      copy,  modify, and distribute this software and its documen-
  143.      tation for any purpose and without fee  is  hereby  granted,
  144.      without  any  conditions  or restrictions.  This software is
  145.      provided ``as is'' without express or implied warranty.
  146.