NAME

       codegroup - encode / decode binary file as five letter codegroups

SYNOPSIS

       codegroup -d|-e [ -u ] [ infile [ outfile ] ]

DESCRIPTION

       For decades, spies have written their encoded messages in groups of five letters.

       codegroup  encodes  any  binary file into this form, allowing it to be transmitted through
       any medium, and decodes files containing codegroups  into  the  original  input.   Encoded
       files  contain  a  16-bit  cyclical  redundancy  check (CRC) and file size to verify, when
       decoded, that the message is complete and correct.  Files being decoded may contain  other
       information  before  and  after  the  codegroups,  allowing in-the-clear annotations to be
       included.

       codegroup makes no attempt,  on  its  own,  to  prevent  your  message  from  being  read.
       Cryptographic security should be delegated to a package intended for that purpose, such as
       pgp.  codegroup can then be applied to the encrypted binary output, transforming  it  into
       easily transmitted text.  Text created by codegroup uses only upper case ASCII letters and
       spaces.  Unlike files encoded with uuencode or pgp's ``ASCII armour'' facility, the output
       of  codegroup  can  be  easily  (albeit  tediously)  read over the telephone, broadcast on
       shortwave radio to agents in the field, or sent by telegram, telex, or Morse code.

       To illustrate the difference, here are the first few lines of a binary file encoded by:

       base64:
            H4sICFJ9MzYAA2EudGFyAOxba3faSNKer+lf0SezO3YmgLnY2I6TyQIGgwOGBTtOYjuJEMJo
            DJJGF1+ys//9rarulpqLHRi/mdk9G84JIKGuqq579eNkNn745q9sNru9tcXhs5gtFPAzm83l
            xad88WyxmNssbhe3sps8m8ttZ/M/8K1vL9oPP0RBaPggypU1vrad+59zosj0HqAj9xF//pe8
            WsaVNbTH1rfkAfoobm7ea//cZn4rtv/mNtq/kM9t/cCz31Io9foftz9nnW77oMdfcdMdWJe+

       uuencode:
            begin 644 data.bin
            M'XL("&7._R\  VUO;V\ /9U+FN2XSF3G6H5OA1(?HOB<=/<7__X7TN<PJ[L&
            M=?-&1;I+) B8 0;P?_Z'?WY_-=7Q"T_JSZ_6)X9?&"$\OU9[N'\A[A%^L^6=
            M?^M[OOV+:9=UM9J^] MAS_ ;X0O]U];(Z?<WWE9_\^[/]ZMM\OO[CG'^2M\M
            M_G(+,US/LWKZE1#C^YO?D_;O#G[7][2R^+0>XJ^&PI/\[?7-7U]KU=]SSWQ?

       pgp:
            -----BEGIN PGP MESSAGE-----
            Version: 2.6.2i

            hIwCCb8iTku3pBUBA/9oSDlfk/On9bwjmTnB98Eejr6agkPSi3n6hd8JkAtJd33f
            kzFq18Jo0xzRUWZ7Di6Jq/FXpeI1yztVDqispbcYOP0aDv4JZOSF1kRsmJ9xK9Bo
            Cv4a967IXPkkRsjIAkx0B39dYxCzf8kHUn4THmyV/b2qLUZ0cc+mr8hxFfFpuYSM

       codegroup:
            ZZZZZ YBPIL AIAIG FMOPP CPAAA DGNGP GPGPA ADNJN ELJKO ELIMO
            GEOHF KIFGP IFBCB PKCPI YJMHE PHBHP PPOBH NCOHD AKLLL AGHFP
            DEGEF LKELC EAIJI ABAGP AHPPO IHHPH OHPDF YNFPB ALEPO KMPKP
            NGCHI GFPBI CBDML PFGHL LIHPC BOOBB HOLDO FJNHP OLHLL OPNIL

       Only codegroup conforms to the telegraphic convention  of  all  upper  case  letters,  and
       passes  the ``telephone test'' of being readable without any modifiers such as ``capital''
       and ``lower-case''.  Avoiding punctuation marks and lower case letters makes the output of
       codegroup much easier to transmit over a voice or traditional telegraphic link.

OPTIONS

       -decode     Decodes  the  input,  previously created by codegroup, to recover the original
                   input file, and  verifies  it  to  detect  truncation  or  corruption  of  the
                   contents.

       -encode     Encodes  the input into an output text file containing five letter code groups
                   (default).

       -usage      Print how-to-call information.

       All options may be abbreviated to a single letter.

APPLICATION NOTES

       Encoding a binary file as ASCII characters inevitably increases its size.   When  used  in
       conjunction  with  existing compression and encryption tools, the resulting growth in file
       size is usually acceptable.  For example, a random extract of electronic mail 32768  bytes
       in  length was chosen as a test sample.  Compression with gzip compacted the file to 15062
       bytes.  It was then encrypted for transmission to  a  single  recipient  with  pgp,  which
       resulted  in  a  15233 byte file.  (Even though pgp has its own compression, smaller files
       usually result from initial compression with gzip.  In this case,  pgp  alone  would  have
       produced a file of 15420 bytes.)

       codegroup  transforms  the  encrypted  file  into  a  37296  byte text file.  Thus, due to
       compression, the code groups for the encrypted file are only  a  little  larger  than  the
       original cleartext.

       Restricting the character set and including spaces between groups results in substantially
       larger output files than those produced by uuencode and pgp.  Files encoded with codegroup
       are  about  2.5  times  the size of the input file, while uuencode and pgp expand the file
       only about 35%.  codegroup is thus preferable only  for  applications  where  its  limited
       character set is an advantage.

FILES

       If  no  infile  is  specified  or  infile is a single ``-'', codegroup reads from standard
       input; if no outfile is given, or outfile is a single ``-'', output is  sent  to  standard
       output.   The input and output are processed strictly serially; consequently codegroup may
       be used in pipelines.

BUGS

       When a CRC error is detected, no indication is given of the location in the file where the
       error(s)  occurred.  When sending large files, you may want to break them into pieces with
       the splits utility (available from the Web page cited below) so, in case  of  error,  only
       the erroneous pieces have to be re-sent.

       It might be nice to embed the original file name and modes in the encoded output, but this
       opens the door to all kinds of system-dependent problems.  You  can  always  include  this
       information  as  text  before  the first codegroup, or send an archive created with tar or
       zip.

SEE ALSO

       base64(1), gzip(1), pgp(1), splits(1), tar(1), uuencode(1), zip(1)

EXIT STATUS

       codegroup returns status 0 if processing was completed without errors, 1  if  errors  were
       detected in decoding a file which indicate the output is incorrect or incomplete, and 2 if
       processing could not be performed at all due, for example, to a nonexistent input file  or
       no codegroups found in the input.

AUTHOR

            John Walker
            <http://www.fourmilab.ch/>

       This  software  is  in the public domain.  Permission to use, copy, modify, and distribute
       this software and its documentation for any purpose and without  fee  is  hereby  granted,
       without  any  conditions  or  restrictions.   This  software is provided ``as is'' without
       express or implied warranty.