README

ASCII Bit Packer/Unpacker
=========================
7-bit ASCII will be packed into a array of 7 bit bytes
base64 encoding of output string.

There are two programs:
1. bptest, which provides detailed proof of packing and unpacking strings
2. bitp, which is a standalone program to pack and unpack

bptest takes one argument: string to pack or unpack
bitp takes 2 arguments. p or u to pack or unpack, and a string
String to unpack must be a base64 encoded string

bitp p password
bitp u base64 encoded bit-packed password

Example:
$ ./bitp p password
Base64 encoding of password is 4YefPvv5ZA==

$ ./bitp u 4YefPvv5ZA==
base64 Decoded packed password is: password

CAUTION: This is not a secure system, merely a way to obscure
passwords.

Make and Run
============
Makefile will compile a shared library libbitpacker.so.
Makefile will link the libbitpacker.so into sample programs, bptest and bitp.
The libbitpacker.so file can be used by other programs.

$ make
$ ./bptest "string to pack"
$ ./bitp p|u "string to pack/unpack"

bptest will also output a file called test.pack which will hold bitpacked
output.

To remove compiled files
========================
$ make clean

DISCUSSION
==========

For each byte, shift left and then move bit 6 or more from next byte
at each byte, move one more bit to above.
7 6 5 4 3 2 1 0
===============
0 1 1 1 1 1 1 1
0 2 2 2 2 2 2 2
becomes
1 1 1 1 1 1 1 2 -> bit 6 from byte 2
2 2 2 2 2 2 3 3 -> bit 6 and 5 from byte 3
3 3 3 3 3 4 4 4 -> bit 6, 5, and 4 from byte 4
...
6 6 7 7 7 7 7 7 -> bit 6, 5...1 from byte 7 
7 8 8 8 8 8 8 8 -> bit 0 from byte 7 and bits 6..0 from byte 8

so that 8 7-bit bytes becomes 7 8-bit bytes.
Output may be unreadable and unprintable
so base64 encoding can be used

Uncompress works the opposite.
Strip 1-6 bits and save from bitpacked byte
Shift remaining bits over and paste saved bits
7 6 5 4 3 2 1 0
===============
1 1 1 1 1 1 1 2 -> save byte 1 bit 0 for byte 2 which is bit 6
0 1 1 1 1 1 1 1 -> restore byte 1 by shifting right
2 2 2 2 2 2 3 3 -> save bits 0 and 1 for byte 3 which will be bits 5 and 6
  ! 2 2 2 2 2 2 -> shift over byte 2 and paste saved bit 6
0 2             -> to complete byte 2
3 3 3 3 3 4 4 4 -> save bits 0-2 for byte 4
  ! ! 3 3 3 3 3 -> shift over byte 3 and paste saved bits 5 and 6
...
6 6 7 7 7 7 7 7 -> save bits 0-5 for byte 7
  ! ! ! ! ! 6 6 -> paste saved bits for byte 6
7 8 8 8 8 8 8 8 -> byte 7 contains an unshifted byte 8. Save it. It also
                   has bit 0 for byte 7 in bit 7
  ! ! ! ! ! ! 7 -> paste saved bits for byte 7
byte 8 is unpacked.
so that 7 8-bit bytes becomes 8 7-bit bytes.

this works for any number of bytes but will only save byte space
if 8 or more bytes are packed. 
 
While not encryption by any standard, it will obscure data stored because of
the bit shifting. Base64 encoding can further obscure the original password.

Functions
---------
unsigned char * abitpack( const unsigned char * input)		// Pack an array of bytes
unsigned char * abitunpack( const unsigned char * input)	// Unpack an array of bytes

Both functions return a pointer to packed/unpacked byte stream.
If input is NULL or 0 bytes long, NULL is returned and bperr is set.
If any byte to be packed is 8 bits, NULL is returned and bperr is set.
If any other error occurs, NULL is returned and bperr is set.

Globals
-------
int bperr;		/* global error */
char *bperrstr[]	/* global error strings */

#defines
--------
#define BPEOK    0	/* all OK */
#define BPENOIN  1	/* No input provided */
#define BPE8BIT  2	/* 8 bit ASCII detected */
#define BPENOOUT 3	/* this is very bad! */

Peter Hyman
January 2022
Updated November 2022
pete@peterhyman.com