CODEGROUP(1) CODEGROUP(1)
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__X7TNXJ^&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 encryp‐
tion 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-depen‐
dent 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
This software is in the public domain. Permission to use, copy, mod‐
ify, and distribute this software and its documentation for any purpose
and without fee is hereby granted, without any conditions or restric‐
tions. This software is provided ‘‘as is’’ without express or implied
warranty.
4th Berkeley Distribution 26 OCT 1998 CODEGROUP(1)